MCPInstall

iai-mcp-memory-server

by reason-machinesAI & Agents

Local MCP memory server for AI coding assistants with verbatim recall, semantic search, and automatic session capture

Installs
216
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/mcp-skills --skill iai-mcp-memory-server
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads iai-mcp-memory-server automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

iai-mcp Memory Server

Skill by 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

# Verify requirements
python3 --version  # Must be 3.11 or 3.12
node --version     # Must be 18+
uname -m           # Apple Silicon recommended

Install the Server

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

# Add to ~/.zshrc or ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"

# Verify
iai-mcp --version

Install Capture Hooks

For Claude Code:

iai-mcp capture-hooks install
iai-mcp capture-hooks status  # Should show "status: ACTIVE"

For Codex CLI:

iai-mcp capture-hooks install --target codex

For both:

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:

cd /path/to/iai-mcp
claude mcp add iai-mcp -- node "$(pwd)/mcp-wrapper/dist/index.js"

Or edit ~/.claude.json manually:

{
  "mcpServers": {
    "iai-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/iai-mcp/mcp-wrapper/dist/index.js"]
    }
  }
}

Codex CLI (~/.codex/config.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

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

# 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

# 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

# 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

# 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

# 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

# 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)

{
  "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

# 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

# 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

# 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

#!/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

# 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:

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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
    }
  }
}

Doctor Check Failures

# Run with verbose output
iai-mcp doctor --verbose

# Fix common issues:

# Check (a) Daemon alive
iai-mcp daemon start

# Check (b) Socket fresh (may fail during consolidation - normal)
# Wait 30s and retry

# Check (h) Crypto file state
chmod 600 ~/.iai-mcp/.key

# Check (i) Lance versions piling up
iai-mcp migrate compact

# Check (k) Lifecycle history
rm ~/.iai-mcp/.daemon-state.json
iai-mcp daemon restart

Migration to New Machine

# On old machine: backup store and key
tar czf iai-mcp-backup.tar.gz ~/.iai-mcp/

# On new machine: install iai-mcp
git clone https://github.com/CodeAbra/iai-mcp.git
cd iai-mcp
bash scripts/install.sh

# Restore backup
tar xzf iai-mcp-backup.tar.gz -C ~/

# Verify key permissions
chmod 600 ~/.iai-mcp/.key

# Restart daemon
iai-mcp daemon restart

# Verify
iai-mcp doctor
iai-mcp stats

Advanced: Custom Embedding Models

# List available models
huggingface-cli scan-cache

# Download custom model
huggingface-cli download BAAI/bge-large-en-v1.5

# Configure
export IAI_MCP_EMBED_MODEL="bge-large-en-v1.5"

# Re-embed existing store
iai-mcp migrate reembed --model bge-large-en-v1.5 --confirm

# Verify
iai-mcp info --embeddings

Security Notes

  • All memories encrypted with AES-256-GCM at rest
  • Encryption key: ~/.iai-mcp/.key (mode 0600)
  • Backup the key — no key recovery possible
  • No network calls except optional Anthropic API for insights (disabled by default)
  • No telemetry, no analytics, fully local
  • Socket: Unix domain socket (no network exposure)
# Backup encryption key
cp ~/.iai-mcp/.key ~/secure-backup/.iai-mcp-key.backup
chmod 400 ~/secure-backup/.iai-mcp-key.backup

Notes

  • Platform: macOS (Apple Silicon tested). Linux/Windows support planned.
  • Python: 3.11 or 3.12 required (3.13 may have torch compatibility issues).
  • Disk: ~500 MB for fresh install, grows with memories (~1-2 MB per 1000 turns).
  • Model: Default bge-small-en-v1.5 is ~130 MB. bge-m3 (multilingual) is ~380 MB.
  • Token Cost: Session-start recall adds 1k-3k tokens (warm) or up to 8k (cold cache).
  • Consolidation: Runs every 5 minutes of idle time. Socket briefly unavailable during sleep cycle (normal).

FAQ

What does the iai-mcp-memory-server skill do?

Local MCP memory server for AI coding assistants with verbatim recall, semantic search, and automatic session capture

How do I install iai-mcp-memory-server?

Run npx skills add https://github.com/reason-machines/mcp-skills --skill iai-mcp-memory-server in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/iai-mcp-memory-server/ (personal) or .claude/skills/iai-mcp-memory-server/ (project).

Which AI agents can use iai-mcp-memory-server?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is iai-mcp-memory-server safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains iai-mcp-memory-server?

It is published by reason-machines in reason-machines/mcp-skills. It has 216 recorded installs.

More from reason-machines/mcp-skills

View all →

codebase-memory-mcp-intelligence

reason-machines/mcp-skills

High-performance code intelligence MCP server that indexes codebases into knowledge graphs for structural queries, call traces, and architecture analysis

AI & Agents505 installs

playwright-mcp-server

reason-machines/mcp-skills

Browser automation MCP server using Playwright's accessibility tree for LLM-friendly web interaction

AI & Agents285 installs

tradingview-mcp-assistant

reason-machines/mcp-skills

Open the skill to read its SKILL.md instructions.

AI & Agents256 installs

lanhu-mcp-collaboration

reason-machines/mcp-skills

Open the skill to read its SKILL.md instructions.

AI & Agents245 installs

chrome-devtools-mcp-automation

reason-machines/mcp-skills

Expert guidance for Chrome DevTools MCP server - browser automation, debugging, and performance analysis for AI agents

AI & Agents239 installs

github-mcp-server

reason-machines/mcp-skills

Open the skill to read its SKILL.md instructions.

AI & Agents237 installs

Popular ai & agents skills

View category →

google-agents-cli-publish

google/agents-cli

This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).

AI & Agents513.9K installs

google-agents-cli-eval

google/agents-cli

This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).

AI & Agents513.5K installs

skill-creator

anthropics/skills

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

OfficialAI & Agents416.4K installs

codex-pet

prime-skills/runcomfy-agent-skills

Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.

AI & Agents402.1K installs

full-output-enforcement

leonxlnx/taste-skill

Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.

AI & Agents401K installs

executing-plans

obra/superpowers

Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available

AI & Agents245.7K installs