ai-memory v0.8.0

ai-memory v0.8.0 — integration guide

How to wire ai-memory to any AI — Claude, Cursor, ChatGPT, Continue.dev, generic MCP clients, and even AIs that don’t speak MCP at all. Target audience: same as docs/install-quickstart.md — anyone comfortable in a terminal — plus prosumers and tinkerers who want multiple AIs sharing one memory.

If you haven’t installed yet, do that first: docs/install-quickstart.md.

1. The pattern, in one paragraph

ai-memory exposes itself in three ways: a stdio MCP server (ai-memory mcp), an HTTP/REST daemon (ai-memory serve), and a CLI (ai-memory store / recall / search / ...). The MCP server is how every modern AI client connects, because MCP — the Model Context Protocol — is the industry-standard plug for AI agents to talk to local tools. Any MCP-compatible client points at the binary, ai-memory boots a per-session process, and the AI now has 7 to 99 memory tools at its disposal (depending on the --profile flag). For AIs that don’t speak MCP, the HTTP API covers everything the MCP surface does, plus a few more endpoints (92 route registrations / 78 unique URL paths).

Every recipe below assumes the binary is on your PATH. If ai-memory --version doesn’t print 0.8.0, go back to docs/install-quickstart.md §3.

2. Claude Code (Anthropic)

The fast path is the bundled installer:

ai-memory install claude-code --apply

That writes a SessionStart hook + an MCP server block into ~/.claude/settings.json (and ~/.claude.json), backs up the prior file to <config>.bak.<timestamp>, and is idempotent. Restart Claude Code; the next session boots memory-aware.

If you’d rather do it by hand, edit ~/.claude/mcp.json (or merge into ~/.claude.json if you already use that file). The exact snippet:

{
  "mcpServers": {
    "ai-memory": {
      "command": "ai-memory",
      "args": [
        "--db", "~/.claude/ai-memory.db",
        "mcp",
        "--tier", "semantic"
      ],
      "env": {
        "AI_MEMORY_DB": "${HOME}/.claude/ai-memory.db"
      }
    }
  }
}

For the full SessionStart-hook story (so Claude proactively recalls memory on every conversation start), see docs/integrations/claude-code.md.

--tier semantic is the right default. It uses local sentence-transformer embeddings — no LLM provider key required. The other tiers (keyword / smart / autonomous) are documented in docs/CLI_REFERENCE.md § mcp.

Using --tier smart or --tier autonomous with a non-default LLM backend? Extend the env block above with AI_MEMORY_LLM_BACKEND, AI_MEMORY_LLM_API_KEY, and AI_MEMORY_LLM_MODEL. Do not rely on shell exports — MCP-spawned subprocesses don’t see your interactive shell’s environment (#1144). Copy-pasteable recipes for every supported provider (Ollama, LMStudio, vLLM, llama.cpp server, xAI Grok, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Qwen, Mistral, Groq, Together, Cerebras, OpenRouter, Fireworks): integrations/llm-backends.md.

2a. PreToolUse governance hook (gate every Bash / Edit / Write)

The --apply recipe above installs the SessionStart hook (memory on every session boot). Claude Code also supports a PreToolUse hook that fires before a tool dispatches and can BLOCK it. ai-memory ships a second, independent installer verb that wires this up so every Bash / Edit / Write the model proposes is routed through the substrate rules engine first — refused actions never run:

# Preview (dry-run is the default — writes nothing):
ai-memory install claude-code --hook pretool

# Commit:
ai-memory install claude-code --hook pretool --apply

This is opt-in and orthogonal to the SessionStart hook — install, uninstall, or skip either one independently. The managed entry is scoped with matcher: "Bash|Edit|Write" (the regex also covers MultiEdit / NotebookEdit); Read, WebFetch, and mcp__* tools are not gated.

v0.8.0 form (#1811) — type:command, not type:mcp_tool. The installed entry is a type:command hook that runs ai-memory governance check-action --from-pretool-stdin. The wrapper reads the PreToolUse event off stdin, maps the proposed tool to a substrate action (Bash → bash, Edit/Write → filesystem_write), evaluates the rules engine, and emits the Claude Code decision contract (hookSpecificOutput.permissionDecision) so a Refuse becomes deny and the tool is actually BLOCKED. The earlier type:mcp_tool form could not enforce — per the hooks contract an mcp_tool error is non-blocking and a non-decision tool response is shown as plain text, so the refusal never blocked the call.

Upgrading from a pre-#1811 install? Re-run with --force to replace the old (non-enforcing) managed entry:

ai-memory install claude-code --hook pretool --apply --force

--force is also required if you previously hand-scoped a PreToolUse entry pointing at memory_check_agent_action to a different matcher — the installer refuses to clobber it otherwise.

The rules engine consults the operator-signed substrate rules (ai-memory rules list / ... enable <id> --sign), which ship inert by design — nothing is refused until you sign and enable a rule. To remove the hook: ai-memory install claude-code --hook pretool --uninstall --apply. Full reference, the allow/warn/refuse decision table, and the operator keygen → sign → enable → smoke-test workflow: docs/integrations/claude-code.md §”Substrate rules enforcement on every tool call”.

3. Cursor

ai-memory install cursor --apply

Or by hand — edit ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (project-scoped; project wins for same-named servers):

{
  "mcpServers": {
    "ai-memory": {
      "command": "ai-memory",
      "args": [
        "--db", "~/.claude/ai-memory.db",
        "mcp",
        "--tier", "semantic"
      ],
      "env": {
        "AI_MEMORY_DB": "${HOME}/.claude/ai-memory.db"
      }
    }
  }
}

Restart Cursor. Verify under Settings → Tools & MCP — a green dot next to ai-memory means it’s live. Full recipe (including the project-rules .cursorrules directive that nudges Cursor to recall on session start): docs/integrations/cursor.md. LLM-backend env-block recipe for smart / autonomous tiers: integrations/llm-backends.md.

Cursor has a ~40 tool cap across all MCP servers. Stick to --profile core (the default — 7 tools) unless you really need the full surface.

4. ChatGPT Desktop

State of the world (v0.8.0): ChatGPT Desktop does not currently ship native MCP-client support. The integration paths are (in order of operational simplicity):

Start the daemon:

ai-memory serve --host 127.0.0.1 --port 9077

Then use ChatGPT’s custom GPT actions to call ai-memory over HTTP. Build a custom GPT, add an Action with the OpenAPI schema from docs/API_REFERENCE.md, and point the server URL at your exposed daemon (use a tunnel like Cloudflare Tunnel or Tailscale Funnel if you want it reachable from ChatGPT’s cloud).

The handful of routes you’ll actually call:

# Store a memory
curl -X POST http://127.0.0.1:9077/api/v1/memories \
  -H "Content-Type: application/json" \
  -d '{"title":"Test","content":"Stored from ChatGPT","tier":"mid"}'

# Recall
curl -X POST http://127.0.0.1:9077/api/v1/recall \
  -H "Content-Type: application/json" \
  -d '{"context":"what did I store","limit":5}'

See §7 for the full HTTP-fallback section.

4b. Programmatic via OpenAI SDK

If you drive the OpenAI Apps SDK / Assistants / Responses API yourself, prepend ai-memory boot to the system message of every request. The SDK recipe lives in docs/integrations/openai-apps-sdk.md. There’s also a built-in wrapper: ai-memory wrap openai-cli -- chat --model gpt-4.1 injects the boot context as the system prompt before launching the downstream CLI — no SDK code needed.

4c. Via an MCP-aware ChatGPT CLI

If you’re calling ChatGPT models through any MCP-aware harness (Codex CLI, Continue.dev, Aider), use that harness’s native MCP config. Codex example:

# ~/.codex/config.toml
[mcp_servers.ai-memory]
command = "ai-memory"
args = ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
enabled = true

When native ChatGPT Desktop MCP lands upstream, the recipe is the same shape as Claude Code — point the client at ai-memory mcp.

5. Continue.dev (VS Code / JetBrains)

ai-memory install continue --apply

Or by hand — edit ~/.continue/config.yaml:

mcpServers:
  - name: ai-memory
    command: ai-memory
    args:
      - "--db"
      - "~/.claude/ai-memory.db"
      - "mcp"
      - "--tier"
      - "semantic"
    env:
      AI_MEMORY_DB: "${HOME}/.claude/ai-memory.db"

If you’re on the older config.json schema:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "ai-memory",
          "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
        }
      }
    ]
  }
}

Full recipe (including the systemMessage that nudges Continue to recall on session start): docs/integrations/continue.md.

MCP tools in Continue only work in agent mode, not in chat mode. Switch to agent mode in the Continue side panel.

6. Generic MCP-compatible AI client

If your client speaks MCP but isn’t listed above, the universal pattern is JSON-RPC 2.0 over stdio. Tell the client to launch:

command: ai-memory
args:    ["mcp"]
# optionally:
#   ["--db", "/path/to/ai-memory.db", "mcp", "--tier", "semantic"]
#   ["mcp", "--profile", "full"]  # advertise all 101 tools

That’s it. ai-memory speaks MCP 2024-11-05 protocol, advertises 7 tools by default and up to 100 with --profile full. Per-harness copy-paste recipes live in docs/integrations/: aider, claude-agent-sdk, cline, codex-cli, cody, gemini, goose, grok-and-xai, openclaw, roo-code, windsurf, zed, and local-models (Ollama / llama.cpp / LM Studio / vLLM). See integrations/README.md for the Category-1 (hook-capable) vs. Category-2 (MCP-only) matrix.

7. HTTP API fallback — for clients that don’t speak MCP

ai-memory ships an HTTP/REST daemon with 92 route registrations / 78 unique URL paths covering everything the MCP surface does. Use it for AI clients with no MCP support (most browser-based assistants), custom scripts, multi-host setups, and browser extensions.

ai-memory serve --host 127.0.0.1 --port 9077
curl http://127.0.0.1:9077/api/v1/health  # {"status":"ok"}

Three curl recipes you’ll actually use:

# Store a memory
curl -X POST http://127.0.0.1:9077/api/v1/memories \
  -H "Content-Type: application/json" \
  -d '{"title":"Deploy target","content":"EKS in us-west-2","tier":"long","namespace":"platform"}'

# Recall (semantic + keyword hybrid)
curl -X POST http://127.0.0.1:9077/api/v1/recall \
  -H "Content-Type: application/json" \
  -d '{"context":"what is our deploy target","namespace":"platform","limit":5}'

# Check whether an action would be governance-allowed (v0.7.0 7th-form)
curl -X POST http://127.0.0.1:9077/api/v1/memory_check_agent_action \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"ai:gpt-5@my-laptop","action":"store","namespace":"platform","content":"test"}'

Production hardening:

Full HTTP surface: docs/API_REFERENCE.md.

8. Multi-AI setup — one ai-memory, many clients

You can wire Claude Code + Cursor + Continue.dev + Codex CLI to the same memory at the same time. They all read and write a single SQLite database. The pattern:

  1. Pick a canonical DB path that’s stable on this host (e.g. ~/.claude/ai-memory.db).

  2. Export it in your shell profile so every AI client picks it up the same way:

    # ~/.zshrc or ~/.bashrc
export AI_MEMORY_DB="${HOME}/.claude/ai-memory.db"
  3. In each AI client’s MCP config, pass the same path explicitly (the snippets in §§2–6 already do this with "--db", "~/.claude/ai-memory.db").

Concurrent access notes: SQLite WAL mode handles many readers

Optional but recommended: run the curator daemon in the background to keep the corpus tidy across the swarm of AIs.

ai-memory curator --daemon

It de-duplicates, tags, and consolidates across whatever every client has been writing. Runs hourly by default.

9. A2A (agent-to-agent) basics

ai-memory can act as a shared substrate for multiple AI agents that need to coordinate — not just per-host but across hosts. The shorthand stack:

That’s the one-paragraph version. For the full deep dive — peer allowlist, quorum rules, vector-clock CRDT merge, agent-to-agent approval flow, and the recommended deployment topologies — see docs/enterprise-deployment.md.

10. Security defaults

ai-memory v0.8.0 ships with secure defaults already on. You do not have to configure these to get them. Worth knowing about:

The trust + audit story works without operator action. This posture is opinionated on purpose.

See also