Installation Guide

Choose your path before you start — installation differs by audience and deployment scale.

I am…	My deployment is…	Start here
A single developer	One AI client (Claude Code / Cursor / ChatGPT / etc.) on one laptop	install-quickstart.md — 5-minute super-simple install + LLM-backend wired in one config block. Skip the rest of this file.
An engineer / architect	Multi-agent on one node, or any single-node production deployment	This file (full singleton reference) → production-deployment.md — 10-min hardening checklist.
An engineer / architect	Multi-server, multi-rack, multi-DC, multi-region, swarm, or hive	enterprise-deployment.md — 60–90 min planning artefact covering 8 topologies, federation, identity material at fleet scale, disaster recovery.
An engineer / architect	PostgreSQL + Apache AGE storage backend (multi-tenant, multi-writer, 10M+ memories, KG-heavy workloads)	postgres-age-guide.md — first-class postgres operator guide.
A decision-maker	Evaluating ai-memory for adoption	audience/decision-maker.html — security posture, threat model, deployment cost envelope.

This file (INSTALL.md) is the SME singleton + single-node reference. Path-A non-technical readers should use install-quickstart.md instead — it covers configuration end-to-end without exposing every flag.

BLUF (Bottom Line Up Front): ai-memory is an AI-agnostic memory management system that works with any MCP-compatible AI client – including Claude AI, OpenAI ChatGPT, xAI Grok, META Llama, OpenClaw, and others. Install the binary, configure your AI client’s MCP settings, and you get 7 MCP memory tools at the default --profile core (or 101 advertised entries at --profile full — 100 callable memory tools + the always-on memory_capabilities bootstrap). The default semantic tier includes embedding-based hybrid recall out of the box. Total time: ~60 seconds (pre-built binary + fast internet; first semantic-tier run also downloads a ~100MB embedding model).

Install in 60 Seconds (pre-built binary + fast internet)

1. Install the binary (pick one):

   One-liner (pre-built binary, Linux/macOS):

   curl -fsSL https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.sh | sh
   

   Windows (PowerShell):

   irm https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.ps1 | iex
   

   Cargo (crates.io):

   cargo install ai-memory
   

   Homebrew (macOS + Linux):

   brew install alphaonedev/tap/ai-memory
   

   cargo-binstall (pre-built, no compile):

   cargo binstall ai-memory
   

   Ubuntu/Debian (.deb manual install):

   # Download from https://github.com/alphaonedev/ai-memory-mcp/releases/latest
   sudo dpkg -i ai-memory_0.7.0_amd64.deb   # or arm64
   

   Fedora/RHEL (COPR — recommended):

   sudo dnf copr enable alpha-one-ai/ai-memory
   sudo dnf install ai-memory
   

   Fedora/RHEL (.rpm manual install):

   # Download from https://github.com/alphaonedev/ai-memory-mcp/releases/latest
   sudo rpm -i ai-memory-0.7.0-1.x86_64.rpm    # or aarch64
   

   Arch Linux (AUR — v0.7.0 Gap #3 / issue #804):

   # via your favourite AUR helper (paru / yay / aurutils):
   paru -S ai-memory
   # or build from the in-repo PKGBUILD:
   git clone https://github.com/alphaonedev/ai-memory-mcp.git
   cd ai-memory-mcp/packaging/aur
   makepkg -si
   

   The PKGBUILD lives at packaging/aur/PKGBUILD and is reviewable in the source tree. The submitted AUR slot is ai-memory (operator ownership; upstream submission tracked in #804).

   Docker:

   docker build -t ai-memory https://github.com/alphaonedev/ai-memory-mcp.git
   docker run -p 9077:9077 -v data:/data ai-memory
   

   From source (requires Rust + C compiler):

   cargo install --git https://github.com/alphaonedev/ai-memory-mcp.git
   

   Version pinning (v0.7.0 Gap #3 / issue #804)

   For production deployments, pin to an exact version. The substrate honours semver discipline (0.7.x series stays backward-compatible; 0.8.0 will land schema bumps and new tools). The supported pin syntax per channel:

   Channel	Pin syntax
   Cargo	cargo install ai-memory --version =0.7.1 --locked
   cargo-binstall	cargo binstall ai-memory --version 0.7.1
   Homebrew	The tap publishes a single rolling Formula/ai-memory.rb (no versioned @0.7.0 formula). Pin by installing the desired release, then brew pin ai-memory to block upgrades.
   COPR	sudo dnf install ai-memory-0.7.1-1.fc40
   .deb / .rpm	Download the 0.7.0 artifact from the GH Release; pin by filename.
   AUR	AUR helpers build the latest PKGBUILD; pin by checking out the package at the 0.7.0-1 revision and makepkg -si, or hold with IgnorePkg = ai-memory in pacman.conf.
   Docker	docker pull ghcr.io/alphaonedev/ai-memory:0.7.1 (digest pin is even safer: @sha256:…).

   In CI, prefer the cargo-binstall + --version form so the version appears in your build manifest and reproducibility is trivial.

2. Configure MCP in your AI client. The example below is for Claude Code — add the mcpServers key to ~/.claude.json (user scope, applies to all projects):

   macOS / Linux — semantic tier (default; no LLM backend needed):

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

   Windows (in %USERPROFILE%\.claude.json):

   {
     "mcpServers": {
       "memory": {
         "command": "ai-memory",
         "args": ["--db", "C:/Users/YourName/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
       }
     }
   }
   

   smart / autonomous tier with a cloud LLM backend (xAI Grok shown; same shape for OpenAI / Anthropic / Gemini / DeepSeek / Kimi / Qwen / Mistral / Groq / Together / Cerebras / OpenRouter / Fireworks / LMStudio / vLLM / llama.cpp server):

   Recommended path — [llm] section in ~/.config/ai-memory/config.toml (#1146)

   Write the backend, model, and an env-var name pointing at your API key into the canonical config file. Every surface — MCP server, HTTP daemon, ai-memory atomise, ai-memory curator, the boot banner, and the ai-memory doctor reachability probe — reads the same file, so the boot banner and the live MCP server agree on the backend.

   # ~/.config/ai-memory/config.toml
   schema_version = 2
   
   tier = "autonomous"
   db   = "~/.claude/ai-memory.db"
   
   [llm]
   backend     = "xai"                    # ollama | openai | xai | anthropic | gemini |
                                          # deepseek | kimi | qwen | mistral | groq |
                                          # together | cerebras | openrouter |
                                          # fireworks | lmstudio | vllm | openai-compatible
   model       = "grok-4.3"               # vendor-specific identifier
   base_url    = "https://api.x.ai/v1"   # optional; vendor-default if unset
   api_key_env = "XAI_API_KEY"            # process-env-var name (NOT the literal key)
   # api_key_file = "/etc/ai-memory/keys/xai.key"   # mode 0400 enforced; alt to api_key_env
   

   Then keep the MCP config minimal — no env: block needed:

   {
     "mcpServers": {
       "memory": {
         "command": "ai-memory",
         "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "autonomous"]
       }
     }
   }
   

   Export XAI_API_KEY in your shell rc (.zshrc / .bashrc / .profile) so the parent process inherits it; the MCP-spawned subprocess inherits from the AI client which inherits from your login shell. Inline keys in config.toml are rejected at parse time — use api_key_env (process-env reference) or api_key_file (file path; mode 0400 enforced).

   Service-manager daemons don’t inherit shell-rc exports. The above works for an MCP server spawned by your AI client. A serve or curator --daemon started by launchd (macOS) or systemd (Linux) does NOT see a key you export from .zshrc/.bashrc — its env comes only from the unit/plist. For those, prefer api_key_file (env-independent across platforms) or declare the key inside the unit’s Environment= / plist EnvironmentVariables dict. See production-deployment.md § 7b.

   Full canonical schema reference: CONFIG_SCHEMA.md.

   Override path — env: block in the MCP config

   Pre-#1146 operators wired LLM config via the env: block of the AI client’s MCP config. This still works and takes precedence over config.toml, but it’s the override layer now — useful for CI / per-session tweaks, not the primary path.

   {
     "mcpServers": {
       "memory": {
         "command": "ai-memory",
         "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "autonomous"],
         "env": {
           "AI_MEMORY_LLM_BACKEND": "xai",
           "AI_MEMORY_LLM_API_KEY": "xai-...",
           "AI_MEMORY_LLM_MODEL": "grok-4.3"
         }
       }
     }
   }
   

   Important — MCP clients do NOT inherit your interactive shell. Setting export AI_MEMORY_LLM_BACKEND=xai in .zshrc / .bashrc is sufficient for the standalone ai-memory CLI and the HTTP daemon, but is NOT sufficient for Claude Code / Cursor / Codex / Cline / Continue / Zed / Windsurf / etc. — they spawn the MCP server as a fresh subprocess with only the env: keys from the MCP config. The recommended path above (a [llm] section in config.toml with api_key_env) avoids this paper-cut by letting every surface read the same file. Background: #1144 (env-block paper-cut) and #1146 (single source of truth). Full per-backend recipes (every supported provider with copy-pasteable snippets): integrations/llm-backends.md.

   Note: ~/.claude.json likely already exists with other settings. Merge the mcpServers key into the existing JSON — do not overwrite the file. See Claude Code MCP Scopes below for project-level and team-shared alternatives.

   ~ in --db args. The binary uses a CLI --db value verbatim — tilde expansion happens in your shell (or in some MCP hosts), NOT inside ai-memory. Only a db = "~/..." line in config.toml is tilde-expanded by ai-memory itself (#507). If memories land in a literal ./~ directory, replace ~/.claude/ai-memory.db in the args with the absolute path (e.g. /Users/you/.claude/ai-memory.db) or move the path into config.toml.

   The --tier flag selects the feature tier: keyword, semantic (default), smart, or autonomous. Important: The --tier flag must be passed in the MCP args — the config.toml tier setting is not used when the server is launched by an AI client. Smart and autonomous tiers require an LLM backend — post-#1067 (v0.7.0), any of: local Ollama, LMStudio, vLLM, llama.cpp server, OR any OpenAI-compatible vendor (xAI Grok, OpenAI, Anthropic, Google Gemini, DeepSeek, Kimi, Qwen, Mistral, Groq, Together, Cerebras, OpenRouter, Fireworks). Selected via AI_MEMORY_LLM_BACKEND env var. Full env-var matrix in ADMIN_GUIDE.md § “LLM Backend Setup”; MCP-config recipes in integrations/llm-backends.md. Other AI platforms (OpenAI ChatGPT, xAI Grok, META Llama, etc.) have their own MCP configuration locations. Consult your platform’s documentation for where to add MCP server entries. The server command and args are the same — only the config file location differs.

3. Restart your AI client.

   Verify the LLM backend wired through (smart/autonomous tier only). After restart, check the ai-memory boot banner that prints on first MCP session-start (or the AI client’s MCP server stderr log). You should see LLM ready (backend=<vendor>, model=<name>, …) matching what you put in the env: block, plus an embedder loaded (…) line reflecting the independently-resolved [embeddings] configuration (#1598 — the embedder can be local Ollama or any API backend; the historical (#1143) dedicated-Ollama embed-client banner was superseded at this boot site). If you see llm=gemma3:4b or another local Ollama tag when you intended a cloud backend, the env: block didn’t land — re-check the MCP config path you edited matches the AI client’s actual scope. Full troubleshooting: TROUBLESHOOTING.md § LLM backend silently fell back.

4. Verify — at the default --profile core (v0.7.0) you should see 7 new tools registered plus the always-on memory_capabilities bootstrap (8 total): memory_store, memory_recall, memory_search, memory_list, memory_get, memory_load_family, memory_smart_load. To eagerly load the full surface (101 advertised entries — 100 callable memory tools + the always-on memory_capabilities bootstrap), launch with ai-memory mcp --profile full. The full-profile surface includes (highlights): memory_update, memory_delete, memory_promote, memory_forget, memory_stats, memory_link, memory_get_links, memory_consolidate, memory_expand_query, memory_auto_tag, memory_detect_contradiction, the 4 archive tools, memory_check_duplicate, the 2 entity tools, the 3 KG tools (memory_kg_query/memory_kg_timeline/memory_kg_invalidate), memory_get_taxonomy, the 3 namespace-standard tools, the 3 pending-action tools, the 2 agent tools, memory_notify/memory_inbox, the 3 subscription tools, memory_session_start, memory_gc, and the v0.7 additions: memory_reflect, memory_atomise, memory_ingest_multistep, memory_persona, memory_persona_generate, memory_offload, memory_deref, memory_calibrate_confidence, the 7 L1-5 Agent Skills tools, memory_check_agent_action, memory_rule_list, memory_export_reflection, memory_reflection_origin, memory_dependents_of_invalidated, memory_find_paths, memory_verify, memory_quota_status, the archive-list metadata helpers (#860), and more. Full per-tool reference: API_REFERENCE.md. Run memory_capabilities from the agent loop to get the live family list.

5. Test – ask your AI assistant to store a memory. It should use memory_store automatically.

6. Disable built-in auto-memory (recommended). ai-memory replaces built-in memory systems with zero-token-cost on-demand recall. Built-in systems load your entire memory into every message, burning tokens and money. Disable them:

   Claude Code (Desktop or CLI): Add to ~/.claude/settings.json:

   {
     "autoMemoryEnabled": false
   }
   

   ChatGPT: Settings > Personalization > Memory > turn off (ai-memory replaces it via MCP/HTTP)

   This stops the built-in system from injecting 200+ lines of memory context into every conversation. ai-memory uses zero tokens until memory_recall is called – only relevant memories are returned, ranked by score.

7. Token savings are automatic. All recall, search, and list responses use TOON compact format by default – eliminating 40-60% of repeated field-name tokens vs JSON. The MCP server also provides recall-first and memory-workflow prompts that teach AI clients to use memory proactively.

That’s it. Everything below is optional detail.

Prerequisites

Pre-built binaries have no prerequisites – just run install.sh or install.ps1 as shown above. The requirements below only apply when building from source.

• Rust toolchain (1.96+; rust-version in Cargo.toml): Install via rustup

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  

• C compiler: Required for the candle ML backend and bundled SQLite:
  • Ubuntu/Debian: sudo apt-get install build-essential pkg-config
  • Fedora/RHEL: sudo dnf install gcc pkg-config
  • macOS: Xcode command line tools (xcode-select --install) – usually already present
  • Windows: MSVC C++ build tools via Visual Studio Installer (select “Desktop development with C++”)

Install from Source (One-Liner)

For the postgres + Apache AGE storage backend, append --features sal,sal-postgres to the cargo install command (adds the migrate + schema-init CLI subcommands and the ai-memory serve --store-url postgres://… daemon path).

cargo install --git https://github.com/alphaonedev/ai-memory-mcp.git

This builds a release binary and places it in ~/.cargo/bin/ai-memory.

Or clone and build locally:

git clone https://github.com/alphaonedev/ai-memory-mcp.git
cd ai-memory
cargo install --path .

Pre-built Binaries

Pre-built binaries are available on the Releases page for five targets: Linux (x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu), macOS (x86_64-apple-darwin, aarch64-apple-darwin), and Windows (x86_64-pc-windows-msvc, zipped). Releases are created on git tags. Note the pre-built binaries are default-feature builds — the migrate / schema-init subcommands and the postgres --store-url daemon path require a --features sal,sal-postgres source build.

The easiest way to install is via the install scripts:

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.ps1 | iex

Or download and install manually:

tar xzf ai-memory-x86_64-unknown-linux-gnu.tar.gz
chmod +x ai-memory
sudo mv ai-memory /usr/local/bin/

Platform Notes

• macOS Gatekeeper: Pre-built binaries downloaded outside the App Store may be quarantined. If you get “cannot be opened because the developer cannot be verified”, run:

  xattr -d com.apple.quarantine ~/.cargo/bin/ai-memory
  # or wherever the binary was installed:
  xattr -d com.apple.quarantine /usr/local/bin/ai-memory
  

• Windows: Use the PowerShell install script (install.ps1) for pre-built binaries. For building from source, use cargo install with the MSVC toolchain (the default Rust target on Windows). MinGW is not supported.

• WSL (Windows Subsystem for Linux): Works as native Linux. Follow the Ubuntu/Debian instructions for both pre-built binaries and building from source.

• Docker: A Dockerfile is included in the repository root. Build and run:

  docker build -t ai-memory .
  docker run --rm -v ai-memory-data:/data ai-memory --db /data/ai-memory.db serve
  

Network Requirements

• First run with semantic tier (or above): Downloads a ~100MB embedding model from HuggingFace. No account or API key is required. The model is cached in ~/.cache/huggingface/ for subsequent runs. After the initial download, no network access is needed for keyword or semantic tiers.
• Smart/autonomous tiers: Require an LLM backend. Post-#1067 (v0.7.0) any of 15 OpenAI-compatible vendors (xAI, OpenAI, Anthropic, Gemini, DeepSeek, Kimi/Moonshot, Qwen/DashScope, Mistral, Groq, Together, Cerebras, OpenRouter, Fireworks, LMStudio) or local Ollama works — selected via AI_MEMORY_LLM_BACKEND. Local Ollama is the default for zero-network installs; cloud backends require their respective API key.

Disk Space

MCP Server Setup (Recommended)

The primary integration path is the MCP tool server. MCP (Model Context Protocol) is an open standard – ai-memory works with any MCP-compatible AI client, including Claude AI, OpenAI ChatGPT, xAI Grok, META Llama, OpenClaw, and others.

Step 1: Add MCP configuration

Each AI platform has its own MCP configuration location. The server command and arguments are identical across all platforms.

Claude Code MCP Configuration Scopes

Claude Code supports three scopes for MCP server configuration. Pick the one that matches your use case:

Scope precedence: Local > Project > User. A server defined in a narrower scope overrides a same-named server from a broader scope.

Important: MCP servers are not configured in settings.json or settings.local.json — those files do not support mcpServers.

User scope (recommended — available in every project):

Merge the mcpServers key into your existing ~/.claude.json:

Note: ~/.claude.json likely already exists with other Claude Code settings (tips, projects, etc.). Add the mcpServers key at the top level of the existing JSON object — do not overwrite the file.

Adding an LLM backend (smart/autonomous tiers). Extend the memory server block with an env map containing 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 (see #1144). Copy-pasteable recipes for every supported provider live in integrations/llm-backends.md.

Project scope (shared with your team via git):

Create .mcp.json in your project root:

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

Claude Code prompts for approval before using project-scoped MCP servers from .mcp.json files.

Local scope (one project, private):

Add an mcpServers entry under the project path in ~/.claude.json:

{
  "projects": {
    "/Users/you/my-project": {
      "mcpServers": {
        "memory": {
          "command": "ai-memory",
          "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "smart"]
        }
      }
    }
  }
}

Database Path by Platform

Use forward slashes in JSON args on all platforms: "C:/Users/YourName/.claude/ai-memory.db". The AI_MEMORY_DB environment variable can also be used to set the database path globally.

OpenAI Codex CLI

Override config directory with the CODEX_HOME environment variable.

[mcp_servers.memory]
command = "ai-memory"
args = ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
enabled = true

Or add via CLI:

codex mcp add memory -- ai-memory --db ~/.local/share/ai-memory/memories.db mcp --tier semantic

Notes for Codex CLI: Codex uses TOML format with underscored key mcp_servers (not camelCase, not hyphenated — this is critical). Additional supported options include env (explicit key/value pairs), env_vars (list of env vars to forward), cwd, startup_timeout_sec, tool_timeout_sec, enabled_tools (restrict which memory tools are exposed), and disabled_tools. Use /mcp in the TUI to view server status. Codex also supports HTTP-based MCP servers via url and bearer_token_env_var. See Codex MCP docs.

Windows: Use %USERPROFILE%\.codex\config.toml. WSL uses the Linux home directory by default — set CODEX_HOME to share config with the Windows host.

Google Gemini CLI

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"],
      "timeout": 30000
    }
  }
}

Or add via CLI:

gemini mcp add memory ai-memory -- --db ~/.local/share/ai-memory/memories.db mcp --tier semantic

Notes for Gemini CLI: Avoid underscores in server names (use hyphens). Tool names are auto-prefixed as mcp_<serverName>_<toolName>. Environment variables in the env field support $VAR / ${VAR} syntax (all platforms) and %VAR% (Windows only) — undefined variables resolve to empty strings. Gemini sanitizes sensitive patterns (*TOKEN*, *SECRET*, *PASSWORD*) from the inherited environment unless explicitly declared. Add "trust": true to skip tool confirmation prompts. Additional supported options include cwd, includeTools, excludeTools, url (SSE), and httpUrl (HTTP). CLI management: gemini mcp list, gemini mcp remove, gemini mcp enable/disable. See Gemini CLI MCP docs.

Cursor IDE

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
    }
  }
}

Or add via Cursor Settings > Tools & MCP.

Notes for Cursor: Restart Cursor (or reload window) after editing mcp.json. Verify server status in Settings > Tools & MCP (green dot = connected). Supports env field for environment variables, envFile for .env files, and ${env:VAR_NAME} interpolation in config values (note: env var interpolation can be unreliable for shell profile variables — use envFile with a .env file as a workaround). Also supports url + headers for remote HTTP/SSE servers. ~40 tool limit across all MCP servers combined. See Cursor MCP docs.

Windsurf (Codeium)

No project-level scope. Windsurf uses global configuration only.

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
    }
  }
}

Notes for Windsurf: Supports ${env:VAR_NAME} interpolation in command, args, env, serverUrl, url, and headers fields. Also supports disabled (boolean) and alwaysAllow (list of tool names) per server. 100 tool limit across all MCP servers. Can also add servers via MCP Marketplace or Windsurf Settings > Cascade > MCP Servers. See Windsurf MCP docs.

Continue.dev

mcpServers:
  - name: memory
    command: ai-memory
    args:
      - "--db"
      - "~/.local/share/ai-memory/memories.db"
      - "mcp"
      - "--tier"
      - "semantic"

Notes for Continue.dev: Uses YAML list format. MCP tools only work in agent mode. Supports ${{ secrets.SECRET_NAME }} syntax for secret interpolation via Continue’s secrets system. Project-level config uses the .continue/mcpServers/ directory — drop individual YAML or JSON config files there (JSON configs from Claude Code, Cursor, etc. are auto-detected). See Continue MCP docs.

xAI Grok (API-level, remote MCP)

Grok connects to MCP servers over HTTPS (remote only, no stdio). No config file — servers are specified per API request.

Start ai-memory as an HTTP server behind HTTPS:

ai-memory serve --host 127.0.0.1 --port 9077
# Expose via HTTPS reverse proxy (nginx, caddy, cloudflare tunnel, etc.)

Then add the MCP server to your Grok API call:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "tools": [{
      "type": "mcp",
      "server_url": "https://your-server.example.com/mcp",
      "server_label": "memory",
      "server_description": "Persistent AI memory with recall and search",
      "allowed_tools": ["memory_store", "memory_recall", "memory_search"]
    }],
    "input": "What do you remember about our project?"
  }'

Requirements: HTTPS required. server_label is required. Supports Streamable HTTP and SSE transports. Optional parameters: allowed_tools / allowed_tool_names (restrict tools), authorization (bearer token), headers / extra_headers (custom HTTP headers). Works with the xAI native SDK, OpenAI-compatible Responses API, and Voice Agent API. See xAI Remote MCP docs.

META Llama (via Llama Stack)

No standardized config file path — configuration is deployment-specific. Two approaches:

Option A: Python/Node.js SDK (programmatic):

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

client.toolgroups.register(
    provider_id="model-context-protocol",
    toolgroup_id="mcp::memory",
    mcp_endpoint={"uri": "http://localhost:9077/sse"}
)

Option B: run.yaml (declarative):

providers:
  tool_runtime:
    - provider_id: model-context-protocol
      provider_type: remote::model-context-protocol
      config: {}

tool_groups:
  - toolgroup_id: mcp::memory
    provider_id: model-context-protocol
    mcp_endpoint:
      uri: "http://localhost:9077/sse"

Notes for Llama Stack: Supports ${env.VARIABLE_NAME} syntax for environment variable interpolation in run.yaml. Transport is migrating from SSE to Streamable HTTP as the primary protocol. See Llama Stack Tools docs.

OpenClaw

Important: OpenClaw uses mcp.servers (NOT mcpServers). The key structure is different from most other platforms.

{
  "mcp": {
    "servers": {
      "memory": {
        "command": "ai-memory",
        "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
      }
    }
  }
}

Or add via CLI:

openclaw mcp set memory '{"command":"ai-memory","args":["--db","~/.local/share/ai-memory/memories.db","mcp","--tier","semantic"]}'

Notes for OpenClaw: Uses mcp.servers key (not camelCase mcpServers — this is critical). CLI management: openclaw mcp list, openclaw mcp show <name>, openclaw mcp unset <name>. See OpenClaw MCP docs.

Nous Research Hermes Agent

Important: Hermes uses mcp_servers (underscored YAML key, NOT camelCase mcpServers).

Stdio (local):

mcp_servers:
  memory:
    command: ai-memory
    args:
      - "--db"
      - "~/.local/share/ai-memory/memories.db"
      - "mcp"
      - "--tier"
      - "semantic"

HTTP (remote — requires ai-memory running as HTTP daemon):

mcp_servers:
  memory:
    url: "http://localhost:9077/mcp"

With tool filtering (restrict to core tools):

mcp_servers:
  memory:
    command: ai-memory
    args: ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
    tools:
      include:
        - memory_store
        - memory_recall
        - memory_search
        - memory_list
        - memory_get

Notes for Hermes Agent: Uses YAML format with underscored mcp_servers key. Supports both stdio (local subprocess) and HTTP (remote endpoint) transports. Per-server tool filtering via tools.include/tools.exclude. Additional supported fields: env (environment variables), timeout (tool call timeout), connect_timeout (connection timeout), enabled (boolean), sampling (LLM inference config). See Hermes MCP docs.

If ai-memory is not in your PATH, use the full path to the binary in any of the configurations above:

{
  "mcpServers": {
    "memory": {
      "command": "/usr/local/bin/ai-memory",
      "args": ["--db", "/var/lib/ai-memory/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}

Step 2: Verify

Restart your AI client. With --profile core (default at v0.7.0) you should see 7 tools available (memory_store, memory_recall, memory_search, memory_list, memory_get, memory_load_family, memory_smart_load) plus the always-on memory_capabilities bootstrap. With --profile full you get all 101 advertised entries (100 callable memory tools + memory_capabilities). Other profiles: graph (18 tools), admin (21 tools), power (56 tools). The full advertised inventory is asserted by Profile::full().expected_tool_count() = 101 in src/profile.rs; the canonical surface list lives in docs/USER_GUIDE.md.

Step 3: Test

Ask your AI assistant to store a memory. It should use the memory_store tool automatically.

Hook Installation (Optional, Claude Code-Specific)

The SessionStart hook auto-recalls relevant memories at the start of each Claude Code session. Other AI platforms may have their own hook/plugin mechanisms – the CLI commands used in this hook work with any platform.

Recommended — one command

ai-memory install claude-code            # dry-run (default) — prints what would change
ai-memory install claude-code --apply    # actually write the file

This writes a managed SessionStart entry into ~/.claude/settings.json running ai-memory boot --quiet --limit 10 --budget-tokens 4096 on every fresh session. Re-running is idempotent; ai-memory install claude-code --uninstall --apply removes the managed entry surgically.

Manual alternative — hooks/session-start.sh

# Copy the hook
cp hooks/session-start.sh ~/.claude/hooks/

# Make it executable
chmod +x ~/.claude/hooks/session-start.sh

Then configure it under the SessionStart event in ~/.claude/settings.json (note the nested hooks array shape Claude Code expects):

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/session-start.sh" }
        ]
      }
    ]
  }
}

Environment variables for the hook

Systemd Service Setup (HTTP Daemon)

If you want to run the HTTP daemon as a background service (alternative to MCP). The HTTP API at localhost:9077 works with any AI platform, framework, or tool – no MCP required:

sudo tee /etc/systemd/system/ai-memory.service > /dev/null << 'EOF'
[Unit]
Description=AI Memory Daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/ai-memory --db /var/lib/ai-memory/ai-memory.db serve
Restart=on-failure
RestartSec=5
Environment=RUST_LOG=ai_memory=info

# Graceful shutdown checkpoints the WAL
KillSignal=SIGINT
TimeoutStopSec=10

[Install]
WantedBy=multi-user.target
EOF

Create the data directory and enable the service:

sudo mkdir -p /var/lib/ai-memory
sudo systemctl daemon-reload
sudo systemctl enable --now ai-memory

Verify Installation

# Check the binary
ai-memory --help

# v0.7.x — comprehensive health check (Storage / Index / Recall /
# Governance / Sync / Webhook / Capabilities / Reflection Health /
# LLM Reachability (#1146) + Embeddings Reachability (#1598)).
# 10-section operator-visible dashboard.
ai-memory doctor

# If running as MCP server, test manually:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ai-memory mcp
# Expected: JSON-RPC response with serverInfo

# If running as HTTP daemon, check health:
curl http://127.0.0.1:9077/api/v1/health
# Expected: {"status":"ok","service":"ai-memory"}

# Store a test memory via CLI
ai-memory store -T "Installation test" -c "It works." --tier short

# Recall it
ai-memory recall "installation"

Post-install: migrate from v0.6.x (if upgrading)

If you’re upgrading from v0.6.x, run the one-shot config migrator to rewrite ~/.config/ai-memory/config.toml from the legacy flat-field shape (llm_model, ollama_url, embed_url, embedding_model, cross_encoder, default_namespace, …) into the v0.7.x sectioned schema ([llm], [llm.auto_tag], [embeddings], [reranker], [storage]):

# 1. Preview the rewrite (no writes)
ai-memory config migrate --dry-run

# 2. Apply with a timestamped .bak backup
ai-memory config migrate

# 3. (Optional, opt-in) — also strip the now-redundant
#    mcpServers.<*>.env block from ~/.claude.json (only entries
#    whose `command` resolves to ai-memory are touched)
ai-memory config migrate --also-clean-claude-json

# 4. Verify wiring end-to-end
ai-memory doctor

The migrator is idempotent — running against an already-v2 file is a no-op INFO log. Legacy v0.6.x flat fields continue to work in v0.7.x with a single-line deprecation WARN at load time; they will be removed in v0.8.0.

The DB schema migration is automatic — the daemon walks v20 → v55 on first open of an existing v0.6.4 DB (writing an automatic <db>.pre-migration-v<from>-to-v<to>-<token>.bak snapshot first). No operator action required.

For a comprehensive walkthrough (security-posture defaults that changed, tiered admin / DevOps recipes, NFS-shared config fleets), see docs/MIGRATION_QUICKSTART.md.

Man Page

Generate and install the man page:

# View immediately
ai-memory man | man -l -

# Install system-wide
ai-memory man | sudo tee /usr/local/share/man/man1/ai-memory.1 > /dev/null
sudo mandb
man ai-memory

Shell Completions

Generate completions for your shell:

# Bash
ai-memory completions bash > ~/.local/share/bash-completion/completions/ai-memory

# Zsh
ai-memory completions zsh > ~/.zfunc/_ai-memory
# Then add to ~/.zshrc: fpath+=~/.zfunc && autoload -Uz compinit && compinit

# Fish
ai-memory completions fish > ~/.config/fish/completions/ai-memory.fish

LLM Backend Setup (Smart & Autonomous Tiers)

Smart and autonomous tiers require an LLM backend. Post-#1067 + #1146 (v0.7.0) the backend is provider-agnostic — pick from:

• Local LLM: Ollama, LMStudio, vLLM, or llama.cpp server (any OpenAI-compatible local endpoint).
• Cloud LLM: xAI Grok, OpenAI, Anthropic (via OpenAI shim), Google Gemini, DeepSeek, Kimi (Moonshot), Qwen (Alibaba), Mistral, Groq, Together AI, Cerebras, OpenRouter, Fireworks.

The keyword and semantic tiers do not require any LLM backend.

Recommended path — [llm] section in config.toml

Single source of truth — every surface (MCP, HTTP daemon, CLI, boot banner, doctor probe) reads the same file. Example for xAI Grok 4.3:

# ~/.config/ai-memory/config.toml
schema_version = 2

[llm]
backend     = "xai"
model       = "grok-4.3"
base_url    = "https://api.x.ai/v1"
api_key_env = "XAI_API_KEY"                       # process-env-var name
# api_key_file = "/etc/ai-memory/keys/xai.key"    # alt — mode 0400 enforced

Export XAI_API_KEY in the parent shell (.zshrc / .bashrc / .profile) so the daemon and MCP-spawned subprocess inherit it. Inline keys in config.toml are rejected at parse time.

Verify end-to-end:

ai-memory boot --quiet --limit 1   # banner should report llm=xai:grok-4.3
ai-memory doctor                    # LLM Reachability (#1146) — DNS + TLS + auth round-trip

Canonical schema reference: CONFIG_SCHEMA.md. Full operator runbook (per-vendor recipes, precedence ladder, secret-handling discipline): ADMIN_GUIDE.md § “LLM Backend Setup”.

Override path — env vars

AI_MEMORY_LLM_BACKEND / _MODEL / _BASE_URL / _API_KEY env vars take precedence over [llm] in config.toml. Useful for CI / per-session tweaks, and the only path that doesn’t require editing a file. Per-vendor recipes: integrations/llm-backends.md.

Ollama (local LLM — v0.6.4 default, still supported)

Below is the canonical local-Ollama install path. For other backends, write the [llm] section per the recipe above (or set env vars as the override path).

macOS

# Install via Homebrew
brew install ollama

# Or download directly from https://ollama.com/download/mac
# Drag Ollama.app to Applications

# Start Ollama (runs as a background service)
ollama serve &

# Pull the model for your tier
ollama pull gemma3:4b     # Default LLM model for ai-memory (~3 GB) — handles smart-tier auto-tag + contradict + query expansion
ollama pull nomic-embed-text:v1.5  # Default embedder (~280 MB) — semantic + autonomous tiers

Linux

# One-line install script
curl -fsSL https://ollama.com/install.sh | sh

# Start the service
sudo systemctl enable ollama
sudo systemctl start ollama

# Or run manually
ollama serve &

# Pull the model for your tier
ollama pull gemma3:4b     # Default LLM model for ai-memory (~3 GB) — handles smart-tier auto-tag + contradict + query expansion
ollama pull nomic-embed-text:v1.5  # Default embedder (~280 MB) — semantic + autonomous tiers

Windows

# Download installer from https://ollama.com/download/windows
# Run OllamaSetup.exe — installs and starts as a background service

# Or install via winget
winget install Ollama.Ollama

# Pull the model (in PowerShell or Command Prompt)
ollama pull gemma3:4b     # Default LLM model for ai-memory (~3 GB) — handles smart-tier auto-tag + contradict + query expansion
ollama pull nomic-embed-text:v1.5  # Default embedder (~280 MB) — semantic + autonomous tiers

Verify Ollama is Running

# Check Ollama status
curl http://localhost:11434/api/tags

# Test the model
ollama run gemma3:4b "Hello, world"

Configure ai-memory for Smart/Autonomous Tier

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "smart"]
    }
  }
}

ai-memory connects to Ollama at http://localhost:11434 automatically. No additional configuration needed. If Ollama is not running, LLM-backed features degrade gracefully (the semantic-tier embedder + keyword recall keep working). Post-#1598 the embedder itself can also be pointed at an API backend instead of Ollama — see [embeddings] in CONFIG_SCHEMA.md.

Note: The semantic tier (default) downloads a HuggingFace embedding model (~100 MB) on first startup. No account or API key is required. The model is cached in ~/.cache/huggingface/.

Multi-Node Sync Setup

If you use ai-memory on multiple machines (e.g., laptop and server), you can sync databases:

# Pull memories from a remote database (e.g., over NFS, sshfs, or rsync'd copy)
ai-memory sync /mnt/server/ai-memory.db --direction pull

# Push local memories to remote
ai-memory sync /mnt/server/ai-memory.db --direction push

# Bidirectional merge (both sides get all memories, dedup-safe)
ai-memory sync /mnt/server/ai-memory.db --direction merge

The sync operation uses the same dedup-safe upsert as regular stores – title+namespace conflicts are resolved by keeping the higher priority and never downgrading tier.

Uninstall

# Stop and remove the service (if using systemd)
sudo systemctl stop ai-memory
sudo systemctl disable ai-memory
sudo rm /etc/systemd/system/ai-memory.service
sudo systemctl daemon-reload

# Remove MCP configuration from ~/.claude.json (delete the "mcpServers" key)
# Or remove .mcp.json from your project root if using project scope

# Remove the binary
cargo uninstall ai-memory
# or: sudo rm /usr/local/bin/ai-memory

# Remove the database (WARNING: deletes all memories)
rm -f ai-memory.db ai-memory.db-wal ai-memory.db-shm
# or if using the systemd path:
# sudo rm -rf /var/lib/ai-memory

Environment Variables

TTL and Archive Configuration

Memory TTLs (time-to-live) can be customized per tier via config.toml. When garbage collection runs, expired memories can optionally be archived instead of permanently deleted by setting archive_on_gc = true. Archived memories can be listed, restored, or purged using the 4 archive tools (memory_archive_list, memory_archive_restore, memory_archive_purge, memory_archive_stats). See the Admin Guide for full configuration details.

Note: Configuration is loaded once at process startup. Changes to config.toml require restarting the ai-memory process (MCP server, HTTP daemon, or CLI) to take effect.

Setting environment variables by platform:

macOS / Linux (add to ~/.bashrc, ~/.zshrc, or equivalent):

export AI_MEMORY_DB="$HOME/.claude/ai-memory.db"

Windows (PowerShell — persistent for current user):

[Environment]::SetEnvironmentVariable("AI_MEMORY_DB", "$env:USERPROFILE\.claude\ai-memory.db", "User")

Windows (Command Prompt — persistent):

setx AI_MEMORY_DB "%USERPROFILE%\.claude\ai-memory.db"