merkhain user guide
| Guide | Covers |
|---|---|
| Install | Release archives, .deb/.rpm, Homebrew, Windows; running serve local as a user service; upgrade; uninstall; building releases |
| Local memory | Identity, config, Claude Code / Codex / OpenCode / pi capture, A2A and AG-UI protocol capture and recording import, importing claude-mem / Claude Code / Codex memories, prompt and search context, MCP setup, provider selection, recall |
| Event filter | What automatic recall and extraction leave out of orchestration and protocol traffic: event_filter.mode, the rules file, merkhain rules check / explain / replay, and the historical rules cleanup |
| Web UI | merkhain ui, --no-open / headless use, Relay Administration operator sign-in and public origin, the local confirmation handoff, sharing and queue troubleshooting in the browser |
| Relay | Deploying serve remote: databases, systemd, container, TLS or reverse proxy, operator token, relay backup |
| Sharing | Personal pools and device pairing, team pools, invitations, removal and key rotation |
| Operations | status / repair, owner recovery export/restore, backups, upgrades |
| Tracing | Opt-in OpenTelemetry tracing: configuration, collector setup, sampling, privacy guarantees, hook flush budget |
| Databases | SQLite and PostgreSQL: configuration, first installation, automatic (local) and explicit (relay) migrations, mixed-version upgrades, legacy adoption, SQLite → PostgreSQL transfer, relay shards, pool and bucket moves, several relay processes and console session affinity, backup, failover, search differences |
| Security | Trust boundaries: what the relay, the local index and the inference endpoint see |
| Troubleshooting | Symptoms, diagnoses, and fixes |
Acceptance evidence: local milestone and the team / release acceptance report, and the web UI packaging report. The retired memory-quality benchmark campaign is summarized in its retrospective; it claims no quality acceptance. Protocol details: docs/protocol/.
Verified versions
| Component | Version | How |
|---|---|---|
| Claude Code (hooks + transcripts) | 2.1.312 | live sessions (claude -p), see the final acceptance live quickstart |
Codex CLI (rollout import, hooks, codexcli provider) |
0.165.0 | live codex exec (codexcli extraction in the final acceptance live quickstart); Codex-invoked hooks need the one-time /hooks trust and were not exercised live |
| OpenAI-compatible provider | Chat Completions API | fixture server only; no live local chat model was run (recipe in Local memory) |
| Go toolchain | 1.27 | CGO_ENABLED=0 builds for darwin/linux/windows × amd64/arm64 |
| SQLite | modernc (pure Go), WAL, synchronous=FULL |
default for instances and relays; every test suite and the native E2E runs |
| PostgreSQL | 16 and 18 | persistence contract, relay routing, move and transfer tests on real servers (make test-postgres); release-binary smoke with PostgreSQL instances, a single-database and a sharded relay, and the relay container (packaging/ci/postgres-smoke.sh) |
| OS key stores | macOS Keychain (live); Secret Service (GNOME Keyring), Windows Credential Manager | Linux/Windows native stores verified on CI runners; use --key-store file where no store exists |
Known limitations
- No hosted service, signing/notarization, or package-manager submission. The web UI is local (
serve local) and an operator console, Relay Administration (serve remote), only; there is no email/SSO login and no browser-held keys. macOS may quarantine a downloaded binary:xattr -d com.apple.quarantine merkhain. - Extraction needs an explicitly configured provider; with
provider.kind: nonesessions are captured but no memories appear (jobs stay pending). - Codex runs new or changed hooks only after you trust them (
codex→/hooks). Until then usemerkhain codex import(also the catch-up path after downtime). - Sharing is future-only: binding a project publishes memories created from then on; older history needs
merkhain publish. Previously downloaded history cannot be revoked from a removed member. - Each pool uses one relay URL. Several relay processes can serve it only on PostgreSQL; their operator console sessions are per process, so the console needs session affinity (Databases). The relay operator token is long-lived (rotate by deleting it and restarting).
- Databases: SQLite and PostgreSQL 16/18 only. The instance database migrates automatically; standalone relay
databases need
merkhain migrate upafter an upgrade. Search ranking, stemming and snippets differ between the engines. A SQLite relay moves to PostgreSQL only offline (transfer relay). Failover needs synchronous replication and a fenced promotion. Relay benchmarks come from one host and are not a capacity statement. See Databases. - On PostgreSQL 16 and 18, CI runs the team milestone (sharded relay on two servers, two relay processes, PostgreSQL local databases), a three-process relay test, process crash tests and synchronous-standby failover tests end to end. The local milestone, the client crash-point and concurrency E2E suites and the Playwright suites except the smoke run on SQLite only. The PostgreSQL crash and failover tests do not run on Windows (no PostgreSQL server or Linux containers on that runner).
- Project mapping is transferred once at pairing/joining; later projects need
merkhain project alias. - Windows: hooks and the service task are not live-verified beyond CI smoke runs.