FixMemory

English | 简体中文

Help your coding agent avoid debugging the same bug twice.

FixMemory is a local-first MCP server that turns successful debugging sessions into evidence-backed, reusable fixes. It searches project history before an agent starts from scratch, makes a lesson searchable only after the agent or user reports a passing check, and promotes it globally only after it works across projects.

No account. No API key. No cloud database.

Requires Node.js 24+. The installer currently runs on Windows, macOS, and Linux; real-agent end-to-end validation has been completed on Windows.

npx fixmemory@latest setup

Restart active agent sessions after setup.

See it once. Reuse it next time.

First encounter

Agent  → searches FixMemory
       → finds no matching fix
       → diagnoses the root cause
       → applies a change and runs the test
       → stores a verified project memory

Next encounter

Agent  → searches FixMemory
       → finds the verified fix
       → checks environment differences
       → applies it and verifies the result

The complete propose → confirm → search lifecycle is reproduced with the official MCP client in the end-to-end test.

Related MCP server: arcane

Why not ordinary agent memory?

FixMemory is deliberately narrower than a personal knowledge base. It remembers debugging experience, not conversations.

FixMemory and GitNexus are complementary

GitNexus builds a graph of the code that exists now: dependencies, call paths, and change impact. FixMemory preserves what happened before: the symptom, root cause, successful change, and verification evidence from earlier debugging sessions.

Use GitNexus to understand the current codebase. Use FixMemory to avoid repeating previously solved investigations.

The verification loop

flowchart LR
    A[Search past fixes] --> B[Debug normally]
    B --> C[Propose candidate]
    C --> D[Agent or user runs a check]
    D -->|failed| B
    D -->|passed| E[Verified project memory]
    E --> F[Helpful in other projects]
    F --> G[Global candidate]
    G --> H[Verify again]

Candidates do not appear in normal search. A verified memory that becomes outdated can be superseded, preserving the reason and optional replacement while removing it from future search.

What “verified” means

FixMemory does not prove a root cause by itself. The agent or user runs the relevant test, build, reproduction, or operational check and submits a description of the successful result. FixMemory enforces the candidate → verified state transition and stores that evidence.

A passing check makes a record eligible for search; it does not make the advice universally correct. Search results remain hypotheses, include environment mismatches, and can receive irrelevant or harmful feedback.

MCP + Skill

FixMemory installs two small layers:

• MCP server: owns the portable tools and local SQLite database.

• Shared Skill: teaches compatible agents when to search, verify, record feedback, and retire bad memory.

MCP makes the data available across Harnesses. The Skill turns those tools into a disciplined debugging workflow. An MCP-compatible client that does not discover shared Skills can still use every tool through its own instructions.

Harness support maturity

Unattended setup is also available:

npx fixmemory@latest setup --agents codex,zcode,local-agent

Without --agents, setup detects supported Harness directories, asks which ones to enable, installs the shared runtime and Skill, and adds only a managed fixmemory entry to the selected configuration files. Existing files are backed up first.

Claude Code, Cursor, OpenCode, VS Code, and additional Harness installers are on the roadmap. Contributions for small configuration adapters are welcome; see Adding a Harness adapter.

Tools

Destructive tools are explicitly annotated. Verified records cannot be directly deleted: supersede them first so the audit trail remains intentional.

Optional Jev relevance rerank

Off by default. When the MCP Server process runs with FIXMEMORY_JEV_RERANK=1 and TYPESAFE_API_KEY, fixmemory_search packs the query and all candidate fixes into a single request to the Jev decision model on jevai.org and re-orders results by relevance probability; each match gains jev_relevance and jev_rank_before. Failures and rate limits fall back to the deterministic order, so search never breaks. The score only influences ordering: it never filters results and never participates in the candidate → verified gate.

Local data and privacy

The machine-local database is stored at:

~/.fixmemory/data/memory.db

By default FixMemory does not upload debugging memory; the only exception is the opt-in Jev rerank above, which sends the query and candidate fix text of a single search. The database uses SQLite WAL mode so several local MCP processes can share one database, rejects content that resembles credentials or private keys, and hashes project identity from the Git remote when available.

“Global” means available across projects on the same machine and user account. It does not mean uploaded or shared online. On Windows, ~ is the current user's home directory, such as C:\Users\name.

Secret detection is a safety net, not a guarantee. Memory text may contain paths, commands, stack traces, or code fragments supplied by an agent. Do not intentionally submit credentials, tokens, private keys, proprietary source, or unsanitized production data.

Commands

# Install, upgrade, or repair selected integrations
npx fixmemory@latest setup

# Verify the installed runtime and MCP tool discovery
npx fixmemory@latest doctor

# Remove integrations and runtime, preserving memory data
npx fixmemory@latest uninstall

# Also delete the local memory database
npx fixmemory@latest uninstall --delete-data

Setup backs up existing Harness configuration files before changing them. Re-running setup is safe, and uninstall removes only FixMemory-managed entries.

Development

Requires Node.js 24 or newer.

npm install
npm run check

npm run check performs strict type checking, builds the bundled runtime, runs store/MCP/installer tests, and inspects the npm tarball. CI runs the same gate on Windows, macOS, and Linux.

See CONTRIBUTING.md for contribution guidelines.

Roadmap

• One-command adapters for Claude Code, Cursor, OpenCode, and VS Code

• Export and import for portable backups

• A reproducible debugging-search evaluation set before changing retrieval engines

• More real-Harness compatibility tests

FixMemory intentionally starts with deterministic local retrieval. Semantic search will be considered only when evaluation data shows that it improves real debugging recall.

License

MIT