# Iai Personal Memory Engine > MCP memory server for AI coding assistants. Works with Claude Code, Cursor, Codex, Gemini CLI, Cline, Continue, Cherry Studio, Zed, Hermes, OpenClaw, and any MCP client. Local, encrypted, verbatim recall. MIT. - **Type:** MCP server - **Install:** `agentstack add mcp-codeabra-iai-personal-memory-engine` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [CodeAbra](https://agentstack.voostack.com/s/codeabra) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [CodeAbra](https://github.com/CodeAbra) - **Source:** https://github.com/CodeAbra/iai-personal-memory-engine ## Install ```sh agentstack add mcp-codeabra-iai-personal-memory-engine ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About **English** | [中文](./README_zh-CN.md) The best open-source personal memory engine for AI coding assistants. Every claim ships with the harness that proves it. Run the benchmarks yourself. Persistent memory for any MCP client. Local, encrypted, verbatim recall via vector search + knowledge graph. MIT. --- # iai-pme **Your AI assistant forgets you every session. iai-pme gives it a memory that doesn't.** *Independent Autistic Intelligence — a personal memory engine. Fully local, ambient. Works with Claude Code, Claude Desktop, Cursor, Codex CLI, Gemini CLI, Cline, Continue.dev, Zed, Cherry Studio, Goose, Aider, Hermes, OpenClaw, Le Chat, Kimi — anything that speaks MCP-over-stdio.* ## Table of contents - [What it is](#what-it-is) - [Quick start](#quick-start) - [Usage](#usage) - [How it works](#how-it-works) - [Built our own](#built-our-own) - [Benchmarks](#benchmarks) - [Configuration](#configuration) - [Doctor](#doctor) - [Notes for AI assistants](#notes-for-ai-assistants-helping-with-installation) - [Status and limitations](#status-and-limitations) - [Compatibility](#compatibility) - [About the name](#about-the-name) - [Authors](#authors) - [License](#license) - [Contributing](#contributing) --- ## What it is A local server that speaks the [MCP protocol](https://modelcontextprotocol.io) and gives Claude, and any other MCP-compatible assistant, a long-term memory. It captures every turn of every session verbatim, organizes those captures over time into a personal map of who you are, and serves a small slice of relevant memory back at the start of each new conversation. You never have to say *"remember this"* or *"what did we say last time?"*. I built this for myself. It worked. I've been running it daily for months, and now I'm sharing it. The benchmarks were mostly for my own curiosity. I wanted to know if it actually works or if I'd just gotten used to it. Under the hood it's not a wrapper around someone else's vector store and graph library — the parts that matter are my own code: the storage engine, the community-detection algorithm, the hyperdimensional memory substrate, and a native engine that makes it fast. More on that in [Built our own](#built-our-own). And unlike cloud memory services, there's no API key, no account, and no telemetry: the engine, the store, and the embeddings all run locally. The only thing that leaves your machine is the normal model call your CLI already makes. --- ## Pick your path | | | | |---|---|---| | **🟢 Just want it to work?** | **🔵 Want the numbers?** | **🟣 Want the internals?** | | Install once, then forget it's there — no commands, fully local. | Every claim ships with the harness that proves it — run them yourself. | We built our own storage engine, clustering, HD substrate and Rust core. | | → [Quick start](#quick-start) | → [Benchmarks](#benchmarks) | → [Built our own](#built-our-own) | --- ## Quick start ### Prerequisites - macOS (Apple Silicon), Linux, or Windows (beta) - Python 3.11 or 3.12 - Node.js 18+ - A Rust toolchain — the native engine builds from source - An MCP-compatible CLI host — [Claude Code](https://docs.claude.com/en/docs/claude-code/overview), Codex CLI, Gemini CLI, Cursor CLI, and others - ~500 MB free disk macOS and Linux are fully supported. **Windows support is in beta** — the runtime is ported and validated on Windows 11, but the test suite is still being ported, so treat it as experimental. Contributions are very welcome: if you hit a Windows issue, open an issue or PR and I'll help however I can. ### Install ```bash git clone https://github.com/CodeAbra/iai-personal-memory-engine.git cd iai-personal-memory-engine python3.12 -m venv .venv && source .venv/bin/activate pip install . ``` `pip install` builds the native Rust engine (`iai_mcp_native` — the embedder + graph kernels) automatically, as part of the package build, via `setuptools-rust`. There's no separate build script. If you change the Rust source later and need to rebuild it by hand, there's an escape hatch: ```bash iai-mcp build-native # rebuild the native engine in place ``` Then build the MCP wrapper and set up the local engine (it runs in the background): ```bash cd mcp-wrapper && npm install && npm run build && cd .. iai-mcp daemon install # launchd on macOS, systemd on Linux, Task Scheduler on Windows iai --version ``` ### Install the capture + recall hooks This is what makes memory ambient. Without these hooks iai-mcp reads memory but never writes conversation content and never injects recall at session start. One command wires all three: ```bash iai-mcp capture-hooks install # copies all three hooks + patches ~/.claude/settings.json iai-mcp capture-hooks status # verify: should print "status: ACTIVE" iai-mcp capture-hooks uninstall # clean removal if ever needed ``` For Codex: ```bash iai-mcp capture-hooks install --target codex ``` To install both: ```bash iai-mcp capture-hooks install --target all ``` What the install does: - Copies three hook scripts bundled with the package to `~/.claude/hooks/` (chmod +x): - `iai-mcp-turn-capture.sh` (`UserPromptSubmit`, timeout 5s) — appends each prompt + the preceding assistant turn(s) to a per-session buffer as pure file IO. Zero engine RPC during the session. - `iai-mcp-session-capture.sh` (`Stop`, timeout 35s) — at session end, rolls the buffer over for the local engine to drain, and runs `iai-mcp capture-transcript --no-spawn` as a safety net. - `iai-mcp-session-recall.sh` (`SessionStart`, timeout 30s) — calls `iai-mcp session-start` and pipes the assembled memory prefix to stdout, which Claude Code injects as `additionalContext` before the first prompt. Fail-safe: empty store or unreachable local engine yields empty stdout — session start is never blocked. - Registers iai-mcp in Claude Desktop's config if installed. - Idempotent — re-running detects existing entries and makes no changes. - No secrets, no tokens, no network calls. What happens at runtime: - **Every prompt** (per-turn hook): appends new transcript turns to the session buffer. ~5 ms per turn, no embedding, no engine socket. - **Every session end** (Stop hook): rolls the buffer over, captures any remaining turns. Fail-safe exit 0. - **Every session start** (recall hook): assembles the cached memory prefix and pipes it to Claude. Empty store or unreachable local engine → empty stdout. - **When idle** (local engine): drains the buffer through the shield → embed → dedup → encrypted insert pipeline on the WAKE → DROWSY edge (5-min idle) and after every REM cycle. ### Connect your MCP host Claude Code: ```bash claude mcp add iai-mcp -- node "$(pwd)/mcp-wrapper/dist/index.js" ``` Or edit `~/.claude.json` directly: ```json { "mcpServers": { "iai-mcp": { "command": "node", "args": ["/absolute/path/to/iai-mcp/mcp-wrapper/dist/index.js"] } } } ``` Use the absolute path. `~` and `$HOME` won't expand here. For Claude Desktop, edit `~/Library/Application Support/Claude/claude_desktop_config.json`. Codex CLI: ```toml [mcp_servers.iai-mcp] command = "node" args = ["/absolute/path/to/iai-mcp/mcp-wrapper/dist/index.js"] [mcp_servers.iai-mcp.env] IAI_MCP_PYTHON = "/absolute/path/to/iai-mcp/.venv/bin/python" IAI_MCP_STORE = "/Users/you/.iai-mcp" ``` Codex hooks are stable in current Codex CLI builds. If hooks are disabled by local policy or an older install, enable `[features].hooks = true` in `~/.codex/config.toml`. ### Verify ```bash iai-mcp doctor iai-mcp daemon status ``` Restart Claude Code. Start a session, do some work, exit. Then: ```bash tail ~/.iai-mcp/logs/capture-$(date -u +%Y-%m-%d).log ``` You should see a `rc=0` line. That's your first memory. --- ## Usage You do not call `iai-mcp` directly during a session. Once it's connected: Capture is automatic. Every turn, yours and the assistant's, is recorded verbatim with timestamps and session metadata. You don't say *"remember this."* Recall is automatic. When a new session starts, the local engine assembles a small relevant slice of your history and injects it into the conversation prefix. You don't say *"what did we say."* Consolidation runs idle. Between sessions, the local engine merges duplicates, strengthens recall pathways for things retrieved often, and prunes weak edges. The system gets quietly better at remembering you over time. After a few weeks of regular use the difference becomes noticeable. The assistant stops asking the same orientation questions, references things you mentioned in passing, and adapts to your style without being told. There's also a CLI — you don't need it for normal use, but when you want to query or add to your memory straight from the terminal, `iai` is there: `recall`, `capture`, `ask` (LLM synthesis grounded in your memory), `status`, and `last`. --- ## How it works The local engine is a Python process that runs in the background — it sleeps when idle and wakes when your assistant needs it, so it isn't always-on or constantly using CPU. Your MCP client connects to it via a Unix socket. No network exposure. Recall doesn't depend on the engine being awake. The store itself is always available: when the engine is asleep or not running, your assistant (and the `iai` CLI) read memory directly from the local store. The engine handles the fast LLM-free recall path when it's up, plus the nightly consolidation pass — it's never a gatekeeper on your memory. Memory is stored in three tiers: *Episodic* is verbatim, timestamped fragments of what was said. Write-once, never overwritten or rewritten. *Semantic* is summaries induced from clusters of related episodes during idle-time consolidation. *Procedural* is a small set of stable parameters about you, learned over time: preferences, style cues, recurring patterns. Eleven sealed knobs that shift based on what works. The three tiers are backed by a hyperdimensional memory substrate — each kind of memory gets its own representation, so episodic detail, semantic gist, and procedural patterns don't collapse into one undifferentiated blob. A background pass runs periodically (sleep cycles): it clusters episodes with my own community-detection algorithm, builds semantic summaries, decays old unreinforced connections, and reinforces frequently co-retrieved paths. Things you haven't revisited fade naturally. One step per night can make a single LLM call **through your existing Claude subscription** (`claude -p`) — no separate API key, capped at ≤1% of your daily quota. (`iai-mcp doctor` row (p) verifies there's no API-key SDK path installed at all.) Recall combines three signals: semantic similarity, graph-link strength, and recency. All ranked together. The hot path runs entirely locally with no LLM in the loop. All records are encrypted at rest with AES-256-GCM. The key lives in `~/.iai-mcp/.key` (mode 0600). Back it up. Lose the key, lose the memories. Everything lives at `~/.iai-mcp/`. Embeddings are computed locally. The only data that leaves the machine is your normal conversation with whatever LLM API your client uses. --- ## Built our own Most memory projects are a thin layer over an off-the-shelf vector store and someone else's graph library. This one isn't. The load-bearing pieces are my own code, written for this exact workload — a small memory graph that mutates every night and gets queried on every recall: | Piece | What it is | |---|---| | **Hippo** | The storage engine — encrypted records, the vector index, and the graph in one local store. | | **MOSAIC** | My community-detection algorithm — a Leiden-family method (CPM objective), rewritten in pure MIT-licensed Python to replace the GPL-licensed `leidenalg`/`igraph` dependency. It clusters the memory graph so recall spreads through the right neighbourhood and sleep can replay coherent episodes — tuned for a small, heterogeneously-weighted graph that changes every cycle, with stable community identity across splits and merges. | | **Lilli HD** | The hyperdimensional memory substrate — distinct representations for episodic / semantic / procedural memory, with structural recall (retrieve by the *shape* of a memory, not just its embedding). | | **Native engine** | A Rust core — the embedder and the graph kernels. This is where the latency comes from. | These sit on a thin layer of proven, permissive primitives — SQLite, the `candle` tensor library, NumPy, and the audited `cryptography` AES implementation. I build the engine and the algorithms; I don't reinvent a database, a tensor kernel, or — deliberately — a crypto primitive. The interesting bricks are mine; the foundation under them is boring, battle-tested, and permissive. MIT throughout. I wrote these because the off-the-shelf options were built for a different problem — large static graphs, multi-tenant clouds, gist-style summarization — and they were slower and a worse fit for "one person's memory on one machine, reorganized every night." Mine are faster *on this shape of problem*, which is the only shape I care about. --- ## Benchmarks I built these because I wanted honest numbers, not a leaderboard. Every harness ships in `bench/` with a one-line reproduce command — run them and get your own results. Where a number missed its target or regressed, it says so. Full detail in [`BENCHMARKS.md`](BENCHMARKS.md). ### LongMemEval-S — the one head-to-head arena Validated in a single harness against [mempalace](https://github.com/MemPalace/mempalace) on the identical 500 cleaned questions, session granularity, `recall_any@k`, raw (no rerank): | System | Embedder | R@5 | R@10 | |---|---|---|---| | **iai** (product) | bge-small-en-v1.5 | **0.962** | 0.978 | | iai (matched embedder) | all-MiniLM-L6-v2 | 0.966 | 0.978 | | mempalace v3.3.6 | all-MiniLM-L6-v2 | 0.966 | 0.978 | On raw retrieval — the headline both projects ship — it's an **exact tie** on the matched embedder — R@5 0.966 = 0.966 and R@10 0.978 = 0.978. Our product embedder scores 0.962 R@5, a 2-question-in-500 difference (noise). No win claimed — an honest tie is the strong, defensible statement. LongMemEval is a *cold, one-shot* retrieval test; it doesn't exercise cross-session memory, which is where the design's real edge is. ### Where it actually leads — longitudinal memory | Benchmark | Result | What it measures | |---|---|---| | **Rescue@10** (post-contradiction) | **1.000** | After a fact is updated/contradicted, the *current* fact still ranks top-10 — where flat-vector stores collapse on the more-similar stale fact. | | Historical-verbatim (hit@10) | **1.000** | The *superseded/archived* wording of an updated fact also ranks top-10 — both current and prior versions stay retrievable. Flat-cosine baseline ~0.71. | | Personal-fact drift (recall@10) | 0.9933 | Retention across 50 facts / 50 sessions / 30 intervening sessions. | | Sleep-consolidation (recall@10) | 1.000 → 1.000 | Recall survives a full consolidation cycle. | | Session-start tokens | 1,629 min / 2,993 std | Under the ≤3,000-token budget. | | MOSAIC parity | 36/36 LFR + 10/10 | NMI vs ground-truth, deterministic. | ### Cost & footprint (honest disclosure — not a brag) | Metric | Measured | Note | |---|---|---| | Recall p95 latency | 77 ms @1k · 368 ms @10k | Above the ```bash iai-mcp doctor ``` What it checks: | # | Check | What it means | |---|---|---| | a | daemon process alive | Is the daemon process running? | | b | socket file fresh | Can the UNIX socket accept a connection? | | c | lock file healthy | Is the process lock held correctly? | | d | no orphan core procs | No leftover stdio core process without a daemon | | e | daemon state file valid | State file parses and has expected fields | | f | hippo storage readable | Can the store be opened and queried? | | g | no dup binders | Only one process is bound to the socket | | h | crypto key file state | Encryption key exists, correct permissions (0 … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [CodeAbra](https://github.com/CodeAbra) - **Source:** [CodeAbra/iai-personal-memory-engine](https://github.com/CodeAbra/iai-personal-memory-engine) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-codeabra-iai-personal-memory-engine - Seller: https://agentstack.voostack.com/s/codeabra - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.