Iai Personal Memory Engine

English | 中文

Keeps every conversation word-for-word and gives your AI agent the right
context on every turn — including the old wording when a fact changes.

Quick start · How it works · Benchmarks · Compatibility · Technical reference

What it is

Your AI agent forgets everything the moment you close the session. iai-memory fixes that, on your own machine. Switch the hooks on and it records both sides of every conversation word-for-word, then feeds the agent the part of your history that matters on every message — not just when a session starts. No memory file to maintain, no “remember this.”

When a fact changes, the old one isn't overwritten. The new version is stored and linked back to what it replaced, so you can still pull up both. When something contradicts itself, recall shows you the conflict instead of quietly handing over a stale answer as if it were true.

It's memory built around you and one agent — not a memory API for a multi-tenant app, and not a wrapper around someone else's database. What you say is stored once, verbatim, and never rewritten. The store, the search, the graph, the dashboard: all of it runs on your machine.

The memory style is autistic by design. It keeps the literal wording instead of smoothing it into a paraphrase, holds onto precise cues, and leaves rare things rare instead of averaging them away. Why the name.

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

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

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

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/; methodology and reproduce commands are in BENCHMARKS.md.

Historical-verbatim retrieval uses a flat-cosine baseline of about 0.71. With the matched all-MiniLM-L6-v2 embedder, iai-memory and mempalace v3.3.6 both score R@5 0.966 and R@10 0.978; no win is claimed.

On the author's store, an automatically injected memory pack averaged about 350 tokens versus about 2,850 tokens for the agent-search round trip it replaced: approximately 88% cheaper on that measured workload. This does not apply to explicit memory_recall, whose default response budget is 1,500 tokens.

MCP tools

memory_recall              memory_temporal_recall
memory_recall_structural   memory_search
memory_capture             memory_contradict
memory_reinforce           memory_consolidate
profile_get_set            topology
schema_list                events_query
episodes_recent            curiosity_pending

Fourteen tools cover cue, temporal, structural, and lexical recall; capture and correction; reinforcement and consolidation; behavioural-profile control; and store introspection.

Compatibility

Privacy and limitations