ML and LLM Dependencies (semantic tier+)

• candle-core, candle-nn, candle-transformers -- Hugging Face Candle ML framework for native Rust inference
• hf-hub -- download models from Hugging Face Hub
• tokenizers -- Hugging Face tokenizers for text preprocessing
• instant-distance -- approximate nearest neighbor search
• reqwest -- HTTP client for LLM-backend communication (smart/autonomous tiers — any provider per #1067: Ollama, xAI, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Qwen, Mistral, Groq, Together, Cerebras, OpenRouter, Fireworks, LMStudio, vLLM, llama.cpp server)

---

Choose your installation path

Configuring the LLM backend (xAI Grok, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Qwen, Mistral, Groq, Together, Cerebras, OpenRouter, Fireworks, LMStudio, vLLM, llama.cpp server, or local Ollama)? See docs/integrations/llm-backends.md — the MCP env-block recipe is the same regardless of installation path.

---

v0.7.0 (attested-cortex) rolls together the cortex-fluent legibility work with the full v0.7 trust + A2A scope from ROADMAP §7.3, plus (per operator directive 2026-05-09) the originally-v0.7.1 postgres+AGE first-class work, plus the post-grand-slam ship-readiness wave (Batman Forms 1-6 + 7th-form Option-B foundation + QW-1/2/3 + reconciliation security sweep). The substrate becomes both more articulate (capabilities v3, named loader tools, compacted schemas, Batman MemoryKind vocabulary, persona/atomisation/multistep-ingest primitives) and cryptographically trustworthy (Ed25519 attestation, sidechain transcripts, programmable 25-event hook pipeline, enforced namespace inheritance, V-4 cross-row signed-events hash chain). v0.7.0 also ships postgres + Apache AGE as a first-class storage backend — ai-memory serve --store-url postgres://… for live daemon use, schema parity across both backends (sqlite + postgres converge on logical schema v57 — CURRENT_SCHEMA_VERSION = 57 (canonical anchors: src/storage/migrations.rs for sqlite + src/store/postgres.rs for postgres); on-disk migration files end at migrations/sqlite/0047_v56_list_composite_indexes.sql and the postgres in-process migrate_v57() ladder arm (file-name counters lag the logical schema version because both ladders apply post-v34 deltas via in-process arms — see docs/MIGRATION_v0.7.md §schema-ladder for the v35-v57 narrative; v48 #933 added the federation-push DLQ table; v49 #1025 added 14 nullable columns to archived_memories so archive → restore is lossless for the full v0.7.0 Memory shape; v50 #1156 extended agent_quotas PRIMARY KEY from (agent_id) to (agent_id, namespace) so per-namespace K8 quota allotments hold even when a single agent operates across many namespaces — pre-v50 rows backfill to the _global sentinel namespace; v51 #1255 (PR #1296) added the federation_nonce_cache table so peer-replay-prevention nonces persist across daemon restarts; v52 #1389 added the transcript_line_dedup table backing RFC-0001 memory_capture_turn L4 + recover_from_transcript L2 idempotency so a SIGKILL between turns never produces a duplicate memory on subsequent rehydration; v53 #1418 scoped the memories_au FTS5 sync trigger to (title, content, tags) only so non-FTS column updates no longer fire a needless sync; v54 #1466 backfilled tier-default expiry onto legacy NULL-expiry mid/short rows to close the TTL-leak immortal-rows class; v55 #1476 made the W=2 federation-catchup query (updated_at > ? ORDER BY updated_at ASC LIMIT) sargable and added the sqlite idx_memories_updated_at index — postgres adds no new index because memories_updated_at_idx DESC already serves the range scan via Index Scan Backward; v56 #1579 added the composite list/archive ordering indexes (idx_memories_list_order, idx_memories_ns_list_order, idx_archived_ns_archived_at) paired with the sargable storage::list rewrite — sqlite-side DDL; the postgres migrate_v56() arm is a version-stamp no-op; v57 #1579 added the postgres stored generated tsv tsvector column + memories_tsv_gin GIN index so the search/recall shapes match AND rank on the precomputed column instead of re-computing the tsvector per matched row — the legacy memories_content_fts expression index is dropped and the sqlite twin is a version-stamp no-op because FTS5 already materialises the indexed text)), the new ai-memory schema-init CLI verb, and 6-factor recall scoring parity. The v0.6.4 default surface grows by two always-on loaders to 7 tools (memory_load_family + memory_smart_load join the original five); the runtime ceiling at --profile full is 74 advertised entries (73 callable memory tools + the always-on memory_capabilities bootstrap; verified against Profile::full().expected_tool_count() — see src/profile.rs). Everything new is additive and (for the trust + postgres surfaces) opt-in. Upgrading from v0.6.x? Read docs/MIGRATION_v0.7.md first — most v0.6.4 callers see no behavior change, but pre-v0.6.3.1 v0.6.x users hit the G1 namespace-inheritance fix. Switching to postgres+AGE? See docs/postgres-age-guide.md and docs/migration-v0.7.0-postgres.md. Full release notes: docs/v0.7.0/release-notes.md.

v0.6.4 (quiet-tools) — the MCP server ships with a 5-tool default surface (memory_store, memory_recall, memory_list, memory_get, memory_search) plus the always-on memory_capabilities bootstrap. The other 38 tools remain reachable via --profile graph|admin|power|full or runtime expansion through memory_capabilities --include-schema family=<name>. Eager-loading harnesses (Claude Desktop / Codex CLI / Grok CLI / Gemini CLI) drop ~4,700 input tokens of tool schemas per request — a 76.4% reduction measured against cl100k_base BPE. To preserve v0.6.3 behavior 1:1, run ai-memory mcp --profile full. See docs/MIGRATION_v0.6.4.md.

Install in 60 Seconds

Pre-built binaries require no dependencies. Building from source needs Rust and a C compiler.

Fastest: Pre-built binary (no Rust required)

```bash

Quickstart

Get from zero to a working memory in under two minutes.

1. Install

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

2. Configure MCP (example for Claude Code -- other platforms work the same way)

Merge into ~/.claude.json:

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

3. Store your first memory

ai-memory store -T "Project uses PostgreSQL 15" -c "Main DB is PG 15 with pgvector." --tier long

4. Recall it

ai-memory recall "database"

5. Check stats

ai-memory stats

6. Use with your AI. Restart your AI client. It now has 7 default memory tools advertised on boot (74 advertised entries reachable via runtime expansion or --profile full at v0.7.0) over MCP -- it can store and recall memories natively during conversations.

---

~/.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 (NOT the literal key)

Export `XAI_API_KEY` in your shell rc (`.zshrc` / `.bashrc`); the MCP config stays minimal:

Verify: `ai-memory boot --quiet --limit 1` should report `llm=xai:grok-4.3`. Canonical schema reference: [`docs/CONFIG_SCHEMA.md`](docs/CONFIG_SCHEMA.md).

> **Override path — `env:` block.** Adding an `env:` block to the MCP config with `AI_MEMORY_LLM_BACKEND` / `_API_KEY` / `_MODEL` still works and takes precedence over `config.toml` — useful for CI / per-session tweaks:
>
> 

>
> MCP clients spawn the server as a fresh subprocess with only the `env:` keys from the MCP config — shell exports in `.zshrc` / `.bashrc` don't reach it. The `[llm]` config-file path above retires this paper-cut (every surface reads the same file). **Inline API keys in `config.toml` are rejected at parse time** — use `api_key_env` or `api_key_file`. Background: [#1144](https://github.com/alphaonedev/ai-memory-mcp/issues/1144) → [#1146](https://github.com/alphaonedev/ai-memory-mcp/issues/1146). Full per-backend recipes: [`docs/integrations/llm-backends.md`](docs/integrations/llm-backends.md).

> **Windows paths:** Use forward slashes or escaped backslashes in `--db`. Example: `"--db", "C:/Users/YourName/.claude/ai-memory.db"`.

> **Tier flag:** The `--tier` flag selects the feature tier: `keyword`, `semantic` (default), `smart`, or `autonomous`. Smart and autonomous tiers need an LLM backend — **post-[#1067](https://github.com/alphaonedev/ai-memory-mcp/issues/1067) (v0.7.0)** that is any of: local [Ollama](https://ollama.com), xAI Grok, OpenAI, Anthropic, Google Gemini, DeepSeek, Kimi (Moonshot), Qwen (Alibaba), Mistral, Groq, Together AI, Cerebras, OpenRouter, Fireworks, LMStudio, vLLM, or llama.cpp server — selected via `AI_MEMORY_LLM_BACKEND`. The `--tier` flag **must** be passed in the args — the `config.toml` tier setting is not used when the MCP server is launched by an AI client.

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

**Make Claude proactively use ai-memory:** Add a `CLAUDE.md` file to your project root with ai-memory directives. This ensures Claude recalls context at the start of every conversation and stores findings as it works. See the [CLAUDE.md integration guide](CLAUDE.md#using-claudemd-in-your-projects) for a copy-paste template and placement options.

</details>

<details>
<summary><strong>OpenAI Codex CLI</strong></summary>

Add to `~/.codex/config.toml` (global) or `.codex/config.toml` (project). Windows: `%USERPROFILE%\.codex\config.toml`. Override with `CODEX_HOME` env var.

Or add via CLI: `codex mcp add memory -- ai-memory --db ~/.local/share/ai-memory/memories.db mcp --tier semantic`

> **Notes:** Codex uses TOML format with underscored key `mcp_servers` (not camelCase, not hyphenated). Supports `env` (key/value pairs), `env_vars` (list to forward), `enabled_tools`, `disabled_tools`, `startup_timeout_sec`, `tool_timeout_sec`. Use `/mcp` in the TUI to view server status. See [Codex MCP docs](https://developers.openai.com/codex/mcp).

</details>

<details>
<summary><strong>Google Gemini CLI</strong></summary>

Add to `~/.gemini/settings.json` (user) or `.gemini/settings.json` (project). Windows: `%USERPROFILE%\.gemini\settings.json`.

Or add via CLI: `gemini mcp add memory ai-memory -- --db ~/.local/share/ai-memory/memories.db mcp --tier semantic`

> **Notes:** Avoid underscores in server names (use hyphens). Tool names are auto-prefixed as `mcp_memory_<toolName>`. Env vars in the `env` field support `$VAR` / `${VAR}` (all platforms) and `%VAR%` (Windows). Gemini sanitizes sensitive patterns from inherited env unless explicitly declared. Add `"trust": true` to skip confirmation prompts. CLI management: `gemini mcp list/remove/enable/disable`. See [Gemini CLI MCP docs](https://geminicli.com/docs/tools/mcp-server/).

</details>

<details>
<summary><strong>Cursor IDE</strong></summary>

Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project). Windows: `%USERPROFILE%\.cursor\mcp.json`. Project config overrides global for same-named servers.

> **Notes:** Restart Cursor after editing `mcp.json`. Verify server status in Settings > Tools & MCP (green dot = connected). Supports `env`, `envFile`, and `${env:VAR_NAME}` interpolation (env var interpolation can be unreliable for shell profile variables — use `envFile` as workaround). **~40 tool limit** across all MCP servers. See [Cursor MCP docs](https://cursor.com/docs/context/mcp).

</details>

<details>
<summary><strong>Windsurf</strong> (Codeium)</summary>

Add to `~/.codeium/windsurf/mcp_config.json` (global only — no project-level scope). Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`.

> **Notes:** Supports `${env:VAR_NAME}` interpolation in `command`, `args`, `env`, `serverUrl`, `url`, and `headers`. **100 tool limit** across all MCP servers. Can also add via MCP Marketplace or Settings > Cascade > MCP Servers. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp).

</details>

<details>
<summary><strong>Continue.dev</strong></summary>

Add to `~/.continue/config.yaml` (user) or `.continue/mcpServers/` directory in project root (per-server YAML/JSON files). Windows: `%USERPROFILE%\.continue\config.yaml`.

> **Notes:** MCP tools only work in agent mode. Supports `${{ secrets.SECRET_NAME }}` for secret interpolation. Project-level `.continue/mcpServers/` directory auto-detects JSON configs from other tools (Claude Code, Cursor, etc.). See [Continue MCP docs](https://docs.continue.dev/customize/deep-dives/mcp).

</details>

<details>
<summary><strong>Grok CLI</strong> (AlphaOne fork — deep integration with auto-recall)</summary>

The [AlphaOne fork of grok-cli](https://github.com/alphaonedev/grok-cli) has built-in ai-memory support with session-scoped MCP connections, automatic memory recall on session start, compaction summary storage, and memory-aware system prompts.

Add to `~/.grok/user-settings.json`:

> **Features:** Auto-recall on session start (injects relevant memories into system prompt), compaction summaries stored as mid-tier memories, MCP tools available in all modes (agent, plan, ask), session-scoped connections (no per-message cold starts). Uses `--tier semantic` by default (local embeddings, no LLM backend required). See [grok-cli docs](https://github.com/alphaonedev/grok-cli/blob/main/docs/CONFIGURATION.md) for full setup.

</details>

<details>
<summary><strong>xAI Grok API</strong> (API-level, remote MCP)</summary>

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

89 REST route registrations (75 unique URL paths) at http://127.0.0.1:9077/api/v1/

```

</details>

Step 4: Done. Test it.

Restart your AI assistant. If using MCP, it now has the 7-tool default surface advertised on session boot (the original 5 + memory_load_family + memory_smart_load; the other 66 of the 73 callable tools load on demand via --profile or memory_capabilities --include-schema). Ask it: "Store a memory that my favorite language is Rust." Then in a new conversation, ask: "What is my favorite language?" It will remember.

---

SDKs

In addition to the MCP / HTTP / CLI surfaces, ai-memory ships first-party language SDKs for HTTP clients and helper utilities (e.g. requireProfile for runtime profile assertions on v0.6.4+ daemons).

TypeScript / JavaScript — @alphaone/ai-memory on npm

npm install @alphaone/ai-memory

Python — ai-memory-mcp on PyPI (the import name remains ai_memory)

pip install ai-memory-mcp

from ai_memory import AiMemoryClient, require_profile

with AiMemoryClient(base_url="http://127.0.0.1:9077", api_key="...") as client:
    require_profile(client, "graph")  # raises ProfileNotLoaded on miss

Both SDKs are versioned with the server (0.6.4 matches ai-memory 0.6.4). v0.6.4+ daemons enforce the profile contract; pre-v0.6.4 daemons fall back to a permissive warn-and-continue so SDK upgrades don't break old servers. Source lives in sdk/typescript/ and sdk/python/.

---

Interfaces

• 89 HTTP routes (75 unique paths) -- full REST API on 127.0.0.1:9077 (works with any AI or tool)
• 82 CLI subcommands at v0.7.x under --features sal OR --features sal-postgres (80 in the default build) -- complete CLI with identical capabilities
• 74 MCP tools at full profile (7 default at v0.7.0; verified against Profile::full().expected_tool_count()) -- native integration for any MCP-compatible AI
• Interactive REPL shell -- recall, search, list, get, stats, namespaces, delete with color output
• JSON output -- --json flag on all CLI commands

Integration Methods