Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: add architecture diagram
AkitaOnRailsf42c2cd91bb7
diff --git a/README.md b/README.mdindex e6cc383f..951f0218 100644--- a/README.md+++ b/README.md@@ -544,10 +544,11 @@ diagram, crate breakdown, schema notes, and invariants.| [`docs/users.md`](docs/users.md) | **Multi-user attribution (v0.8).** Four-rung auth ladder, `ai-memory user add/list/expire/revive/rotate-token` walkthrough, backward-compat migration for pre-v0.8 installs, token storage rationale. || [`docs/https-via-proxy.md`](docs/https-via-proxy.md) | **HTTPS via a reverse proxy.** When you need TLS (multi-user, non-loopback) and when you don't (loopback / stdio). Copy-paste docker compose templates for Caddy + Let's Encrypt, Caddy + internal CA (LAN-only), Cloudflare Tunnel (no open ports), and external cert files; plus native-Caddy + nginx recipes. The "thinking you're secure when you're not" failure modes explicitly called out. || [`docs/lifecycle-ops.md`](docs/lifecycle-ops.md) | **Read before running purge / rename / backup / restore / reset / reindex / restore-page.** Safety matrix for state-touching commands, per-project disk layout (how isolation actually works), checkpoint-based page recovery, and operator workflows for "fresh start", "snapshot before risky op", "drop one project", and rebuilding SQLite from wiki files. |+| [`docs/auto-improvement-loop.md`](docs/auto-improvement-loop.md) | Auto-improvement design notes: Hermes-inspired post-session review, dry-run defaults, approval boundaries, pending proposal storage, and future curator work. || [`docs/llm-provider-comparison.md`](docs/llm-provider-comparison.md) | Empirical notes behind the recommended LLM defaults. || [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Operational summary: data flow, crate layout, cross-cutting invariants, schema. || [`docs/design-decisions.md`](docs/design-decisions.md) | The full v1 spec. |-| Research docs under `docs/` | Karpathy LLM Wiki notes, agentmemory / basic-memory / cognee deep-dives, lessons-learned from upstream issues. |+| Research docs under `docs/` | Karpathy LLM Wiki notes, Hermes Agent, agentmemory / basic-memory / cognee deep-dives, lessons-learned from upstream issues. |## Influences and prior art@@ -555,6 +556,7 @@ diagram, crate breakdown, schema notes, and invariants.- **[agentmemory](https://github.com/rohitg00/agentmemory)** - most of the right ideas; this project is the Rust successor.- **[basic-memory](https://github.com/basicmachines-co/basic-memory)** - the markdown-on-disk source-of-truth model.- **[cognee](https://github.com/topoteretes/cognee)** - pipeline composition and triplet embeddings.+- **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** - the self-improvement loop: post-turn review, approval gates, and curator boundaries.- **[A-MEM](https://arxiv.org/abs/2502.12110)** - Zettelkasten-style atomic notes with link evolution.## Licensediff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex d93c83ee..188b1468 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -22,56 +22,15 @@ markdown stays the source of truth.## Data flow-```- ┌──────────────────────┐- │ Claude Code / Codex │- │ Cursor / Gemini CLI │- │ Antigravity / Grok │- │ OpenClaw / OpenCode │- │ OMP │- └──────────┬───────────┘- lifecycle hooks │ stdio- (fire-and-forget HTTP) ▼- ┌────────────────────────────────────────────┐- │ ai-memory serve (one binary) │- │ ┌────────────────┐ ┌────────────────────┐ │- │ │ /hook router │ │ MCP server (rmcp) │ │- │ │ (ai-memory- │ │ stdio + streamable │ │- │ │ hooks) │ │ HTTP /mcp │ │- │ └────────┬───────┘ └─────────┬──────────┘ │- │ │ sanitize │ tools/call │- │ ▼ ▼ │- │ ┌────────────────────────────┐ │- │ │ WriterHandle (mpsc) │ │- │ │ single dedicated thread, │ │- │ │ one rusqlite Connection, │ │- │ │ WAL mode, busy_timeout 5s │ │- │ └────────┬───────────┬───────┘ │- │ │ │ │- │ ┌─────────────▼──┐ ┌────▼──────────────┐ │- │ │ markdown wiki/ │ │ SQLite db/ │ │- │ │ (source of │ │ memory.sqlite │ │- │ │ truth + git) │ │ (derived index) │ │- │ └────────────────┘ │ - pages + FTS5 │ │- │ ▲ │ - observations │ │- │ watcher │ │ - handoffs │ │- │ ▼─────────┘ │ - page_embeddings│ │- │ reconciliation │ - audit_log │ │- │ every 30s └───────────────────┘ │- └────────────────────────────────────────────┘- ▲ ▲- │ scheduled / on-demand jobs │- ┌─────┴───────────┐ ┌────────┴─────┐- │ ai-memory │ │ ai-memory │- │ consolidate │ │ forget-sweep │- │ (LLM-driven) │ │ (M8 decay) │- └─────────────────┘ └──────────────┘- ┌─────────────────┐ ┌──────────────┐- │ ai-memory lint │ │ ai-memory │- │ (rule + LLM) │ │ embed (M9 │- └─────────────────┘ │ backfill) │- └──────────────┘-```+++Solid arrows are request, read, and write paths. Dashed arrows are+background reconciliation or provider-backed maintenance. The core invariant is+unchanged: the markdown wiki is the source of truth, and SQLite is the derived+index for search, sessions, observations, handoffs, audit, and embeddings.+Auto-improvement sits on the provider-backed maintenance side: it reviews a+completed session and returns validated proposals, but the shipped mode is+dry-run-only and writes no wiki files or pending proposal pages.**Steady-state loop:**@@ -95,16 +54,22 @@ markdown stays the source of truth.4. When `AI_MEMORY_LLM_PROVIDER` is set, `memory_consolidate` rewritesthat summary into a richer durable page or fans out into amulti-page batch under `concepts/`, `decisions/`, `gotchas/`.-5. `memory_query` answers via FTS5 + link-neighbour RRF; when an+5. On explicit CLI/admin/MCP request, `auto-improve --dry-run` /+ `memory_auto_improve` reviews one completed session with the configured LLM,+ validates proposed `concepts/`, `decisions/`, `gotchas/`, `procedures/`, and+ `_rules/` edits, and returns a report. It does not run on SessionEnd by+ default and does not write durable pages, pending proposals, handoffs, or+ audit rows in the current release.+6. `memory_query` answers via FTS5 + link-neighbour RRF; when anembedder is configured, vector cosine over `page_embeddings` joinsthe same RRF. If compiled wiki pages miss entirely, bounded rawobservation FTS returns fallback `raw_hits`. Page hits bump`access_count` + `last_accessed_at` - the M8 reinforcement term.-6. The forget sweep runs on demand and on the server's `[maintenance]`+7. The forget sweep runs on demand and on the server's `[maintenance]`schedule: pages with `retention < cold_threshold` are soft-deleted;soft-deletions older than `hard_delete_after_days` with no subsequentaccess get purged. Semantic / pinned / freshly-touched pages survive.-7. Backups: `ai-memory backup --to <tarball>` uses SQLite's online+8. Backups: `ai-memory backup --to <tarball>` uses SQLite's onlinebackup API so the source stays writable; `ai-memory restore`reverses. Or: `git push` the wiki dir + `rsync` the data dir.@@ -224,7 +189,7 @@ crates/├── ai-memory-mcp/ rmcp transport + tool router.├── ai-memory-hooks/ payload schemas, sanitiser, /hook ingress.├── ai-memory-llm/ provider auth boundary + LlmProvider / Embedder traits.-├── ai-memory-consolidate/ Karpathy ingest / lint / sweep pipeline.+├── ai-memory-consolidate/ Karpathy ingest / lint / sweep / auto-improve pipeline.└── ai-memory-cli/ `ai-memory` binary entry point + thin HTTP subcommands.```@@ -268,7 +233,7 @@ end-to-end), `memory_auto_improve` exposes a safe default-on learning reviewwithout mutation, and `memory_delete_page` is the exact-path destructive pairneeded by admission-aware mirrors. `memory_handoff_cancel` is the safety valvefor mistaken handoff creation. The narrow-surface discipline still holds —-every new tool has to earn its slot — but the v1 count is 15, not 10.+every new tool has to earn its slot — but the v1 count is 16, not 10.MCP parameter aliases are intentionally sparse: `memory_query.query` accepts`q|search`, and limit fields accept `n` / `top_k` where shipped. Project and@@ -350,6 +315,19 @@ sigma = 0.6 # ↑ to reward query-hits moremu = 0.04 # ↑ if recent hits should count morecold_threshold = 0.20 # below this → soft-deletehard_delete_after_days = 180++[auto_improve] # default-available, non-mutating review+enabled = true+mode = "dry_run" # stage / auto_apply are future modes+on_session_end = false # hooks never gain LLM latency on upgrade+min_observations = 8+min_session_duration_secs = 120+min_confidence = 0.75+max_input_tokens = 24000+max_proposals_per_run = 5+include_raw_fallback = false+proposal_actor = "auto_improve"+pending_path = "_pending/auto-improve"```**LLM provider env** (opt-in):@@ -394,6 +372,10 @@ LLM_API_KEY accepted for openai embeddings only with a custom* **Scheduled consolidation queue.** Forget sweep and lint already runon the server's maintenance schedule; a future queue can compilesession summaries outside hook latency.+* **Auto-improvement staging.** The shipped reviewer is dry-run-only; future+ work is durable pending proposal storage under `_pending/auto-improve/` plus+ list/diff/approve/reject flows that keep autonomous proposal attribution+ separate from the approving human or agent.* **Multi-workspace UI / web dashboard.** Out of scope for v1; revisitonce the headless server has been load-tested.* **Real LongMemEval-S harness.** The recall-eval framework exists@@ -409,6 +391,8 @@ LLM_API_KEY accepted for openai embeddings only with a custom* [`docs/research-agentmemory.md`](research-agentmemory.md),[`research-basic-memory.md`](research-basic-memory.md),[`research-cognee.md`](research-cognee.md) - prior art studied.+* [`docs/auto-improvement-loop.md`](auto-improvement-loop.md) -+ Hermes Agent-inspired learning-loop research and safety boundaries.* [`docs/issues-*.md`](.) - concrete failure modes we've designed toavoid.* [`CLAUDE.md`](../CLAUDE.md) - per-session operating rules pinneddiff --git a/docs/architecture-overview.svg b/docs/architecture-overview.svgnew file mode 100644index 00000000..d449ad60--- /dev/null+++ b/docs/architecture-overview.svg@@ -0,0 +1,157 @@+<svg xmlns="http://www.w3.org/2000/svg" width="1400" height="920" viewBox="0 0 1400 920" role="img" aria-labelledby="title desc">+ <title id="title">ai-memory architecture overview</title>+ <desc id="desc">A diagram showing agent clients sending lifecycle hooks and MCP calls into ai-memory serve, which routes through hook, MCP, web, admin, scope, auth, writer, read pool, markdown wiki, SQLite index, maintenance jobs, and optional LLM and embedding providers.</desc>+ <defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">+ <path d="M 0 0 L 10 5 L 0 10 z" fill="#334155" />+ </marker>+ <marker id="arrow-blue" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">+ <path d="M 0 0 L 10 5 L 0 10 z" fill="#2563eb" />+ </marker>+ <marker id="arrow-green" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">+ <path d="M 0 0 L 10 5 L 0 10 z" fill="#15803d" />+ </marker>+ <style>+ .canvas { fill: #f8fafc; }+ .title { font: 700 30px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #0f172a; }+ .subtitle { font: 500 15px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #475569; }+ .group-label { font: 700 16px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #334155; letter-spacing: .02em; }+ .box-title { font: 700 17px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #0f172a; }+ .box-text { font: 500 13px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #334155; }+ .small { font: 500 12px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #475569; }+ .client { fill: #ffffff; stroke: #cbd5e1; stroke-width: 1.5; rx: 16; }+ .server { fill: #eef2ff; stroke: #818cf8; stroke-width: 2; rx: 22; }+ .route { fill: #ffffff; stroke: #a5b4fc; stroke-width: 1.5; rx: 14; }+ .boundary { fill: #fef3c7; stroke: #f59e0b; stroke-width: 1.5; rx: 14; }+ .writer { fill: #dcfce7; stroke: #22c55e; stroke-width: 1.5; rx: 14; }+ .reader { fill: #dbeafe; stroke: #3b82f6; stroke-width: 1.5; rx: 14; }+ .job { fill: #f5f3ff; stroke: #8b5cf6; stroke-width: 1.5; rx: 14; }+ .store { fill: #ffffff; stroke: #64748b; stroke-width: 1.5; rx: 16; }+ .external { fill: #fff7ed; stroke: #fb923c; stroke-width: 1.5; rx: 16; }+ .arrow { fill: none; stroke: #334155; stroke-width: 2.2; marker-end: url(#arrow); }+ .arrow-blue { fill: none; stroke: #2563eb; stroke-width: 2.2; marker-end: url(#arrow-blue); }+ .arrow-green { fill: none; stroke: #15803d; stroke-width: 2.2; marker-end: url(#arrow-green); }+ .arrow-dashed { fill: none; stroke: #64748b; stroke-width: 2; stroke-dasharray: 7 6; marker-end: url(#arrow); }+ </style>+ </defs>++ <rect class="canvas" x="0" y="0" width="1400" height="920" />+ <text class="title" x="700" y="48" text-anchor="middle">ai-memory architecture overview</text>+ <text class="subtitle" x="700" y="76" text-anchor="middle">Hooks capture automatically; markdown is the source of truth; SQLite is the derived search/index layer.</text>++ <text class="group-label" x="70" y="112">CLIENTS</text>+ <rect class="client" x="60" y="130" width="290" height="118" />+ <text class="box-title" x="85" y="164">Agent CLIs</text>+ <text class="box-text" x="85" y="190">Claude Code, Codex, OpenCode</text>+ <text class="box-text" x="85" y="211">Cursor, Gemini, Antigravity</text>+ <text class="box-text" x="85" y="232">Grok, OpenClaw, OMP</text>++ <rect class="client" x="390" y="130" width="290" height="118" />+ <text class="box-title" x="415" y="164">Terminal and automation</text>+ <text class="box-text" x="415" y="190">ai-memory CLI thin clients</text>+ <text class="box-text" x="415" y="211">bootstrap, search, backup</text>+ <text class="box-text" x="415" y="232">lint, embed, forget-sweep</text>++ <rect class="client" x="720" y="130" width="290" height="118" />+ <text class="box-title" x="745" y="164">Browser and API clients</text>+ <text class="box-text" x="745" y="190">/web wiki browser</text>+ <text class="box-text" x="745" y="211">/admin operator routes</text>+ <text class="box-text" x="745" y="232">/api/v1 integration surface</text>++ <rect class="external" x="1050" y="130" width="290" height="118" />+ <text class="box-title" x="1075" y="164">Optional providers</text>+ <text class="box-text" x="1075" y="190">LLM consolidation and lint</text>+ <text class="box-text" x="1075" y="211">dry-run auto-improvement</text>+ <text class="box-text" x="1075" y="232">embedding vector backfill</text>++ <rect class="server" x="60" y="300" width="1280" height="390" />+ <text class="group-label" x="90" y="335">ai-memory serve - one Rust binary</text>++ <rect class="route" x="100" y="365" width="235" height="100" />+ <text class="box-title" x="125" y="397">/hook router</text>+ <text class="box-text" x="125" y="423">fire-and-forget capture</text>+ <text class="box-text" x="125" y="444">sanitizes hook payloads</text>++ <rect class="route" x="375" y="365" width="235" height="100" />+ <text class="box-title" x="400" y="397">MCP server</text>+ <text class="box-text" x="400" y="423">stdio and HTTP /mcp</text>+ <text class="box-text" x="400" y="444">memory_query, handoff, etc.</text>++ <rect class="route" x="650" y="365" width="235" height="100" />+ <text class="box-title" x="675" y="397">Web, admin, API</text>+ <text class="box-text" x="675" y="423">wiki UI and operator routes</text>+ <text class="box-text" x="675" y="444">HTTP API integrations</text>++ <rect class="boundary" x="925" y="365" width="360" height="100" />+ <text class="box-title" x="950" y="397">Scope, auth, admission</text>+ <text class="box-text" x="950" y="423">workspace/project resolution</text>+ <text class="box-text" x="950" y="444">capability gates + webhooks</text>++ <rect class="writer" x="150" y="535" width="345" height="110" />+ <text class="box-title" x="175" y="568">Writer actor</text>+ <text class="box-text" x="175" y="594">single mpsc queue, one rusqlite writer</text>+ <text class="box-text" x="175" y="615">WAL mode, batch transactions</text>++ <rect class="reader" x="555" y="535" width="345" height="110" />+ <text class="box-title" x="580" y="568">Read pool and retrieval</text>+ <text class="box-text" x="580" y="594">FTS5 + graph-neighbor RRF</text>+ <text class="box-text" x="580" y="615">optional vector RRF + raw fallback</text>++ <rect class="job" x="960" y="535" width="300" height="110" />+ <text class="box-title" x="985" y="568">Lifecycle and maintenance jobs</text>+ <text class="box-text" x="985" y="594">session summary + handoff</text>+ <text class="box-text" x="985" y="615">consolidate, auto-improve</text>+ <text class="box-text" x="985" y="636">lint, embed, sweep</text>++ <text class="group-label" x="70" y="735">DURABLE STATE</text>+ <rect class="store" x="105" y="755" width="350" height="120" />+ <text class="box-title" x="130" y="789">Markdown wiki</text>+ <text class="box-text" x="130" y="815">source of truth on disk</text>+ <text class="box-text" x="130" y="836">git commits, restore-page</text>+ <text class="box-text" x="130" y="857">editable by humans/tools</text>++ <rect class="store" x="525" y="755" width="350" height="120" />+ <text class="box-title" x="550" y="789">SQLite memory.sqlite</text>+ <text class="box-text" x="550" y="815">derived index and audit store</text>+ <text class="box-text" x="550" y="836">pages, sessions, observations</text>+ <text class="box-text" x="550" y="857">FTS5, handoffs, embeddings</text>++ <rect class="store" x="945" y="755" width="350" height="120" />+ <text class="box-title" x="970" y="789">Backups and checkpoints</text>+ <text class="box-text" x="970" y="815">SQLite online backup</text>+ <text class="box-text" x="970" y="836">wiki git checkpoints</text>+ <text class="box-text" x="970" y="857">rsync or tarball restore</text>++ <path class="arrow-blue" d="M 205 248 C 205 280 205 320 205 365" />+ <text class="small" x="105" y="287">lifecycle hooks POST /hook</text>+ <path class="arrow-blue" d="M 260 248 C 320 290 410 320 492 365" />+ <text class="small" x="370" y="308">MCP stdio or HTTP</text>+ <path class="arrow-blue" d="M 535 248 C 590 292 660 320 735 365" />+ <text class="small" x="553" y="286">CLI HTTP calls</text>+ <path class="arrow-blue" d="M 865 248 C 865 295 800 320 768 365" />+ <text class="small" x="805" y="287">browser/API HTTP</text>++ <path class="arrow" d="M 335 415 L 375 415" />+ <path class="arrow" d="M 610 415 L 650 415" />+ <path class="arrow" d="M 885 415 L 925 415" />+ <text class="small" x="936" y="488">authorized write/read requests</text>+ <path class="arrow-green" d="M 1040 465 C 910 515 610 500 495 560" />+ <path class="arrow-blue" d="M 1110 465 C 1040 520 940 520 900 570" />++ <path class="arrow-green" d="M 323 645 C 300 690 285 720 280 755" />+ <path class="arrow-green" d="M 405 645 C 500 700 615 710 700 755" />+ <path class="arrow-blue" d="M 700 755 C 705 715 715 680 728 645" />+ <path class="arrow-blue" d="M 600 645 C 505 700 380 714 285 755" />++ <path class="arrow-dashed" d="M 455 810 C 490 775 500 775 525 810" />+ <text class="small" x="458" y="747">watcher reconciliation</text>++ <path class="arrow" d="M 1100 645 C 1090 700 1110 720 1120 755" />+ <path class="arrow" d="M 455 835 C 620 895 780 895 945 835" />+ <path class="arrow" d="M 875 835 C 900 835 920 835 945 835" />++ <path class="arrow-dashed" d="M 1195 535 C 1240 445 1240 330 1195 248" />+ <text class="small" x="1212" y="388">LLM and embedding calls</text>++ <text class="small" x="70" y="900">Solid arrows show request, read, and write paths. Dashed arrows show background reconciliation or provider-backed maintenance.</text>+</svg>