elim-mcp

Every memory tool remembers what's true. This one also remembers what isn't.

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:

{
  "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:

{
  "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. Bug reports from real debugging sessions are especially useful — they double as product dogfooding.

---

License

MIT

Built by DevAsadYasin.