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 project .cursor/mcp.json (recommended) or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "elim": {
      "command": "npx",
      "args": ["-y", "elim-mcp"],
      "env": {
        "ELIM_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

No API key. Restart your editor and it works.

ELIM_PROJECT_ROOT matters: Cursor often starts MCP servers with cwd=$HOME, so without it the ledger would land in ~/.elim/ with no git branch. ${workspaceFolder} pins storage to .elim/ledger.db in the open project and enables branch auto-capture.

Claude Code / Claude Desktop (stdio cwd is usually the project) can omit env:

{
  "mcpServers": {
    "elim": {
      "command": "npx",
      "args": ["-y", "elim-mcp"]
    }
  }
}

Same stdio / npx pattern. Prefer passing the workspace root via env if your client doesn’t set cwd to the project:

{
  "servers": {
    "elim": {
      "command": "npx",
      "args": ["-y", "elim-mcp"],
      "env": {
        "ELIM_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

Use whatever key your client expects (mcpServers vs servers) — the command / args stay the same.

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.