iai-personal-memory-engine

English | 中文

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

python3.12 -m pip install -U iai-pme

Then run inside Claude Code:

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

Restart the session, then verify:

iai --version
iai-mcp daemon status
iai-mcp doctor

Python 3.11 is also supported.

macOS or Linux: all-in-one source install

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

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:

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

Other hosts

python3.12 -m pip install -U iai-pme
iai-mcp crypto init
iai-mcp daemon install
iai-mcp capture-hooks install --target codex

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 hits and anti_hits; memory_contradict closes the old record's validity interval, creates a new record, and links the two.

While idle, the engine groups related episodes, induces semantic memory, reinforces useful paths, and decays weak unreviewed edges. One optional REM step may invoke claude -p through the user's existing Claude subscription, capped at no more than 1% of the daily quota. No Anthropic API key is required.

First-party components

Component	Role
Hippo	Encrypted records, vector index, and graph in one local store
MOSAIC	Leiden-family community detection with stable community identity
Lilli HD	Hyperdimensional substrate and structural recall
Native engine	Rust embedder and graph kernels

---

Dashboard and CLI

iai brain

The local dashboard searches the store, exposes graph neighbourhoods and contradictions, pins or fades memories, ingests files, controls the background engine, and reports token-use estimates from your own store.

iai recall · temporal-recall · search · ask · capture · teach · upload
iai watch · brain · status · last

iai upload accepts documents, Office files, e-books, source code, configuration files, and directories. Full formats and administrative commands are listed in docs/REFERENCE.md.

---

Benchmarks

Every harness ships in bench/; methodolo