Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: add task-oriented cookbook cheat sheet (#726)
AkitaOnRails3ff8b92d6e88
diff --git a/AGENTS.md b/AGENTS.mdindex 0ead52fa..96e884dc 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -536,6 +536,9 @@ Additional boundary rules:and milestone plan.- [`docs/install.md`](docs/install.md) — installation cookbook for everysupported agent client.+- [`docs/cookbook.md`](docs/cookbook.md) — task-oriented cheat sheet: "I want+ to do X" → how (recall, durable rules, importing a knowledge base, two agents+ working together).- [`docs/lifecycle-ops.md`](docs/lifecycle-ops.md) — read before touchingpurge/rename/backup/restore/reset/reindex/restore-page.- [`docs/auto-improvement-loop.md`](docs/auto-improvement-loop.md) —diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 820950cd..50fe8495 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added+- New task-oriented `docs/cookbook.md` cheat sheet ("I want to do X" → how:+ recall, durable rules, importing a knowledge base and reading a specific+ document, two agents working together), linked from the README docs table, to+ make it clearer what ai-memory does and how to use it (#726).- Codex assistant-final-turn capture: `install-hooks --agent codex --capture-assistant`now captures the assistant's final message on `Stop`, the same double opt-in(client flag + server `capture_assistant = true`) and sanitize/bound pipelinediff --git a/README.md b/README.mdindex e1500b16..40439c81 100644--- a/README.md+++ b/README.md@@ -325,6 +325,7 @@ diagram, crate breakdown, schema notes, and invariants.| File | What it is ||---|---|+| [`docs/cookbook.md`](docs/cookbook.md) | **Task-oriented cheat sheet.** "I want to do X" → how: recall prior work, keep a rule a project must follow, import an existing knowledge base (OKF norms/specs) and have a project read a specific document, and get two agents/repos working together. Start here if you're unsure what ai-memory can do for you. || [`docs/install.md`](docs/install.md) | **Installation cookbook.** Every agent CLI, every alternative (curl, source build, no-docker, no-auth), and the server-on-a-different-machine (homelab/LAN) walkthrough. Read after the Quick start if your setup doesn't match the happy path. || [`docs/usage.md`](docs/usage.md) | Handoffs, proactive memory queries, slim routing snippet + managed Agent Skills, migration from other memory tools, web UI, raw-wiki inspection, and rules-vs-facts workflow. || [`docs/managed-workstreams.md`](docs/managed-workstreams.md) | Optional `ai-memory run` continuity across Claude Code, Codex, OpenCode, OpenCode 2 beta, Pi, Crush, Kimi Code, Command Code, Kiro CLI v2/v3, OMP, Grok Build CLI, and Antigravity CLI: automatic harness selection, native resume, argument forwarding, ledger search, privacy, and recovery. |diff --git a/docs/cookbook.md b/docs/cookbook.mdnew file mode 100644index 00000000..92e7516d--- /dev/null+++ b/docs/cookbook.md@@ -0,0 +1,111 @@+# ai-memory cookbook++A task-oriented cheat sheet: "I want to do X" → how. For the full reference see+[`ARCHITECTURE.md`](ARCHITECTURE.md); for install see [`install.md`](install.md);+for the tool-routing table see [`usage.md`](usage.md).++## What ai-memory is, in one paragraph++ai-memory gives your AI coding agents long-term, cross-session memory. It runs+as one server; your agent talks to it over MCP (tools like `memory_query`,+`memory_write_page`) and over lifecycle hooks that automatically capture what you+do. Memory is a **markdown wiki in git** (the source of truth, hand-editable) plus+a derived SQLite index for search. Everything is **scoped per project**+`(workspace, project)`, resolved from your working directory. It works with no+LLM at all (capture + full-text search + rule-based summaries); adding a provider+enables consolidation and auto-improvement.++## Everyday tasks (through your agent, over MCP)++You mostly just talk to your agent; it calls the right tool. Common ones:++| You want | Say to your agent | Tool it uses |+|---|---|---|+| Recall prior work | "Have we discussed X?" / "what did we decide about Y?" | `memory_query` |+| Catch up after time away | "Where did we leave off?" / "catch me up" | handoff block / `memory_explore` |+| Remember a durable fact | "Remember that we always use pnpm here" | `memory_write_page` |+| Remember until a date | "Remember this until the migration ships" | `memory_write_page` + `expires_at` |+| A standing rule for *every* project | "Always: never force-push" | `memory_write_page` with `scope: "global"` |+| Read a specific saved page in full | "Read the `_rules/deploy` page" | `memory_read_page` |+| Save context for the next session | "Wrap up — save context for next time" | `memory_handoff_begin` |+| See project stats | "How much memory do we have?" | `memory_status` / `memory_briefing` |++You rarely write pages by hand: lifecycle hooks capture prompts and tool calls+automatically, and (with an LLM) consolidation compiles them into pages.++## Recipe: keep a rule a project must follow++> "Remember: before touching the payment code, read the PCI notes."++Your agent calls `memory_write_page` and it lands as a durable wiki page (routed+under `_rules/` when it's a rule). Next session, `memory_query` surfaces it, and+if the project's `.ai-memory.toml` opts into the on-start brief, rules are+prepended to the agent's context automatically. To make it apply to **all** your+projects, ask for it as a global rule (`scope: "global"`).++## Recipe: have a project read a specific document before implementing++Two ways, depending on where the document lives:++1. **It's already a wiki page** (you saved it, or imported it — below): tell the+ agent "read the `norms/gdpr-retention` page before implementing" — it calls+ `memory_read_page` with that path and works from the full body.+2. **It's an external file** (a norm/spec on disk): save it as a page first+ ("remember this spec as `norms/gdpr-retention`", paste or point at it), then+ reference it as in (1). Large references are best split into a page per+ document so retrieval can pull just the relevant one.++## Recipe: import an existing knowledge base (e.g. OKF norms/laws/specs)++ai-memory's wiki **is** OKF (Obsidian-compatible markdown + frontmatter). To+bring an existing body of documents in as project memory:++- **A few documents**: save each as a durable page via your agent+ (`memory_write_page`) or the CLI (`ai-memory write-page`), one page per+ document, under a stable prefix like `norms/…`. Then any project can read a+ specific one before implementing (recipe above).+- **A whole OKF/Obsidian vault or an export from another tool**: use the+ companion importer (see [`companion-crates.md`](companion-crates.md)) — it+ ingests OMC and external-conversation exports into the store. `ai-memory+ export-okf` is the inverse (export your wiki as an OKF bundle), useful to see+ the exact on-disk shape your documents should take.+- The wiki lives at `<data_dir>/wiki/<workspace>/<project>/…` and is plain+ markdown in git, so you can also drop files in and let the file watcher ++ reindex pick them up. Keep them under a clear prefix and commit.++Once the material is saved as pages in the right scope, any project can search+it (`memory_query`) and read a specific document in full (`memory_read_page`)+before implementing against it.++## Recipe: two agents / two repos working together++- **Continuity across agents in the same project** (quit Claude Code, open Codex+ in the same repo): automatic. A handoff is captured at session end and the+ next session's on-start hook prepends it. Ask "where did we leave off?".+- **Ask an agent in another project to do something** without loading that+ project's context here: cross-project messaging — "send project-b a request to+ add the export endpoint" (`memory_message_send`), and over there "check my+ inbox" (`memory_message_pop`). See [`agent-messaging.md`](agent-messaging.md).++## From the terminal (CLI)++Most people never need these — the agent does it — but they exist:++```bash+ai-memory status # counts, paths, health+ai-memory write-page … # save a durable page+ai-memory handoffs # list open handoffs for the project+ai-memory message list # cross-project inbox+ai-memory export-okf … # export the wiki as an OKF bundle+ai-memory serve # run the server+```++## When it isn't doing what you expect++- **Nothing is being remembered**: hooks may not be installed — `ai-memory+ install-hooks --agent <your-agent> --apply`, and check `ai-memory status`.+- **A search misses something you saved**: confirm the scope — memory is+ per-project; a page saved in project A is not returned in project B unless it+ was written to the global scope or you query with an explicit scope.+- **You want an LLM feature (consolidation, digests)**: set a provider+ (`AI_MEMORY_LLM_PROVIDER=…`); without one, capture + search still work.