Domain Memory

A local MCP server that accumulates the business-domain knowledge of a software project — flows, integrations, decisions, nuances — and makes it available to any MCP-compatible agent (Claude Code, Cursor, Copilot, Gemini, OpenCode).

The goal is to capture the why behind the code: the stuff a new developer would need six months from now to understand why a thing is built the way it is. The what is already in the code — domain-memory does not duplicate it.

Status: Functional. Local install, single developer, local SQLite.

What this is

Domain Memory is a living glossary of your project's business domain — the concepts, rules, entities, and the why behind decisions — that grows as you build. The frame that matters: this is semantic memory (what "a German invoice" or "a deactivated account" means in your project, and why it behaves the way it does), not episodic memory (what you changed last Tuesday and in which commit). The episodic record already lives in git history; Domain Memory holds the part no diff captures.

You don't stop to write documentation. As the agent works it records findings on its own, and they are folded into the glossary when you run /save-knowledge or open a pull request — so the knowledge accrues from real work instead of becoming a separate authoring chore you have to remember.

Everything is plain markdown you own and version in git. Each entry is a human-readable file under .domain-memory/; the search index is derived from those files and can be rebuilt from them at any time, so the knowledge stays portable, reviewable in a pull request, and never locked inside a database.

If what you want is a history of work sessions, cross-machine sync, or generic per-user assistant memory, this is deliberately not that. Domain Memory stays narrow on purpose: the domain knowledge of one project, and nothing else.

How is this different from…

Domain Memory occupies a narrow niche. The closest neighbours and where it differs:

If you're asking "where does the agent remember that I prefer dark mode?", you want mem0. If you're asking "where does the agent remember that we deliberately bypass tax validation for German invoices because of the 2024 ruling?", you want this.

How it works

Three principles run the whole system:

1. The LLM is the criterion, the MCP is the store. All judgment calls — "does this contradict existing knowledge?", "is this worth remembering?" — live in the agent. The server just persists, searches, and reports. Semantic reasoning never happens in SQL.
2. Markdown on disk is the source of truth. Every entry is a human-readable .md file under .domain-memory/knowledge/. SQLite is a derived index that can be rebuilt from disk at any time (domain-memory reindex).
3. Failures are silent. A down embedder, a slow query, a corrupted staging line — none of it is ever surfaced to the agent session. If domain-memory cannot help, it stays out of the way.

Unit of knowledge: Feature + Aspects

The unit is the feature (checkout, auth, notifications, search…). Each feature is one directory with a feature.md and optional aspects/ underneath:

.domain-memory/knowledge/
  checkout/
    feature.md           ← high-level prose + Mermaid of the whole flow
    aspects/
      taxes.md           ← specific subtopic
      stripe.md
      webhook.md

A feature is the primary context: the general Mermaid diagram in feature.md typically answers 70% of questions. Aspects are loaded on demand when the agent needs detail on a specific slice.

Each entry carries three layers:

• What it does — short prose (no code duplication).
• How it flows — a Mermaid diagram (mandatory for flows and integrations).
• Where it lives — file_paths + qualified symbol names.

Per-branch staging

While you work, the agent appends findings to .domain-memory/staging/<branch>.jsonl. Findings survive session compaction, browser closes, new sessions on the same branch — indexed by git branch, not by session id. When you open a PR or run /save-knowledge, the staging is consolidated into real entries.

If you sometimes push without going through the agent, those findings can sit unconsolidated. The optional pre-push reminder closes that gap: domain-memory install --git-hook writes a non-blocking .git/hooks/pre-push that prints a one-line nudge when the branch you are pushing still has staged findings. It never blocks the push, stays silent when there is nothing to consolidate, and is a no-op if the CLI is not on PATH. It is opt-in — plain install asks before touching .git/hooks.

Triple matcher

search_knowledge runs three matchers in parallel and fuses them:

1. Embedding (semantic, local Transformers.js with all-MiniLM-L6-v2, no API key).
2. BM25 (SQLite FTS5, for exact keyword matches).
3. Path / symbol (exact + basename + short-symbol, resilient to renames).

The fusion is weighted: path = 0.5, embedding = 0.3, bm25 = 0.2. Path/symbol is weighted strongest because it is the most reliable signal when two pieces of knowledge are about the same code.

Drift

Every entry stores SHA-256 hashes of the files it references. On PR open, the agent cross-references the PR's touched files against the knowledge store via check_drift and asks the developer to review any affected entries. Rename/move is absorbed by matching on basename and short symbol; deletes are caught on the next reindex.

Lazy confidence decay

Every entry has a confidence (0–100) that decays -5 points every 30 days without verification. Computed lazily at read time — no scheduled job, always consistent with the wall clock. Below 50 the entry shows up red in /stale and the web viewer. A human review resets it with domain-memory verify <id>.

Install

Two ways to run it. Pick the one that matches what you're trying to do.

Just the MCP server (most common)

Add it to your MCP client's config. No global install needed — npx fetches and runs it on demand.

{
  "mcpServers": {
    "domain-memory": {
      "command": "npx",
      "args": ["-y", "@mashware/domain-memory-server"]
    }
  }
}

That goes in .mcp.json (Claude Code), .cursor/mcp.json (Cursor), .vscode/mcp.json (Copilot), .gemini/settings.json (Gemini), or opencode.json (OpenCode).

Restart your client. From then on the agent will call search_knowledge at the start of each session.

Server + CLI (web viewer, install helper, drift checks)

If you also want the domain-memory CLI (to bootstrap entries, run the web viewer, check drift, etc.):

npm install -g @mashware/domain-memory

This installs three commands globally: domain-memory, domain-memory-server, domain-memory-web. Then in any project:

cd /path/to/your/project
domain-memory install      # writes the MCP config + pointer blocks for the clients you use
domain-memory doctor       # sanity check
domain-memory web          # open the viewer at http://localhost:4373

install is idempotent — re-running updates files in place without clobbering your content.

Updating

npm update -g @mashware/domain-memory

Uninstalling

npm uninstall -g @mashware/domain-memory

To remove domain-memory from a specific project: delete .domain-memory/, remove the <!-- domain-memory:start --> block from the client instruction files, and drop the domain-memory entry from .mcp.json / .cursor/mcp.json / .vscode/mcp.json / .gemini/settings.json / opencode.json. If you installed the pre-push reminder, also remove the # >>> domain-memory pre-push >>> block from .git/hooks/pre-push (or delete the file if it contains nothing else).

From source (contributors)

If you want to hack on the project itself, see CONTRIBUTING.md for the clone-and-link dev workflow.

CLI commands