CodeAbra/iai-personal-memory-engine

Keeps every conversation word-for-word and gives your AI agent the right
context on every turn.
Quick start ·
How it works ·
Benchmarks ·
Compatibility ·
Technical reference
---
What it is
A local server that speaks the MCP protocol and gives Claude, and any other
MCP-compatible agent, 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 and turn. You never have to say *"remember this"* or *"what did we
say last time?"*.
I built this for myself. It worked. The benchmarks were mostly for my own
curiosity.
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.
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
things that leave your machine are the normal model calls your CLI already makes,
plus one optional nightly consolidation step that asks your model for a single
insight through the same subscription your CLI already uses.
---
Quick start
Claude Code
Then run inside Claude Code:
Restart the session, then verify:
Python 3.11 is also supported.
macOS or Linux: all-in-one source install
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:
Other hosts
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.
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 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