AI个人记忆引擎

Prerequisites

• macOS (Apple Silicon tested)
• 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, Codex CLI, Gemini CLI, Cursor CLI, and others
• ~500 MB free disk

Windows and Linux aren't supported yet — the engine and its native core are macOS-only for now. Contributions are very welcome: if you'd like to port iai-mcp to Linux or Windows, open an issue or PR and I'll help however I can.

Install

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:

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):

cd mcp-wrapper && npm install && npm run build && cd ..
iai-mcp daemon install      # launchd on macOS, systemd on Linux
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:

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:

iai-mcp capture-hooks install --target codex

To install both:

iai-mcp capture-hooks install --target all

What the install does:

• Copies three hook scripts from deploy/hooks/ 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.

Notes for AI assistants helping with installation

If you're an AI model helping a user install or debug iai-mcp, read this before diagnosing anything.

Terminology note: this doc calls the background component the local engine. Its process, CLI subcommands and doctor check labels still use the original name daemon — e.g. iai-mcp daemon status, pgrep -f iai_mcp.daemon, and the (a) daemon process alive check. "Local engine" and "daemon" refer to the same process.

The local engine has four FSM states: WAKE, TRANSITIONING, SLEEP, DREAMING. Separately, the wrapper-layer lifecycle has four states: WAKE, DROWSY, SLEEP, HIBERNATION. These are two different state machines in two different files. Don't confuse them.

Things that look broken but are not:

• last_tick_at hasn't changed in hours. This is a sleep-cycle tick timestamp, not a process heartbeat. The daemon can be alive and healthy with a stale last_tick_at. Check iai-mcp daemon status instead.
• fsm_state: DREAMING for hours. Normal. The local engine is running a sleep cycle. Wake transitions are event-driven (a new session arriving wakes it), not time-driven.
• status: deferred in the capture log. This is the only path the Stop hook takes. It writes captures to ~/.iai-mcp/.deferred-captures/ and the local engine picks them up on its next tick. This is by design, not a failure.
• iai-mcp doctor drops the socket check during SLEEP or DREAMING. The socket is intentionally unresponsive during consolidation passes. This is healthy.
• Cold start takes a few seconds. The local engine initializes the store and loads the embedding model into memory. Don't kill it because it hasn't responded in 5 seconds.

Actual problems look like: iai-mcp daemon status returning ok: False, doctor showing multiple FAIL results, or the daemon process not existing at all (pgrep -f iai_mcp.daemon returns nothing).

When in doubt, run iai-mcp doctor and read what it says. The output is self-explanatory.

---

Quick start

<p align="center"><img src="docs/assets/slides/slide-15.jpg" width="850" alt="iai-pme"></p>

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.

<p align="center"> <img src="docs/assets/iai-cli.png" alt="iai — terminal memory for your agent" width="600"> </p>

---

Configuration

The old IAI_MCP_EMBED_MODEL knob is gone — the embedder is a single built-in English-only model. There are many internal tuning knobs (IAI_MCP_*), but you shouldn't need to touch them.

---

Troubleshooting

---