Session-boot integrations — agent matrix

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).

The universal primitive

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.

End-user diagnostic — always-visible manifest header

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 = 81). 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:

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.

Three integration categories

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).

Category 3 — 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:

1. Calls ai-memory boot in-process (no subprocess).
2. Builds a system message of the form <preamble>\n\n<boot output>.

3. 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

4. Propagates the agent’s exit code.

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.

Per-agent recipes

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).

Failure modes (any recipe)

• DB unreachable: pass --quiet to the boot call. Hook/wrapper exits 0, agent starts with no extra context (graceful degrade, no hang).
• Wrong namespace: 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.
• Hook output too large: --budget-tokens (default 4096) clamps the row count cheaply (cumulative chars / 4 ≈ tokens).
• Privacy-sensitive deployment: set [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 drift across a fleet: from v0.6.3.1 the JSON manifest exposes 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.
• Platform mismatch: a recipe written for 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.
• CI gap: not every supported platform is in the GitHub Actions matrix. See the Lifetime test matrix in platforms.md for what CI actually exercises vs. what’s documented best-effort.

Verifying a recipe

After installing any recipe, prove it works with the cold-start test:

1. Quit the agent completely.
2. Open a fresh window in a directory other than the ai-memory project root (this catches recipes that depend on project-local config — they should work everywhere or not be billed as “100%”).
3. Send the agent a single first message: what do you remember?
4. The agent should respond with concrete recalled context (titles, namespaces, ages) without you having to type “access your memories” first.

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.

Cross-org follow-ups

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.