ai-memory Glossary

Every concept in the system, with a single-paragraph definition and a pointer to authoritative documentation.

Agent

A caller of ai-memory. Identified by agent_id. Can be a human, an AI model (e.g. ai:claude-opus-4.7), or an automated system. Each stored memory carries metadata.agent_id for attribution. See Agent Identity (NHI).

Agent Identity (NHI)

Non-Human Identity marker stamped on every memory. A claimed identity (not attested). Follows the regex ^[A-Za-z0-9_\-:@./]{1,128}$. Resolution precedence: explicit flag → env var → MCP client info → process-stable host fallback → anonymous. Once stored, immutable across update / upsert / import / sync / consolidate. See CLAUDE.md § “Agent Identity (NHI)”.

Attested identity (v0.7.0)

An identity that is cryptographically proven rather than merely claimed. Two surfaces at v0.7.0: (1) store-path attestation (#626 Layer-3) — a write presenting a valid detached Ed25519 signature over the SignableWrite envelope lands metadata.attest_level = "agent_attested" instead of "claimed"; AI_MEMORY_REQUIRE_AGENT_ATTESTATION=1 rejects unsigned writes. (2) link/event attestation — every memory_links row and signed event carries an attest_level from the five-variant enum (src/models/link.rs::AttestLevel): unsigned, self_signed, peer_attested, signed_by_peer (L4 memory_capture_turn host-signed), daemon_signed (substrate-signed audit rows). Cert-SAN agent-id attestation on the federation receive path is tracked under #717 for v0.8.

Autonomy hooks (v0.6.0.0)

Synchronous post-store LLM invocations — auto_tag + detect_contradiction — that fire on every successful memory_store when AI_MEMORY_AUTONOMOUS_HOOKS=1. Results persist into metadata.auto_tags and metadata.confirmed_contradictions. Off by default because they add ~1–5 s of Ollama latency.

Backup / restore

Hot-backup-safe snapshot via SQLite VACUUM INTO plus a sha256 manifest. ai-memory backup --to <dir> --keep N for retention; ai-memory restore --from <path> with manifest verification.

Chaos harness

packaging/chaos/run-chaos.sh — runs 200 cycles per fault class against a 3-node Postgres-backed deployment to measure convergence bound. Four fault classes: kill_primary_mid_write, partition_minority, drop_random_acks, clock_skew_peer. Outputs a JSONL convergence-bound report, not a loss probability. Methodology: docs/ADR-0001-quorum-replication.md + docs/RUNBOOK-chaos-campaign.md.

Confidence

confidence field on a memory. Float in [0.0, 1.0]. Default 1.0. Affects recall scoring (higher = ranks higher). The autonomous forget pass requires a superseder to have equal or higher confidence before archiving the older memory.

Consolidate

Merge multiple memories into one long-term summary. Sources are archived (not lost); the consolidated memory carries derived_from links to each source. Available as ai-memory consolidate, memory_consolidate (MCP), and POST /api/v1/consolidate.

Curator (v0.6.1)

Autonomous background process (ai-memory curator). Runs the full autonomy loop: auto-tag → detect-contradiction → consolidate → forget-superseded → priority-feedback → rollback-log → self-report. Opt-in via CLI or the ai-memory-curator.service systemd unit.

Curator rollback log

_curator/rollback/<ts> memories that record every autonomous action as a reversible snapshot. Reverse with ai-memory curator --rollback <id> or --rollback-last N. Once reversed, entries are tagged _reversed — audit trail preserved.

Feature tier

Controls which AI capabilities are active based on available memory budget. keyword (FTS5 only, minimal), semantic (MiniLM + HNSW, ~256 MB), smart (+ LLM-backed expansion/auto-tag/contradiction, ~1 GB with local Ollama or ~256 MB with a remote backend), autonomous (+ cross-encoder reranking, ~4 GB local). Post-#1067 the LLM is provider-agnostic (AI_MEMORY_LLM_BACKEND — Ollama, xAI, OpenAI, Anthropic, Gemini, etc.). Set per-invocation (--tier on mcp/store/recall) or via config.toml for the daemon. See docs/ADMIN_GUIDE.md.

Federation

Opt-in multi-agent replication layer (v0.7, PR #282). Configured via ai-memory serve --quorum-writes N --quorum-peers URL,URL. Every HTTP write fans out to peers; returns 201 only on W-1 peer acks within --quorum-timeout-ms. Otherwise returns 503 quorum_not_met.

FTS5

SQLite’s full-text search extension. Powers keyword search over (title, content, tags) (the memories_fts virtual table). Always enabled regardless of feature tier — it’s the default recall mechanism for keyword and the first stage of hybrid recall for semantic+.

Governance

The mechanism that enforces approval policies on writes. Set via namespace_set_standard (MCP) or governance config. Actions that require approval return 202 Accepted with a pending_id; approvers post to /api/v1/pending/{id}/approve. Consensus gates require N distinct registered agents.

HNSW

Hierarchical Navigable Small World — the approximate nearest-neighbor index used for semantic recall. In-process by default (instant-distance crate). Postgres backend (#279) uses pgvector’s native HNSW instead.

Hybrid recall

The default recall mode. Combines FTS5 keyword scoring, semantic cosine similarity via HNSW, priority/confidence/recency/tier boosts. Adaptive blending weights semantic (0.50 for short content ≤500 chars) → keyword (0.15 for long content ≥5000 chars) because embeddings lose information on long text.

MCP (Model Context Protocol)

Anthropic’s JSON-RPC protocol for AI-tool integration. ai-memory ships an MCP server via ai-memory mcp exposing 101 advertised entries at --profile full (100 callable “memory tools” + the always-on memory_capabilities bootstrap — both numbers are intentional; see issue #862) plus 2 prompts over stdio. Default --profile core exposes 7 tools (the original 5 + memory_load_family + memory_smart_load) plus the always-on bootstrap. Works with Claude Code, Claude Desktop, Cursor, Codex, Grok, Gemini, Llama Stack. See docs/USER_GUIDE.md.

Memory

The core data unit. A 28-field record at v0.9.0 (27 at v0.8.0, 26 at v0.7.0, was 15 at v0.6.x; the 27th field is lifecycle_state, the v0.8.0 Pillar-2 #1709 typed-cognition state machine, schema v64; the 28th field is cid, the v0.9.0 G8 #1825 additive BLAKE3 content-id, schema v74) — adds reflection_depth (Task 1/8 recursive-learning), memory_kind (Batman Form-6 vocabulary), entity_id/persona_version (QW-2 persona artefact), citations/source_uri/source_span (Form-4 fact provenance), confidence_source/confidence_signals/confidence_decayed_at (Form-5 calibration), and version (schema v45 Gap-1 optimistic concurrency). Original v0.6.x fields still present: id, tier, namespace, title, content, tags, priority, confidence, source, access_count, timestamps, expires_at, metadata. (title, namespace) is a unique key — storing a duplicate upserts. Canonical truth in src/models/memory.rs. See docs/DEVELOPER_GUIDE.md § “Data Model”.

Memory link

A typed relationship between two memories. Nine kinds at v0.8.0 (six at v0.7.0, was four at v0.6.x): related_to, supersedes, contradicts, derived_from, reflects_on (recursive-learning Task 1/8), derives_from (WT-1-A atomisation), and the v0.8.0 Pillar-2 typed-cognition trio decomposes_into / depends_on / advances (#1709, closed-taxonomy CHECK extended 6→9 at schema v63). Used by consolidate (to track provenance) and the curator (to mark contradictions).

Namespace

String partition for memories. Typical use: one namespace per project or per agent. Reserved prefix _ (e.g. _messages/<target>, _curator/reports, _agents) is for system use — the curator ignores _-prefixed namespaces.

Post-store hook

See Autonomy hooks.

Priority

Integer 1–10 on a memory. Default 5. Higher values rank higher on recall. The curator’s priority-feedback pass nudges this: +1 (cap 10) for memories with access_count ≥ 10 last accessed within 7 days; −1 (floor 1) for never-accessed memories older than 30 days.

Quorum (W-of-N)

Federation write contract from ADR-0001. N = peer count, W = how many peers must ack before the write returns OK. The operator sets W explicitly via --quorum-writes (default 0 = federation off); the QuorumPolicy::majority convenience targets a simple majority.

Recall

Query operation that returns memories matching a natural-language context. Semantics: semantic + keyword + priority/confidence/recency blend. Mutates the DB: increments access_count, extends TTL, promotes mid→long at 5 accesses, nudges priority every 10 accesses.

SAL — Storage Abstraction Layer (v0.7)

Trait-based storage boundary (MemoryStore, src/store/). Adapters: SqliteStore (default), PostgresStore (pgvector-backed, under --features sal-postgres; GA at v0.7.0). Migration via ai-memory migrate --from … --to …; run the daemon against Postgres with ai-memory serve --store-url postgres://…. See docs/RUNBOOK-adapter-selection.md.

Scope (Task 1.5)

Visibility semantics for multi-agent recall. Stored as metadata.scope on a memory. Values: private (default), team, unit, org, collective. Combined with --as-agent at recall time: an agent in ai-memory-mcp namespace sees private memories only in that exact namespace; team memories in the parent subtree; unit in the grandparent; org anywhere in the org’s namespace tree; collective everywhere.

Source

String tag on a memory indicating where it came from. Canonical allowlist (VALID_SOURCES in src/validate.rs): user, nhi (v0.7.x vendor-neutral NHI default), claude (deprecated back-compat, removal in v0.8.x), hook, api, cli, import, consolidation, system, chaos, notify. Used by admins for filtering and by the curator to avoid recursive tagging of its own outputs.

Sync-daemon

Background peer-to-peer knowledge mesh (pre-v0.7 primitive, still shipped). Configured via ai-memory sync-daemon --peers URL,URL. Pulls and pushes periodically (eventual consistency); no quorum, no synchronous acks. For synchronous quorum writes use serve --quorum-writes (v0.7).

Tier

short (6 h TTL), mid (7 d TTL, default), long (permanent). Tier is monotonic — never downgrades. Promotion happens manually (ai-memory promote) or automatically after 5 recalls.

TOON

Token-efficient JSON alternative format (toon.rs module). 40–60% smaller than JSON for the same payload. Used optionally in MCP tool responses when format: "toon" or "toon_compact" is requested.

TTL (Time-To-Live)

Seconds until a memory expires. Set by tier default or explicitly via --ttl-secs / --expires-at. Extended on recall. GC removes expired memories every 30 minutes by default.

Upsert

(title, namespace) collision behaviour. Storing a memory whose (title, namespace) matches an existing row updates that row in-place. Tier is never downgraded. Original metadata.agent_id is preserved.

Vector clock

Lamport-style causal timestamp the sync-daemon exchanges to avoid double-applying updates. Stored in sync_state table.