This directory documents how to wire ai-memory into every AI agent so the
first turn of every session sees relevant memory context, with no manual
prompt from the user. It is the user-facing remediation for issue
#487 (cold-start
sessions don’t auto-load memory).
Every recipe in this directory invokes the same CLI:
ai-memory boot \
--namespace "<inferred-or-explicit>" \
--limit 10 \
--budget-tokens 4096 \
--format text \
--quiet
ai-memory boot is read-only, fast (no embedder, no daemon, indexed list
only), and graceful by default. With --quiet, a missing or unreachable
DB still exits 0 — a misconfigured agent never wedges its first turn —
but a status header always appears on stdout so the agent (and the
human running it) can see whether boot fired and why context might be
missing. See ai-memory boot --help for the full surface.
Every invocation emits a transparent multi-field manifest (per #487 addendum, PR-4): agents and humans always know exactly what’s loaded and what’s configured.
# ai-memory boot: ok
# version: 0.8.0
# db: /home/u/.claude/ai-memory.db (schema=v78, 161 memories)
# tier: autonomous (embedder=nomic-ai/nomic-embed-text-v1.5, reranker=ms-marco-MiniLM-L-6-v2, llm=gemma3:4b)
# latency: 12ms
# namespace: ai-memory-mcp/v0.8.0-release (loaded 3 memories)
DOC-4 (med/low review batch) — example version + schema bumped to match the current v0.9.0 substrate (
CURRENT_SCHEMA_VERSION = 78). The pre-v0.7.0 example showed v0.6.3 / schema v19, which was many migrations behind the substrate and major releases behind the daemon binary integrators land on today.
The four status variants share the same manifest shape; only the first
line’s status word and the namespace: line’s parenthetical change:
| Status | First line | namespace: line |
|---|---|---|
| Happy path | # ai-memory boot: ok |
(loaded N memories) |
| Namespace empty, fell back | # ai-memory boot: info |
(fallback: loaded N memories from global Long tier) |
| First-run / greenfield | # ai-memory boot: info |
(empty — nothing to load; this is normal on a fresh install) |
| DB unavailable | # ai-memory boot: warn |
(db unavailable — see ai-memory doctor) |
In the warn variant, db: reports <unavailable> for schema and
the live-memories count, while version, tier, and latency still
surface — the manifest never disappears, only what depends on a live
DB is sentinelled.
If no manifest appears at all, the integration recipe didn’t
fire the hook — the agent host either skipped the hook, the binary isn’t
on $PATH, or the recipe is misconfigured. This absence is itself a
diagnostic: silent vs. “warn” vs. “ok” tell the user three different
failure modes apart.
--no-header is supported but should NOT be used in production hooks —
suppressing the header makes silent failure indistinguishable from “no
memories yet.”
The output body (after the manifest, when memories are loaded) is one of three formats:
text (default) — human-readable bulleted list. Works in any agent’s
system message. Easiest to scan.json — single object containing every manifest field as a top-level
key (status, version, db_path, schema_version, total_memories,
tier, embedder, reranker, llm, latency_ms, namespace,
count, note, memories, fell_back_to_global) for programmatic
ingest (Claude Agent SDK, OpenAI Apps SDK, Codex CLI prepend).toon — the canonical token-efficient memory format, byte-identical
to a memory_recall MCP response.| Category | Agent host has… | How memory gets loaded on first turn | Example agents |
|---|---|---|---|
| 1. Hook-capable | A documented session-start hook the user can configure | Hook runs ai-memory boot; stdout is injected as additional context. 100% reliable. |
Claude Code |
| 2. MCP-capable, no hook | An MCP client and a project-rules / system-prompt file but no session-start hook | ai-memory-mcp registered as an MCP server plus a one-line directive in the agent’s rules file telling the model to call memory_session_start first. Best-effort (text-directive subject to model compliance). |
Cursor, Cline, Continue, Windsurf, OpenClaw |
| 3. Programmatic only | An SDK or raw API where the developer assembles each request | Application code uses the SDK pattern (prepends ai-memory boot output to the system message). For the launcher case (just spawn a CLI), ai-memory wrap <agent> is the cross-platform Rust replacement for the bash / PowerShell wrappers earlier PRs shipped — it runs the same code path on macOS / Linux / Windows / Docker / Kubernetes. 100% reliable when implemented. |
Codex CLI, Claude Agent SDK, OpenAI Apps SDK / Assistants API / Responses API, Grok via xAI API, Hermes / local models via LM Studio / Ollama / vLLM |
The bar for “100% remediated” is: every supported agent has a recipe that loads memory on the first turn without user prompting. Categories 1 and 3 hit that bar today; category 2 is best-effort until upstream agents grow a proper session-start hook (see issue #487 cross-files).
ai-memory wrap (PR-6)PR-6 of issue #487 ships ai-memory wrap <agent>: a built-in
cross-platform Rust subcommand that replaces the per-recipe bash and
PowerShell wrappers earlier PRs shipped. The same binary runs on
macOS / Linux / Windows / Docker / Kubernetes — no shell required.
ai-memory wrap:
ai-memory boot in-process (no subprocess).<preamble>\n\n<boot output>.Spawns the named agent CLI with the system message delivered via
the strategy chosen by default_strategy(<agent>):
| Agent | Strategy | Argv shape |
|---|---|---|
codex / codex-cli |
SystemFlag |
codex --system "<msg>" <args> |
gemini |
SystemFlag |
gemini --system "<msg>" <args> |
aider |
MessageFile |
aider --message-file <tempfile> <args> |
ollama |
SystemEnv |
OLLAMA_SYSTEM=<msg> ollama <args> |
| (anything else) | SystemFlag (--system) |
fall-through default |
Override the strategy with --system-flag <flag>, --system-env <name>,
or --message-file-flag <flag> if your agent uses a different
contract. See ai-memory wrap --help for the full surface.
The category-3 recipes (codex-cli.md,
claude-agent-sdk.md,
openai-apps-sdk.md,
grok-and-xai.md,
local-models.md) all link to ai-memory wrap for
the launcher case and keep the SDK code patterns for in-process
integrations.
The Installer column tracks ai-memory install <agent> support
(issue #487 PR-2). yes means a one-line ai-memory install <agent>
--apply writes the recipe’s MCP / hook config block directly. Where
the column reads yes (--config), the agent’s canonical config path
isn’t auto-discoverable yet — pass --config <path> explicitly. no
means the agent isn’t yet a target for the installer (PR-2 follow-up
will extend); use the manual recipe in the meantime. n/a is
programmatic SDK / API code that the installer cannot wire — see the
recipe’s snippets and ai-memory wrap <agent> (PR-6).
| File | Agent | Category | Installer | Status |
|---|---|---|---|---|
claude-code.md |
Claude Code (CLI, Mac/Win desktop, IDE) | 1 (2 hooks: SessionStart boot + PreToolUse governance) | yes | reference recipe |
cursor.md |
Cursor | 2 (MCP + rules) | yes | recipe |
cline.md |
Cline (VS Code extension) | 2 (MCP + custom instructions) | yes (–config) | recipe |
roo-code.md |
Roo Code (Cline fork) | 2 (MCP + custom instructions) | no (PR-2 follow-up) | recipe |
continue.md |
Continue (VS Code / JetBrains) | 2 (MCP + systemMessage) | yes | recipe |
windsurf.md |
Windsurf (Codeium) | 2 (MCP + rules) | yes | recipe |
zed.md |
Zed assistant | 2 (MCP + assistant directive) | no (PR-2 follow-up) | recipe |
goose.md |
Block Goose | 2 (MCP + system instructions) | no (PR-2 follow-up) | recipe |
openclaw.md |
OpenClaw CLI | 2 (MCP + system message) | yes (–config) | recipe |
codex-cli.md |
OpenAI Codex CLI | 3 (programmatic) | n/a (programmatic) | recipe |
gemini.md |
Google Gemini CLI / Gemini Code Assist | 3 (programmatic) | n/a (programmatic) | recipe |
aider.md |
Aider | 3 (programmatic via --message-file) |
n/a (programmatic) | recipe |
cody.md |
Sourcegraph Cody | 3 (programmatic) | n/a (programmatic) | recipe |
claude-agent-sdk.md |
Claude Agent SDK | 3 (programmatic) | n/a (programmatic) | recipe (TS + Python) |
openai-apps-sdk.md |
OpenAI Apps SDK / Assistants / Responses | 3 (programmatic) | n/a (programmatic) | recipe |
grok-and-xai.md |
xAI Grok | 3 (programmatic) | n/a (programmatic) | recipe |
grok-build.md |
xAI Grok Build / Grok Shell (grok CLI) |
1+2 hybrid (MCP stdio + session-boot hooks + permission gates) | yes (–config) | reference recipe |
local-models.md |
Hermes, Llama, Mistral, etc. via LM Studio / Ollama / vLLM | 3 (programmatic) | n/a (programmatic) | recipe |
platforms.md |
macOS / Linux / Windows / WSL / Docker / Kubernetes / ARM Linux / commercial Unix / embedded Linux / BSD platform notes | n/a | n/a | reference |
networking.md |
macOS + Tailscale / VPN per-app intercept gotchas (#704) and tailnet-IP workarounds | n/a | n/a | reference |
global-claude-md-template.md |
~/.claude/CLAUDE.md belt-and-suspenders snippet |
1 fallback | n/a | reference |
v0.6.4-system-prompt-snippet.md |
v0.6.4 discovery-aware NHI bootstrap (drop-in for any harness) | n/a | n/a | reference |
llm-backends.md |
Per-backend MCP env: block recipes (Ollama, LMStudio, xAI, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Qwen, Mistral, Groq, Together, Cerebras, OpenRouter, Fireworks, vLLM, llama.cpp). Closes #1144 (operator paper-cut: shell env doesn’t reach MCP subprocesses). |
n/a | n/a | reference |
mobile.md |
Consumer-signs-at-integration discipline for iOS + Android release artifacts (#1247 / PR #1283); xcframework + jniLibs layout, code-signing handoff to the consuming app, mobile-runtime CI subset. | n/a | n/a | reference |
--quiet to the boot call. Hook/wrapper exits 0,
agent starts with no extra context (graceful degrade, no hang).auto_namespace falls back to cwd basename → “global”.
If still empty, boot returns the most-recently-accessed tier=long
memories globally so a greenfield checkout still has cross-project
context.--budget-tokens (default 4096) clamps the row
count cheaply (cumulative chars / 4 ≈ tokens).[boot] enabled = false to silence
boot entirely (empty stdout + empty stderr, exit 0 — the hook injects
nothing), or [boot] redact_titles = true to keep the manifest but
hide memory subjects (title → <redacted>, every other field —
namespace, tier, id_short, priority, age — still surfaces). The env
var AI_MEMORY_BOOT_ENABLED=0 overrides the config-file value. See
claude-code.md §Privacy / disable
for the full table.schema_supported: bool as a top-level key so SIEMs can alert when a
host’s ai-memory binary version-drifts away from its DB. The text
variant surfaces a # ai-memory boot: warn — db schema vN unsupported
by binary X.Y.Z (supports v16..v19) header directly.bash doesn’t run on native
Windows, embedded BusyBox ash, or inside a Kubernetes sidecar with
no shell. See
platforms.md for per-platform notes —
including the Kubernetes HTTP boot equivalent
for clusters where stdio recipes don’t apply, and
ARM Linux / embedded
resource budgets for low-memory devices.platforms.md for what CI actually exercises vs. what’s
documented best-effort.After installing any recipe, prove it works with the cold-start test:
what do you remember?If step 4 fails on a recipe that claims category 1 or 3, that recipe has a bug and the fix lands in this directory.
Category 2 agents (Cursor, Cline, Roo Code, Continue, Windsurf, Zed, Goose, OpenClaw) all need native session-start hooks to reach 100% remediation. Cross-files tracking those upstream requests live in #487’s comments.
The MCP spec proposal at
modelcontextprotocol/specification for a session/initialize server
callback is the universal architectural fix. Once accepted, it closes
category 2 entirely without per-host work.