iai-mcp-memory-server

# iai-mcp Memory Server > Skill by [ara.so](https://ara.so) — MCP Skills collection. ## What It Is iai-mcp is a local MCP server that provides long-term memory for AI coding assistants (Claude Code, Codex CLI, etc.). It captures every conversation turn verbatim, stores them encrypted with semantic embeddings, and automatically recalls relevant context at session start. All data stays local with no telemetry. **Key Features:** - ≥99% verbatim recall at 10k memories - <100ms p95 recall latency - AES-256-GCM encryption at rest - Automatic capture/recall via hooks - LanceDB vector storage with bge-small-en-v1.5 embeddings - Background consolidation and duplicate merging ## Installation ### Prerequisites Check ```bash # Verify requirements python3 --version # Must be 3.11 or 3.12 node --version # Must be 18+ uname -m # Apple Silicon recommended ``` ### Install the Server ```bash git clone https://github.com/CodeAbra/iai-mcp.git cd iai-mcp bash scripts/install.sh ``` This creates a Python venv, installs dependencies (LanceDB, sentence-transformers, torch, NetworkX, igraph), downloads the embedding model (~130 MB), and registers the daemon with launchd on macOS. ### Add to PATH ```bash # Add to ~/.zshrc or ~/.bashrc export PATH="$HOME/.local/bin:$PATH" # Verify iai-mcp --version ``` ### Install Capture Hooks **For Claude Code:** ```bash iai-mcp capture-hooks install iai-mcp capture-hooks status # Should show "status: ACTIVE" ``` **For Codex CLI:** ```bash iai-mcp capture-hooks install --target codex ``` **For both:** ```bash iai-mcp capture-hooks install --target all ``` This installs three hooks to `~/.claude/hooks/`: - `iai-mcp-turn-capture.sh` (UserPromptSubmit) — Captures each turn to session buffer - `iai-mcp-session-capture.sh` (Stop) — Processes buffer at session end - `iai-mcp-session-recall.sh` (SessionStart) — Injects memory context at start ### Connect MCP Host **Claude Code:** ```bash cd /path/to/iai-mcp claude mcp add iai-mcp -- node "$(pwd)/mcp-wrapper/dist/index.js" ``` **Or edit `~/.claude.json` manually:** ```json { "mcpServers": { "iai-mcp": { "command": "node", "args": ["/absolute/path/to/iai-mcp/mcp-wrapper/dist/index.js"] } } } ``` **Codex CLI (`~/.codex/config.toml`):** ```toml [mcp_servers.iai-mcp] command = "node" args = ["/absolute/path/to/iai-mcp/mcp-wrapper/dist/index.js"] [mcp_servers.iai-mcp.env] IAI_MCP_PYTHON = "/absolute/path/to/iai-mcp/.venv/bin/python" IAI_MCP_STORE = "/Users/you/.iai-mcp" TRANSFORMERS_VERBOSITY = "error" TOKENIZERS_PARALLELISM = "false" ``` ### Verify Installation ```bash iai-mcp doctor # Should show 14/14 PASS or 13/14 during sleep cycle iai-mcp daemon status # Check logs after first session tail ~/.iai-mcp/logs/capture-$(date -u +%Y-%m-%d).log # Look for "rc=0" indicating successful capture ``` ## Key Commands ### Daemon Management ```bash # Start daemon (usually auto-starts via launchd) iai-mcp daemon start # Check status iai-mcp daemon status # Stop daemon iai-mcp daemon stop # Restart daemon iai-mcp daemon restart # View daemon logs tail -f ~/.iai-mcp/logs/daemon.log ``` ### Capture Hooks ```bash # Install hooks iai-mcp capture-hooks install [--target {claude|codex|all}] # Check hook status iai-mcp capture-hooks status # Uninstall hooks iai-mcp capture-hooks uninstall # Manual transcript capture (fallback) iai-mcp capture-transcript --no-spawn ``` ### Memory Operations ```bash # Trigger session start (usually called by hook) iai-mcp session-start # Query memory directly iai-mcp query "what did we discuss about error handling?" # View recent memories iai-mcp list --limit 20 # Export memories iai-mcp export --output memories.json # Clear all memories (irreversible) iai-mcp clear --confirm ``` ### Diagnostics ```bash # Full health check (14 tests) iai-mcp doctor # Check specific components iai-mcp doctor --check daemon iai-mcp doctor --check store iai-mcp doctor --check crypto # View statistics iai-mcp stats # Check embedding model iai-mcp info --embeddings ``` ### Migrations ```bash # Re-embed store with different model iai-mcp migrate reembed --model bge-m3 # Rebuild graph indices iai-mcp migrate rebuild-graph # Compact database iai-mcp migrate compact ``` ## Configuration ### Environment Variables ```bash # Data directory (default: ~/.iai-mcp/) export IAI_MCP_STORE="/custom/path/to/store" # Embedding model (default: bge-small-en-v1.5) export IAI_MCP_EMBED_MODEL="bge-m3" # For multilingual support # Daemon socket path (advanced) export IAI_MCP_SOCKET="/tmp/iai-mcp.sock" # Log level export IAI_MCP_LOG_LEVEL="DEBUG" # DEBUG, INFO, WARN, ERROR ``` ### Config File (`~/.iai-mcp/config.json`) ```json { "embedding": { "model": "bge-small-en-v1.5", "batch_size": 32, "normalize": true }, "recall": { "max_tokens": 3000, "cold_max_tokens": 8000, "min_similarity": 0.3 }, "consolidation": { "enabled": true, "idle_delay_seconds": 300, "cluster_threshold": 0.7, "decay_rate": 0.95 }, "encryption": { "enabled": true, "algorithm": "aes-256-gcm" }, "insights": { "enabled": false, "api_key_env": "ANTHROPIC_API_KEY" } } ``` ## Real Usage Patterns ### Pattern 1: Basic Setup for Claude Code ```bash # Clone and install git clone https://github.com/CodeAbra/iai-mcp.git cd iai-mcp bash scripts/install.sh # Add to PATH echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc # Install hooks iai-mcp capture-hooks install # Connect to Claude Code claude mcp add iai-mcp -- node "$(pwd)/mcp-wrapper/dist/index.js" # Verify iai-mcp doctor ``` ### Pattern 2: Multilingual Setup ```bash # Set multilingual model export IAI_MCP_EMBED_MODEL="bge-m3" # Install with custom model bash scripts/install.sh # Verify model loaded iai-mcp info --embeddings # Should show: Model: bge-m3 ``` ### Pattern 3: Manual Memory Query ```python # Not typical usage (hooks handle this), but for debugging: import subprocess import json def query_memory(text: str) -> dict: """Query iai-mcp memory directly.""" result = subprocess.run( ["iai-mcp", "query", text, "--json"], capture_output=True, text=True ) return json.loads(result.stdout) if result.returncode == 0 else {} # Example memories = query_memory("error handling patterns") for mem in memories.get("results", []): print(f"[{mem['timestamp']}] {mem['content'][:100]}...") ``` ### Pattern 4: Custom Hook Integration ```bash #!/usr/bin/env bash # Custom post-session hook: ~/.claude/hooks/my-custom-capture.sh set -euo pipefail SESSION_ID="$1" TRANSCRIPT_PATH="$2" # Let iai-mcp process the transcript iai-mcp capture-transcript --session-id "$SESSION_ID" --path "$TRANSCRIPT_PATH" # Custom logic: export to external system if [ -f "$HOME/.iai-mcp/exports/latest.json" ]; then curl -X POST https://my-backup.example.com/sync \ -H "Authorization: Bearer $MY_BACKUP_TOKEN" \ --data-binary "@$HOME/.iai-mcp/exports/latest.json" fi ``` ### Pattern 5: Programmatic Memory Access ```python # Advanced: Direct LanceDB access (not recommended for normal use) import lancedb import os from pathlib import Path store_path = Path.home() / ".iai-mcp" db = lancedb.connect(str(store_path / "lance")) # Query episodic memories table = db.open_table("records") results = table.search([0.1] * 384) \ # Replace with actual embedding .limit(10) \ .to_pandas() print(results[["timestamp", "content", "session_id"]]) ``` ## Benchmarks Run the included benchmark suite to verify performance on your hardware: ```bash cd /path/to/iai-mcp # Verbatim recall accuracy python -m bench.verbatim # Expected: >=99% byte-exact recall at N=10k # Recall latency python -m bench.neural_map # Expected: p95 <100ms # Memory footprint python -m bench.memory_footprint # Expected: ~150-300 MB steady state # Session-start token cost python -m bench.tokens # Expected: <=3000 tokens warm, <=8000 cold # Full session cost python -m bench.total_session_cost # Longitudinal trajectory (30 sessions) python -m bench.trajectory # Contradiction detection python -m bench.contradiction_longitudinal # LongMemEval-S blind run (no tuning) python -m bench.longmemeval_blind ``` ## Troubleshooting ### Daemon Won't Start ```bash # Check for orphan processes ps aux | grep iai-mcp # Kill orphans killall -9 iai-mcp-daemon # Remove stale socket rm -f ~/.iai-mcp/daemon.sock # Check logs tail -n 100 ~/.iai-mcp/logs/daemon.log # Restart iai-mcp daemon restart ``` ### Hooks Not Capturing ```bash # Verify hook installation iai-mcp capture-hooks status # Check hook permissions ls -la ~/.claude/hooks/iai-mcp-*.sh # Should be -rwxr-xr-x # Test hook manually ~/.claude/hooks/iai-mcp-turn-capture.sh "test-session-id" "user" "Test prompt" # Check buffer cat ~/.iai-mcp/session-buffers/test-session-id.jsonl ``` ### No Memory Recalled at Session Start ```bash # Check if store is empty iai-mcp stats # Should show total_memories > 0 # Test recall manually iai-mcp session-start --debug # Check recall hook logs tail ~/.iai-mcp/logs/recall-$(date -u +%Y-%m-%d).log # Verify daemon is running iai-mcp daemon status ``` ### Encryption Key Lost ```bash # Check key exists ls -la ~/.iai-mcp/.key # Should be -rw------- (600) # If lost, data is unrecoverable # Backup key location (if you made one): cat ~/.iai-mcp/.key.backup # Start fresh (destroys all memories) iai-mcp clear --confirm # New key generated on next capture ``` ### High Memory Usage ```bash # Check current footprint iai-mcp stats --memory # Compact database iai-mcp migrate compact # Reduce embedding batch size export IAI_MCP_EMBED_BATCH=16 # Default 32 # Restart daemon iai-mcp daemon restart ``` ### Slow Recall ```bash # Check store size du -sh ~/.iai-mcp/lance/ # Rebuild indices iai-mcp migrate rebuild-graph # Check embedding model is cached ls -lh ~/.cache/huggingface/hub/ # Should see models--BAAI--bge-small-en-v1.5 # Profile a query time iai-mcp query "test query" --debug ``` ### Hook Timeout Errors ```bash # Increase hook timeout (Claude Code settings.json) # Edit: ~/.claude/settings.json { "hooks": { "timeouts": { "UserPromptSubmit": 10000, # Default 5000ms "Stop": 60000, # Default 35000ms "SessionStart": 45000 # Default 30000ms }