Keeps every conversation word-for-word and gives your AI agent the right
context on every turn — including the old wording when a fact changes.
Quick start · How it works · Benchmarks · Compatibility · Technical reference
--- ## What it is Your AI agent forgets everything the moment you close the session. iai-memory fixes that, on your own machine. Switch the hooks on and it records both sides of every conversation word-for-word, then feeds the agent the part of your history that matters on every message — not just when a session starts. No memory file to maintain, no “remember this.” When a fact changes, the old one isn't overwritten. The new version is stored and linked back to what it replaced, so you can still pull up both. When something contradicts itself, recall shows you the conflict instead of quietly handing over a stale answer as if it were true. It's memory built around you and one agent — not a memory API for a multi-tenant app, and not a wrapper around someone else's database. What you say is stored once, verbatim, and never rewritten. The store, the search, the graph, the dashboard: all of it runs on your machine. The memory style is autistic by design. It keeps the literal wording instead of smoothing it into a paraphrase, holds onto precise cues, and leaves rare things rare instead of averaging them away. [Why the name](#about-the-name). --- ## Quick start ### Claude Code ```bash python3.12 -m pip install -U iai-pme ``` Then run inside Claude Code: ```text /plugin marketplace add CodeAbra/iai-personal-memory-engine /plugin install iai-memory@iai-pme ``` Restart the session, then verify: ```bash iai --version iai-mcp daemon status iai-mcp doctor ``` Python 3.11 is also supported. ### macOS or Linux: all-in-one source install ```bash curl -fsSL https://raw.githubusercontent.com/CodeAbra/iai-personal-memory-engine/main/scripts/bootstrap.sh | bash ``` This builds the Rust engine and TypeScript wrapper, installs the background service and hooks, registers Claude Code, and runs the health check. It requires Git, Python 3.11/3.12, Node.js 18+, and Rust. To inspect the steps without changing anything: ```bash curl -fsSL https://raw.githubusercontent.com/CodeAbra/iai-personal-memory-engine/main/scripts/bootstrap.sh | bash -s -- --dry-run ``` ### Other hosts ```bash python3.12 -m pip install -U iai-pme iai-mcp crypto init iai-mcp daemon install iai-mcp capture-hooks install --target codex ``` Replace `codex` with `cursor`, `antigravity`, `hermes`, `openclaw`, or `all`. MCP tools work with any MCP-over-stdio client; automatic capture and context injection depend on the hooks exposed by the host. See the [technical reference](https://github.com/CodeAbra/iai-personal-memory-engine/blob/HEAD/docs/REFERENCE.md). New stores use the native engine format by default; an existing store keeps its current format on upgrade. To move an existing legacy SQLite store onto the native engine, run `iai-mcp migrate-to-lilli` — `iai-mcp doctor` prints the exact command, and the [technical reference](https://github.com/CodeAbra/iai-personal-memory-engine/blob/HEAD/docs/REFERENCE.md) documents the full flow. --- ## What happens after installation | Event | Action | |---|---| | Prompt | New turns are appended to a session buffer as file IO; no embedding or engine RPC is needed on the capture path | | Session end | Remaining transcript content is rolled over for ingestion; hook failures do not block the host | | Session start | A bounded memory prefix is exposed as host context; an empty store or unavailable engine yields empty output | | Later turns | Supported hosts receive a small foresight or delta pack with age and revision markers | | Idle time | Captures are embedded, deduplicated, encrypted, inserted, clustered, consolidated, reinforced, and decayed | The background process is called the `daemon` in the CLI. The MCP wrapper and `iai` can still read the local store directly when it is asleep or temporarily unavailable. --- ## How it works ### Memory model | Tier | Contains | |---|---| | **Episodic** | Timestamped, write-once fragments of what was said | | **Semantic** | Summaries induced from related episodes during idle consolidation | | **Procedural** | Ten bounded behavioural parameters learned over time | Distinct hyperdimensional representations keep literal detail, semantic structure, and behavioural tendencies from collapsing into one vector surface. The local, LLM-free recall path combines semantic similarity, graph evidence, recency, temporal validity, and lexical evidence. `memory_recall` returns both `hits` and `anti_hits`; `memory_contradict` closes the old record's validity interval, creates a new record, and links the two. While idle, the engine groups related episodes, induces semantic memory, reinforces useful paths, and decays weak unreviewed edges. One optional REM step may invoke `claude -p` through the user's existing Claude subscription, capped at no more than 1% of the daily quota. No Anthropic API key is required. ### First-party components | Component | Role | |---|---| | **Hippo** | Encrypted records, vector index, and graph in one local store | | **MOSAIC** | Leiden-family community detection with stable community identity | | **Lilli HD** | Hyperdimensional substrate and structural recall | | **Native engine** | Rust embedder and graph kernels | --- ## Dashboard and CLI ```bash iai brain ``` The local dashboard searches the store, exposes graph neighbourhoods and contradictions, pins or fades memories, ingests files, controls the background engine, and reports token-use estimates from your own store. ```text iai recall · temporal-recall · search · ask · capture · teach · upload iai watch · brain · status · last ``` `iai upload` accepts documents, Office files, e-books, source code, configuration files, and directories. Full formats and administrative commands are listed in [`docs/REFERENCE.md`](https://github.com/CodeAbra/iai-personal-memory-engine/blob/HEAD/docs/REFERENCE.md). --- ## Benchmarks Every harness ships in `bench/`; methodology and reproduce commands are in [`BENCHMARKS.md`](https://github.com/CodeAbra/iai-personal-memory-engine/blob/HEAD/BENCHMARKS.md). | Benchmark | Result | |---|---:| | Rescue@10 after contradiction | **1.000** | | Historical-verbatim hit@10 | **1.000** | | LongMemEval-S R@5, product embedder | **0.962** | | LongMemEval-S R@10, product embedder | **0.978** | Historical-verbatim retrieval uses a flat-cosine baseline of about 0.71. With the matched `all-MiniLM-L6-v2` embedder, iai-memory and mempalace v3.3.6 both score R@5 `0.966` and R@10 `0.978`; no win is claimed. On the author's store, an automatically injected memory pack averaged about 350 tokens versus about 2,850 tokens for the agent-search round trip it replaced: approximately 88% cheaper on that measured workload. This does not apply to explicit `memory_recall`, whose default response budget is 1,500 tokens. --- ## MCP tools ```text memory_recall memory_temporal_recall memory_recall_structural memory_search memory_capture memory_contradict memory_reinforce memory_consolidate profile_get_set topology schema_list events_query episodes_recent curiosity_pending ``` Fourteen tools cover cue, temporal, structural, and lexical recall; capture and correction; reinforcement and consolidation; behavioural-profile control; and store introspection. --- ## Compatibility | Host | Ambient behaviour | |---|---| | **Claude Code** | Session-start recall, per-turn updates, turn capture, and session capture | | **Codex CLI** | Full integration through Codex hooks | | **Cursor** | Session-start recall and capture; no per-turn text injection | | **Antigravity** | Recall per invocation and lossless transcript capture | | **Hermes 0.5.0+** | Recall before model calls and capture from its message store | | **OpenClaw** | MCP tools on request; no ambient shell hooks | | **Gemini CLI and other MCP hosts** | MCP tools; no bundled host-specific hooks unless listed above | | **Claude Desktop** | MCP tools; plain Chat does not expose Claude Code-style ambient hooks | --- ## Privacy and limitations - Records are encrypted at rest with AES-256-GCM. The store and key live under `~/.iai-mcp/`; back them up together. - macOS and Linux use a Unix socket. Windows uses an ephemeral loopback port with a per-user token. - There is no iai-memory account, telemetry pipeline, hosted dashboard, or cross-machine sync. - Optional iai-memory network activity is the REM `claude -p` step and a daily PyPI version check. Set `IAI_MCP_VERSION_CHECK=0` to disable the check. - The store refuses to mix incompatible embedding generations; changing the embedder requires an explicit migration. - Recall is usually mediocre during roughly the first ten sessions, and quality and latency depend on corpus size, language, embedder, and stored history. - The default store is English-first. Raw non-English records require an explicit `raw: