Skip to content

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.md
index 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 every
supported 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 touching
purge/rename/backup/restore/reset/reindex/restore-page.
- [`docs/auto-improvement-loop.md`](docs/auto-improvement-loop.md) —
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 pipeline
diff --git a/README.md b/README.md
index 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.md
new file mode 100644
index 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.