Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
audit followups: extract build_update + same-path admin test; README polish
AkitaOnRails4c8bb4f9b6c9
diff --git a/README.md b/README.mdindex 9641dc34..77543359 100644--- a/README.md+++ b/README.md@@ -29,6 +29,65 @@ Obsidian, backed up with `rsync`. No vector database to babysit, noin [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md); the influences andpriors are at the [bottom](#influences-and-prior-art).+## Key features++- **Zero-friction capture.** Lifecycle hooks fire-and-forget every+ prompt + tool call + session boundary. You never type `write_note`.+- **Cross-agent handoffs.** Quit Claude Code mid-task, start Codex+ in the same directory hours later — the next agent sees a+ "where you left off" block before its first prompt.+- **Per-project isolation by construction.** Each project lives at+ `<wiki_root>/<workspace_id>/<project_id>/…` keyed by stable UUIDs.+ Same page path can exist in two projects without collision; a+ rename is one column update; a purge is one `rm -rf`.+- **Karpathy-style LLM wiki.** Pages are compiled from observations+ at session-end (or PreCompact), not retrieved over raw logs.+ Supersession chain + git-versioned markdown means you can+ time-travel with `git log`.+- **Built-in `/web` browser.** Read-only HTML UI for the wiki —+ project list, folder tree, FTS5 search, markdown rendering, dark+ mode. Mounted on the same axum server as MCP.+- **Multi-agent + multi-machine ready.** Supported clients: Claude+ Code, Codex, OpenCode, Cursor, Claude Desktop (via `mcp-remote`),+ Gemini CLI, OpenClaw. Server runs local (loopback) OR on a homelab+ box (LAN/VPN/cloud) with bearer-token auth.+- **Thin-client CLI.** `ai-memory bootstrap`, `purge-project`,+ `rename-project`, `lint`, `embed`, `forget-sweep`, `backup` are+ all HTTP clients of the running server — never touch SQLite or+ wiki files directly. Server is the single source of truth.+- **LLM is opt-in.** Zero-LLM mode still gives you FTS5 search ++ rule-based summarisation. Add a provider when you want consolidated+ pages and lint contradictions.++## Use cases++- **"Quit at 4 PM, pick up at 9 AM in a different agent."** The+ classic. SessionStart hook in the next agent (any of the+ supported CLIs) prepends a typed handoff with the open questions,+ next steps, and a session summary.+- **"What did we decide about X six weeks ago?"** Type+ `memory_query X` from the agent (or `ai-memory search X` from a+ terminal) — FTS5 over the wiki. Pages are LLM-consolidated, so+ the hit is a coherent decision page, not a raw chat log.+- **"This new project has months of history before ai-memory."**+ `cd ~/Projects/<that-project> && ai-memory bootstrap` collects+ `git log`, README, `docs/`, module headers, project rules and+ one-shot-summarises them into seed wiki pages. Future sessions+ build on top.+- **"Run one ai-memory for the whole household."** Stand the server+ up on a homelab box at `0.0.0.0:49374` with a bearer token; every+ laptop/desktop talks to it. Per-cwd routing keeps each project's+ pages cleanly separated; the `/web` UI is reachable from a+ browser anywhere on the LAN.+- **"Audit what landed before sharing with a teammate."** Browse+ the wiki at `http://<server>:49374/web` — HTTP Basic dialog if+ auth is on, paste the token as password. Per-project tree view,+ rendered markdown, supersession chain visible per page.+- **"Drop an experiment, keep the rest."**+ `ai-memory purge-project --project experimental --confirm`.+ Atomic: that project's DB rows cascade away, its wiki subdir gets+ `rm -rf`'d, every sibling project is untouched by construction.+## Quick startYou need: Docker + an agent CLI (Claude Code, Codex, OpenCode, Cursor,diff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rsindex 682facfb..94d2185b 100644--- a/crates/ai-memory-consolidate/src/consolidator.rs+++ b/crates/ai-memory-consolidate/src/consolidator.rs@@ -239,63 +239,9 @@ impl Consolidator {let mut requests = Vec::with_capacity(batch.updates.len());let mut outcomes_preview = Vec::with_capacity(batch.updates.len());for upd in &batch.updates {- // When the LLM classifies an update as a rule, ALWAYS- // route it to `_rules/<slug>.md` regardless of what- // path it suggested — this is the M20 contract that- // lets the lint pass find every rule-shaped page in a- // single sweep without scanning frontmatter across the- // whole wiki.- let final_path = if upd.kind == crate::types::PageKind::Rule {- let slug = slugify_for_rule(&upd.title);- format!("_rules/{slug}.md")- } else {- upd.path.clone()- };- let path = PagePath::new(final_path)?;- let tier = upd.tier;- let mut fm = serde_json::Map::new();- fm.insert("title".into(), serde_json::Value::String(upd.title.clone()));- fm.insert(- "tier".into(),- serde_json::Value::String(tier_as_str(tier).into()),- );- // M20: surface the semantic classification into- // frontmatter so the lint pass + downstream tooling- // can branch on it without re-classifying.- fm.insert(- "kind".into(),- serde_json::Value::String(upd.kind.as_str().into()),- );- if !upd.tags.is_empty() {- fm.insert(- "tags".into(),- serde_json::Value::Array(- upd.tags- .iter()- .map(|t| serde_json::Value::String(t.clone()))- .collect(),- ),- );- }- fm.insert("consolidated".into(), serde_json::Value::Bool(true));- requests.push(WritePageRequest {- workspace_id: ws,- project_id: proj,- path: path.clone(),- frontmatter: serde_json::Value::Object(fm),- body: upd.body_markdown.clone(),- tier,- pinned: false,- title: Some(upd.title.clone()),- });- outcomes_preview.push(ConsolidationOutcome {- path,- dry_run,- new_title: upd.title.clone(),- new_body_markdown: upd.body_markdown.clone(),- page_id: None,- tags: upd.tags.clone(),- });+ let (req, outcome) = build_update(ws, proj, upd, dry_run)?;+ requests.push(req);+ outcomes_preview.push(outcome);}if dry_run {@@ -324,6 +270,78 @@ impl Consolidator {}}+/// Convert one LLM-produced batch update into the+/// `(WritePageRequest, ConsolidationOutcome)` pair the consolidator+/// hands to `Wiki::apply_batch`. Pulled out of+/// `consolidate_session_multi` so the rule-routing + frontmatter+/// assembly can be exercised in isolation if needed.+///+/// M20 contract: when `upd.kind == Rule`, ALWAYS route to+/// `_rules/<slug>.md` regardless of the LLM's suggested path. The+/// lint pass relies on `_rules/` being the single sweep-able+/// location for rule pages.+fn build_update(+ ws: WorkspaceId,+ proj: ProjectId,+ upd: &crate::types::ConsolidatedPageUpdate,+ dry_run: bool,+) -> ConsolidatorResult<(WritePageRequest, ConsolidationOutcome)> {+ let final_path = if upd.kind == crate::types::PageKind::Rule {+ let slug = slugify_for_rule(&upd.title);+ format!("_rules/{slug}.md")+ } else {+ upd.path.clone()+ };+ let path = PagePath::new(final_path)?;+ let tier = upd.tier;++ let mut fm = serde_json::Map::new();+ fm.insert("title".into(), serde_json::Value::String(upd.title.clone()));+ fm.insert(+ "tier".into(),+ serde_json::Value::String(tier_as_str(tier).into()),+ );+ // M20: surface the semantic classification into frontmatter so+ // the lint pass + downstream tooling can branch on it without+ // re-classifying.+ fm.insert(+ "kind".into(),+ serde_json::Value::String(upd.kind.as_str().into()),+ );+ if !upd.tags.is_empty() {+ fm.insert(+ "tags".into(),+ serde_json::Value::Array(+ upd.tags+ .iter()+ .map(|t| serde_json::Value::String(t.clone()))+ .collect(),+ ),+ );+ }+ fm.insert("consolidated".into(), serde_json::Value::Bool(true));++ let req = WritePageRequest {+ workspace_id: ws,+ project_id: proj,+ path: path.clone(),+ frontmatter: serde_json::Value::Object(fm),+ body: upd.body_markdown.clone(),+ tier,+ pinned: false,+ title: Some(upd.title.clone()),+ };+ let outcome = ConsolidationOutcome {+ path,+ dry_run,+ new_title: upd.title.clone(),+ new_body_markdown: upd.body_markdown.clone(),+ page_id: None,+ tags: upd.tags.clone(),+ };+ Ok((req, outcome))+}+const fn tier_as_str(t: Tier) -> &'static str {match t {Tier::Working => "working",diff --git a/crates/ai-memory-mcp/tests/admin_write_page.rs b/crates/ai-memory-mcp/tests/admin_write_page.rsindex b529fbff..f25e96f5 100644--- a/crates/ai-memory-mcp/tests/admin_write_page.rs+++ b/crates/ai-memory-mcp/tests/admin_write_page.rs@@ -157,6 +157,129 @@ async fn write_page_invalid_tier_returns_422() {);}+#[tokio::test]+async fn write_page_two_projects_same_path_no_collision() {+ // Two projects can hold pages with the same `pages.path` without+ // colliding on disk — the per-project UUID-keyed layout (CLAUDE.md+ // §15) guarantees structural isolation. The wiki crate already+ // exercises this at the `Wiki::write_page` level; this test makes+ // sure the invariant survives through the full+ // `POST /admin/write-page` handler path.+ let tmp = TempDir::new().unwrap();+ let state = make_state(&tmp).await;++ // Body 1: alpha project.+ let resp = post_json(+ state.clone(),+ "/admin/write-page",+ json!({+ "workspace": "default",+ "project": "alpha",+ "path": "decisions/0001.md",+ "body": "Page from project alpha — fingerprint AAAA-alpha.",+ "tier": "semantic",+ }),+ )+ .await;+ assert_eq!(resp.status(), StatusCode::OK);+ let alpha_id = body_json(resp).await["page_id"]+ .as_str()+ .expect("alpha page_id")+ .to_string();++ // Body 2: beta project, SAME page path.+ let resp = post_json(+ state.clone(),+ "/admin/write-page",+ json!({+ "workspace": "default",+ "project": "beta",+ "path": "decisions/0001.md",+ "body": "Page from project beta — fingerprint BBBB-beta.",+ "tier": "semantic",+ }),+ )+ .await;+ assert_eq!(resp.status(), StatusCode::OK);+ let beta_id = body_json(resp).await["page_id"]+ .as_str()+ .expect("beta page_id")+ .to_string();++ // Distinct page rows.+ assert_ne!(+ alpha_id, beta_id,+ "the two writes must produce distinct page_ids"+ );++ // FTS5 search: both fingerprints findable, exactly one hit each.+ let resp = post_json(state.clone(), "/admin/search?q=AAAA-alpha", json!(null)).await;+ // /admin/search is a GET, not POST — re-route via the router.+ drop(resp);+ let router = admin_router(state.clone());+ let resp = router+ .clone()+ .oneshot(+ Request::builder()+ .method("GET")+ .uri("/admin/search?q=fingerprint")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(resp.status(), StatusCode::OK);+ let hits: serde_json::Value = body_json(resp).await;+ let hits_arr = hits.as_array().expect("array");+ assert_eq!(+ hits_arr.len(),+ 2,+ "both projects' pages must be searchable: {hits}"+ );+ // Same wiki path appears on both hits.+ assert!(+ hits_arr+ .iter()+ .all(|h| h["path"].as_str() == Some("decisions/0001.md")),+ "both hits should share the same relative path: {hits}"+ );++ // Files on disk: both exist at their per-project namespaced paths.+ // The two project_id UUIDs differ, so two distinct files live on+ // disk even though pages.path is identical. Recursive walk via+ // std::fs (no walkdir dep) — collect every `decisions/0001.md`+ // we find under wiki/.+ let wiki_dir = tmp.path().join("wiki");+ let mut on_disk: Vec<std::path::PathBuf> = Vec::new();+ collect_files_named(&wiki_dir, "decisions/0001.md", &mut on_disk);+ assert_eq!(+ on_disk.len(),+ 2,+ "expected two physical files for the same page path; found: {on_disk:?}"+ );+}++/// Recurse into `dir`, collecting every file whose relative path+/// (from `dir`) ends with `suffix`. Test helper kept inline because+/// it's only used here and we don't want a walkdir dep.+fn collect_files_named(dir: &std::path::Path, suffix: &str, out: &mut Vec<std::path::PathBuf>) {+ let Ok(entries) = std::fs::read_dir(dir) else {+ return;+ };+ for entry in entries.flatten() {+ let p = entry.path();+ let ft = match entry.file_type() {+ Ok(ft) => ft,+ Err(_) => continue,+ };+ if ft.is_dir() {+ collect_files_named(&p, suffix, out);+ } else if ft.is_file() && p.to_string_lossy().replace('\\', "/").ends_with(suffix) {+ out.push(p);+ }+ }+}+#[tokio::test]async fn write_page_with_tags_and_pinned() {let tmp = TempDir::new().unwrap();