[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-11344":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":15,"stars7d":15,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":17,"rankGlobal":9,"rankLanguage":9,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":34,"readmeContent":35,"aiSummary":36,"trendingCount":15,"starSnapshotCount":15,"syncStatus":37,"lastSyncTime":38,"discoverSource":39},11344,"iai-mcp","CodeAbra\u002Fiai-mcp","CodeAbra","The best-benchmarked open-source memory system for AI coding assistants",null,"Python",135,16,28,4,0,25,3.69,"MIT License",false,"main",true,[23,24,25,26,27,28,29,30,31,32,33],"ai-agents","claude","claude-code","embeddings","llm-tools","local-first","mcp","mcp-server","memory","python","vector-search","2026-06-12 02:02:31","\u003Cp align=\"center\">\n  \u003Cimg src=\"logo.png\" alt=\"IAI-MCP\" width=\"600\">\n\u003C\u002Fp>\n\n\n\u003Ch3 align=\"center\">The best-benchmarked open-source memory system 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  \u003Ca href=\"LICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-blue.svg\" alt=\"License: MIT\">\u003C\u002Fa>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.11%20%7C%203.12-blue.svg\" alt=\"Python 3.11 | 3.12\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-macOS-lightgrey.svg\" alt=\"Platform: macOS\">\n\u003C\u002Fp>\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fverbatim%20recall-%E2%89%A599%25%20at%2010k-brightgreen.svg\" alt=\"Verbatim recall >= 99%\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fp95%20latency-%3C100ms-brightgreen.svg\" alt=\"p95 \u003C 100ms\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fencryption-AES--256--GCM-green.svg\" alt=\"AES-256-GCM\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flocal--only-no%20telemetry-green.svg\" alt=\"Local only, no telemetry\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP-compatible-purple.svg\" 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-mcp\n\n*Independent Autistic Intelligence — a local memory layer for Claude (and other MCP-compatible assistants).*\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- [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\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\n---\n\n## Quick start\n\n### Prerequisites\n\n- macOS (Apple Silicon tested)\n- Python 3.11 or 3.12\n- Node.js 18+\n- [Claude Code](https:\u002F\u002Fdocs.claude.com\u002Fen\u002Fdocs\u002Fclaude-code\u002Foverview) or Codex CLI as the MCP host\n- ~500 MB free disk\n\nWindows and Linux not supported yet but I'm working on it.\n\n### Install\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FCodeAbra\u002Fiai-mcp.git\ncd iai-mcp\nbash scripts\u002Finstall.sh\n```\n\nThe installer creates a Python venv, installs dependencies (LanceDB, sentence-transformers, torch-hd, NetworkX, igraph), builds the TypeScript MCP wrapper, pre-downloads the default embedding model (~130 MB), symlinks the CLI to `~\u002F.local\u002Fbin\u002Fiai-mcp`, and on macOS registers the daemon with launchd.\n\nMake sure `~\u002F.local\u002Fbin` is on your `PATH`:\n\n```bash\nexport PATH=\"$HOME\u002F.local\u002Fbin:$PATH\"  # add to ~\u002F.zshrc or ~\u002F.bashrc\niai-mcp --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 daemon RPC during the session.\n  - `iai-mcp-session-capture.sh` (`Stop`, timeout 35s) — at session end, rolls the buffer over for the daemon 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 daemon 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 daemon 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 daemon → empty stdout.\n- **When idle** (daemon): 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 (untested), 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\"\nTRANSFORMERS_VERBOSITY = \"error\"\nTOKENIZERS_PARALLELISM = \"false\"\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 daemon 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 daemon 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\n---\n\n## How it works\n\nThe daemon is a Python process that runs in the background. Your MCP client connects to it via a Unix socket. No network exposure.\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\nA background pass runs periodically (sleep cycles): it clusters episodes, builds semantic summaries, decays old unreinforced connections, and reinforces frequently co-retrieved paths. Things you haven't revisited fade naturally. There's an optional \"insight of the day\" step that makes one Anthropic API call, but it's off by default.\n\nRecall combines three signals: semantic similarity, graph-link strength, and recency. All ranked together.\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 with `bge-small-en-v1.5`. The only data that leaves the machine is your normal conversation with whatever LLM API your client uses.\n\n```\nClaude Code  \u003C--MCP-stdio-->  TypeScript wrapper  \u003C--UNIX socket-->  Python daemon  \u003C-->  LanceDB\n```\n\n---\n\n## Benchmarks\n\nI made these because I wanted honest numbers. Every harness ships in `bench\u002F`. Run them on your machine, get your own results.\n\n| Metric | Target | Measured |\n|---|---|---|\n| Verbatim recall (byte-exact) | >=99% | >=99% at N=10k |\n| Recall p95 latency | \u003C100 ms | \u003C100 ms at N=10k |\n| RAM at steady state | \u003C=300 MB | ~150-300 MB |\n| Session-start tokens (warm cache) | \u003C=3,000 | \u003C=3,000 |\n| Session-start tokens (cold) | \u003C=8,000 | \u003C=8,000 |\n\n```bash\npython -m bench.verbatim                     # verbatim fidelity\npython -m bench.neural_map                   # recall latency\npython -m bench.memory_footprint             # RAM usage\npython -m bench.tokens                       # session-start cost\npython -m bench.total_session_cost           # full 10-turn cost\npython -m bench.trajectory                   # 30-session corpus\npython -m bench.contradiction_longitudinal   # falsifiability\npython -m bench.longmemeval_blind            # LongMemEval-S blind run\n```\n\nThe LongMemEval-S run is blind on purpose. No dataset-specific tuning, no hyperparameter sweep. The numbers are what they are.\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_EMBED_MODEL` | `bge-small-en-v1.5` | Embedding model. `bge-m3` for multilingual at ~3x size. |\n\nSwitching embedders requires re-embedding the store: `iai-mcp migrate reembed`.\n\n---\n\n## Doctor\n\n`iai-mcp doctor` runs 14 checks against the daemon, the store, and the runtime state. Output is one line per check: PASS, WARN, or FAIL.\n\n```bash\niai-mcp doctor\n```\n\nWhat it checks:\n\n| # | Check | What it means |\n|---|---|---|\n| a | Daemon alive | Is the daemon process running? |\n| b | Socket fresh | Can the UNIX socket accept a connection? |\n| c | Lock healthy | Is the process lock held correctly? |\n| d | No orphan core | No leftover stdio core process without a daemon |\n| e | State file valid | `.daemon-state.json` parses and has expected fields |\n| f | LanceDB readable | Can the records table be opened and queried? |\n| g | No duplicate binders | Only one process is bound to the socket |\n| h | Crypto file state | Encryption key exists, correct permissions (0600) |\n| i | Lance versions count | LanceDB version manifests aren't piling up |\n| j | Lifecycle current state | Current FSM state is valid |\n| k | Lifecycle history 24h | Recent lifecycle transitions look sane |\n| l | Sleep cycle status | Last sleep cycle completed or is running normally |\n| m | Heartbeat scanner | Wrapper heartbeat files are fresh |\n| n | HID idle source | Idle detection source is available |\n\n14\u002F14 PASS is healthy. 13\u002F14 with check (b) failing during a sleep cycle is also normal (the socket is busy during consolidation). Multiple FAILs or a FAIL on (a) or (f) means something is actually wrong.\n\n---\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n|---|---|---|\n| `import lancedb` crashes with `Illegal instruction (SIGILL)` | CPU lacks AVX2 (Intel Celeron N4020, Atom, older Core2, some embedded ARM). LanceDB has no SSE-only fallback. | Deploy on a host with AVX2 and connect over SSH stdio — see [Headless \u002F VPS deployment](#headless--vps-deployment). |\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` (e.g. systemd unit copied manually) — 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### Headless \u002F VPS deployment\n\nIf your local CPU lacks AVX2 (Intel Celeron N4020 Gemini Lake, older Atoms, some embedded ARM) `import lancedb` will crash with `SIGILL` and the daemon can't run locally. The escape hatch is to run the daemon on a remote host (any cheap VPS with AVX2) and let Claude Code spawn the MCP wrapper over SSH stdio.\n\nOn the **remote host** (Linux example):\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FCodeAbra\u002Fiai-mcp.git \u002Fopt\u002Fiai-mcp\ncd \u002Fopt\u002Fiai-mcp && bash scripts\u002Finstall.sh\nloginctl enable-linger \"$USER\"\niai-mcp daemon install --yes\nsystemctl --user status iai-mcp-daemon.service\n```\n\nOn the **local host**:\n\n```bash\nclaude mcp add iai-mcp -- \\\n  ssh -o ConnectTimeout=5 -o ServerAliveInterval=30 \\\n      user@vps.example.com \\\n      node \u002Fopt\u002Fiai-mcp\u002Fmcp-wrapper\u002Fdist\u002Findex.js\n```\n\nRound-trip latency on the same continent is typically 10-50 ms per call.\n\n**Doctor caveats on headless hosts.** `iai-mcp doctor` check (n) \"HID idle source\" returns WARN because there is no display hardware. The daemon's wake\u002Fsleep cycle falls back to heartbeat-idle, which works correctly. Check (b) \"socket\" may FAIL transiently during `DREAMING` state. Both are expected.\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\nThe daemon 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 daemon 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 daemon picks them up on its next tick. This is by design, not a failure.\n- `iai-mcp doctor` shows 13\u002F14 PASS with check (b) \"socket unreachable.\" Expected when the daemon FSM is in SLEEP or DREAMING. The socket is intentionally unresponsive during consolidation passes. This is healthy.\n- Cold start takes a few seconds. The daemon needs to initialize the LanceDB store and load 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\nThis is experimental. I built it for myself, it works on my machine, and I'm sharing it because it might be useful to you. No SLA, no support guarantee. Breaking changes are possible between versions. Pin a commit hash if you depend on stability.\n\nLimitations worth knowing about:\n\n- The default embedding model is English-only. The assistant translates to English on the way into memory. The opt-in `bge-m3` model removes this constraint at a cost of ~3x storage and slower indexing.\n- No cross-machine sync. The data lives where the daemon 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 daemon 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\nClaude Code is the primary host, validated in daily use.\n\nClaude Desktop should work (uses `claude_desktop_config.json` instead of `~\u002F.claude.json`) but hasn't been tested end to end.\n\nCodex CLI supports the MCP wrapper and ambient capture through a `Stop` hook.\n\nOther MCP-over-stdio hosts speak the same protocol and should work in principle. Not tested.\n\nIf you get it running on something else, open an issue or PR.\n\n---\n\n## About the name\n\n*IAI* stands for Independent Autistic Intelligence.\n\n- **Independent.** Fully local. The daemon runs on your machine, embeddings are computed locally, no telemetry, no cloud dependency. Your memory is your data and stays your data.\n- **Autistic.** Describes the memory style, not a diagnosis or a metaphor. The memory is built around verbatim recall, attention to specific cues, and 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. 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---\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## Acknowledgements\n\nv0.2.0 — thanks to Reddit user [u\u002FBeginningReflection4](https:\u002F\u002Fwww.reddit.com\u002Fuser\u002FBeginningReflection4) for the feedback and testing that shaped this release.\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-mcp 是一个为AI编码助手设计的开源内存系统，旨在提供长期记忆功能。其核心功能包括支持MCP协议，能够精确地记录和组织会话内容，并在新对话开始时提供相关的历史信息，从而提高AI助手的理解能力。技术特点上，iai-mcp使用Python编写，支持Python 3.11和3.12版本，具有高准确率（≥99%）的文本回忆能力和低延迟（p95\u003C100ms），同时采用AES-256-GCM加密保证数据安全且无遥测数据收集。该系统适合于需要增强AI助手记忆能力的场景，特别是对于那些希望本地化存储和处理对话历史的开发者而言。",2,"2026-06-01 03:23:43","CREATED_QUERY"]