memspec MCP server
Commit Oct 30, 2026Provides Git-backed project memory for AI coding agents with code-anchored verification and drift detection.
Also known as siimvene/memspec
- Stars
- 10
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 30, 2026
- License
- MIT
What is memspec MCP?
memspec provides Git-backed project memory for AI coding agents with code-anchored verification and drift detection.
Summary generated from the project's README
About memspec MCP server
Memspec provides a Git-backed memory system designed specifically for AI coding agents to maintain project context without relying on external APIs or hosted services. It functions by storing memories as human-readable Markdown files with YAML frontmatter within a local .memspec/ directory. This approach ensures that all project knowledge is version-controlled, diffable, and searchable using FTS5 and BM25 algorithms. Developers can use it locally via npm without needing any accounts or API keys.
The system distinguishes itself through code-anchored verification, where claims are tied to specific git blob SHAs. When the underlying code changes, the server flags these claims for review to prevent information rot. It manages different types of information including facts, decisions, procedures, and observations, each with its own temporal validity and lifecycle states like active, superseded, or retired. This creates a structured, testable history of project evolution rather than a simple collection of notes.
What you can do with it
- 1Verify code-related claimsAn AI agent can check if its stored knowledge about a specific file still matches the current codebase.
- 2Manage evolving project decisionsA developer can replace an outdated architectural decision with a new one while preserving the reasoning chain.
- 3Prevent contradictory knowledge in teamsRun a check during a pull request to ensure new memory claims do not conflict with existing project facts.
- 4Search interconnected project contextRetrieve a specific piece of information along with all its related dependencies and supporting notes.
Written from the project's README. Every use case is checked against a quote from it.
How to install memspec MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall memspec MCP in Claude Code
$ claude mcp add memspec -- npx -y memspecInstall memspec MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"memspec": {
"command": "npx",
"args": [
"-y",
"memspec"
]
}
}
}Install memspec MCP in VS Code
.vscode/mcp.json
{
"servers": {
"memspec": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"memspec"
]
}
}
}Install memspec MCP in VS Code CLI
$ code --add-mcp '{"name":"memspec","type":"stdio","command":"npx","args":["-y","memspec"]}'Install memspec MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"memspec": {
"command": "npx",
"args": [
"-y",
"memspec"
]
}
}
}Install memspec MCP in Codex
$ codex mcp add memspec -- npx -y memspecInstall memspec MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.memspec] command = "npx" args = ["-y", "memspec"]
Install memspec MCP in Gemini CLI
$ gemini mcp add -s user memspec npx -- -y memspecInstall memspec MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"memspec": {
"command": "npx",
"args": [
"-y",
"memspec"
]
}
}
}Configuration
MEMSPEC_DREAM_AUTOCOMMIT
| Name | Description | |
|---|---|---|
| MEMSPEC_DREAM_AUTOCOMMIT | — |
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesiimvene/memspec is public and reachablegithub.com/siimvene/memspec ↗Pass
- Package names this repository as its sourcememspec names siimvene/memspec as sourcenpmjs.com/package/memspec ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-30github.com/siimvene/memspec ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from memspecPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMemspec
Memspec is Git-backed project memory for AI coding agents, with verification and drift detection. Claims about code are anchored to file SHAs; when the code changes, memspec flags the claim for review instead of letting facts rot silently. Duplicate rejection, typed supersede chains, and per-claim provenance turn memory into testable claims, not a notes file.
Markdown files under .memspec/ are the canonical source of truth: human-readable, git-diffable, greppable. Lose the index, lose speed — not data. No backend service. No hosted memory API. No vendor lock-in.
Architecture
Agents remember claims and observe notes; everything lands as markdown under .memspec/. From there a structured layer — lifecycle (active → superseded → retired), code anchors, typed links, and temporal validity — feeds FTS5/BM25 search, the MCP server, and session-start hooks, so the next session wakes up with the right context instead of amnesia.
Features
- File-canonical. Memories are markdown files with YAML frontmatter. Human-readable, git-diffable, greppable. Lose the index, lose speed — not data.
- Three claim types + observations.
fact,decision,procedurewith per-type TTLs;observationfor point-in-time notes with hard expiry. - Lifecycle, not curation.
active | superseded | retired. Corrections create a new memory linked back to the original; supersede chains preserve the reason on every record involved. Past TTL = stale flag at read time, never deletion. - Code-anchored verification. Tie memories to git blob SHAs. When code drifts, memspec flags drifted anchors for review instead of letting facts about code rot silently.
verify --reanchorre-baselines a claim that still holds, keeping the old SHAs as history. Anchors are file-grain today: on an active repository most alarms are false (measured in BENCHMARK.md), so treat a drift flag as "review this", not "this is wrong". - Linked notes (v0.5+). Records reference other records by id (
refines,supports,depends_on,derived_from,conflicts_with,supersedes,superseded_by). Search can follow these links one or more hops to surface neighbours alongside direct matches;--include-supersededlets link-following reach archived predecessors (v0.6+). - Temporal validity (v0.5+). Optional
valid_from/valid_toper memory. Search with--as-of <iso>filters by world-state truth window, orthogonal to thecheck_byreview schedule. - Operator-tier storage (v0.4+). Records sourced by the operator land in a separate filesystem path with stricter overwrite protection (
--override-operatorrequired to supersede). Write authority comes from the channel: no MCP call can create, modify, re-anchor, merge into or retract an operator record, and an operator-lookingsourcesent over MCP is stored at agent tier. - Layered stores (v0.6+). A project
.memspec/and a global~/.memspec/merge at retrieval time — project records take priority, global merges as a lower layer. Every search, context, and MCP path honours the configuredstores:layers. A repo without its own store can bind to external stores via a.memspec.yamlpointer file (v0.9+). - Scope claims (v0.9+). Stores declare which working directories they own; ingestion routes knowledge to the claiming store and holds unclaimed content local, so nothing crosses a sync boundary by default — team knowledge stays out of personal stores and vice versa.
- Transcript ingestion (v0.9+).
normalize→distill→reduceturns raw harness session logs (Claude Code, Codex) into weekly experience digests; the dream pass diffs them against memory writes to catch work that happened but was never recorded. Raw transcripts never leave the machine. - Dedup-aware writes.
rememberrefuses near-duplicate claims (same identifiers, same wording) and points at the existing record, so memory accretes corrections viasupersedeinstead of silent duplicates. A value a supersede replaced or retracted is refused if an agent writes it again over MCP (a lexical, best-effort guardrail; the limits are listed in SPEC.md). - FTS5/BM25 search. SQLite FTS5 relevance, recency-weighted, ranked per profile.
- MCP server. Fourteen tools; setup for eleven harnesses in docs/harnesses.md.
- Open Knowledge Format.
export --format okf/import --format okfround-trip the store losslessly through Google's OKF v0.2 markdown bundles. - Witnessed claims. Every memory carries
verified_with(anchor | operator | evidence | assertion) — provenance, not a confidence score. - Dream pass (v0.7+). Periodic reflection script (
memspec-dream) reads the last N days of memspec writes and git log, asks an LLM to surface stale memories, supersede candidates, verify candidates, missing relations, and behavioural rules worth promoting. Output is review material, never auto-applied. - Zero infrastructure.
npm install -g memspec+memspec init. No accounts, no API keys, no hosted services.
Install
npm install -g memspec
Or local:
git clone https://github.com/siimvene/memspec.git
cd memspec && npm install && npm run build && npm link
Quick start
memspec init # interactive setup, creates .memspec/
memspec remember fact "Auth uses JWT" \ # write a claim, anchor it to code
--source agent --tags auth --anchor src/auth/jwt.ts
memspec search "auth" # BM25; --expand-edges follows linked notes
memspec reconcile # find anchored claims whose code drifted
memspec verify ms_01HXK... --evidence "still JWT" # confirm still true; refreshes timestamp
memspec supersede ms_01HXK... \ # or replace with a corrected version
--reason "Migrated to OAuth" --body "Now OAuth2 + PKCE"
The anchor → reconcile → verify | supersede loop is the differentiator: claims about code stay accountable to the code.
Why not just AGENTS.md?
| Approach | Reviewable in Git | Code-anchored | Lifecycle | Search | Self-hosted |
|---|---|---|---|---|---|
AGENTS.md / CLAUDE.md |
yes | no | none | grep | yes |
MEMORY.md / scratchpad |
yes | no | none | grep | yes |
| Vector DB (Chroma, Qdrant) | no | no | manual | semantic | yes |
| Hosted memory API (Mem0, Letta) | no | no | hosted | hosted | no |
| Memspec | per-claim | yes | typed states | FTS5 + BM25 | yes |
If project memory fits in a paragraph in a single file, AGENTS.md is fine. Memspec is for when memory grows into a list of claims that need to track code reality, expire, supersede, and link to each other.
Memory model
Three claim types plus observations, agent-operated, lifecycle handled in the tool:
| Type | Captures | Default TTL |
|---|---|---|
fact |
Verified project state | 90d |
decision |
A choice with rationale | 180d |
procedure |
A reusable workflow | 90d |
observation |
Point-in-time, hard expiry | 7d |
Each memory is one markdown file with YAML frontmatter. Past check_by → stale flag at read time, never deletion. memspec sweep is the only removal path, operator-approved one item at a time.
States: active | superseded | retired. Corrections create a new memory linked back to the original; supersede chains preserve the reason on every record involved. Everything lives in git history.
Linked notes
Records reference other records by id in their frontmatter — refines, supports, depends_on, derived_from, conflicts_with, supersedes, superseded_by. Search can follow these links to surface neighbours alongside direct matches:
memspec search "v0.5 plan" --expand-edges --expand-depth 1
Follows the listed ids one hop out and includes the linked notes in results. Each surfaced neighbour carries expanded_via showing how it got there. --include-superseded lets expansion reach archived predecessors via supersede chains. --as-of <iso> filters by valid_from / valid_to for world-state queries.
Derived vs observed (derived_from, v0.11)
derived_from marks a record as inferred from other records rather than observed directly — a conclusion, not a measurement. A record carrying any derived_from edge is derived: true in search/get JSON, and its search hit's header carries a (derived) marker in CLI/MCP text. Like the other positive edges it cannot coexist with a conflicts_with to the same target. See Search for how derived affects coverage_witness.
memspec remember fact "The cache layer is the bottleneck" --source claude-code \
--derived-from ms_01AAA… --derived-from ms_01BBB…
Compared, independent (distinct_from, v0.13)
distinct_from records that you compared two records and they are independent claims: neither contradicts, refines, supports nor depends on the other. It exists to acknowledge an overlap memspec check flagged (see below). It is not a retrieval edge, so search expansion and lineage never follow it, and it cannot sit next to any other edge between the same two records (whichever record carries either one).
memspec relate --from ms_01AAA… --to ms_01BBB… --type distinct_from
Merge-time contradiction check (memspec check, v0.13)
A team store shared through pull requests never gets a git conflict (one file per record), so two records that contradict each other can merge a week apart. memspec check runs in CI on the PR branch and fails when the change set adds or edits an active claim that plausibly overlaps another active claim with no recorded relation between them:
memspec check # vs the merge-base with origin's default branch
memspec check --base main --json # explicit base, JSON report
memspec check --all # audit every active claim (no git needed)
- What is checked: records that are new at the merge-base, were not active claims there (a revived archive record), or whose title, body, set of anchored files, type, validity window or scope changed (working tree and untracked files included). Frontmatter-only edits (verify, tags, added edges, anchor sha refresh) don't count, so a triage PR doesn't surface pre-existing pairs. Removing an acknowledgement or a
conflicts_withdoes count: anunrelated edge, a question group that drops or loses an answer, a deleted copy of a record that carried the edge. - What overlaps: a shared anchored file, or one record's text naming a file the other is anchored to, plus 2+ shared distinctive title terms; or 3+ shared title terms with an overlap of at least 0.5. Any type against any type.
- What clears a finding: either record lists the other in
refines,supports,depends_on,derived_fromordistinct_from, or a question group lists both. Aconflicts_withbetween two active records, carried by either one, is itself a finding (declared_conflict) when either file changes: supersede one or file both in a question group. So is asupersedesnaming a record that is still active (unapplied_supersede): archive the target (state: superseded,superseded_by), or letmemspec supersededo it in that store. In a team store that is the promote PR that copied a local survivor but not the target's retirement. - Invalid files: a changed record file that does not load (bad frontmatter, non-YAML front matter such as
---js, which is refused and never evaluated), any duplicate record id in the store, a changed symlink, or a record naming one target indistinct_fromand another edge list. Git mode refuses outright (exit 2) a store with a symlink at its root or undermemory/,observations/orarchive/, and a store whose record files git does not track (gitignored, or the wrong--store). - Exit codes: 0 clean, 1 findings (overlaps, declared conflicts, unapplied supersedes, invalid files), 2 usage or git error. The text output ends with the commands to resolve the first finding.
Running the check in CI
The check diffs against a merge-base, so the job needs the history: check out with full depth (fetch-depth: 0). The default GitHub checkout is depth 1; there the merge-base cannot be found and the check exits 2, failing closed rather than passing. Pass the base explicitly: origin/<base branch> on a pull request, and the previous tip of main on a push to main (so the push run checks exactly what the push added). Exit 0 passes the job; 1 (findings) and 2 (usage or git error) fail it.
name: memspec-check
on:
pull_request:
push:
branches: [main]
jobs:
check:
runs-on: ubuntu-latest
steps:
# Pin actions by commit SHA in a real workflow.
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm install -g memspec@0.14.0
- name: memspec check
env:
EVENT: ${{ github.event_name }}
BASE_REF: ${{ github.base_ref }}
BEFORE: ${{ github.event.before }}
run: |
if [ "$EVENT" = pull_request ]; then
memspec check --base "origin/$BASE_REF"
else
memspec check --base "$BEFORE"
fi
The check is only as strong as the branch protection around it: make it a required status check on main, and treat a PR that edits the workflow itself as a change to the gate.
Actuation boundary (requires_human, v0.11)
A procedure can flag steps only a human may perform. An unattended runner reads requires_human and refuses those steps instead of executing them. It is a procedure-only field (a schema error elsewhere). A non-empty requires_human also carries through to search hits (JSON requires_human; CLI/MCP text prints a requires human: … line under the hit) and memspec_get, so a runner sees the constraint without a separate lookup.
memspec remember procedure "Rotate the signing key" --source human:siim \
--requires-human "approve the rotation in the console" \
--requires-human "confirm the new key in the HSM"
Evidence attachments (--evidence, v0.11)
Attach committed proof to a claim. A local file is copied, content-addressed, into <store>/evidence/<sha256>/… (refused over 5 MB, from the machine-local local/ subtree — checked on real paths, so a symlinked parent directory doesn't slip past — or when the path itself is a symlink: pass the real file); an http(s) URL is recorded as a pointer and never fetched. A file-backed attachment witnesses an anchorless claim as evidence — stronger than a bare assertion. verify --evidence-file <path> attaches the same way, but only on a clean verification: a needs_review result copies nothing. remember validates every input (all evidence paths, dates, edge targets, the answered question) before the first copy, so a refused write never leaves an orphan under evidence/. The entry's source field is provenance, never an absolute path: ~/… for a file under your home directory, <repo>:<path> inside a git checkout, otherwise omitted (the basename is in name).
memspec remember fact "p99 latency is 40ms under 2k rps" --source claude-code \
--evidence ./bench/2026-09-11.json --evidence https://grafana.internal/d/abc
The evidence/ directory is committed (not gitignored): it holds public/derived artifacts only. Secrets belong in the untracked local/ subtree, which --evidence refuses to copy from.
Question groups (v0.11)
When two or more records answer one named question, group them instead of wiring pairwise conflicts_with. A closed question (its listed answers are the only candidates) resolves by elimination: once every answer but one is superseded/retired, status reports the survivor. Resolution is never automatic — you confirm it.
memspec question "Which DB backs the ledger?" --source siim --answers ms_01AAA… ms_01BBB… --closed
memspec remember fact "Ledger uses Postgres 16" --source siim --answers-question ms_01QQQ…
memspec question ms_01QQQ… --resolve # once one answer survives
Question records never carry state: active, so they're invisible to a plain memspec search — the normal query pipeline is built on the active-only FTS pool. --type question (MCP type: "question") is the dedicated path: it lists question records directly instead of ranking them, open groups first, then resolved (each group newest-first); a query filters by a case-insensitive substring match against the title. Hits carry closed, answers, state, and resolved_by alongside the usual fields.
memspec search "ledger" --type question # or: memspec search "" --type question for all of them
Code-anchored verification
Calendar TTL is the wrong signal for facts about code. Memspec ties claims to file SHAs:
memspec anchor <id> <files...>— record the git blob SHAs of the files this memory depends onmemspec verify <id>— refresh "still true"; drifted anchors flag for review without mutating the memorymemspec reconcile— scan all anchored memories for drift, including uncommitted edits
Anchor paths may be absolute (preferred), project-relative, or repo-qualified (repo/path). Prefer absolute paths when the store's project root is not the repo you're working in — a home-rooted personal store's project root is $HOME, so a bare src/x.ts resolves nowhere and the claim silently degrades to an unanchored assertion. For a repo-relative path to a sibling checkout, pass --anchor-root <dir> (anchor_root over MCP). A path that resolves nowhere is reported back, never silently dropped.
Which form gets recorded. A file that belongs to the same git repo as the store's project root (or to no repo) is recorded project-relative and repo-less. A file inside a different git repo is always recorded as {repo: <basename>, file: <repo-relative>} — even when it also lies under the project root. That is the personal-store case: $HOME/git/kvart/src/x.ts becomes {repo: kvart, file: src/x.ts}, which resolves on every machine the store syncs to, where a git/kvart/src/x.ts form would read as drifted the moment the repo lived somewhere else. On read, repo is looked up as a sibling of the project root, then under each anchors.repo_search_paths entry in config.yaml — defaulting to ~/git when none is configured (set the list explicitly, e.g. [~, ~/git], on a machine whose checkouts live elsewhere). repo must be a bare directory name: a record carrying an absolute or traversal repo reads as repo_unavailable / anchor_unchecked, never as a probe of that directory. When a write records a {repo, file} anchor that this store could not resolve on read, the result says so and names the directory to add to repo_search_paths.
Drifted memories never auto-archive. They surface for human judgement via memspec status.
Search
SQLite FTS5 full-text + BM25, recency-weighted per profile. Zero setup beyond better-sqlite3.
Index rebuilds on demand from the markdown files. Lose the index, lose speed — not data. Parsed records are cached per file (mtime, size, inode), so a long-lived MCP server does not re-read the store on every query.
Matching is tiered: records carrying every query term rank first; when they fill less than a page, records carrying only some of the terms are added below them, never above. A query with one word the right record lacks still finds it.
Every result set carries a coverage verdict so an agent can tell "the store knows nothing here" from a low-ranked hit: none (no active record matches; with a narrowing --type filter the note names the filter and how many records of other types do match), weak (fewer than half of the distinct content-bearing query terms occur in the best-covered hit, or that hit is a partial-term match carrying under three quarters of them, or a title/tag-only match, or the best full-term match is barely above the BM25 floor — don't infer from rank; the note names which terms matched nothing), or ok. The term test uses the index tokenizer, so remootio, hubitat, gate and "remootio relay" hubitat count like their bare words, tariffs matches tariff, gate does not match gateway, and function words (does the ... use) are ignored; in a layered store the hit judged is the best-covered one, not whichever layer won the rank-1 tiebreak. Weak/ok notes name the active scope when one is set. A coverage_witness names the strongest witness behind the hits (anchor > operator > evidence > assertion), so coverage ok with witness assertion reads as "claimed, but unverified"; a drifted or unchecked anchor counts as evidence and the line says so (best witness: evidence (drifted)). A derived hit (any derived_from edge — see "Derived vs observed" above) counts one tier weaker than its own verified_with when coverage_witness is computed — e.g. evidence reads as assertion — because the record's own witness only attests to how the inference step was checked, not to the ground truth its premises rest on; assertion is already the floor and stays assertion. The CLI prints a final Coverage: line; search --json and MCP return the same payload object (query, count, results, coverage, coverage_note, coverage_witness).
Anchored results are drift-checked on the read path: a record whose anchored file has changed since it was last anchored prints a [DRIFTED] marker (JSON/MCP: drifted, with anchor_unchecked when the anchor's repo is not checked out here). No reconcile run needed to see it. An anchor reads as drifted only when its recorded blob matches neither the working-tree file nor the file on the anchored repo's remote default branch (origin/HEAD, else origin/main, else origin/master, from local refs as of the last fetch). So a checkout on a feature branch does not drift records anchored to main, and a record anchored on that branch a moment ago is not drifted either (the working tree, which reconcile and anchor hash, still matches). Each drift entry's compared_to says what was compared: worktree+origin/main, or worktree when the repo has no remote default ref or the file is gitignored. A symlinked anchor is looked up on the ref by its target path, matching how it was hashed. status's drift count, boot context and verify use the same rule, and the same anchors.repo_search_paths; verify's note names any anchor that held only on the default branch (this checkout's copy differs). reconcile keeps working-tree semantics: it answers what this checkout changed.
memspec MCP questions
How do I add memspec MCP to Claude Code?
Run claude mcp add memspec -- npx -y memspec in your terminal. Add --scope user to make it available in every project.
How do I add memspec MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does memspec handle code changes?
It ties memories to git blob SHAs and flags claims for review when the code drifts, preventing facts from rotting silently.
Where is the memory data stored?
Memories are stored as human-readable markdown files with YAML frontmatter within a .memspec/ directory in your repository.
Does memspec require a backend or cloud service?
No, it has zero infrastructure requirements, meaning no accounts, no API keys, and no hosted services are needed.