agentmemory Mental Model Wiki

Pages

1. The Mental Model — How agentmemory ThinksThe simplest useful model of the system: one long-lived Node process (the iii worker) owns all state, every agent interaction flows through REST or MCP, and memories are first-class objects with confidence scores, TTLs, and graph relationships — not raw text logs.
2. Memory Lifecycle — Write, Age, Decay, ForgetHow a memory is born (mem::remember), enriched with concepts and graph edges, ages through hot/warm/cold retention tiers via exponential decay, and is eventually evicted or crystallized into long-term patterns — all driven by access frequency, TTL, and consolidation pipelines.
3. State Layer & Hybrid SearchAll persistent data lives in the iii-engine KV store (StateKV wrapping state::get/set/list triggers); reads go through HybridSearch which fuses BM25 (weight 0.4), vector cosine (weight 0.6), and graph traversal (weight 0.3) via Reciprocal Rank Fusion, with an optional reranker pass on top.
4. LLM & Embedding Providers — BYOK Designagentmemory is fully provider-neutral: LLM calls (summarize, compress, graph-extract) route through a resilient fallback chain across Anthropic, OpenAI, OpenRouter, MiniMax, or a noop stub; embeddings (text and image/CLIP) are independently switchable across OpenAI, Cohere, Gemini, Voyage, or a local Xenova model — the system degrades to BM25-only if no embedding key is set.
5. Hooks & MCP — How Agents ConnectAgents connect via two surfaces: (1) MCP server exposing 53 tools over stdio or HTTP transport, and (2) shell hooks (prompt-submit, post-tool-use, session-start/end, pre-compact, stop) that fire as thin HTTP POSTs to the local REST API at :3111 — the hooks are agent-installed scripts that bridge the agent runtime event stream into the memory server without requiring code changes inside the agent.
6. Invariants, Failure Modes & Safe-Change RulesThe core invariants: state lives exclusively in iii-engine (no local SQLite or Postgres required); the worker suppresses unhandledRejection to survive iii SDK 30s timeouts under write bursts; BM25 index is always present so search never fully fails; circuit-breakers isolate provider outages; and the sdk-guard hook prevents recursive hook invocations. Safe-change rules: embedding dimension changes require index migration; adding a new function requires both registerXxx in index.ts and a tools-registry entry; provider fallback order is config-driven, not hardcoded.