English | 中文

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
• Quick start
• Usage
• How it works
• Built our own
• Benchmarks
• Configuration
• Doctor
• Notes for AI assistants
• Status and limitations
• Compatibility
• About the name
• Authors
• License
• Contributing

What it is

A local server that speaks the MCP protocol 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.

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

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, 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

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

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

claude mcp add iai-mcp -- node "$(pwd)/mcp-wrapper/dist/index.js"

Or edit ~/.claude.json directly:

{
  "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:

[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

iai-mcp doctor
iai-mcp daemon status

Restart Claude Code. Start a session, do some work, exit. Then:

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 s