Skip to content

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.md
index 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.
## License
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 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) │
- └──────────────┘
-```
+![ai-memory architecture overview](architecture-overview.svg)
+
+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` rewrites
that summary into a richer durable page or fans out into a
multi-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 an
embedder is configured, vector cosine over `page_embeddings` joins
the same RRF. If compiled wiki pages miss entirely, bounded raw
observation 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 subsequent
access 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 online
backup 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 review
without mutation, and `memory_delete_page` is the exact-path destructive pair
needed by admission-aware mirrors. `memory_handoff_cancel` is the safety valve
for 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 more
mu = 0.04 # ↑ if recent hits should count more
cold_threshold = 0.20 # below this → soft-delete
hard_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 run
on the server's maintenance schedule; a future queue can compile
session 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; revisit
once 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 to
avoid.
* [`CLAUDE.md`](../CLAUDE.md) - per-session operating rules pinned
diff --git a/docs/architecture-overview.svg b/docs/architecture-overview.svg
new file mode 100644
index 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>