by rtk-ai
Permanent memory for AI agents. Single binary, zero dependencies, MCP native.
# Add to your Claude Code skills
git clone https://github.com/rtk-ai/icmEnglish | Français | Español | Deutsch | Italiano | Português | Nederlands | Polski | Русский | 日本語 | 中文 | العربية | 한국어
ICM gives your AI agent a real memory — not a note-taking tool, not a context manager, a memory.
ICM (Infinite Context Memory)
┌──────────────────────┬─────────────────────────┐
│ MEMORIES (Topics) │ MEMOIRS (Knowledge) │
│ │ │
│ Episodic, temporal │ Permanent, structured │
│ │ │
│ ┌───┐ ┌───┐ ┌───┐ │ ┌───┐ │
│ │ m │ │ m │ │ m │ │ │ C │──depends_on──┐ │
│ └─┬─┘ └─┬─┘ └─┬─┘ │ └───┘ │ │
│ │decay │ │ │ │ refines ┌─▼─┐│
│ ▼ ▼ ▼ │ ┌─▼─┐ │ C ││
│ weight decreases │ │ C │──part_of──>└───┘│
│ over time unless │ └───┘ │
│ accessed/critical │ Concepts + Relations │
├──────────────────────┴─────────────────────────┤
│ SQLite + FTS5 + sqlite-vec │
│ Hybrid search: BM25 (30%) + cosine (70%) │
└─────────────────────────────────────────────────┘
Two memory models:
No comments yet. Be the first to share your thoughts!
depends_on, contradicts, superseded_by, ...). Filter by label.# Homebrew (macOS / Linux)
brew tap rtk-ai/tap && brew install icm
# Quick install (macOS / Linux) — verifies SHA256 against the release checksums
curl -fsSL https://raw.githubusercontent.com/rtk-ai/icm/main/install.sh | sh
# Quick install (Windows PowerShell)
irm https://raw.githubusercontent.com/rtk-ai/icm/main/install.ps1 | iex
# From source
cargo install --path crates/icm-cli
Re-run the install command to upgrade to the latest release. To pin a version, pass --version icm-vX.Y.Z (sh: sh -s -- --version …).
# Auto-detect and configure all supported tools
icm init
Configures 17 tools in one command (full integration guide):
| Tool | MCP | Hooks | CLI | Skills |
|------|:---:|:-----:|:---:|:------:|
| Claude Code | ~/.claude.json | 5 hooks | CLAUDE.md | /recall /remember |
| Claude Desktop | JSON | — | — | — |
| Gemini CLI | ~/.gemini/settings.json | 5 hooks | GEMINI.md | — |
| Codex CLI | ~/.codex/config.toml | 4 hooks | AGENTS.md | — |
| Copilot CLI | ~/.copilot/mcp-config.json | 4 hooks | .github/copilot-instructions.md | — |
| Cursor | ~/.cursor/mcp.json | — | — | .mdc rule |
| Windsurf | JSON | — | .windsurfrules | — |
| VS Code | ~/Library/.../Code/User/mcp.json | — | — | — |
| Amp | JSON | — | — | /icm-recall /icm-remember |
| Amazon Q | JSON | — | — | — |
| Cline | VS Code globalStorage | — | — | — |
| Roo Code | VS Code globalStorage | — | — | .md rule |
| Kilo Code | VS Code globalStorage | — | — | — |
| Zed | ~/.zed/settings.json | — | — | — |
| OpenCode | JSON | TS plugin | — | — |
| Continue.dev | ~/.continue/config.yaml | — | — | — |
| Aider | — | — | .aider.conventions.md | — |
Or manually:
# Claude Code
claude mcp add icm -- icm serve
# Compact mode (shorter responses, saves tokens)
claude mcp add icm -- icm serve --compact
# Any MCP client: command = "icm", args = ["serve"]
icm init --mode skill
Installs slash commands and rules for Claude Code (/recall, /remember), Cursor (.mdc rule), Roo Code (.md rule), and Amp (/icm-recall, /icm-remember).
icm init --mode cli
Injects ICM instructions into each tool's instruction file:
| Tool | File |
|------|------|
| Claude Code | CLAUDE.md |
| GitHub Copilot | .github/copilot-instructions.md |
| Windsurf | .windsurfrules |
| OpenAI Codex | AGENTS.md |
| Gemini | ~/.gemini/GEMINI.md |
icm init --mode hook
Installs auto-extraction and auto-recall hooks for all supported tools:
| Tool | SessionStart | PreTool | PostTool | Compact | PromptRecall | Config |
|------|:-----------:|:-------:|:--------:|:-------:|:------------:|--------|
| Claude Code | icm hook start | icm hook pre | icm hook post | icm hook compact | icm hook prompt | ~/.claude/settings.json |
| Gemini CLI | icm hook start | icm hook pre | icm hook post | icm hook compact | icm hook prompt | ~/.gemini/settings.json |
| Codex CLI | icm hook start | icm hook pre | icm hook post | — | icm hook prompt | ~/.codex/hooks.json |
| Copilot CLI | icm hook start | icm hook pre | icm hook post | — | icm hook prompt | .github/hooks/icm.json |
| OpenCode | session start | — | tool extract | compaction | — | ~/.config/opencode/plugins/icm.ts |
What each hook does:
| Hook | What it does |
|------|-------------|
| icm hook start | Inject a wake-up pack of critical/high memories at session start (~500 tokens) |
| icm hook pre | Auto-allow icm CLI commands (no permission prompt) |
| icm hook post | Extract facts from tool output every N calls (auto-extraction) |
| icm hook compact | Extract memories from transcript before context compression |
| icm hook prompt | Inject recalled context at the start of each user prompt |
ICM can be used via CLI (icm commands) or MCP server (icm serve). Both access the same database.
| | CLI | MCP |
|---|-----|-----|
| Latency | ~30ms (direct binary) | ~50ms (JSON-RPC stdio) |
| Token cost | 0 (hook-based, invisible) | ~20-50 tokens/call (tool schema) |
| Setup | icm init --mode hook | icm init --mode mcp |
| Works with | Claude Code, Gemini, Codex, Copilot, OpenCode (via hooks) | All 17 MCP-compatible tools |
| Auto-extraction | Yes (hooks trigger icm extract) | Yes (MCP tools call store) |
| Best for | Power users, token savings | Universal compatibility |
icm dashboard # or: icm tui
Interactive TUI with 5 tabs: Overview, Topics, Memories, Health, Memoirs. Keyboard navigation (vim-style: j/k, g/G, Tab, 1-5), live search (/), auto-refresh.
Requires the tui feature (enabled by default). Build without: cargo install --path crates/icm-cli --no-default-features --features embeddings.
# Store
icm store -t "my-project" -c "Use PostgreSQL for the main DB" -i high -k "db,postgres"
# Recall
icm recall "database choice"
icm recall "auth setup" --topic "my-project" --limit 10
icm recall "architecture" --keyword "postgres"
# Manage
icm forget <memory-id>
icm consolidate --topic "my-project"
icm topics
icm stats
# Extract facts from text (rule-based, zero LLM cost)
echo "The parser uses Pratt algorithm" | icm extract -p my-project
# Create a memoir
icm memoir create -n "system-architecture" -d "System design decisions"
# Add concepts with labels
icm memoir add-concept -m "system-architecture" -n "auth-service" \
-d "Handles JWT tokens and OAuth2 flows" -l "domain:auth,type:service"
# Link concepts
icm memoir link -m "system-architecture" --from "api-gateway" --to "auth-service" -r depends-on
# Search with label filter
icm memoir search -m "system-architecture" "authentication"
icm memoir search -m "system-architecture" "service" --label "domain:auth"
# Inspect neighborhood
icm memoir inspect -m "system-architecture" "auth-service" -D 2
# Export graph (formats: json, dot, ascii, ai)
icm memoir export -m "system-architecture" -f ascii # Box-drawing with confidence bars
icm memoir export -m "system-architecture" -f dot # Graphviz DOT (color = confidence level)
icm memoir export -m "system-architecture" -f ai # Markdown optimized for LLM context
icm memoir export -m "system-architecture" -f json # Structured JSON with all metadata
# Generate SVG visualization
icm memoir export -m "system-architecture" -f dot | dot -Tsvg > graph.svg
Store every message exchanged with an agent as-is — no summarization, no extraction. Search later with FTS5 (BM25 + boolean + phrase + prefix). Useful for session replay, post-mortem review, compliance audit, training data. Complementary to curated memories.
# 1. Start a session
SID=$(icm transcript start-session --agent claude-code --project myapp)
# 2. Record every turn verbatim
icm transcript record -s "$SID" -r user -c "Pourquoi on avait choisi Postgres ?"
icm transcript record -s "$SID" -r assistant -c "JSONB natif, BRIN pour les logs, auto-vacuum tuné."
icm transcript record