English | 中文

<p align="center"> <img src="docs/assets/iai-brain-demo.gif" alt="iai-pme — the brain, live: search, pin, fade, rescue, teach it a file" width="850"> </p> <h3 align="center">Give your coding agent a brain that remembers exactly what you said — forever, on your machine.</h3> <p align="center"><b>The best open-source personal memory engine for AI coding assistants.</b><br>Pays for itself in tokens: an injected memory pack costs ≈88% less than the agent search it displaces.<br>Every claim ships with the harness that proves it — run the benchmarks yourself.</p> <p align="center"><a href="https://pypi.org/project/iai-pme/"><img src="https://img.shields.io/pypi/v/iai-pme?style=flat-square&color=1f6feb&label=pypi&v=281" alt="iai-pme on PyPI"></a> <img src="https://img.shields.io/badge/release-v3.0.0-1f6feb?style=flat-square" alt="Release v3.0.0"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-1f6feb?style=flat-square" alt="License: MIT"></a> <img src="https://img.shields.io/badge/python-3.11%20|%203.12-3776ab?style=flat-square&logo=python&logoColor=white" alt="Python 3.11 | 3.12"> <img src="https://img.shields.io/badge/platform-macOS%20|%20Linux-555?style=flat-square" alt="Platform: macOS and Linux"> <img src="https://img.shields.io/badge/Windows-beta-dbab09?style=flat-square&logo=windows&logoColor=white" alt="Windows: beta"> <img src="https://img.shields.io/badge/engine-Rust%20native-dea584?style=flat-square&logo=rust&logoColor=black" alt="Rust-native engine"></p> <p align="center"><img src="https://img.shields.io/badge/LongMemEval%20R%405-0.962-2ea043?style=flat-square" alt="LongMemEval R@5 0.962"> <img src="https://img.shields.io/badge/Rescue%4010-1.000-2ea043?style=flat-square" alt="Rescue@10 1.000"> <img src="https://img.shields.io/badge/memory_pack-%E2%89%8888%25_cheaper_than_search-2ea043?style=flat-square" alt="An injected memory pack costs ≈88% less than the agent search it displaces"> <img src="https://img.shields.io/badge/at%20rest-AES--256--GCM-2ea043?style=flat-square" alt="AES-256-GCM"> <img src="https://img.shields.io/badge/local--only-no%20telemetry-2ea043?style=flat-square" alt="Local only, no telemetry"> <img src="https://img.shields.io/badge/MCP-compatible-8957e5?style=flat-square" alt="MCP compatible"> <a href="https://glama.ai/mcp/servers/CodeAbra/iai-mcp"><img src="https://glama.ai/mcp/servers/CodeAbra/iai-mcp/badges/score.svg" alt="Glama MCP score"></a></p> <p align="center"><a href="#quick-start"><b>Quick start</b></a> · <a href="#benchmarks"><b>Benchmarks</b></a> · <a href="#watch-it-think"><b>Dashboard</b></a> · <a href="https://github.com/CodeAbra/iai-personal-memory-engine/discussions"><b>Discussions</b></a> · <a href="./README_zh-CN.md"><b>中文</b></a></p>

---

iai-pme

Your AI assistant forgets you every session. iai-pme gives it a memory that doesn't.

The memory style is autistic — by design: verbatim over paraphrase, precise cues, rare events kept rare. (Why the name)

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
• Compare
• Quick start
• Usage
• Watch it think
• How it works
• MCP tools
• Everything it does
• Built our own
• Benchmarks
• Configuration
• Languages
• Doctor
• Staying up to date
• FAQ
• 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?".

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

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.

It also pays for itself in tokens. Memory injected at session start is context your assistant doesn't have to rebuild — no re-reading files it already read yesterday, no asking you the same orientation questions. In effect the engine doubles as a local context provider for your MCP host, and the dashboard keeps honest count: memory packs served, tokens injected, and a lower-bound estimate of tokens saved. For scale, measured on the author's own store over three recent weeks: 282 memory packs served (≈99,000 tokens of context injected) displaced agent searches that average 2,639 tokens a call — a lower-bound saving of ≈707,000 tokens, by the engine's own conservative formula. Per pack served that makes memory ≈88% cheaper (~350-token pack vs a ~2,850-token search round-trip, which is the measured 2,639 plus the per-call overhead). Your dashboard keeps your own count, live, and it measures the search side rather than assuming it.

That figure is about the packs the engine injects on its own — session start and the per-turn foresight pack. An explicit memory_recall you call mid-session is a different object: it is bounded by budget_tokens (default 1,500) and typically returns more than an ambient pack, so it saves real tokens against a search but not 88% of them.

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

---

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 | → Benchmarks | → Built our own |

---

Compare

Mem0, Supermemory, Graphiti and Letta are memory layers for products you build — good at what they do, cloud-first, LLM-extraction pipelines. claude-mem is compression-based — it stores AI-generated summaries of your sessions (its own description). iai-pme is neither: it's a personal memory engine for the assistant you already use.

| | iai-pme | typical memory layer | |---|---|---| | What gets stored | Every turn, verbatim — write-once, never rewritten | LLM-extracted facts or compressed summaries | | When a fact changes | Old version archived and still retrievable — Rescue@10 1.000, historical wording 1.000 | Profile updated; history retention varies | | Where it runs | Your machine only — no account, no API key, embeddings computed locally | Managed cloud, or OSS + external LLM and vector DB | | Storage | Own Rust engine — nothing external to install | Qdrant / Neo4j / Postgres / managed store | | Cost of a memory write | File IO + a local embedding — no LLM in the capture path | An LLM call per extraction | | Price | MIT. Everything is in this repo | OSS core + paid managed tier |

If you need multi-tenant memory for an app you're shipping, use one of them — honestly. If you want your assistant to remember you, that's this repo.

---

Quick start

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

Install from PyPI — a prebuilt wheel carries the engine, so no clone and no toolchains:

pip install iai-pme
iai-mcp crypto init      # one-time: creates the encryption key

That gives you the engine, the iai CLI, the dashboard and the MCP server. To point Claude Code at the server the wheel just installed:

claude mcp add iai-pme -- node "$(python -c 'from iai_mcp.cli._capture import _resolve_wrapper_path as w; print(w())')"

Claude Code users can skip even that — the plugin wires the MCP server and ambient capture in one step:

/plugin marketplace add CodeAbra/iai-personal-memory-engine
/plugin install iai-memory@iai-pme

Restart the session and work normally: capture and recall are automatic from there. (pip install iai-pme first — the plugin carries the wiring, the package carries the engine.)

Want the whole thing wired for you, including the background engine? One command, macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/CodeAbra/iai-personal-memory-engine/main/scripts/bootstrap.sh | bash

It checks your prerequisites, clones the repo to ~/.local/share/iai-pme, builds, installs the background engine and the capture hooks, registers the MCP server with Claude Code, and finishes with a health check. Re-run it any time to update. Prefer to look before you leap: add --dry-run to print every step without changing anything, or --preflight-only to check just the prerequisites.

Or the whole thing by hand (the Rust engine compiles from source, so give it a few minutes):

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 .
cd mcp-wrapper && npm install && npm run build && cd .. && iai-mcp daemon install && iai-mcp capture-hooks install
claude mcp add iai-mcp -- node "$(pwd)/mcp-wrapper/dist/index.js"

Details, other hosts, and what each step actually does — below.

Prerequisites

For pip install iai-pme — the engine, the CLI, the dashboard and the MCP server, all from a prebuilt wheel:

• Python 3.11 or 3.12
• macOS on Apple Silicon, Linux with glibc 2.28 or newer (Ubuntu 20.04+, Debian 10+, RHEL 8+), or Windows x86_64
• Node.js 18+ to run the MCP server (the server itself ships bundled — nothing to install from npm)
• Intel macOS has no wheel — the projects we depend on stopped publishing them — so it installs from source and needs the Rust toolchain below

For the source install — same engine, built on your machine:

• Python 3.11 or 3.12
• Node.js 18+ — the MCP server is TypeScript
• 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 .
`