It's a local, MCP-compatible long-term memory server that captures your conversations verbatim and serves the right slice of memory back to an AI agent.
Recall by cue — memory_recall returns verbatim hits plus anti_hits (things that look similar but don't match) under a token budget, with hints, cue mode, and overnight digest.
Structural recall — memory_recall_structural answers role→filler queries (e.g. agent=..., file=...) using hyperdimensional bindings.
Code/doc search hints — memory_search surfaces past notes about identifiers or phrases to verify, explicitly not a replacement for a repository search.
Time-travel recall — memory_temporal_recall reconstructs what was known as_of a timestamp and lists what changed since.
Claim checking — claim_check tests a statement like "X is not done yet" against memory and returns a freshness verdict with reasoning.
Capture turns — memory_capture stores verbatim text with role, tier, cue, salience, epistemic status, goal/next_action/focus, and background-agent spawn/completion tracking; near-duplicates auto-dedup.
Correct without deleting — memory_contradict preserves the old record, closes its validity interval, writes a new record, and links them with a contradicts edge.
Reinforce associations — memory_reinforce boosts Hebbian edges between records that co-answered a question.
Run the sleep cycle — memory_consolidate triggers schema induction, decay, and pruning.
Tune behaviour — profile_get_set reads or writes the ten sealed behavioural knobs.
Introspect the store — topology (graph metrics/regime), schema_list (induced schemas by domain/confidence), events_query (event log), episodes_recent (latest turns), curiosity_pending (queued questions from the daemon).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@iai-personal-memory-engine what was my last session about?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
English | 中文
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,
a nightly consolidation step that asks your model for a single insight through
the same subscription your CLI already uses (on by default;
IAI_MCP_REM_DISABLED=1 turns it off), a daily version check, and the one-time
download of the embedding model.
Related MCP server: local-agent-context
python3.12 -m pip install -U iai-pmeThen run inside Claude Code:
/plugin marketplace add CodeAbra/iai-personal-memory-engine
/plugin install iai-memory@iai-pmeRestart the session, then verify:
iai --version
iai-mcp daemon status
iai-mcp doctorPython 3.11 is also supported.
curl -fsSL https://raw.githubusercontent.com/CodeAbra/iai-personal-memory-engine/main/scripts/bootstrap.sh | bashThis 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-runpython3.12 -m pip install -U iai-pme
iai-mcp crypto init
iai-mcp daemon install
iai-mcp capture-hooks install --target codexReplace 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.
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.
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 REM step, on by
default, may invoke claude -p through the user's existing Claude subscription,
capped at no more than 1% of the daily quota; IAI_MCP_REM_DISABLED=1 turns it
off. No Anthropic API key is required.
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 |
iai brainThe 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 · lastiai upload accepts documents, Office files, e-books, source code,
configuration files, and directories. Full formats and administrative commands
are listed in docs/REFERENCE.md.
Every harness ships in bench/; methodology and reproduce commands are in
BENCHMARKS.md.
Benchmark | Result |
Rescue@10 after contradiction | 1.000 |
Historical-verbatim hit@10 | 1.000 |
LongMemEval-S R@5, product embedder | 0.962 |
LongMemEval-S R@10, product embedder | 0.978 |
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.
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
claim_checkFifteen tools cover cue, temporal, structural, and lexical recall; checking a claim against memory; capture and correction; reinforcement and consolidation; behavioural-profile control; and store introspection.
Host | Ambient behaviour |
Claude Code | Session-start recall, per-turn updates, turn capture, and session capture |
Codex CLI | Full integration through Codex hooks |
Cursor | Session-start recall and capture; no per-turn text injection |
Antigravity | Recall per invocation and lossless transcript capture |
Hermes 0.5.0+ | Recall before model calls and capture from its message store |
OpenClaw | MCP tools on request; no ambient shell hooks |
Gemini CLI and other MCP hosts | MCP tools; no bundled host-specific hooks unless listed above |
Claude Desktop | MCP tools; plain Chat does not expose Claude Code-style ambient hooks |
Records are encrypted at rest with AES-256-GCM. The store and key live under
~/.iai-mcp/; back them up together. Two kinds of files there are plain
text: the per-turn capture spool until the engine's next pass encrypts it,
and the caches the hooks inject memory from. The
plugin README lists them.
macOS and Linux use a Unix socket. Windows uses an ephemeral loopback port with a per-user token.
There is no iai-memory account, telemetry pipeline, hosted dashboard, or cross-machine sync.
iai-memory goes online in three places, each with an off switch: the nightly
REM claude -p step (on by default, IAI_MCP_REM_DISABLED=1), a daily PyPI
version check (IAI_MCP_VERSION_CHECK=0), and the first-use download of the
embedding model from Hugging Face (IAI_MCP_EMBED_OFFLINE=1).
The engine checks that your Claude Code login is a subscription by reading
Claude Code's login record (~/.claude/.credentials.json, or the macOS
Keychain item) when the MCP server starts and before the REM step. Nothing
from the record is sent anywhere.
The MCP server starts the engine in the background, and it keeps running
after the session ends. Stop it with iai-mcp daemon stop.
The store refuses to mix incompatible embedding generations; changing the embedder requires an explicit migration.
Recall is usually mediocre during roughly the first ten sessions, and quality and latency depend on corpus size, language, embedder, and stored history.
The default store is English-first. Raw non-English records require an
explicit raw:<lang> tag and a multilingual or custom embedder.
Windows support is beta. Ambient behaviour varies with host hook support.
The project is solo-maintained and has no enterprise SLA.
Health and updates:
iai-mcp doctor # 38 checks
iai-mcp daemon status
iai-mcp self-updateIAI — Independent Autistic Intelligence describes the memory design.
Independent: the engine, store, embeddings, and dashboard run locally.
Autistic: literal preservation, precise cues, sustained focus, and rare events retained as rare rather than smoothed into a typical summary. This is an operational design description, not a diagnosis or casual metaphor.
Intelligence: used in the systems sense — a process that observes, adapts, reorganizes itself, and remains viable over time.
“Personal memory engine” describes the scope: one person's memory, on one machine, used by the assistant they already have.
docs/REFERENCE.md — technical and operational reference
BENCHMARKS.md — methodology and reproduce commands
docs/EMBEDDERS.md — providers, languages, and migrations
CHANGELOG.md — release history
CONTRIBUTING.md — development and test setup
SECURITY.md — private vulnerability reporting
Issues and pull requests are welcome. Changes to retrieval, capture, contradiction handling, or consolidation should include relevant benchmark reruns.
By Areg Aramovich Noya and Lilli Noya, in collaboration with the team at lcgc.dev.
Check a claim (e.g. 'X is not done') against memory. Returns hits + anti_hits + a freshness verdict in one call.
Inputs: cue (required), session_id, budget_tokens. Returns: hits, _source, verdict, anti_hits, +1 more
List pending curiosity questions queued by the sleep daemon. Read-only. Filter by session_id.
Inputs: session_id. Returns: count, questions
Returns the N most-recent user-turn records, time-desc. Optional session_id filter. GLOBAL across all projects.
Inputs: n, session_id. Returns: count, turns
Query user-visible events (kind whitelist). Read-only. Optional since (ISO-8601), severity, limit.
Inputs: kind (required), limit, since, severity. Returns: count, events
Capture a verbatim turn (auto-dedups near-duplicates). Use for corrections, not for minting standing-order directives.
Inputs: text (required), cue, goal, role, +11 more. Returns: reason, status, record_id
Trigger sleep-cycle consolidation: schema induction, FSRS decay, Hebbian pruning. Mutates store; idempotent in one sleep window.
Inputs: session_id. Returns: mode, tier, decay_result, schema_candidates, +1 more
Mark a record contradicted; new fact stored as a NEW record (old NEVER deleted). Mutates store.
Inputs: id (required), new_fact (required), cue_embedding, epistemic_status. Returns: ts, edge_type, original_id, new_record_id
Recall verbatim memories by cue — decisions, preferences, prior discussion, rationale. Call before a repository search. Returns hits + anti_hits.
Inputs: cue (required), language, session_id, budget_tokens, +1 more. Returns: hits, hints, cue_mode, anti_hits, +7 more
Structural recall via TEM role->filler bindings (BSC hypervectors). Read-only. Prefer over memory_recall for role-filler queries.
Inputs: max_records, budget_tokens, structure_query. Returns: hits, anti_hits, budget_used, activation_trace, +1 more
Boost Hebbian edges among co-retrieved record ids. Mutates edge weights. Use when two records co-answered.
Inputs: ids (required), session_id. Returns: new_weights, edges_boosted
Use for code/doc search; returns hints to verify — never replaces a repository search.
Inputs: query (required), k. Returns: hits, frame
Time-travel recall: as_of bounds records, changed_since filters events. Read-only.
Inputs: cue, as_of, limit, changed_since. Returns: hits, _scope, changed_since_events
Read or write a profile knob (10 sealed: 9 AUTIST + wake_depth). operation get|set; returns knob value.
Inputs: operation (required), knob, value. Returns: object
List induced schemas (Tier-0 + Tier-1) from sleep consolidation. Read-only. Filter by domain and confidence_min.
Inputs: domain, confidence_min. Returns: total, schemas
Snapshot of memory-graph topology: N, C, L, sigma, community_count, regime. Read-only diagnostic; sigma never toggles retrieval.
Inputs: no named parameters. Returns: C, L, N, sigma, +3 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 15 tools
The set has multiple recall-flavored tools (memory_recall, memory_search, memory_recall_structural, memory_temporal_recall, claim_check), but each description emphasizes a different cue type or output contract. The only notable risk is choosing between memory_recall and memory_temporal_recall for time-bounded verbatim queries, but the descriptions still distinguish them.
Core memory operations use the memory_<verb> pattern consistently, but the convention is mixed across non-core tools: bare nouns (topology), noun_adjective (episodes_recent, curiosity_pending), verb_noun (schema_list, events_query), and verb pairs (profile_get_set). Names are readable individually, but they do not follow a single cohesive convention.
Fifteen tools is at the upper edge of the ideal range, and most operations have a genuine purpose. However, several recall variants and diagnostic read-only tools could potentially be consolidated without making the server less clear.
The memory lifecycle is well covered: capture, recall variants, contradiction, reinforcement, consolidation, profiling, and diagnostics are all present. There is no hard-delete operation, but the descriptions indicate this is intentional (contradicted records are marked, never deleted), so the gap is design-driven rather than accidental.
Persistent, verbatim, searchable memory for AI assistants — one memory across every MCP client.
Cloud-hosted MCP server for durable AI memory
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
An MCP memory server. One memory your agents share — across models, devices and apps.
