Skip to content

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.md
index 9641dc34..77543359 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,65 @@ Obsidian, backed up with `rsync`. No vector database to babysit, no
in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md); the influences and
priors 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 start
You 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.rs
index 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.rs
index 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();