icm

English | Français | Español | Deutsch | Italiano | Português | Nederlands | Polski | Русский | 日本語 | 中文 | العربية | 한국어

⚠️ Project status: experimental

ICM is pre-1.0 and under active development. Breaking changes can land in any minor release, and hooks/MCP configuration formats may shift.

That said, I (the maintainer) use ICM every day as my primary AI coding memory layer — it's experimental in API stability, not in day-to-day usefulness.

My focus is currently on rtk; ICM updates are merged on a best-effort cadence. Issues and pull requests are welcome but may take longer to review than usual.

ICM is Apache-2.0 licensed and ships as-is, without warranty of any kind (see LICENSE). Before any destructive operation, run the read-only equivalent first (icm uninstall --dry-run, icm uninstall --check).

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        │  │
            │    ▼     ▼     ▼     │    ┌─▼─┐            ┌─▼─┐│
            │  weight decreases    │    │ C │──part_of──>│ C ││
            │  over time unless    │    └───┘            └───┘│
            │  accessed/critical   │  Concepts + Relations    │
            ├──────────────────────┴──────────────────────────┤
            │          SQLite + FTS5 + sqlite-vec             │
            │     Hybrid search: BM25 (30%) + cosine (70%)    │
            └─────────────────────────────────────────────────┘

Two memory models:

• Memories — store/recall with temporal decay by importance. Critical memories never fade, low-importance ones decay naturally. Filter by topic or keyword.
• Memoirs — permanent knowledge graphs. Concepts linked by typed relations (depends_on, contradicts, superseded_by, ...). Filter by label.
• Feedback — record corrections when AI predictions are wrong. Search past mistakes before making new predictions. Closed-loop learning.

One memory, every AI tool — no re-explaining

The point of ICM: you stop re-explaining context every time you switch AI tools. Tell Claude Code about your project's auth strategy on Monday — Tuesday's Gemini session already knows it. Hit a Postgres indexing gotcha in a Codex run — next week's Cursor session finds the fix in errors-resolved.

This works because every AI tool you configure with icm init reads and writes the same SQLite database at the OS-standard data location (e.g. ~/.local/share/icm/memories.db on Linux, ~/Library/Application Support/icm/memories.db on macOS, %APPDATA%\icm\icm\data\memories.db on Windows):

• A icm store -t decisions-myapp -c "..." from Claude Code is immediately visible to Codex, Gemini, Cursor, Roo, Amp, Aider, ...
• icm recall "query" from any tool searches the same corpus.
• Topics (decisions-myapp, preferences, errors-resolved, ...) are global — there is no per-tool partition.

The multi-agent benchmark below confirms it end-to-end: facts seeded through ICM are recalled with 100% accuracy by Claude Code, Gemini CLI, Copilot CLI, Cursor Agent, and Aider — 98% cross-agent efficiency on the standard test.

If you want isolation (per-project, per-tool, etc.) pass --db <path>, set ICM_DB, or use icm init --per-project to create a project-local database under .icm/; each path is an independent corpus.

Install

# 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

# Nix / NixOS (flake)
nix run github:rtk-ai/icm -- --version
nix profile install github:rtk-ai/icm

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 …).

Semantic search runtime

Keyword search works out of the box. Semantic (vector) search needs the ONNX Runtime. The prebuilt binaries and install.sh bundle it — nothing to do. The Homebrew build ships lean without it (it builds in a network-less sandbox), and offers a one-time download on first use in a terminal:

# Explicitly enable semantic search (downloads onnxruntime ~7 MB, one time)
icm embeddings download

# Check the runtime state
icm embeddings status

If declined (or in a non-interactive context — MCP server, hooks, CI), ICM stays keyword-only until you run icm embeddings download. To use your own runtime, set ORT_DYLIB_PATH to an ONNX Runtime 1.20.x library.

The download supports macOS (arm64/x86_64), Linux (x86_64/aarch64), and Windows (x86_64). On Windows the runtime is the larger onnxruntime.dll package (~65 MB); everywhere else it's ~7 MB.

Setup

# Auto-detect and configure all supported tools (global database)
icm init

# Per-project database (stores memories in .icm/memories.db)
icm init --per-project

--per-project creates a project-local .icm/config.toml at the git root, so all icm commands run from within the project automatically use an isolated database. Combine with global icm init — global settings (tools, hooks) are unaffected; only the database is scoped.

Configures 18 tools in one command (full integration guide):

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

Skills / rules

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

CLI instructions

icm init --mode cli

Injects ICM instructions into each tool's instruction file:

Hooks (5 tools)

icm init --mode hook

Installs auto-extraction and auto-recall hooks for all supported tools:

What each hook does: