[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-83108":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":44,"readmeContent":45,"aiSummary":46,"trendingCount":15,"starSnapshotCount":15,"syncStatus":47,"lastSyncTime":48,"discoverSource":49},83108,"iai-personal-memory-engine","CodeAbra\u002Fiai-personal-memory-engine","CodeAbra","The best-benchmarked open-source memory system for AI coding assistants",null,"Python",142,18,1,4,0,3,7,9,3.84,"MIT License",false,"main",true,[25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"ai-agents","ai-memory","claude","claude-code","embeddings","episodic-memory","lancedb","llm-tools","local-first","long-term-memory","mcp","mcp-server","memory","model-context-protocol","openclaw","python","semantic-search","sentence-transformers","vector-search","2026-06-12 02:04:31","\u003Cp align=\"center\">\n  \u003Cimg src=\"logo.png\" alt=\"iai-pme\" width=\"600\">\n\u003C\u002Fp>\n\n\u003Ch3 align=\"center\">The best open-source personal memory engine for AI coding assistants.\u003C\u002Fh3>\n\u003Cp align=\"center\">Every claim ships with the harness that proves it. Run the benchmarks yourself.\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Frelease-v1.0.0-1f6feb?style=flat-square\" alt=\"Release v1.0.0\">\n  \u003Ca href=\"LICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-1f6feb?style=flat-square\" alt=\"License: MIT\">\u003C\u002Fa>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.11%20|%203.12-3776ab?style=flat-square&logo=python&logoColor=white\" alt=\"Python 3.11 | 3.12\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-macOS-555?style=flat-square&logo=apple&logoColor=white\" alt=\"Platform: macOS\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fengine-Rust%20native-dea584?style=flat-square&logo=rust&logoColor=black\" alt=\"Rust-native engine\">\n\u003C\u002Fp>\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLongMemEval%20R%405-0.962-2ea043?style=flat-square\" alt=\"LongMemEval R@5 0.962\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FRescue%4010-1.000-2ea043?style=flat-square\" alt=\"Rescue@10 1.000\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fat%20rest-AES--256--GCM-2ea043?style=flat-square\" alt=\"AES-256-GCM\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flocal--only-no%20telemetry-2ea043?style=flat-square\" alt=\"Local only, no telemetry\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP-compatible-8957e5?style=flat-square\" alt=\"MCP compatible\">\n  \u003Ca href=\"https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002FCodeAbra\u002Fiai-mcp\">\u003Cimg src=\"https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002FCodeAbra\u002Fiai-mcp\u002Fbadges\u002Fscore.svg\" alt=\"Glama MCP score\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n---\n\n# iai-pme\n\n**Your AI assistant forgets you every session. iai-pme gives it a memory that doesn't.**\n\n*Independent Autistic Intelligence — a personal memory engine. Fully local, ambient. Works with Claude and other MCP-compatible hosts.*\n\n## Table of contents\n\n- [What it is](#what-it-is)\n- [Quick start](#quick-start)\n- [Usage](#usage)\n- [How it works](#how-it-works)\n- [Built our own](#built-our-own)\n- [Benchmarks](#benchmarks)\n- [Configuration](#configuration)\n- [Doctor](#doctor)\n- [Notes for AI assistants](#notes-for-ai-assistants-helping-with-installation)\n- [Status and limitations](#status-and-limitations)\n- [Compatibility](#compatibility)\n- [About the name](#about-the-name)\n- [Authors](#authors)\n- [License](#license)\n- [Contributing](#contributing)\n\n---\n\n## What it is\n\nA local server that speaks the [MCP protocol](https:\u002F\u002Fmodelcontextprotocol.io) and gives Claude, and any other MCP-compatible assistant, 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. You never have to say *\"remember this\"* or *\"what did we say last time?\"*.\n\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fassets\u002Fslides\u002Fslide-02.jpg\" width=\"850\" alt=\"iai-pme\">\u003C\u002Fp>\n\nI built this for myself. It worked. I've been running it daily for months, and now I'm sharing it. The benchmarks were mostly for my own curiosity. I wanted to know if it actually works or if I'd just gotten used to it.\n\nUnder 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. More on that in [Built our own](#built-our-own).\n\nAnd unlike cloud memory services, nothing leaves your machine: no API key, no account, no telemetry. The local engine, the store, and the embeddings are all local.\n\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fassets\u002Fslides\u002Fslide-04.jpg\" width=\"850\" alt=\"iai-pme\">\u003C\u002Fp>\n\n---\n\n## Pick your path\n\n|  |  |  |\n|---|---|---|\n| **🟢 Just want it to work?** | **🔵 Want the numbers?** | **🟣 Want the internals?** |\n| Install once, then forget it's there — no commands, fully local. | Every claim ships with the harness that proves it — run them yourself. | We built our own storage engine, clustering, HD substrate and Rust core. |\n| → [Quick start](#quick-start) | → [Benchmarks](#benchmarks) | → [Built our own](#built-our-own) |\n\n---\n\n## Quick start\n\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fassets\u002Fslides\u002Fslide-15.jpg\" width=\"850\" alt=\"iai-pme\">\u003C\u002Fp>\n\n### Prerequisites\n\n- macOS (Apple Silicon tested)\n- Python 3.11 or 3.12\n- Node.js 18+\n- A Rust toolchain — the native engine builds from source\n- An MCP-compatible CLI host — [Claude Code](https:\u002F\u002Fdocs.claude.com\u002Fen\u002Fdocs\u002Fclaude-code\u002Foverview), Codex CLI, Gemini CLI, Cursor CLI, and others\n- ~500 MB free disk\n\nWindows and Linux aren't supported yet — the engine and its native core are macOS-only for now. **Contributions are very welcome:** if you'd like to port iai-mcp to Linux or Windows, open an issue or PR and I'll help however I can.\n\n### Install\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FCodeAbra\u002Fiai-personal-memory-engine.git\ncd iai-personal-memory-engine\npython3.12 -m venv .venv && source .venv\u002Fbin\u002Factivate\npip install .\n```\n\n`pip install` builds the native Rust engine (`iai_mcp_native` — the embedder + graph kernels) automatically, as part of the package build, via `setuptools-rust`. There's no separate build script. If you change the Rust source later and need to rebuild it by hand, there's an escape hatch:\n\n```bash\niai-mcp build-native        # rebuild the native engine in place\n```\n\nThen build the MCP wrapper and set up the local engine (it runs in the background):\n\n```bash\ncd mcp-wrapper && npm install && npm run build && cd ..\niai-mcp daemon install      # launchd on macOS, systemd on Linux\niai --version\n```\n\n### Install the capture + recall hooks\n\nThis is what makes memory ambient. Without these hooks iai-mcp reads memory but never writes conversation content and never injects recall at session start. One command wires all three:\n\n```bash\niai-mcp capture-hooks install       # copies all three hooks + patches ~\u002F.claude\u002Fsettings.json\niai-mcp capture-hooks status        # verify: should print \"status: ACTIVE\"\niai-mcp capture-hooks uninstall     # clean removal if ever needed\n```\n\nFor Codex:\n\n```bash\niai-mcp capture-hooks install --target codex\n```\n\nTo install both:\n\n```bash\niai-mcp capture-hooks install --target all\n```\n\nWhat the install does:\n\n- Copies three hook scripts from `deploy\u002Fhooks\u002F` to `~\u002F.claude\u002Fhooks\u002F` (chmod +x):\n  - `iai-mcp-turn-capture.sh` (`UserPromptSubmit`, timeout 5s) — appends each prompt + the preceding assistant turn(s) to a per-session buffer as pure file IO. Zero engine RPC during the session.\n  - `iai-mcp-session-capture.sh` (`Stop`, timeout 35s) — at session end, rolls the buffer over for the local engine to drain, and runs `iai-mcp capture-transcript --no-spawn` as a safety net.\n  - `iai-mcp-session-recall.sh` (`SessionStart`, timeout 30s) — calls `iai-mcp session-start` and pipes the assembled memory prefix to stdout, which Claude Code injects as `additionalContext` before the first prompt. Fail-safe: empty store or unreachable local engine yields empty stdout — session start is never blocked.\n- Registers iai-mcp in Claude Desktop's config if installed.\n- Idempotent — re-running detects existing entries and makes no changes.\n- No secrets, no tokens, no network calls.\n\nWhat happens at runtime:\n\n- **Every prompt** (per-turn hook): appends new transcript turns to the session buffer. ~5 ms per turn, no embedding, no engine socket.\n- **Every session end** (Stop hook): rolls the buffer over, captures any remaining turns. Fail-safe exit 0.\n- **Every session start** (recall hook): assembles the cached memory prefix and pipes it to Claude. Empty store or unreachable local engine → empty stdout.\n- **When idle** (local engine): drains the buffer through the shield → embed → dedup → encrypted insert pipeline on the WAKE → DROWSY edge (5-min idle) and after every REM cycle.\n\n### Connect your MCP host\n\nClaude Code:\n\n```bash\nclaude mcp add iai-mcp -- node \"$(pwd)\u002Fmcp-wrapper\u002Fdist\u002Findex.js\"\n```\n\nOr edit `~\u002F.claude.json` directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"iai-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fiai-mcp\u002Fmcp-wrapper\u002Fdist\u002Findex.js\"]\n    }\n  }\n}\n```\n\nUse the absolute path. `~` and `$HOME` won't expand here.\n\nFor Claude Desktop, edit `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`.\n\nCodex CLI:\n\n```toml\n[mcp_servers.iai-mcp]\ncommand = \"node\"\nargs = [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fiai-mcp\u002Fmcp-wrapper\u002Fdist\u002Findex.js\"]\n\n[mcp_servers.iai-mcp.env]\nIAI_MCP_PYTHON = \"\u002Fabsolute\u002Fpath\u002Fto\u002Fiai-mcp\u002F.venv\u002Fbin\u002Fpython\"\nIAI_MCP_STORE = \"\u002FUsers\u002Fyou\u002F.iai-mcp\"\n```\n\nCodex hooks are stable in current Codex CLI builds. If hooks are disabled by\nlocal policy or an older install, enable `[features].hooks = true` in\n`~\u002F.codex\u002Fconfig.toml`.\n\n### Verify\n\n```bash\niai-mcp doctor\niai-mcp daemon status\n```\n\nRestart Claude Code. Start a session, do some work, exit. Then:\n\n```bash\ntail ~\u002F.iai-mcp\u002Flogs\u002Fcapture-$(date -u +%Y-%m-%d).log\n```\n\nYou should see a `rc=0` line. That's your first memory.\n\n---\n\n## Usage\n\nYou do not call `iai-mcp` directly during a session. Once it's connected:\n\nCapture is automatic. Every turn, yours and the assistant's, is recorded verbatim with timestamps and session metadata. You don't say *\"remember this.\"*\n\nRecall is automatic. When a new session starts, the local engine assembles a small relevant slice of your history and injects it into the conversation prefix. You don't say *\"what did we say.\"*\n\nConsolidation runs idle. Between sessions, the local engine merges duplicates, strengthens recall pathways for things retrieved often, and prunes weak edges. The system gets quietly better at remembering you over time.\n\nAfter a few weeks of regular use the difference becomes noticeable. The assistant stops asking the same orientation questions, references things you mentioned in passing, and adapts to your style without being told.\n\nThere's also a CLI — you don't need it for normal use, but when you want to query or add to your memory straight from the terminal, `iai` is there: `recall`, `capture`, `ask` (LLM synthesis grounded in your memory), `status`, and `last`.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Fassets\u002Fiai-cli.png\" alt=\"iai — terminal memory for your agent\" width=\"600\">\n\u003C\u002Fp>\n\n---\n\n## How it works\n\nThe local engine is a Python process that runs in the background — it sleeps when idle and wakes when your assistant needs it, so it isn't always-on or constantly using CPU. Your MCP client connects to it via a Unix socket. No network exposure.\n\nRecall doesn't depend on the engine being awake. The store itself is always available: when the engine is asleep or not running, your assistant (and the `iai` CLI) read memory directly from the local store. The engine handles the fast LLM-free recall path when it's up, plus the nightly consolidation pass — it's never a gatekeeper on your memory.\n\nMemory is stored in three tiers:\n\n*Episodic* is verbatim, timestamped fragments of what was said. Write-once, never overwritten or rewritten.\n\n*Semantic* is summaries induced from clusters of related episodes during idle-time consolidation.\n\n*Procedural* is a small set of stable parameters about you, learned over time: preferences, style cues, recurring patterns. Eleven sealed knobs that shift based on what works.\n\nThe three tiers are backed by a hyperdimensional memory substrate — each kind of memory gets its own representation, so episodic detail, semantic gist, and procedural patterns don't collapse into one undifferentiated blob.\n\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fassets\u002Fslides\u002Fslide-05.jpg\" width=\"850\" alt=\"iai-pme\">\u003C\u002Fp>\n\nA background pass runs periodically (sleep cycles): it clusters episodes with my own community-detection algorithm, builds semantic summaries, decays old unreinforced connections, and reinforces frequently co-retrieved paths. Things you haven't revisited fade naturally. One step per night can make a single LLM call **through your existing Claude subscription** (`claude -p`) — no separate API key, capped at ≤1% of your daily quota. (`iai-mcp doctor` row (p) verifies there's no API-key SDK path installed at all.)\n\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fassets\u002Fslides\u002Fslide-08.jpg\" width=\"850\" alt=\"iai-pme\">\u003C\u002Fp>\n\nRecall combines three signals: semantic similarity, graph-link strength, and recency. All ranked together. The hot path runs entirely locally with no LLM in the loop.\n\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fassets\u002Fslides\u002Fslide-06.jpg\" width=\"850\" alt=\"iai-pme\">\u003C\u002Fp>\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fassets\u002Fslides\u002Fslide-07.jpg\" width=\"850\" alt=\"iai-pme\">\u003C\u002Fp>\n\nAll records are encrypted at rest with AES-256-GCM. The key lives in `~\u002F.iai-mcp\u002F.key` (mode 0600). Back it up. Lose the key, lose the memories.\n\nEverything lives at `~\u002F.iai-mcp\u002F`. Embeddings are computed locally. The only data that leaves the machine is your normal conversation with whatever LLM API your client uses.\n\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fassets\u002Fslides\u002Fslide-10.jpg\" width=\"850\" alt=\"iai-pme\">\u003C\u002Fp>\n\n---\n\n## Built our own\n\nMost memory projects are a thin layer over an off-the-shelf vector store and someone else's graph library. This one isn't. The load-bearing pieces are my own code, written for this exact workload — a small memory graph that mutates every night and gets queried on every recall:\n\n| Piece | What it is |\n|---|---|\n| **Hippo** | The storage engine — encrypted records, the vector index, and the graph in one local store. |\n| **MOSAIC** | My community-detection algorithm. It clusters the memory graph so recall spreads through the right neighbourhood and sleep can replay coherent episodes — tuned for a small, heterogeneously-weighted graph that changes every cycle, with stable community identity across splits and merges. |\n| **Lilli HD** | The hyperdimensional memory substrate — distinct representations for episodic \u002F semantic \u002F procedural memory, with structural recall (retrieve by the *shape* of a memory, not just its embedding). |\n| **Native engine** | A Rust core — the embedder and the graph kernels. This is where the latency comes from. |\n\nThese sit on a thin layer of proven, permissive primitives — SQLite, the `candle` tensor library, NumPy, and the audited `cryptography` AES implementation. I build the engine and the algorithms; I don't reinvent a database, a tensor kernel, or — deliberately — a crypto primitive. The interesting bricks are mine; the foundation under them is boring, battle-tested, and permissive. MIT throughout.\n\nI wrote these because the off-the-shelf options were built for a different problem — large static graphs, multi-tenant clouds, gist-style summarization — and they were slower and a worse fit for \"one person's memory on one machine, reorganized every night.\" Mine are faster *on this shape of problem*, which is the only shape I care about.\n\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fassets\u002Fslides\u002Fslide-09.jpg\" width=\"850\" alt=\"iai-pme\">\u003C\u002Fp>\n\n---\n\n## Benchmarks\n\nI built these because I wanted honest numbers, not a leaderboard. Every harness ships in `bench\u002F` with a one-line reproduce command — run them and get your own results. Where a number missed its target or regressed, it says so. Full detail in [`BENCHMARKS.md`](BENCHMARKS.md).\n\n### LongMemEval-S — the one head-to-head arena\n\nValidated in a single harness against [mempalace](https:\u002F\u002Fgithub.com\u002FMemPalace\u002Fmempalace) on the identical 500 cleaned questions, session granularity, `recall_any@k`, raw (no rerank):\n\n| System | Embedder | R@5 | R@10 |\n|---|---|---|---|\n| **iai** (product) | bge-small-en-v1.5 | **0.962** | 0.978 |\n| iai (matched embedder) | all-MiniLM-L6-v2 | 0.966 | 0.978 |\n| mempalace v3.3.6 | all-MiniLM-L6-v2 | 0.966 | 0.978 |\n\nOn raw retrieval — the headline both projects ship — it's an **exact tie** on the matched embedder — R@5 0.966 = 0.966 and R@10 0.978 = 0.978. Our product embedder scores 0.962 R@5, a 2-question-in-500 difference (noise). No win claimed — an honest tie is the strong, defensible statement. LongMemEval is a *cold, one-shot* retrieval test; it doesn't exercise cross-session memory, which is where the design's real edge is.\n\n### Where it actually leads — longitudinal memory\n\n| Benchmark | Result | What it measures |\n|---|---|---|\n| **Rescue@10** (post-contradiction) | **1.000** | After a fact is updated\u002Fcontradicted, the *current* fact still ranks top-10 — where flat-vector stores collapse on the more-similar stale fact. |\n| Personal-fact drift (recall@10) | 0.9933 | Retention across 50 facts \u002F 50 sessions \u002F 30 intervening sessions. |\n| Sleep-consolidation (recall@10) | 1.000 → 1.000 | Recall survives a full consolidation cycle. |\n| Session-start tokens | 1,629 min \u002F 2,993 std | Under the ≤3,000-token budget. |\n| MOSAIC parity | 36\u002F36 LFR + 10\u002F10 | NMI vs ground-truth, deterministic. |\n\n### Cost & footprint (honest disclosure — not a brag)\n\n| Metric | Measured | Note |\n|---|---|---|\n| Recall p95 latency | 77 ms @1k · 368 ms @10k | Above the \u003C100 ms@10k target at scale; the rank\u002Fcentrality stage dominates — a known optimization candidate. |\n| Memory (RSS) | 589 MB @10k records | Embedder + graph runtime; well under the 2 GB budget. |\n| Rust embedder | p50 70 ms \u002F p95 253 ms | bge-small-en-v1.5, 384-dim. |\n\n**One honest gap:** retrieving the *superseded* wording of an updated fact verbatim regressed (0.90 → 0.71) in this release — separate from Rescue@10 (current-fact retrieval, still 1.000) — and is a tracked fix for the next release.\n\n```bash\npython -m bench.longmemeval_blind            # LongMemEval-S (raw)\npython -m bench.contradiction_longitudinal   # Rescue@10 \u002F longitudinal\npython -m bench.personal_fact_drift          # drift \u002F retention\npython bench\u002Fsleep_ablation.py               # sleep-consolidation recall\npython -m bench.tokens                       # session-start token cost\npython -m bench.neural_map                   # recall latency\npython -m bench.memory_footprint             # RAM footprint\n```\n\nMeasured on an Apple M2 Max (64 GB). The harnesses are the proof — run them yourself.\n\n---\n\n## Configuration\n\n| Variable | Default | What it does |\n|---|---|---|\n| `IAI_MCP_STORE` | `~\u002F.iai-mcp\u002F` | Data directory |\n| `IAI_MCP_PYTHON` | — | Absolute path to the venv Python (for the MCP host config) |\n\nThe old `IAI_MCP_EMBED_MODEL` knob is gone — the embedder is a single built-in English-only model. There are many internal tuning knobs (`IAI_MCP_*`), but you shouldn't need to touch them.\n\n---\n\n## Doctor\n\n`iai-mcp doctor` runs 23 checks against the local engine, the store, the native engine, and the runtime state. Output is one line per check: PASS, WARN, or FAIL.\n\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fassets\u002Fslides\u002Fslide-13.jpg\" width=\"850\" alt=\"iai-pme\">\u003C\u002Fp>\n\n```bash\niai-mcp doctor\n```\n\nWhat it checks:\n\n| # | Check | What it means |\n|---|---|---|\n| a | daemon process alive | Is the daemon process running? |\n| b | socket file fresh | Can the UNIX socket accept a connection? |\n| c | lock file healthy | Is the process lock held correctly? |\n| d | no orphan core procs | No leftover stdio core process without a daemon |\n| e | daemon state file valid | State file parses and has expected fields |\n| f | hippo storage readable | Can the store be opened and queried? |\n| g | no dup binders | Only one process is bound to the socket |\n| h | crypto key file state | Encryption key exists, correct permissions (0600) |\n| i | hippo db size | Store size is within healthy bounds |\n| j | lifecycle current state | Current FSM state is valid |\n| k | lifecycle history 24h | Recent lifecycle transitions look sane |\n| l | sleep cycle quarantine | No sleep cycle is stuck or quarantined |\n| m | heartbeat scanner | Wrapper heartbeat files are fresh |\n| n | HID idle source | Idle detection source is available |\n| o | Claude subscription credentials | Subscription creds present for the nightly LLM step |\n| p | anthropic SDK absent | Confirms no API-key SDK path is installed |\n| q | iai CLI reachable | The `iai` user CLI is on `PATH` |\n| r | hippo hnsw index | The ANN index is loadable |\n| s | hippo schema version | Store schema is current |\n| t | hippo_compacted freshness | Compaction has run recently |\n| u | recall centrality regression | Recall ranking hasn't regressed |\n| v | native Rust embedder | The Rust embedder is built and produces vectors |\n| z | AVX2 CPU support | CPU supports the instructions the native libs need |\n\nA full-PASS run is healthy. Dropping (b) during a sleep cycle is normal (the socket is busy during consolidation). Multiple FAILs, or a FAIL on (a)\u002F(f)\u002F(v), means something is actually wrong.\n\n---\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n|---|---|---|\n| Local engine refuses to start, error ends in a build command | The native Rust engine isn't built (mandatory — no fallback) | Run the build command the error prints (the installer normally does this). |\n| `keyring.errors.NoKeyringError` on first run | Storage is file-backed at `~\u002F.iai-mcp\u002F.crypto.key`. Older setups referenced a Keychain-only path. | `iai-mcp crypto init` (idempotent). `iai-mcp daemon install` calls this automatically on fresh installs. |\n| Daemon crashes on first start with `CryptoKeyError` | Fresh install bypassed `daemon install` — no `.crypto.key` exists yet. | `iai-mcp crypto init`, then restart the daemon. |\n| `iai-mcp daemon install` says \"launchd bootstrap failed\" | Existing plist from previous install | `iai-mcp daemon uninstall` first, then `install` again. |\n| Daemon \"active\" but no tick events | First-week bootstrap (no quiet-window data yet) | Wait 2 h of MCP idle, or force: `iai-mcp daemon force-rem` |\n| Claude Code doesn't show iai-mcp tools after `claude mcp add` | Forgot to fully quit — \"reload window\" is not enough | `killall Claude` then relaunch. Check `~\u002FLibrary\u002FLogs\u002FClaude\u002F*.log` for MCP stderr. |\n\n---\n\n## Notes for AI assistants helping with installation\n\nIf you're an AI model helping a user install or debug iai-mcp, read this before diagnosing anything.\n\nTerminology note: this doc calls the background component the **local engine**. Its process, CLI subcommands and `doctor` check labels still use the original name `daemon` — e.g. `iai-mcp daemon status`, `pgrep -f iai_mcp.daemon`, and the `(a) daemon process alive` check. \"Local engine\" and \"daemon\" refer to the same process.\n\nThe local engine has four FSM states: `WAKE`, `TRANSITIONING`, `SLEEP`, `DREAMING`. Separately, the wrapper-layer lifecycle has four states: `WAKE`, `DROWSY`, `SLEEP`, `HIBERNATION`. These are two different state machines in two different files. Don't confuse them.\n\nThings that look broken but are not:\n\n- `last_tick_at` hasn't changed in hours. This is a sleep-cycle tick timestamp, not a process heartbeat. The daemon can be alive and healthy with a stale `last_tick_at`. Check `iai-mcp daemon status` instead.\n- `fsm_state: DREAMING` for hours. Normal. The local engine is running a sleep cycle. Wake transitions are event-driven (a new session arriving wakes it), not time-driven.\n- `status: deferred` in the capture log. This is the only path the Stop hook takes. It writes captures to `~\u002F.iai-mcp\u002F.deferred-captures\u002F` and the local engine picks them up on its next tick. This is by design, not a failure.\n- `iai-mcp doctor` drops the socket check during SLEEP or DREAMING. The socket is intentionally unresponsive during consolidation passes. This is healthy.\n- Cold start takes a few seconds. The local engine initializes the store and loads the embedding model into memory. Don't kill it because it hasn't responded in 5 seconds.\n\nActual problems look like: `iai-mcp daemon status` returning `ok: False`, doctor showing multiple FAIL results, or the daemon process not existing at all (`pgrep -f iai_mcp.daemon` returns nothing).\n\nWhen in doubt, run `iai-mcp doctor` and read what it says. The output is self-explanatory.\n\n---\n\n## Status and limitations\n\n**v1.0.0 — out of experimental.** I built this for myself and ran it daily for months; it's now a stable release with a committed public surface. The MCP tool set and the on-disk store stay stable across `1.x` — breaking changes go through the changelog with a deprecation window. It's still a solo-maintained project with no enterprise SLA, but it's no longer a moving target.\n\nLimitations worth knowing about:\n\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fassets\u002Fslides\u002Fslide-14.jpg\" width=\"850\" alt=\"iai-pme\">\u003C\u002Fp>\n\n- English-only by design. The assistant translates to English on the way into memory; the store and the embedder are English-only on purpose.\n- No cross-machine sync. The data lives where the local engine runs. Backup is `cp -a ~\u002F.iai-mcp\u002F` somewhere safe.\n- No GUI. Inspection happens through CLI subcommands (`iai-mcp doctor`, `iai-mcp daemon status`, `iai-mcp topology`).\n- Cold start on a freshly booted machine takes a few seconds while the local engine initializes caches.\n- Recall quality on the first ~10 sessions is mediocre. The system needs material to consolidate before it gets useful.\n\n---\n\n## Compatibility\n\niai-mcp talks to its host over **MCP-over-stdio** — the same protocol every MCP-compatible CLI speaks. So the memory tools (recall, capture, ask, status) work with **any MCP CLI**:\n\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fassets\u002Fslides\u002Fslide-12.jpg\" width=\"850\" alt=\"iai-pme\">\u003C\u002Fp>\n\n- **Claude Code** — primary host, validated in daily use.\n- **Codex CLI** — supported, with ambient capture through a `Stop` hook.\n- **Gemini CLI**, **Cursor CLI**, and other MCP-over-stdio CLIs — connect through the same standard protocol; the MCP tools work out of the box.\n- **Claude Desktop** — works; uses `claude_desktop_config.json` instead of `~\u002F.claude.json`.\n\nAmbient capture (the hooks that record and recall automatically) ships for Claude Code and Codex today. On other CLIs the MCP tools work directly; wiring up their native hooks for fully automatic capture is a great first contribution — open an issue or PR.\n\n---\n\n## About the name\n\nThe project is **iai** — a *personal memory engine*. The short name is an acronym; the descriptor says what it is.\n\n**IAI — Independent Autistic Intelligence** (the memory style):\n\n- **Independent.** Fully local. The local engine runs on your machine, embeddings are computed locally, no telemetry, no cloud dependency. Your memory is your data and stays your data — and it tunes itself over time without you steering it.\n- **Autistic.** Describes the memory style, not a diagnosis or a metaphor. The memory is built around verbatim recall, attention to specific cues, and a refusal to smooth rare events into typical ones. Most memory systems compress and summarize aggressively, aiming to give the assistant a *gist* of the past. This one preserves what was actually said and surfaces it on a precise cue. In practice that shows up as: literal preservation over paraphrase; deep focus on the current thread rather than diffuse association; direct, unmasked output; a stable identity that doesn't drift. The trade-off is intentional: more storage and a stricter retrieval interface, in exchange for not losing details.\n- **Intelligence.** Used in the systems sense — something that observes, adapts, and stays viable over time — not the marketing sense.\n\n**Personal memory engine** (what it is): not a chatbot feature or a cloud add-on, but a memory *engine* — its own storage, clustering, hyperdimensional substrate and native core — that belongs to one person and runs on one machine. See [Built our own](#built-our-own).\n\nIt's an operational design choice about how memory should behave, not a clinical claim.\n\n---\n\n## Authors\n\nBy Areg Aramovich Noya, in collaboration with the team at [lcgc.dev](https:\u002F\u002Flcgc.dev).\n\nI built this because I needed it. It works for me. If it works for you, take it.\n\n## License\n\n[MIT](LICENSE)\n\n## Contributing\n\nIssues and PRs welcome. If your change touches retrieval, capture, or consolidation, include bench re-runs.\n","iai-personal-memory-engine 是一个为AI编码助手设计的开源记忆系统。该项目通过MCP协议，为Claude等AI助手提供长期记忆功能，能够记录每次会话的内容，并在新对话开始时提供相关记忆片段，从而避免了重复输入相同信息的需求。其核心功能包括语义搜索、向量搜索和情景记忆等，利用Python编写，并支持Rust原生引擎以提高性能。该系统适合需要增强AI助手记忆力的开发者或团队使用，在本地运行且不收集遥测数据，确保用户隐私安全。",2,"2026-06-11 04:10:09","CREATED_QUERY"]