ai-memory · Feature Matrix — every tool, endpoint, command

4 Operational Modes

One binary. Four ways to run it.

Same Rust binary, four startup mode flags. The mode determines which IPC surface is active and which background loops run. Switch by changing one CLI flag — no config file edits required.

📡

MODE 1 · Foreground stdio

MCP server

ai-memory mcp --tier semantic

JSON-RPC over stdio. Spawned by Claude Code, Cursor, Codex, etc. as a subprocess. Lives the lifetime of the host AI session.

🌐

MODE 2 · Background daemon

HTTP daemon

ai-memory serve --port 9077 --mtls-cert ...

REST + SSE on TCP. mTLS-aware with fingerprint allowlist. Federation peers reach this surface. Shared multi-client server.

🔁

MODE 3 · Background daemon

Sync daemon

ai-memory sync-daemon --peers https://node-2,https://node-3

Periodic pull-and-push against peers. W-of-N quorum. Each cycle exchanges memories observed since last cursor.

🤖

MODE 4 · Background daemon

Curator daemon

ai-memory curator --daemon --interval-secs 1800 --tier autonomous

Auto-tag, contradiction detection, consolidation. Tier-gated: smart adds LLM tagging, autonomous adds rerank + auto-merge.

43 MCP Tools

Every tool a host AI can call.

Auto-discovered by Claude Code, Cursor, Codex, Continue, Gemini CLI, Windsurf, and any MCP-compliant client. Tool names follow memory_<verb> convention.

READ — recall, search, list

WRITE — store, update, delete

ADMIN — stats, capabilities, gc

KG — knowledge graph

FED — federation / subscriptions

GOV — governance / pending

▸ READ

memory_recall

Hybrid recall: FTS5 + HNSW vector + cross-encoder rerank. The agent reasoning hot-path.

context, namespace?, limit?, tags?, since?, until?, tier?, as_agent?, budget_tokens?, context_tokens?[]

▸ READ

memory_search

Pure FTS5 keyword search with BM25 ranking. Faster than recall, no vector cost.

query, namespace?, tier?, limit?, tags?, since?, until?, agent_id?

▸ READ

memory_get

Fetch a single memory by ID (full or 8-char prefix). Includes outbound links.

▸ READ

memory_list

Paginated list with namespace / tier / tags filters. Backfills HNSW for unembedded memories on read.

namespace?, tier?, limit?, offset?, since?, until?, tags?, agent_id?

▸ READ

memory_get_taxonomy

Hierarchical namespace tree with per-node memory counts. Rooted at any prefix.

namespace_prefix?, depth?, limit?

▸ READ

memory_check_duplicate

Pre-write similarity check. Returns nearest-neighbor cosine + above-threshold flag.

title, content, namespace, threshold?

▸ READ

memory_get_links

All inbound and outbound typed links for a memory. Filters on relation type.

memory_id, relation?, direction?

▸ READ

memory_inbox

Pending notifications addressed to this agent. Marks-as-read on read.

since_cursor?, namespace?, limit?

▸ WRITE

memory_store

Insert with tier (short/mid/long), tags, priority 1-10, confidence 0-1, scope, expires_at.

title, content, namespace, tier?, tags?, priority?, confidence?, source?, scope?, expires_at?

▸ WRITE

memory_update

Patch existing memory. Same-source allowed; cross-source warns (governance gate).

id, title?, content?, tags?, priority?, confidence?, expires_at?

▸ WRITE

memory_delete

Single-memory soft delete to archive tier. Recoverable via restore.

▸ WRITE

memory_promote

Tier promotion: short → mid → long, or hierarchical-vertical (clone into ancestor namespace).

id, to_namespace?

▸ WRITE

memory_forget

Bulk delete by namespace / pattern / tier. Always governance-gated. Wide blast radius.

namespace?, pattern?, tier?, dry_run?

▸ WRITE

memory_consolidate

Merge N memories into 1. Creates derived_from links. Sources soft-archived.

ids[], title, summary, namespace?

▸ WRITE

memory_link

Create typed link. Relation: related_to / supersedes / refines / contradicts / derived_from / etc.

source_id, target_id, relation?

▸ WRITE

memory_notify

Send a notification message to another agent's inbox. A2A primitive.

target_agent_id, title, payload

▸ KG

memory_kg_query

Recursive CTE traverse. Time / scope / observed-by filters. Cycle detection. Up to depth 5.

source_id, max_depth?, valid_at?, allowed_agents?[]

▸ KG

memory_kg_timeline

Ordered fact timeline for an entity. Each event has valid_from / observed_by metadata.

entity_id, since?, until?, limit?

▸ KG

memory_kg_invalidate

Mark a link superseded by setting valid_until. Original link history preserved.

link_id, valid_until, reason?

▸ KG

memory_entity_register

canonical_name, namespace, aliases?[], metadata?

▸ KG

memory_entity_get_by_alias

Resolve any alias back to canonical entity. Powers fuzzy-match lookups.

alias, namespace?

▸ ADMIN

memory_capabilities

Self-describing introspection. Schema v2 reports tier, models, tools, hooks (planned), permissions.

— (no parameters)

▸ ADMIN

memory_stats

Per-namespace counts, tier breakdown, total bytes, oldest/newest timestamps.

namespace?

▸ ADMIN

memory_session_start

Returns recent context + session_id. The Claude Code hook critical path. Sub-100ms p95.

agent_id?, namespace?, limit?

▸ ADMIN

memory_gc

Manual GC trigger. Sweeps expired short-tier memories per archive_on_gc policy.

— (no parameters)

▸ ADMIN

memory_namespace_*

3 tools: get_standard / set_standard / clear_standard. Per-namespace policy + governance hooks.

namespace, standard?

▸ FED

memory_subscribe

url, events?[], namespace_filter?, secret?

▸ FED

memory_unsubscribe

Remove a webhook subscription by ID.

subscription_id

▸ FED

memory_list_subscriptions

Active subscriptions with dispatch_count and failure_count counters.

— (no parameters)

▸ GOV

memory_pending_list

List pending governance-gated actions awaiting human approval. Filter by status.

status?, namespace?

▸ GOV

memory_pending_approve

Approve a pending action. Executes the deferred operation.

pending_id

▸ GOV

memory_pending_reject

Reject a pending action with reason. Operation discarded.

pending_id, reason?

▸ GOV

memory_agent_register

agent_id, agent_type, capabilities?[]

▸ GOV

memory_agent_list

List registered agents with last_seen_at timestamps.

— (no parameters)

▸ GOV

memory_detect_contradiction

LLM-powered contradiction detection across recent memories. Smart+ tier only.

topic?, namespace?, limit?

▸ GOV

memory_auto_tag

Suggest tags for a memory via local LLM. Smart+ tier only. Returns tag list.

memory_id

▸ GOV

memory_expand_query

LLM-rewrite a query into related terms. Smart+ tier only. Powers query-time expansion.

query

50 HTTP Endpoints

REST surface for services + federation peers.

Axum-served. mTLS-aware. CORS layer. Prometheus metrics at /metrics. Body limit 2 MiB. Trace spans on every request. The same operations as MCP, plus federation-private peer endpoints.

Method	Path	Purpose
GET	/api/v1/health	Liveness check. Always returns 200.
GET	/metrics	Prometheus scrape (community convention path).
GET	/api/v1/metrics	Prometheus scrape (REST-consistent path).
GET	/api/v1/capabilities	Self-describing introspection.
GET	/api/v1/stats	Per-namespace counts + tier breakdown.
— Memory CRUD —
GET	/api/v1/memories	List memories, paginated, filter.
POST	/api/v1/memories	Create new memory.
POST	/api/v1/memories/bulk	Bulk insert with partial-success semantics.
GET	/api/v1/memories/{id}	Fetch one memory by ID.
PUT	/api/v1/memories/{id}	Update existing memory.
DELETE	/api/v1/memories/{id}	Soft-delete to archive tier.
POST	/api/v1/memories/{id}/promote	Tier promotion or vertical hierarchy clone.
— Search & recall —
GET	/api/v1/search	FTS5 keyword search.
GET	/api/v1/recall	Hybrid recall (GET form for cacheability).
POST	/api/v1/recall	Hybrid recall (POST form for large payloads).
POST	/api/v1/forget	Bulk delete by query.
POST	/api/v1/consolidate	Merge N memories into 1.
GET	/api/v1/contradictions	List detected contradiction pairs.
GET	/api/v1/check_duplicate	Pre-write similarity check.
— Knowledge graph —
POST	/api/v1/links	Create typed link.
DELETE	/api/v1/links	Delete a link.
GET	/api/v1/links/{id}	Fetch one link.
GET	/api/v1/taxonomy	Hierarchical namespace tree.
GET	/api/v1/kg/timeline	Ordered fact timeline for an entity.
POST	/api/v1/kg/invalidate	Set valid_until on a link.
POST	/api/v1/kg/query	Recursive-CTE outbound traversal.
— Entities (Stream B) —
POST	/api/v1/entities	Register entity with aliases.
GET	/api/v1/entities/by_alias	Resolve alias → canonical entity.
— Namespace policy —
GET	/api/v1/namespaces	List namespaces (or get standard via ?namespace=).
POST	/api/v1/namespaces	Set namespace standard (query-string form).
DELETE	/api/v1/namespaces	Clear namespace standard (query-string form).
GET	/api/v1/namespaces/{ns}/standard	Get standard (path form, MCP parity).
POST	/api/v1/namespaces/{ns}/standard	Set standard (path form).
DELETE	/api/v1/namespaces/{ns}/standard	Clear standard (path form).
— Archive & GC —
GET	/api/v1/archive	List archived memories.
POST	/api/v1/archive	Bulk archive by IDs.
DELETE	/api/v1/archive	Hard purge archived > N days old.
POST	/api/v1/archive/{id}/restore	Restore archived to original tier.
GET	/api/v1/archive/stats	Archive size + age histogram.
POST	/api/v1/gc	Manual GC trigger.
GET	/api/v1/export	JSON dump of all memories + links.
POST	/api/v1/import	Bulk JSON import.
— Federation peer-private —
POST	/api/v1/sync/push	Peer pushes a batch.
GET	/api/v1/sync/since	Peer pulls since cursor.
— Subscriptions & A2A —
POST	/api/v1/notify	Send notification to agent inbox.
GET	/api/v1/inbox	Read pending notifications.
POST	/api/v1/subscriptions	Register webhook.
DELETE	/api/v1/subscriptions	Unsubscribe.
GET	/api/v1/subscriptions	List active subscriptions.
POST	/api/v1/session/start	Initialize agent session.
— Agents & pending —
GET	/api/v1/agents	List registered agents.
POST	/api/v1/agents	Register agent.
GET	/api/v1/pending	List pending governance actions.
POST	/api/v1/pending/{id}/approve	Approve pending action.
POST	/api/v1/pending/{id}/reject	Reject pending action.

40 CLI Commands

For humans, scripts, and CI.

Direct subcommands of the ai-memory binary. No daemon required for read/write commands. Run against any database file via --db <path>.

$ ai-memory recall "context" [--namespace ns --limit N --tier ...]

Hybrid recall from a namespace.

$ ai-memory search "query" [--namespace ns --tier ...]

FTS5 keyword search.

$ ai-memory get id-or-prefix

Fetch one memory.

$ ai-memory list [--namespace ns --tier ... --limit N --offset M]

Paginated listing.

$ ai-memory stats [--namespace ns]

DB summary or per-namespace.

$ ai-memory namespaces

All namespaces with counts.

$ ai-memory store --title "..." --content "..." [--namespace ns --tier long --priority 8]

Create memory. --content - reads stdin.

$ ai-memory update id-or-prefix [--title --content --priority ...]

Patch existing memory.

$ ai-memory delete id-or-prefix

Soft-delete to archive.

$ ai-memory forget [--namespace ns --pattern "*" --tier ...]

Bulk delete by filter.

$ ai-memory promote id [--to-namespace path]

Tier promotion or hierarchical clone.

$ ai-memory link src tgt [--relation related_to]

Create typed link.

$ ai-memory resolve winner_id loser_id

Mark one memory as superseding another.

$ ai-memory consolidate --ids id1,id2,id3 --title "..." --summary "..."

Merge memories.

$ ai-memory auto-consolidate --namespace ns --min-count 5

Threshold-based group-and-merge.

$ ai-memory gc

Manual GC sweep.

$ ai-memory archive [list --restore id --purge --older-than 90]

Manage archived memories.

$ ai-memory backup [--out path/]

SQLite VACUUM INTO + manifest.json.

$ ai-memory restore --from path/file.db [--skip-verify]

Restore from backup with sha256 verify.

$ ai-memory export

JSON dump to stdout (memories + links).

$ ai-memory import [--trust-source]

JSON import from stdin.

$ ai-memory mine --input claude-export.zip [--dry-run]

Import from Claude/ChatGPT/Slack export.

$ ai-memory bench [--baseline path.json]

Canonical workload + p50/p95/p99 vs PERFORMANCE.md.

$ ai-memory mcp --tier semantic

Start MCP stdio server.

$ ai-memory serve --port 9077 [--tls-cert ... --quorum-w 2]

Start HTTP daemon.

$ ai-memory sync --peers https://... [--dry-run]

One-shot sync against peers.

$ ai-memory sync-daemon --peers https://... --interval-secs 60

Continuous sync loop.

$ ai-memory curator [--once | --daemon] [--dry-run]

Curator pass: tag/contradict/consolidate.

$ ai-memory agents [register --type ai:claude | list]

Agent registry.

$ ai-memory pending [list | approve id | reject id]

Manage governance queue.

$ ai-memory shell

Interactive REPL with all subcommands.

$ ai-memory completions shell

Generate bash/zsh/fish/pwsh completions.

$ ai-memory man

Generate manpage.

Cross-reference

One operation, three protocol fronts.

For each logical operation, here's the MCP tool, the HTTP endpoint, and the CLI command. Every row maps to the same underlying handler in src/db.rs — three protocol fronts, one source of truth.

Operation	MCP Tool	HTTP Endpoint	CLI Command
Hybrid recall	memory_recall	GET /api/v1/recall	recall <ctx>
Keyword search	memory_search	GET /api/v1/search	search <q>
Get one	memory_get	GET /api/v1/memories/{id}	get <id>
List	memory_list	GET /api/v1/memories	list
Store	memory_store	POST /api/v1/memories	store --title --content
Bulk store	via multiple stores	POST /api/v1/memories/bulk	import (stdin JSON)
Update	memory_update	PUT /api/v1/memories/{id}	update <id>
Delete	memory_delete	DELETE /api/v1/memories/{id}	delete <id>
Promote	memory_promote	POST /api/v1/memories/{id}/promote	promote <id>
Bulk forget	memory_forget	POST /api/v1/forget	forget --pattern
Consolidate	memory_consolidate	POST /api/v1/consolidate	consolidate --ids
Detect contradiction	memory_detect_contradiction	GET /api/v1/contradictions	via curator
Check duplicate	memory_check_duplicate	GET /api/v1/check_duplicate	via store --check
Create link	memory_link	POST /api/v1/links	link <src> <tgt>
Get links	memory_get_links	GET /api/v1/links/{id}	via get (auto-includes)
Taxonomy	memory_get_taxonomy	GET /api/v1/taxonomy	via stats
KG query	memory_kg_query	POST /api/v1/kg/query	via shell
KG timeline	memory_kg_timeline	GET /api/v1/kg/timeline	via shell
KG invalidate	memory_kg_invalidate	POST /api/v1/kg/invalidate	resolve <winner> <loser>
Register entity	memory_entity_register	POST /api/v1/entities	via store + tag
Resolve alias	memory_entity_get_by_alias	GET /api/v1/entities/by_alias	via search
Stats	memory_stats	GET /api/v1/stats	stats
Capabilities	memory_capabilities	GET /api/v1/capabilities	via stats --json
Session start	memory_session_start	POST /api/v1/session/start	N/A
GC	memory_gc	POST /api/v1/gc	gc
Archive list	via list + filter	GET /api/v1/archive	archive list
Archive restore	via promote	POST /api/v1/archive/{id}/restore	archive restore --id
Archive purge	via forget	DELETE /api/v1/archive	archive purge --older-than
Export	via list bulk	GET /api/v1/export	export
Import	via store batch	POST /api/v1/import	import
Subscribe	memory_subscribe	POST /api/v1/subscriptions	via shell
Unsubscribe	memory_unsubscribe	DELETE /api/v1/subscriptions	via shell
List subs	memory_list_subscriptions	GET /api/v1/subscriptions	via shell
Notify	memory_notify	POST /api/v1/notify	via shell
Inbox	memory_inbox	GET /api/v1/inbox	via shell
Register agent	memory_agent_register	POST /api/v1/agents	agents register
List agents	memory_agent_list	GET /api/v1/agents	agents list
Pending list	memory_pending_list	GET /api/v1/pending	pending list
Pending approve	memory_pending_approve	POST /api/v1/pending/{id}/approve	pending approve <id>
Pending reject	memory_pending_reject	POST /api/v1/pending/{id}/reject	pending reject <id>
Sync push (peer)	peer-private	POST /api/v1/sync/push	peer-private
Sync since (peer)	peer-private	GET /api/v1/sync/since	peer-private

The complete surface area.

One binary. Four ways to run it.

Every tool a host AI can call.

REST surface for services + federation peers.

For humans, scripts, and CI.

One operation, three protocol fronts.