iai-personal-memory-engine is a local server that provides long-term memory for AI, working through the MCP protocol and compatible with Claude as well as other MCP-compatible agents. It captures every turn of every session verbatim, organizes these records over time into a personal memory map about "who you are," and injects a small piece of relevant memory back at the start of each new conversation and each turn. Users do not need to say "remember this" or "what did we say last time."
[Main Capabilities]
- Verbatim preservation: retains the exact wording and details of every conversation.
- Layered memory: uses different hyperdimensional representations to separately store literal details, semantic structure, and behavioral tendencies, preventing the three from collapsing onto the same vector surface.
- Local LLM-free recall path: combines semantic similarity, graph evidence, temporal recency, temporal validity, and lexical evidence; memory_recall returns both hits and anti_hits; memory_contradict can close the validity interval of old records, create new records, and establish links between the two.
- Sleep-cycle consolidation: during idle time, groups related episodes, induces semantic memory, reinforces useful paths, and decays weak edges that have not been reviewed. An optional REM step invokes claude -p through the user's existing Claude subscription, capped at within 1% of the daily quota, with no need for an Anthropic API Key.
- Local dashboard and CLI: can search storage, view graph neighborhoods and contradictions, pin or fade memories, import files, control the background engine, and report token usage estimates based on its own storage.
- iai upload supports documents, Office files, ebooks, source code, configuration files, and directories.
- 14 tools cover cue-based, temporal, structural, and lexical recall; capture and correction; reinforcement and consolidation; behavioral profile control; and storage introspection.
[Installation and Usage] After running it in Claude Code, restart the session to verify. Supports Python 3.11/3.12. On macOS or Linux, an all-in-one source installation is available: it builds the Rust engine and TypeScript wrapper, installs the background service and hooks, registers Claude Code, and runs a health check; it requires Git, Python 3.11/3.12, Node.js 18+, and Rust. You can replace codex with cursor, antigravity, hermes, openclaw, or all to adapt to different hosts. The MCP tool is suitable for any MCP-over-stdio client; automatic capture and context injection depend on the hooks exposed by the host. New storage uses the native engine format by default, and existing storage keeps its original format when upgraded; to migrate old SQLite storage to the native engine, run iai-mcp migrate-to-lilli, and the specific command is printed by iai-mcp doctor, with the complete process described in the technical reference.
After installation, the background process is called a daemon in the CLI. When it is dormant or temporarily unavailable, the MCP wrapper and iai can still read local storage directly.
[Privacy and Limitations]
- Records are encrypted at rest with AES-256-GCM, and both storage and keys are under ~/.iai-mcp/, so they need to be backed up together.
- macOS and Linux use Unix sockets; Windows uses an ephemeral loopback port with a per-user token.
- There is no iai-memory account, telemetry pipeline, managed dashboard, or cross-machine sync. The only optional network activity is REM's claude -p step and the daily PyPI version check; setting IAI_MCP_VERSION_CHECK=0 disables the version check.
- Storage refuses to mix incompatible embedding generations; changing embedders requires an explicit migration.
- Recall quality is usually mediocre for roughly the first ten sessions; quality and latency depend on corpus size, language, embedder, and stored history.
- Storage is English-first by default; raw non-English records require an explicit raw:<lang> tag as well as a multilingual or custom embedder.
- Windows support is beta, and environment behavior varies with host hook support.
- The project is maintained by an individual, with no enterprise-grade SLA.
[Benchmarks and Notes] Historical verbatim retrieval uses a flat cosine baseline of about 0.71; when using the matching all-MiniLM-L6-v2 embedder, both iai-memory and mempalace v3.3.6 achieve R@5 0.966 and R@10 0.978, and no victory is claimed. On the author's own storage, automatically injected memory packs average about 350 tokens, while the agent search round trips they replace are about 2,850 tokens, making them about 88% cheaper on that measured workload; this does not apply to explicit memory_recall, whose default response budget is 1,500 tokens.
In the name IAI stands for Independent Autistic Intelligence: Independent means the engine, storage, embeddings, and dashboard run locally; Autistic means verbatim preservation, precise cues, sustained focus, and preserving rare events as rare events rather than smoothing them into typical summaries, which is an operational design description; Intelligence is used in the systems sense, referring to the process of observing, adapting, self-reorganizing, and surviving over the long term. "personal memory engine" describes its scope: one person's memory, on one machine, for use by the assistants they already have. The project was created by Areg Aramovich Noya and Lilli Noya, in collaboration with the lcgc.dev team, under the MIT license.
