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
Persistent memory for any AI — zero token cost until recall
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.9.0 — current release. A security-hardening and code-review release: 49 fixes from a 5-lane adversarial review (#1885–#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, surface-scoped by #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) and the HTTP write path (#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), routes inbound federated PENDING approvals through the registered-approver gate (#1920), tightens team/unit/org visibility scope so it is no longer over-broad across the namespace hierarchy (#1921), and confines skill_register's folder_path import under the configured root with a symlink jail (#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). Additive feature work: agent-authored skill memories with a parameters_schema + invocation_record (B7-SKILL, #1865), the recall_observations shadow-feedback loop (#1706), a memory-derivation lineage DAG (memory_lineage, #1859), and an opt-in vector-search minimal slice (#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-fieldMemory. 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 §"[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: 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, per-transition signatures #1718, per-write content attestation #1464, transition-replay nonces #1805, outbound peer-cert pinning #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). 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-fieldMemory. 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.
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 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.
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–#1935) — plus a smaller set of additive features layered on the v0.8.0 coordination substrate. Full changelog: CHANGELOG.md §"[0.9.0] — 2026-07-08".
Secure-by-default hardening
Agent attestation required by default on the HTTP direct-write surface (#1751, surface-scoped by #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; corrected to surface-scoped by #1985.)
Dual MCP + HTTP hook-enforcement gate (#1885 / #1924). The mandatory-hook-presence enforcement gate (originally MCP-only, #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). 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). 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). 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). 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). 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). parameters_schema at register time, an invocation_record, and a version surface for agent-authored skills.
recall_observations shadow-feedback loop (#1706, SHADOW mode). Closes the recall feedback loop without yet changing ranking behavior.
Memory-derivation lineage DAG (memory_lineage, schema v78, #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; full substrate deferred to #1860).
Reranker worker pool sized to physical CPUs (#1867) and recall is PURE by default (#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), three-key Recorder/Judge/Stopper signing separation (#1826), macaroon capability tokens wired end-to-end (#1827), and a signed identity-lineage key-succession chain for rotation survival (#1828, schema v76).
Where to start:CHANGELOG.md (full changelog), 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); 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; full notes: docs/v0.8.0/release-notes.md.
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); 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).
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), per-transition signatures on authority-granting writes (#1718), per-write content attestation for relayed memories (#1464), transition-replay nonces (#1805), and outbound peer-cert fingerprint pinning (#1678). Heterogeneous fleets that don't have to trust each other — review the secure-default flips in docs/v0.8.0/release-notes.md §"Federation hardening" before upgrading.
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) and a new escalate governance verdict (§22 PE-5) for human-in-the-loop.
Pillar-4 operational controls
HTTP admission control (#1733 — opt-in concurrency cap that sheds excess with a typed 503), deferred Apache-AGE graph projection (#1735 — takes the synchronous AGE round-trips off the postgres link-write hot path), curator compaction activation (#1749 / #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.
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. Every surface stays default-off or default-equivalent for v0.6.4 callers — see the v0.7 compatibility matrix for the breakdown.
Substrate-native write-time investment (Batman Forms 1-6 + 7th-form)
Form 1 — online dedup-and-synthesis (issue #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). 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.
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.
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.
Signed events V-4 closeout (cross-row hash chain) (issue #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.
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.
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.
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.
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. Migration runbook: 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.
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.
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. Agent Skills primer: docs/agent-skills.md. Forensic-export primer: docs/forensic-export.md.
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:
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
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
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, surface-scoped by #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 and the attested-cortex RFC 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.
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 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.
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)
# 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)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Follow the prompts, then restart your terminal (or run source ~/.cargo/env).
smart / autonomous tier with a cloud LLM — the recommended path is the [llm] section in ~/.config/ai-memory/config.toml (#1146). One file, every surface, no per-AI-client edits:
# ~/.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:
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 → #1146. Full per-backend recipes: 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 (v0.7.0) that is any of: local Ollama, 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 for a copy-paste template and placement options.
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.
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.
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.
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.
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.
The AlphaOne fork of 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.
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 for full setup.
Grok connects to MCP servers over HTTPS (remote only, no stdio). No config file — servers are specified per API request.
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 93 of the 100 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.
Mobile platform support (v0.7.0 Posture-1a)
ai-memory is portable to iOS and Android via the standard Rust mobile cross-compile path. v0.7.0 ships CI coverage for both targets at three escalating levels:
Layer
Coverage
CI workflow
Layer 1 — Cross-compile
cargo check --target aarch64-apple-ios --no-default-features --features sqlite-bundled --lib and the matching Android cross-compile run on every PR + push to release/**. Catches ~80% of mobile bit-rot risk (any crate update that drops mobile portability surfaces here).
Release tag cuts produce ai-memory-ios.xcframework.tar.gz (iOS device + simulator slices via xcodebuild -create-xcframework) and ai-memory-android.tar.gz (Android arm64 / armv7 / x86_64 / x86 .so bundle in jniLibs/<abi>/ layout).
A scoped ~50-test subset (file-system sandboxing, FTS5 on device SQLite, HNSW CPU recall, embedder CPU path, LLM client TLS) runs against the iOS Simulator on every release/** push + a manual workflow_dispatch; the Android emulator arm runs on release/** push + workflow_dispatch only. Selection rationale: tests/mobile/README.md.
Status at v0.7.0: Layer 1 is the ship-gate — mobile cross-compile must be GREEN before tag-cut. Layer 2 (release artifacts) ships the BUILD pipeline + artifact layout; the C-callable FFI surface itself lands in a v0.7.x follow-up. Layer 3 runs the scoped test subset on every release/** push.
Consuming the release artifacts:
iOS — download ai-memory-ios.xcframework.tar.gz from the v0.7.x release page, unpack, and drag AiMemory.xcframework into your Xcode project under "Frameworks, Libraries, and Embedded Content."
Android — download ai-memory-android.tar.gz from the v0.7.x release page, unpack, and copy the jniLibs/ tree into your app module's src/main/jniLibs/.
The mobile artifacts are also part of every published v0.7.x release; the Homebrew formula + APT/RPM packages (which ship the desktop binaries) include a note linking to the mobile downloads. See issue #1068 for the CI implementation history.
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)
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 (101 advertised entries reachable via runtime expansion or --profile full) over MCP -- it can store and recall memories natively during conversations.
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).
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.9.0 matches ai-memory 0.9.0). 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/.
What Does It Do?
AI assistants forget everything between conversations. ai-memory fixes that.
It runs as an MCP (Model Context Protocol) tool server -- a background process that your AI talks to natively. When your AI learns something important, it stores it. When it needs context, it recalls relevant memories ranked by a 6-factor scoring algorithm. Memories live in three tiers:
Short-term (6 hours default, configurable) -- throwaway context like current debugging state
Mid-term (7 days default, configurable) -- working knowledge like sprint goals and recent decisions
Long-term (permanent) -- architecture, user preferences, hard-won lessons
Memories that keep getting accessed automatically promote from mid to long-term. Each recall extends the TTL. Priority increases with usage. The system is self-curating.
Beyond MCP, ai-memory also exposes a full HTTP REST API (92 route registrations / 78 unique URL paths on port 9077) and a complete 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,SAL} + the mechanical tests/cli_subcommand_count_invariant.rs parity test) for direct interaction, scripting, and integration with any AI platform or tool.
Features
Core
MCP tool server -- 101 tools over stdio JSON-RPC (full profile), compatible with any MCP client
Three-tier memory -- short (6h TTL default), mid (7d TTL default), long (permanent) -- TTLs are configurable
Full-text search -- SQLite FTS5 with ranked retrieval
Hybrid recall -- FTS5 keyword + cosine similarity with adaptive blending: the semantic weight varies 0.50 (short content) → 0.15 (long content) because embeddings lose information on long text
Agent identity (NHI) -- every memory carries metadata.agent_id (claimed identity) with defense-in-depth immutability across update/dedup/import/sync/consolidate; filter list/search by agent
Tagging -- comma-separated tags with filter support
Interfaces
92 HTTP routes (78 unique paths) -- full REST API on 127.0.0.1:9077 (works with any AI or tool)
89 CLI subcommands under --features sal OR --features sal-postgres (87 in the default build) -- complete CLI with identical capabilities
101 MCP tools at full profile (7 default; 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
Distributed coordination (v0.8.0 Pillar-1 + Pillar-2) -- action DAG (memory_action_*), single-holder leases (memory_lease_*), Ed25519-signed signals (memory_signal_*), attested checkpoints (memory_checkpoint_*), parameterised routines (memory_routine_*), and the Goal/Plan/Step typed-cognition lifecycle. See docs/coordination.md.
Operations
Multi-node sync -- pull, push, or bidirectional merge between database files
Import/Export -- full JSON roundtrip preserving memory links
Garbage collection -- automatic background expiry every 30 minutes
Graceful shutdown -- SIGTERM/SIGINT checkpoints WAL for clean exit
Deep health check -- verifies DB accessibility and FTS5 integrity
Shell completions -- bash, zsh, fish
Man page -- ai-memory man generates roff to stdout
Time filters -- --since/--until on list and search
Human-readable ages -- "2h ago", "3d ago" in CLI output
~10,000 tests across the full surface -- roughly 6,712 #[test]/#[tokio::test] attributes under src/ (5,759 #[test] + 953 #[tokio::test]) plus roughly 3,362 under tests/ (2,138 #[test] + 1,224 #[tokio::test]), grown from the v0.6.4-era ~2,400-test baseline (1,960 lib + 211 integration + 16 mcp_integration + 4 webhook_http_parity + 16 recipe_contract + ~150 across other binary targets). Line coverage held above the ≥92% project bar; net-new v0.6.4 modules at 100% (sizes.rs), 99.50% (profile.rs), 97.58% (cli/audit.rs), 97.05% (cli/doctor.rs), 92.56% (handlers.rs), 92.26% (cli/install.rs). v0.6.3.x baselines (1,809 / 93.08% and 1,886 / 93.84%) remain frozen on the evidence page; v0.6.4 metrics in the release notes and on the test-hub campaign. Empirical NHI discovery acceptance proven separately by the Discovery Gate (T1–T4 matrix vs. live xAI Grok 4.3, 6/6 PASS, GATE GREEN).
LongMemEval benchmark -- 97.0% R@5 pure FTS5 keyword (LLM-independent, 2.2 seconds, 232 q/s, zero API costs) on the ICLR 2025 LongMemEval-S dataset; LLM query expansion with the current-generation Gemma 4 model measures 97.2% R@5 / 99.6% R@10 / 99.8% R@20 (cloud-API venue; the historical gemma3:4b 97.8% figure is retired as headline per #1975). See benchmark details.
MCP Prompts -- recall-first and memory-workflow prompts teach AI clients to use memory proactively
TOON-default -- recall/list/search responses use TOON compact by default (79% smaller than JSON)
Criterion benchmarks -- insert, recall, search at 1K scale
GitHub Actions CI/CD -- fmt, clippy, test, build on Ubuntu + macOS, release on tag
Coverage Floor (hard CI gate)
The Code Coverage job is a required status check. CI re-asserts two invariants on every PR: an absolute floor of >= 90% lines (catastrophic-regression backstop, set at the current measurement rounded down to the nearest 5%), and a ratchet against the value pinned in .coverage-baseline with a 0.5% slack window (the day-to-day enforcement). PRs that raise coverage should bump the baseline file in the same commit so future PRs benefit from the new floor; PRs that regress more than 0.5% are blocked from merging. Current measurement: 93.13% lines.
Token-Budget Gate (hard CI gate, v0.7 C5)
The token-budget workflow is a required status check. It enforces three cl100k_base-measured invariants on every PR:
Per-tool ceiling of 1500 tokens -- no single MCP tool's serialized schema (name + description + inputSchema) may exceed 1500 cl100k_base tokens.
Full-profile honest range (5K-8K) -- the v0.6.4 backstop, kept in place to detect pathological shrinkage (accidentally dropping tools).
Full-profile hard ceiling (v0.7 C5, raised post-D1.6/D1.7) -- the trimmed tools/list payload under --profile full may not exceed 11,000 cl100k_base tokens (TRIMMED_FULL_PROFILE_CEILING_TOKENS in tests/token_budget_guard.rs; the original C5 target was 3500 against the pre-D1.6 hand-coded schemas — the schemars-derived D1.6/D1.7 expansion raised the pinned ceiling). C2 (split docs field), C3 (collapse repeated schema boilerplate), and C4 (hide rarely-used optional params) drove the original compaction; this gate forces future PRs that grow the surface to claw back budget elsewhere. Inspect ai-memory doctor --tokens --raw-table to see per-tool costs. See .github/workflows/token-budget.yml and docs/v0.7/schema-compaction-audit.md.
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
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)
Architecture
Benchmark
Evaluated on the ICLR 2025 LongMemEval-S dataset (500 questions, 6 categories). Pure FTS5 keyword tier achieves 97.0% R@5 in 2.2 seconds — LLM-independent, fully local, zero cloud API calls, zero cost. LLM query expansion (smart tier) measures 97.2% R@5 with the current-generation Gemma 4 model (cloud-API venue).
Benchmark-model note (updated 2026-07-10, #1975 ruling): the historical 97.8% R@5 smart-tier figure was measured with Gemma 3 4B (still the compiled default expansion model) and is retired as the headline. The published current-generation anchor is the measured OpenRouter Gemma 4 run: 97.2% R@5 / 99.6% R@10 / 99.8% R@20 (2026-05-31, 500 questions, 0 expansion failures). No local-Ollama Gemma-4 number exists — the reference benchmark host is CPU-only, where a valid full-protocol local run is infeasible (see #1983); a local GPU re-run stays open post-v1.0. The keyword-tier 97.0% R@5 is LLM-independent and unaffected.
Tier
R@5
Speed
Dependencies
keyword
97.0%
232 q/s
None
semantic
97.4%
45 q/s
Embedding model (~100MB)
smart
97.2% (Gemma 4, API venue; historical gemma3:4b 97.8%)
12 q/s
Any LLM backend (e.g. local Ollama + Gemma; or xAI Grok 4.3, OpenAI gpt-5, Anthropic Claude Opus 4.7, Gemini, DeepSeek, etc. post-#1067)
Performance Budgets (v0.6.4)
Every release ships with published p95/p99 budgets for hot-path
operations and a CI gate that fails any PR whose measured p95 exceeds
the budget by more than 10 %. Targets are calibrated for M4 reference
hardware; full table and methodology in
PERFORMANCE.md.
Substrate is unchanged across v0.6.3.x → v0.6.4 (the quiet-tools release ships a smaller default tool surface, not a different hot-path). p99 targets here remain informational pending the next dedicated soak window; latest soak evidence is on the test hub.
Integration Methods
MCP (Primary -- for MCP-compatible AI platforms)
MCP is the recommended integration. Your AI gets 7 native memory tools advertised by default (the original 5 + memory_load_family + memory_smart_load; plus the always-on `memory_capabil
A
Ai Memory
io.github.alphaonedev·57 顆星·
Persistent memory for any AI — zero token cost until recall