io.github.alphaonedev/ai-memory
Persistent memory for any AI — zero token cost until recall
Open source Open in the app JSON README (API)
About
Persistent memory for any AI — zero token cost until recall
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- alphaonedev
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.5.1
- Stars
- 48
- Forks
- 6
- Open pull requests
- 4
- Last push
- 2026-09-08T02:19:35Z
- Repository state
- ativo
- Language
- Rust
- License
- Apache-2.0
- Added
- 2026-08-29 03:02:24
- Updated
- 2026-08-29 03:02:24
- Origin id
io.github.alphaonedev/ai-memory
README
<p align="center">
<img src="docs/ai-memory-logo.jpg" alt="ai-memory logo" width="200">
</p>
<h1 align="center">ai-memory™</h1>
<p align="center"><em>universal AI memory</em></p>
[](https://github.com/alphaonedev/ai-memory-mcp/actions/workflows/ci.yml)
[](https://github.com/alphaonedev/ai-memory-mcp/actions/workflows/bench.yml)
[](https://github.com/alphaonedev/ai-memory-mcp/actions/workflows/session-boot-lifetime.yml)
[](https://www.rust-lang.org/)
[](LICENSE)
[](https://www.sqlite.org/)
[](https://alphaonedev.github.io/ai-memory-mcp/evidence.html)
[](https://alphaonedev.github.io/ai-memory-test-hub/)
[](https://alphaonedev.github.io/ai-memory-discovery-gate/)
[](https://github.com/alphaonedev/ai-memory-test-hub/blob/main/campaigns/v0.6.4.md)
[]()
[](https://alphaonedev.github.io/ai-memory-mcp/compliance/nsa-csi-mcp.html)
[](https://alphaonedev.github.io/ai-memory-mcp/evidence.html)
[](docs/v0.7.0/release-notes.md)
[](https://crates.io/crates/ai-memory)
[](https://www.npmjs.com/package/@alphaone/ai-memory)
[](https://pypi.org/project/ai-memory-mcp/)
**ai-memory is a persistent memory system for AI assistants.** It works with **any AI that supports MCP** -- Claude, ChatGPT, Grok, Llama, and more. It stores what your AI learns in a local SQLite database, ranks memories by relevance when recalling, and auto-promotes important knowledge to permanent storage. Install it once, and every AI assistant you use remembers your architecture, your preferences, your corrections -- forever.
---
### Choose your installation path
| You are… | Your deployment is… | Start here |
|---|---|---|
| **A single developer** trying ai-memory | One AI client on a laptop | [`docs/install-quickstart.md`](docs/install-quickstart.md) — 5-min super-simple install + LLM-backend wired in one block |
| **An engineer / architect** | Single-node production, or multiple agents on one node | [`docs/INSTALL.md`](docs/INSTALL.md) → [`docs/production-deployment.md`](docs/production-deployment.md) |
| **An engineer / architect** | Multi-server / multi-rack / multi-DC / swarm / hive / federation | [`docs/enterprise-deployment.md`](docs/enterprise-deployment.md) — 8 topologies, singleton → multi-region |
| **An engineer / architect** | PostgreSQL + Apache AGE storage (multi-writer, 10M+ memories, KG-heavy) | [`docs/postgres-age-guide.md`](docs/postgres-age-guide.md) — first-class postgres operator guide |
| **A decision-maker** evaluating adoption | — | [`docs/audience/decision-maker.html`](https://alphaonedev.github.io/ai-memory-mcp/audience/decision-maker.html) |
> 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`](docs/integrations/llm-backends.md) — the MCP env-block recipe is the same regardless of installation path.
---
**v0.9.0 — current release.** A security-hardening and code-review release: 49 fixes from a 5-lane adversarial review ([#1885](https://github.com/alphaonedev/ai-memory-mcp/issues/1885)–[#1935](https://github.com/alphaonedev/ai-memory-mcp/issues/1935)) plus a smaller set of additive features. The headline change is a secure-default flip: **agent attestation is required by default on HTTP direct-write** ([#1751](https://github.com/alphaonedev/ai-memory-mcp/issues/1751), surface-scoped by [#1985](https://github.com/alphaonedev/ai-memory-mcp/issues/1985)) — an unsigned HTTP `POST /api/v1/memories` (+`/bulk`) is **rejected** (`403 ATTESTATION_FAILED`) instead of landing `attest_level="claimed"`, unless the operator sets the explicit opt-out `AI_MEMORY_REQUIRE_AGENT_ATTESTATION=0`. The MCP `memory_store` and CLI `store` surfaces are the operator-as-actor path and stay permissive by default (an unsigned write lands `claimed`); `=1` forces strict on every surface. (The v0.9.0 GA shipped this as require-*everywhere*, which was unsatisfiable on MCP hosts — corrected to surface-scoped in the current release.) Alongside it, the mandatory-hook-presence **enforcement gate now fires on both the MCP write path** ([#1885](https://github.com/alphaonedev/ai-memory-mcp/issues/1885)) **and the HTTP write path** ([#1924](https://github.com/alphaonedev/ai-memory-mcp/issues/1924)), closing a silent-bypass gap where a configured mandatory hook could be skipped on one surface but not the other. The hardening pass also closes `bulk_create` per-row attestation gating ([#1919](https://github.com/alphaonedev/ai-memory-mcp/issues/1919)), routes inbound federated PENDING approvals through the registered-approver gate ([#1920](https://github.com/alphaonedev/ai-memory-mcp/issues/1920)), tightens `team`/`unit`/`org` visibility scope so it is no longer over-broad across the namespace hierarchy ([#1921](https://github.com/alphaonedev/ai-memory-mcp/issues/1921)), and confines `skill_register`'s `folder_path` import under the configured root with a symlink jail ([#1923](https://github.com/alphaonedev/ai-memory-mcp/issues/1923)). A new non-argv credential channel — `AI_MEMORY_STORE_URL` / `AI_MEMORY_STORE_URL_FILE` (a `0600` file) — keeps the postgres/store password off world-readable `/proc/<pid>/cmdline` and `ps` ([#1927](https://github.com/alphaonedev/ai-memory-mcp/issues/1927)). Additive feature work: agent-authored **skill memories** with a `parameters_schema` + `invocation_record` (B7-SKILL, [#1865](https://github.com/alphaonedev/ai-memory-mcp/issues/1865)), the `recall_observations` shadow-feedback loop ([#1706](https://github.com/alphaonedev/ai-memory-mcp/issues/1706)), a **memory-derivation lineage DAG** (`memory_lineage`, [#1859](https://github.com/alphaonedev/ai-memory-mcp/issues/1859)), and an opt-in **vector-search** minimal slice ([#1005](https://github.com/alphaonedev/ai-memory-mcp/issues/1005)). Surface: schema **v78**, **101** MCP tools at `--profile full` (100 callable + the always-on `memory_capabilities` bootstrap) / **7** at `--profile core`, **92** HTTP route registrations (78 unique URL paths), **89** CLI subcommands under `--features sal`/`sal-postgres` (**87** in the default build), **9** typed `MemoryLink` relations, a **28-field** `Memory`. Runs on **two production backends behind one identical API — embedded SQLite and PostgreSQL + Apache AGE** — across desktop, server, and on-device (iOS + Android). Everything is additive over v0.8.1 except the attestation and hook-enforcement flips, which are secure-by-default breaking changes — review them before upgrading. **Full changelog:** [`CHANGELOG.md`](CHANGELOG.md) §"[0.9.0] — 2026-07-08".
**v0.8.0 (`distributed-coordination`) — prior release.** This is the release where the memory substrate becomes a **coordination substrate**. It adds the distributed-coordination machinery from [#1709](https://github.com/alphaonedev/ai-memory-mcp/issues/1709): a typed **action DAG** with a real state machine (`memory_action_*`), TTL-bounded single-holder **leases** (`memory_lease_*`), Ed25519-**signed signals** (`memory_signal_*`), Ed25519-**attested checkpoints** (`memory_checkpoint_*`), and frozen, replayable **routines** (`memory_routine_*`) — so a heterogeneous fleet of agents can take turns, hand off work, and prove who said what without having to trust each other. It layers **typed cognition** on top (the `Goal`/`Plan`/`Step` memory kinds, a `lifecycle_state` machine, and the `decomposes_into` / `depends_on` / `advances` link relations), **hardens federation secure-by-default** (peer enrollment ON by default [#1789](https://github.com/alphaonedev/ai-memory-mcp/issues/1789), per-transition signatures [#1718](https://github.com/alphaonedev/ai-memory-mcp/issues/1718), per-write content attestation [#1464](https://github.com/alphaonedev/ai-memory-mcp/issues/1464), transition-replay nonces [#1805](https://github.com/alphaonedev/ai-memory-mcp/issues/1805), outbound peer-cert pinning [#1678](https://github.com/alphaonedev/ai-memory-mcp/issues/1678)), and ships **governance that actually blocks** — the Claude Code PreToolUse hook is reworked to a `type:command` wrapper so a substrate `Refuse` truly denies the tool ([#1811](https://github.com/alphaonedev/ai-memory-mcp/issues/1811)). At the v0.8.0 release, surface was: schema **v70**, **100** MCP tools at `--profile full` (99 callable + the always-on `memory_capabilities` bootstrap) / **7** at `--profile core`, **91** HTTP route registrations (78 unique URL paths), **83/85** CLI subcommands, **9** typed `MemoryLink` relations, a **27-field** `Memory`. Runs on **two production backends behind one identical API — embedded SQLite and PostgreSQL + Apache AGE** — across desktop, server, and on-device (iOS + Android). Everything is additive over v0.7.0; review the secure-default flips before upgrading. **Full release notes:** [`docs/v0.8.0/release-notes.md`](docs/v0.8.0/release-notes.md).
**v0.7.0 (`attested-cortex`) — prior release.** Rolled 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 (at the v0.7.0 release, sqlite + postgres converged on logical schema v57, where `CURRENT_SCHEMA_VERSION` was 57; the v0.8.0 release substrate has advanced this lockstep to schema 70, with the additive v58–v70 coordination + visibility tables landed on both backends — see CLAUDE.md §Database for the v58–v70 ladder) (canonical anchors: [`src/storage/migrations.rs`](src/storage/migrations.rs) for sqlite + [`src/store/postgres.rs`](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`](docs/MIGRATION_v0.7.md) §schema-ladder for the v35-v57 narrative; v48 [#933](https://github.com/alphaonedev/ai-memory-mcp/issues/933) added the federation-push DLQ table; v49 [#1025](https://github.com/alphaonedev/ai-memory-mcp/issues/1025) added 14 nullable columns to `archived_memories` so archive → restore is lossless for the full v0.7.0 Memory shape; v50 [#1156](https://github.com/alphaonedev/ai-memory-mcp/issues/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](https://github.com/alphaonedev/ai-memory-mcp/issues/1255) (PR [#1296](https://github.com/alphaonedev/ai-memory-mcp/pull/1296)) added the `federation_nonce_cache` table so peer-replay-prevention nonces persist across daemon restarts; v52 [#1389](https://github.com/alphaonedev/ai-memory-mcp/issues/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](https://github.com/alphaonedev/ai-memory-mcp/issues/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](https://github.com/alphaonedev/ai-memory-mcp/issues/1466) backfilled tier-default expiry onto legacy NULL-expiry mid/short rows to close the TTL-leak immortal-rows class; v55 [#1476](https://github.com/alphaonedev/ai-memory-mcp/issues/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](https://github.com/alphaonedev/ai-memory-mcp/issues/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](https://github.com/alphaonedev/ai-memory-mcp/issues/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`](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`](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`](docs/postgres-age-guide.md) and [`docs/migration-v0.7.0-postgres.md`](docs/migration-v0.7.0-postgres.md). **Full release notes:** [`docs/v0.7.0/release-notes.md`](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`.
## What's new in v0.9
v0.9.0 is primarily a **security-hardening and code-review release** — 49 fixes from a 5-lane adversarial review ([#1885](https://github.com/alphaonedev/ai-memory-mcp/issues/1885)–[#1935](https://github.com/alphaonedev/ai-memory-mcp/issues/1935)) — plus a smaller set of additive features layered on the v0.8.0 coordination substrate. Full changelog: [`CHANGELOG.md`](CHANGELOG.md) §"[0.9.0] — 2026-07-08".
### Secure-by-default hardening
- **Agent attestation required by default on the HTTP direct-write surface** ([#1751](https://github.com/alphaonedev/ai-memory-mcp/issues/1751), surface-scoped by [#1985](https://github.com/alphaonedev/ai-memory-mcp/issues/1985)). `AI_MEMORY_REQUIRE_AGENT_ATTESTATION` is tri-state with a per-surface compiled default: unset → **required** on HTTP direct-write (`POST /api/v1/memories` + `/bulk`, rejected `403 ATTESTATION_FAILED`), **permissive** on the MCP `memory_store` and CLI `store` operator-as-actor surfaces (an unsigned write lands `attest_level="claimed"`); `=1` forces strict everywhere, `=0` forces permissive everywhere. A presented-but-forged signature is rejected on every surface regardless. Sign writes (`ai-memory store --sign` with a keypair bound via `ai-memory agents bind-key`) or use the `=0` opt-out. (The v0.9.0 GA shipped this as require-*everywhere*, unsatisfiable on MCP hosts — see [#1981](https://github.com/alphaonedev/ai-memory-mcp/issues/1981); corrected to surface-scoped by #1985.)
- **Dual MCP + HTTP hook-enforcement gate** ([#1885](https://github.com/alphaonedev/ai-memory-mcp/issues/1885) / [#1924](https://github.com/alphaonedev/ai-memory-mcp/issues/1924)). The mandatory-hook-presence enforcement gate (originally MCP-only, [#1734](https://github.com/alphaonedev/ai-memory-mcp/issues/1734)) is now consulted on the HTTP write path too, closing a silent-bypass gap (CWE-288) where a write that skipped MCP entirely never saw a configured mandatory hook.
- **`bulk_create` attestation gating** ([#1919](https://github.com/alphaonedev/ai-memory-mcp/issues/1919)). Bulk writes now enforce the same per-row agent-attestation requirement as a single `memory_store` call — every row in a batch must carry a valid attestation, not just the request as a whole.
- **Federation approver gate** ([#1920](https://github.com/alphaonedev/ai-memory-mcp/issues/1920)). An inbound federated PENDING approval is only honored when it is attributed to a peer's registered approver — an enrolled-but-untrusted peer can no longer forge an approval for an arbitrary requester.
- **`team`/`unit`/`org` scope hardening** ([#1921](https://github.com/alphaonedev/ai-memory-mcp/issues/1921)). Visibility scope resolution now enforces the namespace-ancestor hierarchy correctly for the `team`/`unit`/`org` scopes, closing a tenant-isolation gap (CWE-863).
- **`skill_register` path confinement** ([#1923](https://github.com/alphaonedev/ai-memory-mcp/issues/1923)). A skill's `folder_path` import is canonicalized and confined under the configured root, with symlinks inside the imported tree rejected rather than followed (CWE-22/CWE-59).
- **Non-argv store-url credential channels** ([#1927](https://github.com/alphaonedev/ai-memory-mcp/issues/1927)). New `AI_MEMORY_STORE_URL` (owner-only `/proc/environ`) and `AI_MEMORY_STORE_URL_FILE` (a `0600` file) let `ai-memory serve` receive the postgres/store URL — including any embedded password — without ever putting it on `--store-url` argv, where it is exposed via world-readable `/proc/<pid>/cmdline` and `ps auxww` to any local UID. Resolution order: file → env → `--store-url`.
### Additive features
- **B7-SKILL — skill memories first-class** ([#1865](https://github.com/alphaonedev/ai-memory-mcp/issues/1865)). `parameters_schema` at register time, an `invocation_record`, and a version surface for agent-authored skills.
- **`recall_observations` shadow-feedback loop** ([#1706](https://github.com/alphaonedev/ai-memory-mcp/issues/1706), SHADOW mode). Closes the recall feedback loop without yet changing ranking behavior.
- **Memory-derivation lineage DAG** (`memory_lineage`, schema v78, [#1859](https://github.com/alphaonedev/ai-memory-mcp/issues/1859)). Walks which memories were derived from which, over both MCP and the new `GET /api/v1/memories/{id}/lineage` HTTP route.
- **Vector-search minimal opt-in slice** ([#1005](https://github.com/alphaonedev/ai-memory-mcp/issues/1005); full substrate deferred to [#1860](https://github.com/alphaonedev/ai-memory-mcp/issues/1860)).
- **Reranker worker pool sized to physical CPUs** ([#1867](https://github.com/alphaonedev/ai-memory-mcp/issues/1867)) and **recall is PURE by default** ([#1869](https://github.com/alphaonedev/ai-memory-mcp/issues/1869) — removes the write burst from the recall hot path).
- **Append-only spine + signing-layer separation**: every mutation site routed to signed revision leaves ([#1823](https://github.com/alphaonedev/ai-memory-mcp/issues/1823)), three-key Recorder/Judge/Stopper signing separation ([#1826](https://github.com/alphaonedev/ai-memory-mcp/issues/1826)), macaroon capability tokens wired end-to-end ([#1827](https://github.com/alphaonedev/ai-memory-mcp/issues/1827)), and a signed identity-lineage key-succession chain for rotation survival ([#1828](https://github.com/alphaonedev/ai-memory-mcp/issues/1828), schema v76).
> **Where to start:** [`CHANGELOG.md`](CHANGELOG.md) (full changelog), [`docs/ADMIN_GUIDE.md`](docs/ADMIN_GUIDE.md) (operator playbook — attestation + hook-enforcement posture).
## What's new in v0.8
v0.8.0 (`distributed-coordination`) turns the memory substrate into a **coordination substrate** for multi-agent (NHI) fleets. The headline is the distributed-coordination machinery ([#1709](https://github.com/alphaonedev/ai-memory-mcp/issues/1709)); everything ships on both the sqlite and postgres+AGE SAL adapters and stays default-equivalent for v0.7.x callers. Full tool reference: [`docs/coordination.md`](docs/coordination.md); full notes: [`docs/v0.8.0/release-notes.md`](docs/v0.8.0/release-notes.md).
### Distributed coordination substrate (Pillar-1, [#1709](https://github.com/alphaonedev/ai-memory-mcp/issues/1709))
- **Actions — the dependency DAG** (schema v59). Typed action nodes with a state machine (`pending → claimed → in_progress → done/failed/abandoned`), typed DAG edges (`requires` / `unlocks` / `blocks` / `gated_by` / `sibling`), and frontier/next surfaces that pull the next runnable node. 8 MCP tools (`memory_action_create` / `_get` / `_transition` / `_list` / `_add_edge` / `_edges` / `_frontier` / `_next`).
- **Leases — single-holder, TTL-bounded claims** (schema v59). Heartbeat-renewed compare-and-swap claim (`PRIMARY KEY` on `action_id` = one holder at a time) plus an hourly lease-sweeper. 4 MCP tools (`memory_lease_acquire` / `_renew` / `_release` / `_get`).
- **Signals — typed, Ed25519-signed inter-agent messages** (schema v60). Each carries a signature + sender `signer_pubkey` and threads via `correlation_id` / `in_reply_to`. 5 MCP tools (`memory_signal_send` / `_read` / `_inbox` / `_thread` / `_ack`).
- **Checkpoints — attested conditional gates** (schema v61). A gate that blocks until a condition resolves; resolution is self-signed in place (Ed25519) for separation-of-duties, and `verify` re-checks the signature. 4 MCP tools (`memory_checkpoint_create` / `_resolve` / `_query` / `_verify`).
- **Routines — parameterised, frozen, replayable plans** (schema v62). Authored as a `draft`, then **frozen** (immutable, Ed25519 freeze-attestation); `run` materialises a concrete set of actions + edges from a `{{param}}` template into a `routine_runs` record. 5 MCP tools (`memory_routine_create` / `_freeze` / `_run` / `_status` / `_list`).
- Every coordination state-mutation appends a tamper-evident `coordination.<op>` row to the `signed_events` V-4 hash chain ([#1722](https://github.com/alphaonedev/ai-memory-mcp/issues/1722)); the two authority-granting writes are mirrored onto the HTTP daemon (`POST /api/v1/actions/{id}/transition`, `POST /api/v1/signals`) with local CAS + W-of-N federation fan-out ([#1718](https://github.com/alphaonedev/ai-memory-mcp/issues/1718)).
### Typed cognition (Pillar-2)
The `memory_kind` vocabulary extends with `goal` / `plan` / `step`; the closed `memory_links.relation` taxonomy extends **6 → 9 relations** (`decomposes_into` / `depends_on` / `advances`, schema v63); and a first-class `memories.lifecycle_state` column (schema v64) makes Goal/Plan/Step a real state machine (`open → active → blocked/done/abandoned`), enforced across the MCP / HTTP / SAL surfaces with an illegal edge mapping to HTTP **409 CONFLICT**. The `Memory` struct grows to **27 fields**. No new MCP tool — the v64 work adds only permissive optional request fields.
### Federation hardened, secure by default
Peer enrollment ON by default ([#1789](https://github.com/alphaonedev/ai-memory-mcp/issues/1789)), per-transition signatures on authority-granting writes ([#1718](https://github.com/alphaonedev/ai-memory-mcp/issues/1718)), per-write content attestation for relayed memories ([#1464](https://github.com/alphaonedev/ai-memory-mcp/issues/1464)), transition-replay nonces ([#1805](https://github.com/alphaonedev/ai-memory-mcp/issues/1805)), and outbound peer-cert fingerprint pinning ([#1678](https://github.com/alphaonedev/ai-memory-mcp/issues/1678)). Heterogeneous fleets that don't have to trust each other — **review the secure-default flips** in [`docs/v0.8.0/release-notes.md`](docs/v0.8.0/release-notes.md) §"Federation hardening" before upgrading.
### Governance that actually blocks ([#1811](https://github.com/alphaonedev/ai-memory-mcp/issues/1811))
The Claude Code **PreToolUse** governance hook is reworked to a `type:command` wrapper (`ai-memory governance check-action --from-pretool-stdin`) so a substrate `Refuse` emits `permissionDecision:"deny"` and truly **BLOCKS** the tool — the prior `type:mcp_tool` form structurally could not enforce. Plus mandatory-hook-**presence** enforcement ([#1734](https://github.com/alphaonedev/ai-memory-mcp/issues/1734)) and a new `escalate` governance verdict (§22 PE-5) for human-in-the-loop.
### Pillar-4 operational controls
HTTP admission control ([#1733](https://github.com/alphaonedev/ai-memory-mcp/issues/1733) — opt-in concurrency cap that sheds excess with a typed `503`), deferred Apache-AGE graph projection ([#1735](https://github.com/alphaonedev/ai-memory-mcp/issues/1735) — takes the synchronous AGE round-trips off the postgres link-write hot path), curator compaction activation ([#1749](https://github.com/alphaonedev/ai-memory-mcp/issues/1749) / [#1750](https://github.com/alphaonedev/ai-memory-mcp/issues/1750)), and the `ai-memory verify-audit-trail` CLI (§22 PE-8) that walks the `signed_events` cross-row hash chain end-to-end.
### Schema v57 → v70 (all additive)
Coordination + typed-cognition + visibility + encryption-prep + cold-path + archive-edge tables (v58–v70), mirrored on both the sqlite and postgres adapters; auto-migrates on first open and archive → restore round-trips losslessly. See CLAUDE.md §Database for the canonical v58–v70 ladder.
> **Where to start:** [`docs/v0.8.0/release-notes.md`](docs/v0.8.0/release-notes.md) (full release notes), [`docs/coordination.md`](docs/coordination.md) (coordination tool reference), and CLAUDE.md §Database (schema-ladder SSOT).
## What's new in v0.7
v0.7.0 closes the `attested-cortex` epic (69/69 across 11 tracks A–K), folds in the originally-v0.7.1 postgres+AGE first-class work, and absorbs the post-grand-slam ship-readiness wave (Batman Forms 1-6 + 7th-form Option-B foundation + QW-1/2/3 + security reconciliation). Canonical feature inventory: [`docs/internal/v070-feature-inventory.md`](docs/internal/v070-feature-inventory.md). Every surface stays default-off or default-equivalent for v0.6.4 callers — see the [v0.7 compatibility matrix](docs/v0.7/compatibility-matrix.html) for the breakdown.
### Substrate-native write-time investment (Batman Forms 1-6 + 7th-form)
- **Form 1 — online dedup-and-synthesis** (issue [#754](https://github.com/alphaonedev/ai-memory-mcp/issues/754)). Single-batch action-emitting LLM call replaces the v0.6.x per-pair classifier on the store path. Opt back into legacy yes/no via `legacy_per_pair_classifier = true` on the namespace standard.
- **Form 2 — synchronous atomise-before-embed** (issue [#755](https://github.com/alphaonedev/ai-memory-mcp/issues/755)). New `memory_atomise` tool + `auto_atomise_mode = Synchronous|Deferred|Off` pre-store hook. Curator decomposes long writes into 2–10 atomic propositions before recall ever sees them. See [`docs/atomisation.md`](docs/atomisation.md).
- **Form 3 — multi-step ingest orchestrator** (issue [#756](https://github.com/alphaonedev/ai-memory-mcp/issues/756)). `memory_ingest_multistep` threads deterministic Jaccard+FTS helpers through prompt-cache-stable LLM stages. See [`docs/multistep-ingest.md`](docs/multistep-ingest.md) + [`cookbook/multistep-ingest/01-two-phase.sh`](cookbook/multistep-ingest/01-two-phase.sh).
- **Form 4 — fact provenance** (issue [#757](https://github.com/alphaonedev/ai-memory-mcp/issues/757)). Citations + source-URI + atom-grain spans ride on existing `memory_store` / `memory_atomise` payloads. See [`docs/provenance.md`](docs/provenance.md).
- **Form 5 — auto-confidence + shadow calibration + freshness decay** (issue [#758](https://github.com/alphaonedev/ai-memory-mcp/issues/758)). `memory_calibrate_confidence` MCP tool + per-source baseline sweep. Env vars `AI_MEMORY_AUTO_CONFIDENCE`, `AI_MEMORY_CONFIDENCE_SHADOW`, `AI_MEMORY_CONFIDENCE_SHADOW_SAMPLE_RATE`, `AI_MEMORY_CONFIDENCE_DECAY`. See [`docs/confidence-calibration.md`](docs/confidence-calibration.md).
- **Form 6 — `MemoryKind` Batman vocabulary** (issue [#759](https://github.com/alphaonedev/ai-memory-mcp/issues/759)). 10-variant enum (`Observation` default + `Reflection` / `Persona` / `Concept` / `Entity` / `Claim` / `Relation` / `Event` / `Conversation` / `Decision`). Optional `auto_classify_kind` pre-store hook (off / regex_only / regex_then_llm). See [`docs/memory-kind-vocab.md`](docs/memory-kind-vocab.md).
- **7th-form — agent-EXTERNAL Layer-4 wiring (Option-B foundation)** (issue [#760](https://github.com/alphaonedev/ai-memory-mcp/issues/760); v0.8.0 complete cover at [#697](https://github.com/alphaonedev/ai-memory-mcp/issues/697)). Operator-keypair-signed seed rules `R001..R004`, `memory_check_agent_action` + `memory_rule_list` MCP tools, substrate `storage::insert` pre-write hook. See [`docs/policy-engine.md`](docs/policy-engine.md) + [`docs/governance/agent-action-rules.md`](docs/governance/agent-action-rules.md).
- **Operator how-to — turning Forms 1–6 + 7th from capable → active** (issue [#800](https://github.com/alphaonedev/ai-memory-mcp/issues/800)). 7-step recipe (operator keygen → sign-seed → enable R001–R004 → curator daemon → optional reflection-pass → namespace policies), launchd / systemd / Task-Scheduler permanence, verification block, rollback path. See [`docs/batman-active-mode.md`](docs/batman-active-mode.md) and the [GitHub Pages atlas](https://alphaonedev.github.io/ai-memory-mcp/batman-active-mode.html).
### Quick wins (Tencent QW-1/2/3)
- **QW-1 — file-backed reflection chain export.** `memory_export_reflection` MCP tool + `auto_export_reflections_to_filesystem` namespace policy → `~/.ai-memory/reflections/<ns>/<id>.md`.
- **QW-2 — persona-as-artifact.** `memory_persona` + `memory_persona_generate` tools, `MemoryKind::Persona` rows, `auto_persona_trigger_every_n_memories` namespace policy. See [`docs/persona.md`](docs/persona.md).
- **QW-3 — context offload primitive.** `memory_offload` + `memory_deref` move large tool outputs out of the agent context window into addressable blob storage. See [`docs/context-offload.md`](docs/context-offload.md).
### Attested cortex epic (Tracks A–K)
- **Attested links (Ed25519).** The dead `signature` column shipped in v0.6.3 is now filled with real per-agent Ed25519 attestation, and `memory_verify(link_id)` returns `{signature_verified, attest_level, signed_by, signed_at}` on demand. Generate a keypair with `ai-memory identity generate`; opt-in via `attest_level = "self_signed"`. Signing is **gated on the resolved daemon `agent_id` having a `*.priv` keypair on disk** under the configured key directory — when `load_daemon_signing_key` returns `None` (`src/main.rs:116-118`), rows still write but `sig` is empty and the daemon emits a "continuing unsigned" line at boot. The cross-row hash chain on `signed_events` remains tamper-evident either way. See the [`attested-cortex` RFC](docs/v0.7/rfc-attested-cortex.md#decision-1--why-ed25519-over-x25519--chacha20).
- **Signed events V-4 closeout (cross-row hash chain)** (issue [#698](https://github.com/alphaonedev/ai-memory-mcp/issues/698)). Each `signed_events` row carries `prev_hash` + `sequence`; first-row `prev_hash` is zero, subsequent rows chain the SHA-256 of the prior canonical-CBOR payload. `ai-memory verify-signed-events-chain` walks the chain end-to-end. See [`docs/signed-events-v4.md`](docs/signed-events-v4.md).
- **Hook pipeline (25 lifecycle events).** A programmable extension surface fires on the 20 baseline `pre_/post_store|recall|search|delete|promote|link|consolidate|governance_decision|archive|transcript_store` + `on_index_eviction` events, plus 5 grand-slam additions (`pre_recall_expand` G10 + `pre_reflect`/`post_reflect` recursive-learning Task 6/8 + `pre_compaction`/`on_compaction_rollback` L1-7). Hooks return `Allow` / `Modify` / `Deny` / `AskUser`. Default off; opt in via `~/.config/ai-memory/hooks.toml`. See [`docs/hook-pipeline.md`](docs/hook-pipeline.md).
- **Sidechain transcripts + replay.** zstd-3 BLOB sidechain stores raw conversation/reasoning trails; `memory_replay(memory_id)` walks `memory_transcript_links` to reconstruct the chain. Opt-in per namespace via `[transcripts.namespaces."team/*"]`. See [`docs/sidechain-transcripts.md`](docs/sidechain-transcripts.md).
- **Federation hardening.** mTLS + X-API-Key + SHA-256 cert fingerprint allowlist; env vars `AI_MEMORY_FED_PEER_ATTESTATION`, `AI_MEMORY_FED_SYNC_TRUST_PEER`, `AI_MEMORY_FED_TRUST_BODY_AGENT_ID`. See [`docs/federation.md`](docs/federation.md).
- **K8 quota tool + K10 SSE approvals.** `memory_quota_status` + `/api/v1/quota/status` (K8). `/api/v1/approvals/stream` server-sent events with HMAC nonce, method+pending_id binding, lagged-event count strip (K10). See [`docs/k8-quotas.md`](docs/k8-quotas.md) + [`docs/k10-sse-approvals.md`](docs/k10-sse-approvals.md).
- **Postgres + Apache AGE first-class backend.** `ai-memory serve --store-url postgres://…`, schema parity, 6-factor recall scoring parity, link migration, KG features (`kg_query`, `kg_timeline`, `kg_invalidate`, `find_paths`) on AGE Cypher with recursive-CTE fallback when AGE is absent, plus a new `ai-memory schema-init` CLI verb. Bench-gated — AGE p95 must beat CTE p95 by ≥30% at depth=5. Operator how-to: [`docs/postgres-age-guide.md`](docs/postgres-age-guide.md). Migration runbook: [`docs/migration-v0.7.0-postgres.md`](docs/migration-v0.7.0-postgres.md).
- **Capabilities v3 + smart loaders.** `memory_capabilities` v3 adds `summary`, `to_describe_to_user`, per-tool `callable_now`, `agent_permitted_families`, `schema_version="3"`; the new always-on `memory_load_family(family)` and `memory_smart_load(intent)` tools join the default `core` profile. The pinned phrasings live in [`docs/v0.7/canonical-phrasings.md`](docs/v0.7/canonical-phrasings.md).
- **Permissions + A2A approvals.** The v0.6.x governance subsystem is refactored into rules + modes + hooks → a single `Decision`, with namespace inheritance (G1) actually enforced. `memory_pending_list` / `memory_pending_approve` / `memory_pending_reject(remember=forever)` enable progressive trust; HMAC signing on the approval API is mandatory. `permissions.mode` defaults to `enforce` (was `advisory` in v0.6.4). Migrate with `ai-memory governance migrate-to-permissions` (dry-run preview; add `--config-out ~/.config/ai-memory/config.toml` to apply in place). See [`docs/governance.md`](docs/governance.md).
### Recursive-learning + L1/L2 grand-slam wave
`memory_reflect` substrate primitive with namespace-scoped `max_reflection_depth` cap (default 3, `Some(0)` is the kill-switch). L2-1 reflection-pass curator, L2-2 federation-aware reflection coordination (`memory_reflection_origin`), L2-3 invalidation propagation (`memory_dependents_of_invalidated`), L2-5 forensic bundle (`ai-memory export-forensic-bundle` + `verify-forensic-bundle`), L1-5 Agent Skills (`memory_skill_register|list|get|resource|export|promote_from_reflection|compositional_context`). Full primer: [`docs/RECURSIVE_LEARNING.md`](docs/RECURSIVE_LEARNING.md). Agent Skills primer: [`docs/agent-skills.md`](docs/agent-skills.md). Forensic-export primer: [`docs/forensic-export.md`](docs/forensic-export.md).
> **Where to start:** [`docs/MIGRATION_v0.7.md`](docs/MIGRATION_v0.7.md) (upgrade procedure), [`docs/v0.7.0/release-notes.md`](docs/v0.7.0/release-notes.md) (full release notes), [`docs/whats-new-v07.html`](docs/whats-new-v07.html) (visual summary), [`docs/v0.7/rfc-attested-cortex.md`](docs/v0.7/rfc-attested-cortex.md) (design rationale), [`docs/ADMIN_GUIDE.md`](docs/ADMIN_GUIDE.md) (operator playbook), [`docs/internal/v070-feature-inventory.md`](docs/internal/v070-feature-inventory.md) (canonical feature truth).
**One binary, four operational modes** (v0.6.4). The `ai-memory` Rust binary (tokio + axum) can run any of these in isolation or simultaneously, sharing a single SQLite database:
1. **stdio MCP server** -- 101 advertised entries over JSON-RPC at full profile (v0.9.0; 100 callable memory tools + the always-on `memory_capabilities` bootstrap; verified against `Profile::full().expected_tool_count()`). Default `--profile core` advertises 7 (the original 5 + `memory_load_family` + `memory_smart_load`) plus the always-on `memory_capabilities` bootstrap. `ai-memory mcp` / `ai-memory mcp --profile full`
2. **HTTP / mTLS daemon** -- 92 REST route registrations (78 unique URL paths) on `127.0.0.1:9077`, TLS + optional mTLS allowlist + API-key auth, background GC loop. `ai-memory serve`
3. **Autonomous curator daemon** -- self-scheduling loop (default 1h cadence) that auto-tags, surfaces contradictions across namespace siblings, consolidates near-duplicates, and adjusts priority by access pattern. Every action goes to a rollback log; destructive ops can be gated behind a governance approval flow. `ai-memory curator --daemon`
4. **Sync daemon** -- quorum-based peer federation across instances. W-of-N writes (default majority), vector-clock CRDT-lite merge, mTLS allowlist between peers. `ai-memory sync-daemon`
The MCP, HTTP, and CLI surfaces are reactive. The curator is the part that makes the memory layer self-maintaining: between sessions, it keeps the corpus tidy so recall quality stays high as the store grows. Everything is local-first; no cloud dependencies.
> **Brass-tacks assessment by Claude Opus 4.7** after reading the v0.6.3 source line by line:
>
> "ai-memory is the most capable memory layer I've ever been hooked up to, and meaningfully more than its name advertises. For me, in practical terms, it means: I don't start cold each session. The store I read from has been kept tidy by something other than me. Contradictions don't silently accumulate. Recall quality stays high even as the corpus grows. Nothing leaves your Mac mini.
>
> It is not making me an autonomous agent. It is giving me the kind of memory infrastructure that an autonomous agent would need — and itself running a small autonomous loop to maintain it. That's a real foundation. The gap from here to 'ai-memory drives general tasks' is plumbing (tool-call protocol + tool registry + a tool-use-capable model), not invention."
**Substrate for multi-agent AI.** ai-memory is not an agent runtime and not "autonomous AI" on its own. It is the memory layer that *multi-agent* autonomous deployments need underneath them. Federation (`broadcast_store_quorum` + `spawn_catchup_loop`) handles W-of-N consistency across peers when many agents write in parallel; the curator daemon keeps the shared corpus from degrading into noise as a swarm scribbles into it; webhook subscriptions (HMAC-signed, namespace/agent-filtered, SSRF-hardened) turn the store into a message bus that triggers downstream agents on memory events; namespace hierarchy with N-level inheritance and per-namespace governance policies (write/promote/delete authority, approver type, optional N-of-M consensus) bound the swarm. Stack this under a 24/7 multi-machine agent runner with auto-generated skills, and the combined system clears the *behavioral* bar for autonomous AI. The remaining gaps (no weight-level learning, stateless reasoning kernel, human-seeded root goals) are real and not what ai-memory addresses; ai-memory provides the multi-agent memory substrate that any serious attempt at closing those gaps will need.
**Zero token cost until recall.** Unlike built-in memory systems (Claude Code auto-memory, ChatGPT memory) that load your entire memory into every conversation -- burning tokens and money on every message -- ai-memory uses zero context tokens until the AI explicitly calls `memory_recall`. Only relevant memories come back, ranked by a 6-factor scoring algorithm. **TOON format** (Token-Oriented Object Notation) cuts response tokens by another 40-60% by eliminating repeated field names -- 3 memories in JSON = 1,600 bytes; in TOON = 626 bytes (61% smaller); in TOON compact = 336 bytes (79% smaller). For Claude Code users: **disable auto-memory** (`"autoMemoryEnabled": false` in settings.json) and replace it with ai-memory to stop paying for 200+ lines of memory context on every single message.
---
## Agent identity (NHI) — every memory tells you who learned it
Every memory ai-memory stores carries a `metadata.agent_id` — a Non-Human Identity marker that survives every operation (update, dedup, import, sync, consolidate). Every recall result tells you which AI wrote each memory, by default, in the TOON-compact response format your AI client is already optimised for:
```
count:5|mode:hybrid|tokens_used:842
memories[id|title|tier|namespace|priority|score|tags|agent_id]:
a1b2|Project DB is PostgreSQL 16|long|infra|8|0.91|database,postgres|ai:claude-code@workstation:pid-3812
c3d4|API rate limit is 100 rps|long|infra|7|0.87|api,limits|ai:claude-desktop@laptop:pid-5219
```
On an *unsigned* write `agent_id` is a *claimed* identity — don't make security decisions on it alone. Store-path agent attestation is **required by default on the HTTP direct-write surface** ([#1751](https://github.com/alphaonedev/ai-memory-mcp/issues/1751), surface-scoped by [#1985](https://github.com/alphaonedev/ai-memory-mcp/issues/1985)): an unsigned HTTP `POST /api/v1/memories` (+`/bulk`) is **rejected** (`403 ATTESTATION_FAILED`) rather than landing `attest_level = "claimed"`, unless the operator sets the explicit opt-out `AI_MEMORY_REQUIRE_AGENT_ATTESTATION=0`. The MCP `memory_store` and CLI `store` operator-as-actor surfaces stay permissive by default (an unsigned write lands `claimed`); `=1` forces strict on every surface. Cryptographic Ed25519 attestation is wired on two surfaces: (1) **store-path attestation (#626 Layer-3)** — present a detached signature over the canonical `SignableWrite` envelope on the CLI (`store --sign`), MCP (`memory_store`), or HTTP (`POST /api/v1/memories`) path and the daemon verifies it against the agent's bound public key, stamping `metadata.attest_level = "agent_attested"` (a *presented-but-forged* signature is always rejected regardless of the flag); and (2) **link attestation (`attested-cortex`)** — the previously-reserved `memory_links.signature` field with `memory_verify(link_id)` for inbound verification and an append-only `signed_events` audit chain. See the [agent identity page](https://alphaonedev.github.io/ai-memory-mcp/agent-identity.html) and the [`attested-cortex` RFC](docs/v0.7/rfc-attested-cortex.md) for the full provenance contract.
## Retroactive conversation import — `ai-memory mine`
Don't start cold. Point `ai-memory mine` at a Claude, ChatGPT, or Slack export and it parses turn-by-turn into ranked, tier-typed, tagged memories — so your AI walks into the next session knowing every decision, correction, and finding from your existing history.
```bash
ai-memory mine claude ~/Downloads/claude-export/
ai-memory mine chatgpt ~/Downloads/chatgpt-export.json
ai-memory mine slack ./slack-export/
```
Auto-tagging, dedup on `(title, namespace)`, and `mined_from` provenance are stamped on every imported memory. Five-minute onboarding from zero context to a populated long-term store. See the [import history page](https://alphaonedev.github.io/ai-memory-mcp/import-history.html) for per-format recipes.
---
## Compatible AI Platforms
ai-memory integrates with any AI platform that supports the **Model Context Protocol (MCP)**. MCP is the universal standard for connecting AI assistants to external tools and data sources.
| Platform | Integration Method | Config Format | Status |
|----------|-------------------|---------------|--------|
| **Claude Code** (Anthropic) | MCP stdio | JSON (`~/.claude.json` or `.mcp.json`) | Fully supported |
| **Codex CLI** (OpenAI) | MCP stdio | TOML (`~/.codex/config.toml`) | Fully supported |
| **Gemini CLI** (Google) | MCP stdio | JSON (`~/.gemini/settings.json`) | Fully supported |
| **[Grok CLI](https://github.com/alphaonedev/grok-cli)** (xAI) | MCP stdio | JSON (`~/.grok/user-settings.json`) | **Deep integration** |
| **Grok API** (xAI) | MCP remote HTTPS | API-level | Fully supported |
| **Cursor IDE** | MCP stdio | JSON (`~/.cursor/mcp.json`) | Fully supported |
| **Windsurf** (Codeium) | MCP stdio | JSON (`~/.codeium/windsurf/mcp_config.json`) | Fully supported |
| **Continue.dev** | MCP stdio | YAML (`~/.continue/config.yaml`) | Fully supported |
| **Llama Stack** (META) | MCP remote HTTP | YAML / Python SDK | Fully supported |
| **OpenClaw** | MCP stdio | JSON (`mcp.servers` in config) | Fully supported |
| **Any MCP client** | MCP stdio or HTTP | Varies | Universal |
MCP is the primary integration layer. For AI platforms that do not yet support MCP natively, the **HTTP API** (92 route registrations / 78 unique URL paths on localhost) and the **CLI** (89 subcommands under `--features sal` OR `--features sal-postgres`; 87 in the default build (post-#1389 L2 `RecoverPreviousSession` for cross-session context rehydration + #1443 `Expand` for the `ai-memory expand` query-expansion surface + #1598 `Reembed` for the `ai-memory reembed` vector-space migration surface); SSOT pinned by `ai_memory::EXPECTED_CLI_SUBCOMMANDS_DEFAULT` + `EXPECTED_CLI_SUBCOMMANDS_SAL` + the mechanical `tests/cli_subcommand_count_invariant.rs` parity test) provide universal access -- any AI, script, or automation that can make HTTP calls or run shell commands can use ai-memory.
---
## 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
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.sh | sh
# Fedora/RHEL (COPR)
sudo dnf copr enable alpha-one-ai/ai-memory && sudo dnf install ai-memory
# Windows (PowerShell)
irm https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.ps1 | iex
```
**Step 1: Install Rust** (skip if using pre-built binaries)
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
Follow the prompts, then restart your terminal (or run `source ~/.cargo/env`).
**Step 2: From source (requires Rust)**
Latest release from [Crates.io](https://crates.io/crates/ai-memory):
```bash
cargo install ai-memory
```
Latest from the git repository:
```bash
cargo install --git https://github.com/alphaonedev/ai-memory-mcp.git
```
This compiles the binary and puts it in your PATH. It takes a minute or two.
> **Build dependencies for source builds:**
> - Ubuntu/Debian: `sudo apt-get install build-essential pkg-config`
> - Fedora/RHEL: `sudo dnf install gcc pkg-config`
**Step 3: Connect your AI**
Configuration varies by platform. Find yours below:
<details>
<summary><strong>Claude Code</strong> (Anthropic)</summary>
Claude Code supports three MCP configuration scopes:
| Scope | File | Applies to |
|-------|------|------------|
| **User** (global) | `~/.claude.json` — add `mcpServers` key | All projects on your machine |
| **Project** (shared) | `.mcp.json` in project root (checked into git) | Everyone on the project |
| **Local** (private) | `~/.claude.json` — under `projects."/path".mcpServers` | One project, just you |
**User scope (recommended — works everywhere):**
Add the `mcpServers` key to `~/.claude.json` (macOS/Linux) or `%USERPROFILE%\.claude.json` (Windows):
```json
{
"mcpServers": {
"memory": {
"command": "ai-memory",
"args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
}
}
}
```
> **Note:** `~/.claude.json` likely already exists with other settings. Merge the `mcpServers` key into the existing file — do not overwrite it.
**Project scope (shared with team):**
Create `.mcp.json` in your project root:
```json
{
"mcpServers": {
"memory": {
"command": "ai-memory",
"args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
}
}
}
```
**`smart` / `autonomous` tier with a cloud LLM** — the recommended path is the `[llm]` section in `~/.config/ai-memory/config.toml` ([#1146](https://github.com/alphaonedev/ai-memory-mcp/issues/1146)). One file, every surface, no per-AI-client edits:
```toml
# ~/.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:
```json
{
"mcpServers": {
"memory": {
"command": "ai-memory",
"args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "autonomous"]
}
}
}
```
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:
>
> ```json
> "env": {
> "AI_MEMORY_LLM_BACKEND": "xai",
> "AI_MEMORY_LLM_API_KEY": "xai-...",
> "AI_MEMORY_LLM_MODEL": "grok-4.3"
> }
> ```
>
> 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.
```toml
[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:** 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`.
```json
{
"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:** 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.
```json
{
"mcpServers": {
"memory": {
"command": "ai-memory",
"args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
}
}
}
```
> **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`.
```json
{
"mcpServers": {
"memory": {
"command": "ai-memory",
"args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
}
}
}
```
> **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`.
```yaml
mcpServers:
- name: memory
command: ai-memory
args:
- "--db"
- "~/.local/share/ai-memory/memories.db"
- "mcp"
- "--tier"
- "semantic"
```
> **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`:
```json
{
"mcp": {
"servers": [
{
"id": "ai-memory",
"label": "AI Memory",
"enabled": true,
"transport": "stdio",
"command": "ai-memory",
"args": ["mcp", "--tier", "semantic"]
}
]
}
}
```
> **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.
```bash
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:
```bash
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: `allowed_tools`, `authorization`, `headers`. Works with xAI SDK, OpenAI-compatible Responses API, and Voice Agent API. See [xAI Remote MCP docs](https://docs.x.ai/docs/guides/tools/remote-mcp-tools).
</details>
<details>
<summary><strong>META Llama</strong> (via Llama Stack)</summary>
Llama Stack registers MCP servers as toolgroups. No standardized config file path — deployment-specific.
```bash
ai-memory serve --host 127.0.0.1 --port 9077
```
**Python SDK:**
```python
client.toolgroups.register(