{"id":50411605,"url":"https://github.com/ncmonx/icemage","last_synced_at":"2026-06-06T03:04:19.545Z","repository":{"id":356004291,"uuid":"1230572205","full_name":"ncmonx/icemage","owner":"ncmonx","description":"Token-efficient context/memory/graph CLI for AI coding agents. 70-98% cheaper. 1187/1187 tests, 40 MCP tools, Apache-2.0.","archived":false,"fork":false,"pushed_at":"2026-05-30T17:28:28.000Z","size":3600,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T19:13:01.906Z","etag":null,"topics":["ai-agents","ai-coding","anthropic","claude-code","cli","cline","context-engineering","cpp17","cursor","developer-tools","knowledge-graph","llm-tools","local-first","mcp","mcp-server","prompt-engineering","semantic-search","sqlite","token-optimization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ncmonx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"ncmonx","ko_fi":"ncmonx"}},"created_at":"2026-05-06T05:59:16.000Z","updated_at":"2026-05-30T17:29:34.000Z","dependencies_parsed_at":"2026-05-12T06:00:48.173Z","dependency_job_id":null,"html_url":"https://github.com/ncmonx/icemage","commit_stats":null,"previous_names":["ncmonx/icm-graph","ncmonx/icemage"],"tags_count":262,"template":false,"template_full_name":null,"purl":"pkg:github/ncmonx/icemage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncmonx%2Ficemage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncmonx%2Ficemage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncmonx%2Ficemage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncmonx%2Ficemage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ncmonx","download_url":"https://codeload.github.com/ncmonx/icemage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncmonx%2Ficemage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33718446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-coding","anthropic","claude-code","cli","cline","context-engineering","cpp17","cursor","developer-tools","knowledge-graph","llm-tools","local-first","mcp","mcp-server","prompt-engineering","semantic-search","sqlite","token-optimization"],"created_at":"2026-05-31T04:01:39.913Z","updated_at":"2026-05-31T04:01:40.545Z","avatar_url":"https://github.com/ncmonx.png","language":"Python","funding_links":["https://github.com/sponsors/ncmonx","https://ko-fi.com/ncmonx"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.svg\" alt=\"Icemage\" width=\"160\"/\u003e\n\u003c/p\u003e\n\n# Icemage \u003csub\u003e\u003csup\u003e(`icmg`)\u003c/sup\u003e\u003c/sub\u003e\n\n[![release](https://img.shields.io/github/v/release/ncmonx/icm-graph)](https://github.com/ncmonx/icm-graph/releases)\n[![downloads](https://img.shields.io/github/downloads/ncmonx/icm-graph/total)](https://github.com/ncmonx/icm-graph/releases)\n[![last-commit](https://img.shields.io/github/last-commit/ncmonx/icm-graph)](https://github.com/ncmonx/icm-graph/commits/main)\n[![ctest](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/ncmonx/7d6a2efa9d6191e28ff3f6a26e6ba7c7/raw/ctest.json)](#)\n[![mcp tools](https://img.shields.io/badge/MCP%20tools-40-blueviolet)](#)\n[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/ncmonx/icm-graph/badge)](https://securityscorecards.dev/viewer/?uri=github.com/ncmonx/icm-graph)\n[![OpenSSF Best Practices](https://img.shields.io/cii/level/12818?label=OpenSSF%20Best%20Practices)](https://www.bestpractices.dev/projects/12818)\n[![sponsor](https://img.shields.io/badge/sponsor-GitHub-ea4aaa?logo=github-sponsors)](https://github.com/sponsors/ncmonx)\n[![ko-fi](https://img.shields.io/badge/Ko--fi-tip-ff5e5b?logo=ko-fi)](https://ko-fi.com/ncmonx)\n\n\u003e **Stop burning tokens. Stop losing context. Ship faster.**\n\nA small helper app that makes AI coding assistants — Claude Code, Cursor, and friends — **70 – 98 % cheaper** to run, without making them less helpful.\n\n**40 MCP tools · 1203/1203 tests · single-binary · 100 % local · pure-bash hooks** (zero Python/jq dependency).\n\nIf you've ever watched a huge token bill evaporate on a single file read, paid for \"thinking\" you didn't need, or re-explained your project to the AI for the fifth time today — Icemage is for you.\n\n---\n\n## 🟢 Why Icemage\n\nAI assistants are powerful but **wasteful by default**. Every time the AI opens a file, runs a command, or starts a new chat, it re-reads context it has seen many times and dumps full output into the conversation. Icemage sits quietly in the background and trims the noise before it ever reaches the AI:\n\n- **Long files** → only the relevant slice\n- **Noisy command output** → just the parts that matter\n- **Web pages** → cached + summarised\n- **Past decisions** → remembered across sessions so the AI doesn't ask twice\n- **Repeated work** → results reused instead of recomputed\n\nThe AI keeps its full intelligence. Your wallet keeps more of its money.\n\n---\n\n## 📊 Headline numbers\n\n| Metric | Typical | Best | Since |\n|---|---|---|---|\n| File-read savings | 70 – 85 % fewer tokens | up to 92 % | v0.5 |\n| Test / build output | 60 – 80 % shorter | up to 90 % | v0.5 |\n| **Multi-file UI propagation** (style-clone) | **30 – 50× cheaper** | up to 98 % | v1.22.0 |\n| **Cross-project bundle** (port) | **8 – 12× cheaper** | up to 95 % | v1.24.0 |\n| **Compressed-Write** (AI emit diff) | **70 – 95% fewer tokens** | up to 98 % | v1.25.0 |\n| Web-fetch reduction | 70 – 90 % smaller | up to 95 % | v0.4 |\n| Repeat-context recall | near-zero, **\u003c 5 ms cached** | — | v1.21.8 |\n| **Semantic atom recall** (`recall --atoms`) | **fact-level hits, not blobs** | — | v1.79.0 |\n| **Auto-bisect** (`icmg bisect`) | **first-bad commit in ~log2(N) tests** | — | v1.80.0 |\n| Past-chat full-text search | **\u003c 10 ms** across months | — | v1.21.7 |\n| Graph symbol lookup | **256-slot in-RAM cache** | — | v1.21.8 |\n| First-prompt warmup | \u003c 1 s | — | v1.18 |\n| **Cold build time** (icmg itself) | **~50 % faster** (20 min → 9-10 min) | — | v1.26.0 |\n| **MCP response filter** (verbose plugins) | **50 – 80 % smaller** | up to 90 % | v1.30.0 |\n| **Auto-thinking suppress** (trivial prompts) | **~1500 tok / call saved** | — | v1.30.0 |\n| **Sayless-auto** (long-prose replies) | **60 – 75 % compress** | up to 85 % | v1.30.0 |\n| **Service auto-start** (UserPromptSubmit) | **0-touch warm-up** | — | v1.30.0 |\n| **Path ambiguity warning** (icmg context) | wrong-file lookups → loud | — | v1.29.0 |\n| **rg-wrapper + brace glob** (icmg grep/files) | flag-mirror, **{a,b}** expand | — | v1.29.0 |\n| **Local AI model** (built-in, opt-in) | **0 cloud calls** | privacy-first | v1.31.0 |\n| **Smart router** (REGEX vs LLM_LOCAL vs CACHE) | **\u003c100 us p99** | hot-path forced regex | v1.31.0 |\n| **HTTP streaming download** (model fetch + SHA256) | **400 MB - 2 GB** safe-verify | tamper-detect | v1.31.0 |\n| **icmg git** wrapper (single ergonomic entry) | **Tkil-filtered** + safety-gated | enforces icmg-FIRST | v1.31.0 |\n| **Python-free core** (PRECOMPACT_PY dropped) | **-200-500 ms** boot saved | single-binary | v1.31.0 |\n| **pack --rerank** (LLM-reorder memory hits) | **opt-in** warm-path | router-gated | v1.32.0 |\n| **PreCompact LLM summary** (warm-pool Qwen 0.5B) | **\u003c15 s** cold | regex fallback always | v1.32.0 |\n| **icmg compact-bg** (proactive memory worker) | **\u003c3 s** warm | manual + future hook | v1.32.0 |\n| **Smarter local AI memory** | **multi-prompt safe** | no overflow | v1.32.0 |\n| **Code graph viz + report** (`icmg graph viz`) | **interactive D3 + god-nodes** | — | v1.71.0 |\n| **Secret scanner** (`icmg scan`) | **21 detectors, CI-gate** | redact-by-default | v1.68.0 |\n| **MCP server hardening** (token + rate-limit + path-guard) | **abuse / RCE-safe** | — | v1.72.0 |\n| **Post-compact memory re-anchor** | **rules survive compaction** | auto on `init` | v1.73.0 |\n| **Scripted-safe `icmg run`** (non-interactive guard) | **no hang on destructive** | `--yes`/env opt-in | v1.74.0 |\n| **Clean self-upgrade** (idempotent Defender step) | **no phantom B: drive popup** | `--no-defender` opt-out | v1.75.0 |\n| **Encryption-at-rest** (`icmg encrypt`, SQLCipher AES-256) | **opt-in full-DB encrypt** | BM25 recall intact | v1.76.0 |\n| **Hot recall cache** (RAM, daemon-shared) | **\u003c 5 ms repeat recall** | self-governing RAM | v1.77.0 |\n| **Init + upgrade hardening** (no 30-min hang, no stale-proc lock) | **`init` returns immediately** | detached imports + lock-guard | v1.78.4 |\n| Cost per AI session | **down 70 – 90 %** vs. raw | up to 95 % | — |\n\nMeasured on real-world sessions. Your mileage will vary with project size and habits — anyone running a busy AI agent for a day already sees meaningful savings.\n---\n\n## ✨ What's new\n\n\u003e **Recent releases.** Older entries archived in [`CHANGELOG.md`](CHANGELOG.md).\n\n- **v1.80.0** - **`icmg bisect`: auto-find the commit that broke a test, plus atom-memory completion**. New `icmg bisect --good \u003cref\u003e --bad \u003cref\u003e --test \"\u003ccmd\u003e\"` binary-searches your git history, checking out each midpoint and running your test, to pinpoint the first commit where it starts failing, then restores your original HEAD (refuses a dirty working tree, never commits or rewrites history). It prints a `~N test runs` estimate up front. Separately, the v1.79.0 semantic-atom layer is completed: derived atoms now carry precomputed embeddings when an ONNX backend is available (enabling semantic atom matching; clean BM25 fallback when absent), and `ICMG_ATOMIZE_LLM=1` opts into local-LLM fact extraction (self-contained, pronoun-resolved) with automatic heuristic fallback. Also folds in a rebrand fix so `icmg bug-report` files to the correct repository. Full automated suite passes (1203 checks).\n- **v1.79.0** - **Semantic memory: recall can hit single facts instead of whole blobs — plus a real headless sub-agent**. icmg now derives an atomic-fact layer from your stored memories. When you `icmg store` a multi-sentence decision, a background worker (`icmg atomize run`) splits it into atomic propositions — heuristic by default, opt-in local-LLM via `ICMG_ATOMIZE_LLM=1` — so `icmg recall \"\u003cquery\u003e\" --atoms` matches the exact fact and returns its source memory. Sharper hits on a large store, and **zero latency added to `store`** (it only enqueues; atomization happens off the hot path) and **zero change to default recall** (`--atoms` is opt-in). New `icmg atomize status` shows atom count + pending queue; opt out entirely with `ICMG_ATOMIZE=0`. Separately, `icmg agent \"\u003ctask\u003e\" --exec` upgrades the LLM proxy into a real headless sub-agent with file-edit + shell tools (gated behind `ICMG_AGENT_EXEC=1` so it never fires by accident). This release also folds in two Windows reliability fixes: `icmg init` no longer hangs for 30+ minutes (background imports now run fully detached) and `icmg update --apply` no longer gets blocked when stale icmg processes hold the binary (`updating.lock` sentinel + rename retry). Full automated suite passes (1196 checks).\n- **v1.78.4** - **Fix: `icmg init` no longer hangs, and self-upgrade no longer gets blocked by stale processes**. Two Windows reliability fixes. (1) On some projects `icmg init` could appear to hang for 30+ minutes: it launched its background import helpers (`claudemd import` / `plan import` / `skill index`) through a shell whose stdout pipe was inherited by the spawned grandchild processes, so icmg blocked reading that pipe until *those* children exited — and they in turn stalled on a database lock. init now spawns the background work fully detached (no inherited handles), so it returns immediately while the imports finish on their own. (2) `icmg update --apply` could fail to swap the binary when other icmg processes (editor hooks, the background daemon) were still running and holding the `.exe` file lock. icmg now writes an `updating.lock` sentinel so any freshly-spawned icmg bails out during the brief swap window, and the upgrade retries the rename a few times to let in-flight processes exit cleanly. Full automated suite passes (1187 checks).\n- **v1.78.3** - **RAM cache now survives daemon restart**. v1.77 introduced the in-memory recall cache that keeps repeat recalls under 5 ms; v1.78.2 shipped the write-through + warm-reload building blocks. v1.78.3 finally wires it end-to-end inside the daemon: every PUT is persisted asynchronously through a write queue (non-blocking on the hot path), and on first touch of a project's scope the daemon lazy-hydrates the top-256 hottest entries from disk into RAM. The cache is daemon-shared across sessions and projects, but each entry is tagged with a scope hash so different projects can't see each other's recalls. The RCACHE protocol gains a `scope` field on PUT/GET (older clients without it land in a back-compat empty bucket and continue to work). Persist is on by default; opt out with `ICMG_RECALL_CACHE_PERSIST=0` or a per-project `.icmg/cache-persist.off` marker. Full automated suite passes (1182 atomic, +13 new daemon-wire tests).\n- **v1.78.2** - **`icmg bug-report` now tells you why it failed**. Issue #193 reported `sent=0 failed=13` from `icmg bug-report --send-pending` with no actionable error detail — gh CLI sometimes routes diagnostics (missing label, repo-perm issues, auth) to **stdout** instead of stderr, so the previous version printed nothing useful and kept retrying. v1.78.2 surfaces both streams (capped) plus the exit code on every failure, adds heuristic hints (`gh label create auto-report` / `gh repo view` / `gh auth login`) based on the error pattern, and aborts after 3 consecutive failures so it stops spamming. Closes #193. Also lands the **RAM-cache persist infrastructure** for v1.77's hot recall cache — Phases A–D building blocks (scope hash, write-through sink, SQLite `recall_cache_persist` table with per-project `scope_hash` isolation + UPSERT, hydrate top-N by hit_count, and `icmg memory cache persist enable/disable/status` CLI sub-cmd). Default ON; opt-out `ICMG_RECALL_CACHE_PERSIST=0` or per-project `.icmg/cache-persist.off` marker. Daemon hookup (hydrate-on-boot + write-queue sink) lands in v1.78.3. Full automated suite passes (24 new persist tests).\n\n\n1. **Download** the latest installer from the [Releases page](https://github.com/ncmonx/icm-graph/releases) — `icmg-\u003cversion\u003e-win-x64.zip` for Windows, `icmg-\u003cversion\u003e-linux-x64.tar.gz` for Linux.\n2. **Extract** the archive into any folder of your choice.\n3. **Add the folder to your `PATH`** so the `icmg` command is available everywhere.\n4. **Open your project** in a terminal and run:\n\n   ```text\n   icmg init\n   ```\n\n   That's it. The next time you launch Claude Code (or Cursor / Cline / Windsurf — see below), Icemage will quietly start trimming tokens.\n\n---\n\n## 🧰 What you'll actually use day-to-day\n\nAfter install, the only command most people type is `icmg init` once per project. Everything else happens automatically. A few useful commands when you want to peek under the hood:\n\n| Want to | Type |\n|---|---|\n| See how much you saved this month | `icmg savings` |\n| See a chart in the terminal | `icmg savings --ascii` |\n| Recall a past decision in this project | `icmg recall \"\u003cquestion\u003e\"` |\n| Recall something from another project | `icmg cross-recall \"\u003cquestion\u003e\"` |\n| Wake-up briefing for a fresh session | `icmg wake-up` |\n| Update Icemage in place | `icmg update --apply` |\n| Health-check the install | `icmg doctor` |\n\nFor the full menu run `icmg --help`.\n\n---\n\n## 🤖 Works with\n\n- **Claude Code** (primary target — best-tested)\n- **Cursor** — drop-in via the same hooks\n- **Cline**, **Windsurf**, **OpenCode** — same approach, may need a small config nudge\n- **Anything that exposes hooks or MCP** — the MCP server bundled with Icemage is reusable\n\n---\n\n## 🛡️ Safety + privacy\n\n- **100 % local.** Everything Icemage knows about your projects lives in a small SQLite database next to your code. Nothing is sent to a remote server — not the project name, not the file paths, not the recalled snippets.\n- **No telemetry.** Icemage doesn't phone home.\n- **Open source.** [Apache-2.0](LICENSE). Audit the binary, the release notes, and the file structure freely. Source code is held privately to keep the bug surface manageable for a solo maintainer — public reports + private fixes is the operating model.\n- **Tamper-evident.** Every release ships with a `sha256` sidecar so you can verify the binary you downloaded.\n\n---\n\n## 🩹 Honest limits\n\n- **Windows + Linux only** for prebuilt binaries today. macOS users currently need to wait for a self-hosted runner build (planned).\n- **First-time install on Windows with strict antivirus** can be slow until you let Icemage run once. After that it's fast.\n- **Not a replacement for the AI.** Icemage is a token-trimming layer — it doesn't write code for you and it doesn't make a bad AI smart.\n\n---\n\n## 💖 Support\n\nIf Icemage saved you a few hours or a few dollars and you want to send a small thank-you, both routes work:\n\n- [GitHub Sponsors](https://github.com/sponsors/ncmonx)\n- [Ko-fi tip jar](https://ko-fi.com/ncmonx)\n\nAll revenue goes straight into more releases — there is no team behind this, just one maintainer and a long backlog of \"make AI agents less wasteful\" ideas.\n\n---\n\n## ❓ FAQ\n\n**Does Icemage send my code anywhere?**\nNo. Everything is local. The only network call is when you ask Icemage to update itself or fetch a URL through `icmg fetch`.\n\n**Can my company use it?**\nYes — Apache-2.0 licensed, free for any use including commercial. If you want a private support arrangement or a custom build, [open a sponsorship](https://github.com/sponsors/ncmonx).\n\n**Why is the source code repo private?**\nOne maintainer, no security team. Public bug reports + private fixes lets me ship hotfixes the same day without telegraphing exploitable details. The release binaries and reproducible build hash are still public.\n\n**Does it slow my AI down?**\nNo. Trimming happens *before* the AI reads anything, so the AI sees a smaller, cleaner version of the same context. End-to-end interactions get faster, not slower.\n\n**Where are the savings stored?**\nIn `.icmg/data.db` inside each project (small SQLite file). Run `icmg savings` to see the breakdown.\n\n**How do I report a bug or ask for a feature?**\nOpen an issue at the [GitHub issues](https://github.com/ncmonx/icm-graph/issues) page. Real-world reproductions with `icmg savings --json` attached get triaged fastest.\n\n---\n\n## 🌟 Star history\n\n\u003ca href=\"https://star-history.com/#ncmonx/icm-graph\u0026Date\"\u003e\n  \u003cimg src=\"https://api.star-history.com/svg?repos=ncmonx/icm-graph\u0026type=Date\" alt=\"Star history\" width=\"600\"/\u003e\n\u003c/a\u003e\n\n---\n\n## 📜 License\n\n[Apache-2.0](LICENSE).\n\n---\n\n## 📚 Other docs\n\n- [CHANGELOG.md](CHANGELOG.md) — full version history\n- [SECURITY.md](SECURITY.md) — vulnerability reporting\n- [NOTICE](NOTICE) — third-party attributions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncmonx%2Ficemage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fncmonx%2Ficemage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncmonx%2Ficemage/lists"}