# agentmemory Mental Model Wiki

> agentmemory is a persistent, self-managing memory server for AI coding agents — it hooks into any MCP client or agent runtime and automatically stores, searches, decays, and consolidates memories across sessions, requiring zero external databases.

This is a Grok-Wiki source-grounded repository wiki. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown wiki](https://grok-wiki.com/public/wiki/rohitg00-agentmemory-94f173bce1dc/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/wiki/rohitg00-agentmemory-94f173bce1dc.md)
- [Human interactive wiki](https://grok-wiki.com/public/wiki/rohitg00-agentmemory-94f173bce1dc)
- [GitHub repository](https://github.com/rohitg00/agentmemory)

## Repository

- Repository: rohitg00/agentmemory

- Generated: 2026-05-21T07:09:45.903Z
- Updated: 2026-05-21T19:26:20.598Z
- Runtime: Claude Code
- Format: Mental Model
- Pages: 6

## Pages

- [The Mental Model — How agentmemory Thinks](https://grok-wiki.com/public/wiki/rohitg00-agentmemory-94f173bce1dc/pages/01-the-mental-model-how-agentmemory-thinks.md): The 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.
- [Memory Lifecycle — Write, Age, Decay, Forget](https://grok-wiki.com/public/wiki/rohitg00-agentmemory-94f173bce1dc/pages/02-memory-lifecycle-write-age-decay-forget.md): How 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.
- [State Layer & Hybrid Search](https://grok-wiki.com/public/wiki/rohitg00-agentmemory-94f173bce1dc/pages/03-state-layer-hybrid-search.md): All 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.
- [LLM & Embedding Providers — BYOK Design](https://grok-wiki.com/public/wiki/rohitg00-agentmemory-94f173bce1dc/pages/04-llm-embedding-providers-byok-design.md): agentmemory 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.
- [Hooks & MCP — How Agents Connect](https://grok-wiki.com/public/wiki/rohitg00-agentmemory-94f173bce1dc/pages/05-hooks-mcp-how-agents-connect.md): Agents 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.
- [Invariants, Failure Modes & Safe-Change Rules](https://grok-wiki.com/public/wiki/rohitg00-agentmemory-94f173bce1dc/pages/06-invariants-failure-modes-safe-change-rules.md): The 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.

## Source Files

- `iii-config.yaml`
- `README.md`
- `src/cli/connect/claude-code.ts`
- `src/config.ts`
- `src/functions/access-tracker.ts`
- `src/functions/auto-forget.ts`
- `src/functions/consolidation-pipeline.ts`
- `src/functions/crystallize.ts`
- `src/functions/evict.ts`
- `src/functions/graph-retrieval.ts`
- `src/functions/graph.ts`
- `src/functions/migrate-vector-index.ts`
- `src/functions/remember.ts`
- `src/functions/retention.ts`
- `src/health/monitor.ts`
- `src/health/thresholds.ts`
- `src/hooks/post-tool-use.ts`
- `src/hooks/pre-compact.ts`
- `src/hooks/prompt-submit.ts`
- `src/hooks/sdk-guard.ts`
- `src/hooks/session-end.ts`
- `src/hooks/session-start.ts`
- `src/index.ts`
- `src/mcp/server.ts`
- `src/mcp/tools-registry.ts`
- `src/providers/circuit-breaker.ts`
- `src/providers/embedding/index.ts`
- `src/providers/embedding/local.ts`
- `src/providers/fallback-chain.ts`
- `src/providers/index.ts`
- `src/providers/noop.ts`
- `src/providers/resilient.ts`
- `src/state/hybrid-search.ts`
- `src/state/index-persistence.ts`
- `src/state/kv.ts`
- `src/state/reranker.ts`
- `src/state/schema.ts`
- `src/state/search-index.ts`
- `src/state/vector-index.ts`
- `src/triggers/api.ts`
- `src/types.ts`