Memspec

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

<p align="center"> <img src="assets/memspec_architecture_flow.svg" alt="How memspec works: agents read and write markdown memories under .memspec/, which flow through lifecycle, code anchors, linked notes, and FTS5/BM25 search to the MCP server and session hooks" width="620"> </p>

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, procedure with per-type TTLs; observation for 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.
• 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-superseded lets link-following reach archived predecessors (v0.6+).
• Temporal validity (v0.5+). Optional valid_from / valid_to per memory. Search with --as-of <iso> filters by world-state truth window, orthogonal to the check_by review schedule.
• Operator-tier storage (v0.4+). Records sourced by the operator land in a separate filesystem path with stricter overwrite protection (--override-operator required to supersede).
• 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 configured stores: layers. A repo without its own store can bind to external stores via a .memspec.yaml pointer 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 → reduce turns 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. remember refuses near-duplicate claims and points at the existing record, so memory accretes corrections via supersede instead of silent duplicates.
• FTS5/BM25 search. SQLite FTS5 relevance, recency-weighted, ranked per profile.
• MCP server. Fourteen tools, first-class integration with Claude Code, Cursor, Codex.
• 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_with does count: an unrelated 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_from or distinct_from, or a question group lists both. A conflicts_with between 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 a supersedes naming a record that is still active (unapplied_supersede): archive the target (state: superseded, superseded_by), or let memspec supersede do 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 in distinct_from and another edge list. Git mode refuses outright (exit 2) a store with a symlink at its root or under memory/, observations/ or archive/, 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 e