ICM: a shared SQLite memory layer for AI coding agents

The problem ICM targets: context re-explained per tool

If you use more than one AI coding tool, you have probably repeated the same project facts more than once. Claude Code learns your auth strategy on Monday. A Gemini session on Tuesday starts from zero. The README frames this as the reason ICM exists: you stop re-explaining context every time you switch tools. The unit of storage is not a chat log and not a scratchpad. It is a database that every configured tool reads and writes. The README calls the result a memory rather than a note-taking tool or a context manager, which is marketing language, but the underlying claim is concrete: one SQLite file at an OS-standard data location, shared by all agents configured through `icm init`. Topics such as `decisions-myapp`, `preferences` and `errors-resolved` are global, so there is no per-tool partition unless you deliberately create one. The intended user is a developer running several agent CLIs against the same repository, not a team building a multi-tenant memory service. That distinction matters for the rest of this review, because almost every design decision in ICM follows from it.

Two memory models: decaying episodes and a permanent concept graph

ICM splits storage into two structures. Memories are episodic and temporal: each entry carries an importance weight that decays over time unless the entry is accessed or marked critical. The README states that critical memories never fade while low-importance ones decay naturally. You can filter them by topic or keyword. Memoirs are different: permanent knowledge graphs where concepts are linked by typed relations such as `depends_on`, `contradicts` and `superseded_by`, filterable by label. There is a third mechanism, feedback, for recording corrections when an AI prediction was wrong so that past mistakes can be searched before a new prediction is made. The separation is the most interesting design choice here. A decay schedule is the right default for observations that were true last week and may not be true now, and the wrong default for architecture facts, which is why the graph exists alongside it. The cost is that you have to decide which model a piece of information belongs to. ICM does not appear to make that decision for you, based on the README. Getting it wrong means either a durable fact quietly decaying or a stale observation sitting permanently in the graph.

Storage and retrieval: SQLite, FTS5 and a 30/70 hybrid ranking

The stack is SQLite with FTS5 for keyword search and sqlite-vec for vectors. The README describes hybrid search as BM25 at 30 percent and cosine similarity at 70 percent, and the banner diagram shows both sitting under the two memory models. That ratio is a fixed weighting rather than a learned or tunable one, at least as documented, which is worth knowing if your corpus is heavy on identifiers and error strings where lexical matching usually beats embeddings. The README also states that keyword search works out of the box while semantic search needs the ONNX Runtime. Prebuilt binaries and `install.sh` bundle it. The Homebrew build ships without it because it compiles in a network-less sandbox and offers a one-time download on first use in a terminal. In a non-interactive context (MCP server, hooks, CI) a declined or impossible download means ICM stays keyword-only until you run `icm embeddings download` explicitly. That is a quiet degradation mode: retrieval still works, results just get worse for paraphrased queries, and nothing in the described flow forces a warning.

Getting it running: install, init and the per-project database switch

Installation options listed in the README are Homebrew via `brew tap rtk-ai/tap && brew install icm`, a shell script at `https://raw.githubusercontent.com/rtk-ai/icm/main/install.sh` that the README says verifies SHA256 against the release checksums, a PowerShell equivalent at `install.ps1`, `cargo install --path crates/icm-cli` from source, and Nix via `nix run github:rtk-ai/icm -- --version`. Upgrades are a re-run of the install command, with `--version icm-vX.Y.Z` to pin. Setup is `icm init`, which the README says auto-detects and configures all supported tools against a global database, and `icm init --per-project`, which creates a project-local `.icm/config.toml` at the git root so commands run from inside the project use an isolated database. The README notes the two can be combined: global settings such as tools and hooks are unaffected, only the database is scoped. Isolation is also available through `--db <path>` or the `ICM_DB` environment variable. The README claims 18 tools are configured, though the supplied excerpt is truncated at that point, so the full list is not something I can confirm here. The README gives these example paths: `~/.local/share/icm/memories.db` on Linux, `~/Library/Application Support/icm/memories.db` on macOS, and `%APPDATA%\icm\icm\data\memories.db` on Windows. Note the doubled `icm` segment in the Windows path; that is what the README shows.

The experimental label is not boilerplate

The README carries an explicit project status warning: ICM is pre-1.0 and under active development, breaking changes can land in any minor release, and hooks and MCP configuration formats may shift. The maintainer states that ICM is used daily as a primary AI coding memory layer, and that the distinction is experimental in API stability rather than in day-to-day usefulness. That is a fair framing, but it has operational consequences. A tool that writes to your agent's hook configuration can change the shape of that configuration between releases, and the release cadence visible in the supplied data is fast: three releases in the v0.10.6x line within roughly two weeks in September 2026. The README also says the maintainer's focus is currently on a different project, rtk, and that ICM updates are merged on a best-effort cadence, with issues and pull requests possibly taking longer than usual to review. For a component that sits in the path of every agent session, that is the single largest risk in the repository, larger than any technical limitation listed below. The README recommends running the read-only equivalent before any destructive operation, naming `icm uninstall --dry-run` and `icm uninstall --check`. Take that literally if you are removing hooks from a working setup.

Where ICM is the wrong tool

Three cases stand out. First, single-tool users. If you only run one agent, the shared-database argument disappears and you are left with a memory store you could approximate with files the agent already reads. Second, anyone who needs a stable integration contract. The README says breaking changes can land in any minor release and that hooks and MCP configuration formats may shift, so pinning a version is the only defensible posture, and pinning means you forgo fixes on a project whose maintainer already describes review as best-effort. Third, teams wanting shared memory across machines or people. ICM is a local SQLite file. The README describes per-project and per-tool isolation but nothing about server mode, sync or concurrent multi-writer access, and I cannot confirm any of those from the supplied material. The temporal decay model is also a poor fit for audit use. If you need to prove what an agent knew at a given time, a weight that decreases unless accessed is the opposite of what you want, unless every relevant entry is marked critical. The README does not describe how decay is computed, what the half-life is, or whether decay is applied on read or on a schedule. Those are real gaps, not nitpicks, because they determine whether recall results are reproducible.

Alternatives and the actual difference in approach

The obvious comparison is with the built-in memory features that agent vendors ship, and the difference is architectural rather than feature-level. Vendor memory lives inside one product's account or local state, which is precisely the boundary ICM is built to cross: the README's claim is that a `icm store -t decisions-myapp -c "..."` from Claude Code is immediately visible to Codex, Gemini, Cursor, Roo, Amp and Aider. A per-vendor memory cannot do that, by design. The second comparison is with general-purpose vector databases such as the sqlite-vec-plus-embeddings combination ICM itself uses internally, or a hosted vector store. Those give you tunable retrieval and scale but no opinion about decay, typed relations between concepts, or correction feedback, and no MCP surface for an agent to call. ICM's value is the opinionated layer, not the storage engine. The third comparison is with plain markdown files in the repository, which remain the most portable option and are readable by any tool without configuration. ICM's advantage over files is retrieval ranking and the decay model; its disadvantage is that a binary and a database now sit between the agent and the text. The README's own multi-agent benchmark section cites 100 percent recall of seeded facts across five named agents and 98 percent cross-agent efficiency. I have not reproduced that, and the excerpt does not include the methodology, so treat it as the maintainer's measurement rather than an independent one.

Maintenance, upgrades and licence

Upgrading is a re-run of the install command, or `--version icm-vX.Y.Z` to pin. Because the README warns that hooks and MCP configuration formats may shift between minor releases, an upgrade is not a no-op for a configured machine: it can rewrite the files your agents read at startup. The read-only checks the README names, `icm uninstall --dry-run` and `icm uninstall --check`, are the closest thing to a safety net for the removal path, and there is no equivalent pre-flight named for upgrades in the supplied material. On the runtime side, semantic search depends on an ONNX Runtime at 1.20.x, which you can point at yourself with `ORT_DYLIB_PATH`, or let ICM download through `icm embeddings download` and inspect with `icm embeddings status`. That is a versioned native dependency inside a project that advertises zero dependencies, and the two statements are only reconcilable if you read zero dependencies as no runtime dependency for keyword-only use. The licence is Apache-2.0. The README states the software ships as-is, without warranty of any kind. That is standard for the licence, and it is worth reading alongside the experimental status rather than separately. I am not a lawyer and this is not legal advice; if you redistribute ICM inside a product, read the LICENSE file in the repository yourself.

Editorial conclusion

Adopt ICM if you regularly switch between Claude Code, Codex, Gemini CLI, Cursor or Aider on the same codebase and want one corpus instead of per-tool notes, and if you can tolerate a pre-1.0 project that reserves the right to break config formats in any minor release. Do not adopt it if you need API stability, a multi-user server, or a hosted vector database behind a service level agreement. Before wiring it into hooks, verify three things yourself: which database path `icm init` selected on your machine, whether `icm embeddings status` reports a working ONNX Runtime 1.20.x, and whether the tool list `icm init` writes matches the agents you actually run.

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. rtk-ai/icm on GitHub