elim-mcp
by DevAsadYasin
README.md
# elim-mcp
**Every memory tool remembers what's true. This one also remembers what isn't.**
[](https://www.npmjs.com/package/elim-mcp)
[](https://www.npmjs.com/package/elim-mcp)
[](./LICENSE)
[](https://modelcontextprotocol.io)
An MCP server that remembers what coding agents have already **tried, ruled out, and solved** — so nobody, human or agent, re-investigates the same dead end twice across sessions, branches, and tools.
---
## Before / after
```
── Session 1 · Claude Code · branch fix/checkout-500s ──────────────────
Agent: Checking if checkout timeouts are a DB connection pool issue…
→ remember(
content: "Investigated connection pool exhaustion — ruled out,
pool metrics normal under load",
kind: "ruled_out",
topic: "checkout-timeout"
)
→ remember(
content: "Suspected API key rotation mid-deploy — ruled out,
keys match and auth logs are clean",
kind: "ruled_out",
topic: "checkout-timeout",
follows_from: "<id of previous record>"
)
── Session 2 · Cursor · same branch, days later ────────────────────────
Agent: Let me check the DB connection pool—
→ recall(query: "checkout timeout")
← Found 3 record(s):
1. [ruled_out] checkout-timeout
Already ruled out: connection pool (metrics normal under load)
2. [ruled_out] checkout-timeout
Already ruled out: API key rotation (auth logs clean)
3. [solution] checkout-timeout
Confirmed cause: Redis disconnect on deploy
Agent: Skipping the pool. Looking at Redis reconnect behavior instead.
```
Then dump the whole trail for a handoff or commit message:
```
→ trace(record_id: "<latest id>")
← Investigation chain (3 step(s), oldest → newest):
Step 1 — ruled out: connection pool
Step 2 — ruled out: API key rotation
Step 3 — solution: Redis disconnect on deploy
```
---
## Why this exists
Fresh chats and tool switches wipe working context. Mid-debug reasoning — “we ruled out the pool because CPU was fine, then ruled out the API key, then found Redis” — almost never survives past the current window. The fix sometimes lands in a commit message. The dead ends get thrown away.
Existing coding-agent memory tools are good at recording **decisions and facts**. None give first-class structure to **what was investigated and eliminated**, chained as one investigation. That negative trail is the wedge: narrower than “generic AI memory,” sharper for day-to-day debugging.
You already use some memory MCP. This one is specifically for stopping agents from cheerfully re-checking the connection pool next Tuesday.
---
## Install
Paste into Cursor (`.cursor/mcp.json`) or Claude Code / Claude Desktop MCP config:
```json
{
"mcpServers": {
"elim": {
"command": "npx",
"args": ["-y", "elim-mcp"]
}
}
}
```
No API key. No setup. Restart your editor and it works.
On first write it creates `.elim/ledger.db` in the project root and auto-captures git branch + session id.
<details>
<summary>VS Code / Windsurf</summary>
Same stdio / `npx` pattern. Example for VS Code–style MCP config:
```json
{
"servers": {
"elim": {
"command": "npx",
"args": ["-y", "elim-mcp"]
}
}
}
```
Use whatever key your client expects (`mcpServers` vs `servers`) — the `command` / `args` stay the same.
</details>
---
## The 4 tools
| Tool | Purpose | Example |
|---|---|---|
| `remember` | Write a ruled-out theory, solution, decision, or note | `remember({ kind: "ruled_out", topic: "checkout-timeout", content: "…" })` |
| `recall` | Search the ledger before re-investigating | `recall({ query: "checkout timeout" })` |
| `get_current` | Load recent records for a chat, branch, or project | `get_current({ scope: { level: "branch" } })` |
| `trace` | Walk the `follows_from` chain for one investigation | `trace({ record_id: "<uuid>" })` |
Four tools on purpose. Crowded memory servers expose dozens; MCP clients pick tools less reliably as that list grows.
---
## How it works
- **Local-first SQLite** at `.elim/ledger.db` (project root, gitignored) with FTS5 keyword search
- **Auto-capture** of git branch and a per-process session id — no manual scope required for the common case
- **`follows_from` chaining** links ruled-out steps into one investigation you can `trace()` later
- **Scopes**: `chat` · `branch` (default) · `project` · `global`
Kinds: `ruled_out` · `solution` · `decision` · `note`.
---
## Platform support (better-sqlite3)
elim-mcp keeps native SQLite performance via **better-sqlite3**. Install tries a **prebuilt binary first**, then compiles only if needed.
| Usually zero compile | May need build tools |
|---|---|
| macOS (Intel + Apple Silicon) | Alpine / musl Linux |
| Windows 10/11 | Unusual architectures |
| Linux glibc (Ubuntu, Debian, Fedora, …) | Very new / very old Node |
| Node 18 / 20 / 22 / 24 · x64 / arm64 | Networks blocking prebuild downloads |
Most users never compile anything. If the native module can't load, elim-mcp prints **actionable build-tool instructions to stderr** and exits — it does **not** fall back to an in-memory or degraded database.
If that happens:
- **macOS:** `xcode-select --install`
- **Linux (Debian/Ubuntu):** `sudo apt install -y python3 make g++ build-essential`
- **Windows:** Visual Studio Build Tools (Desktop development with C++)
Then: `npm rebuild better-sqlite3` and re-run `npx -y elim-mcp`.
---
## Roadmap
Planned, **not** implemented yet:
- Phase 2 — verify identical behavior across Cursor, Windsurf, VS Code; local embeddings for semantic recall; agent skill snippet (“`recall` before proposing a fix”)
- Phase 3 — optional hosted team sync so “has anyone on the team already ruled this out?” is a real query
---
## Contributing
Issues and PRs welcome on [GitHub](https://github.com/DevAsadYasin/elim-mcp). Bug reports from real debugging sessions are especially useful — they double as product dogfooding.
---
## License
MIT
Built by [DevAsadYasin](https://github.com/DevAsadYasin).
This server cannot be deployed
Maintenance
ActivityStale
ResponsivenessNo issues