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

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…

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 on
• memspec verify <id> — refresh "still true"; drifted anchors flag for review without mutating the memory
• memspec 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.

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 a title/tag-only match, or 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.

Usage receipts & outcomes

Every search hit is logged to a local, gitignored usage.jsonl — one row per result, carrying the query (truncated to 200 chars), the hit's rank, which surface issued it (cli | mcp | context), and a session id when one exists: MEMSPEC_SESSION_ID, else CLAUDE_SESSION_ID, else mcp:<pid> inside the MCP server (one process per client connection, so the process is the session). A bare CLI invocation with none of those carries no session — there is deliberately no per-process fallback, because an id that changes on every call would make two searches in one agent turn count as two sessions. Rows without a session never contribute to sessions, so Promotion candidates require real session ids (the status text says so). Boot context (memspec context, the session-start hook) logs the records it surfaces with surface context, so a pinned record that boots every session is never reported cold. In a layered store each row lands in the store that owns the record, so a read-only team layer accumulates its own receipts. Search hits and memspec_get results carry last_referenced / sessions back to the caller when known — read-only derivations, never written to frontmatter.

Retrieval alone doesn't say whether a memory actually helped. memspec outcome <id> <useful|dead_end|corrected> [--note] [--source] (CLI + memspec_outcome MCP tool) appends a durable, append-only receipt to outcomes.jsonl without ever mutating the record. supersede records a corrected outcome automatically for every id it collapses — you don't have to call it yourself when you already know a claim was wrong. Record dead_end whenever a retrieved memory turned out wrong or useless for the task at hand; it feeds status's two usage-derived surfaces:

• Cold — active records created more than 30 days ago that have never been retrieved, or weren't retrieved in the last 60 days. Candidates for memspec supersede or a closer look, not automatic removal.
• Promotion candidates — active observations, and facts witnessed only by assertion and created in the last 14 days, that have been retrieved in 2+ distinct sessions with zero dead_end outcomes. Candidates only — nothing is auto-promoted.

Both sections print in memspec status text output and surface as cold / promotion_candidates arrays in the MCP memspec_status JSON.

Trust profiles

Memspec doesn't enforce a write policy; the agent's instruction file does (see AGENTS-ADDON.md). Two reference profiles:

Operator solo (default). The agent writes facts, decisions, procedures, and observations freely. Duplicate rejection, anchor drift, and supersede chains catch bad writes. Friction-free; relies on git log to undo mistakes. Suits single-operator setups where memspec is your own agent infrastructure.

Team review. For shared repos with multiple writers:

• Observations: agent writes freely.
• Facts: agent writes only when anchored to code; anchorless facts route to a PR for review.
• Decisions: drafted by agent, merged by human.
• Procedures: agent-written, reviewed at first use.
• Operator-tier claims: never overridden without --override-operator and a reason in the supersede record.
• Secrets: never stored. Anywhere. Ever.

Pick the profile in your AGENTS.md / CLAUDE.md and the agent will follow it. The store records every write, so deviations show up in git log.

MCP server

memspec-mcp                          # stdio in current project
memspec-mcp --cwd /path/to/project   # pin a root

memspec init auto-creates .mcp.json for host tool discovery (Claude Code, Cursor, etc).

Fourteen MCP tools: memspec_search, memspec_get, memspec_remember, memspec_supersede, memspec_relate, memspec_unrelate, memspec_observe, memspec_verify, memspec_outcome, memspec_question, memspec_anchor, memspec_reconcile, memspec_status, memspec_export. The CLI exposes a superset (init, migrate, sweep, context are CLI-only — store creation, schema migration, physical removal, and session-start context are operator acts, not an agent surface).

For manual .mcp.json setup:

{
  "mcpServers": {
    "memspec": { "command": "memspec-mcp", "args": ["--cwd", "/abs/path/to/project"] }
  }
}

Global store

~/.memspec/ is a cross-project memory layer for personal preferences, common patterns, infra knowledge. When both stores exist, the project store takes priority; global merges as a lower layer.

memspec init --cwd ~/.memspec

Store resolution

Every command resolves which store to use from --cwd (defaulting to the process cwd) by walking up the directory tree: the first ancestor holding a .memspec/ directory (or a .memspec.yaml pointer) is the store. A session started three directories deep in a repo, or in a repo with no store of its own, resolves the nearest real store instead of a phantom empty <cwd>/.memspec.

The walk is fenced, and the .memspec/ walk and the .memspec.yaml pointer walk share the same fence (so search, which honours pointers, and status, which does not, always agree on the store):

• Inside $HOME it stops at $HOME (inclusive). A home-rooted ~/.memspec is found; nothing above $HOME is ever consulted — a .memspec/ or pointer file in /Users or /home cannot capture a session.
• Outside $HOME it walks to the filesystem root, as memspec always did before 0.11: a repo at /srv/app, /opt/x, or a container's /work resolves /srv/app/.memspec from any subdirectory.
• MEMSPEC_NO_WALK=1 disables it entirely: only cwd itself is checked (a .memspec/ or pointer file right there still applies); otherwise <cwd>/.memspec is used verbatim.
• A nearer .memspec/ directory beats a farther .memspec.yaml pointer — the closest store to cwd wins.
• A pointer file is only honoured when it can be trusted: one that sits in a world-writable directory (/tmp, a shared scratch dir) or is owned by another user is ignored with a stderr note and resolution continues as if it were absent. A .memspec/ directory says where you are; a pointer redirects reads and writes to whatever path its author chose, so it has to be yours.
• An explicit store path (one that already ends in .memspec, e.g. MEMSPEC_ROOT=~/.memspec or --store global) is used as-is and never walked.

Scope derives from the original cwd, not the resolved store. When the walk climbs from repo/service/api up to repo/.memspec, the active scope is still computed from repo/service/api against the store's scopes: map — so a session in a subdirectory is scoped correctly rather than left unscoped.

Writes follow the same layers as reads. When the resolved store's config.yaml (or a pointer file) declares stores:, a write from that cwd targets the single writable layer — or the one named by --store <name> — never the walked-up store itself unless it is one of the layers. Relative path: entries resolve against the directory that holds the config that declared them, not against the caller's cwd. Zero writable layers refuses; several writable layers without --store refuses as ambiguous; --store naming a writable: false layer refuses. memspec question resolves its store exactly the same way and never creates a store as a side effect.

Missing layers are reported, not dropped. A configured layer whose directory is absent on this machine (not cloned yet, typo, moved) is still skipped for reads, but the composite now carries layers_unavailable: [name] and a warning naming the path, so a coverage: none can say "the team layer isn't here" instead of "the store is empty".

init refuses to create a store nested inside an existing one (a .memspec/ already exists up the tree, ~/.memspec included) and exits 1 naming the parent store; pass --force to create the nested store deliberately.

Multi-store: pointer files & scope claims

Different orgs lay memory out differently — store beside the code, store in a sibling team repo, one personal umbrella. Two declarations make any layout explicit and keep knowledge from leaking across store boundaries:

Pointer file. A repo with no store of its own carries a .memspec.yaml at its root binding it to the stores that serve it (paths resolve against the pointer's directory; a .memspec/ directory closer to cwd always wins):

# service-repo/.memspec.yaml — memory lives in the sibling team repo
stores:
  - name: team
    path: ../platform-team-specs
    priority: 10
    writable: true
  - name: personal
    path: ~/.memspec
    priority: 0
    writable: true

Reads fan out across the layers. Writes must be unambiguous: with more than one writable layer in scope, remember refuses until you say --store team or --store personal — a silently-guessed store is how team knowledge ends up in a personal repo.

Read-only layers (writable: false). A layer marked writable: false is included in every read but refuses every write. A write with no explicit --store never selects it, and an in-place edit of a record it owns — supersede, relate/unrelate, verify, anchor — refuses, naming the layer:

"ms_01K…" lives in read-only store layer 'kvart-team' (…); it cannot be modified here.

An explicit --store kvart-team write also refuses. This is how a personal store layers a shared team store it should read but never mutate.

The layer field. A search hit or memspec_get result served from a non-primary layer carries layer: <name> in JSON, and the CLI/MCP text appends a (layer: <name>) suffix. Hits from the primary (writable) layer carry no layer — single-store retrieval stays byte-identical.

Recipe: a personal store layers a read-only team store. Add a stores: block to the personal store's own config.yaml, pointing at the team store by absolute path (~ and absolute paths both work):

# ~/.memspec/config.yaml
stores:
  - name: personal
    path: ~/.memspec          # writable primary
    priority: 0
    writable: true
  - name: kvart-team
    path: /Users/siim/git/kvart-team-context/.memspec   # read-only team layer
    priority: 10
    writable: false

$ memspec search "meter reading" --limit 3
[decision] Meter reading estimation from historical data … (assertion) (layer: kvart-team)
  ms_01KQ5S73FHC7582BZEBFBVYMXJ | 2026-04-26 | siim
…

Team records surface with (layer: kvart-team); remember without --store lands in personal; any edit of a team record refuses.

Scope claims. A store's config.yaml declares the working directories whose knowledge it owns:

claims:
  - ~/work/platform/**
  - ~/git/my-project

Ingestion (memspec reduce) routes each session's digest to the claiming store. Sessions nobody claims are held local — they never cross a sync boundary, and route automatically the day a claim appears. No claims configured anywhere = classic single-store behaviour.

Record scoping

A store shared across several projects (a home-rooted personal store, or one shared repo store) can partition records by working directory so a query issued while working on one project doesn't surface another's noise:

scopes:
  kleidia: [~/git/kleidia, ~/git/kleidia-docs]
  plg: ['~/piletilevi/**']

A record's scope is absent (visible from every scope — the default), universal (explicitly visible everywhere), or a name from the map above (visible only when that scope is active). remember/observe/search all accept --scope, or derive it from cwd against the patterns above.

Set scopes_require: true in config.yaml to make this mandatory: remember/observe then refuse a write that resolves no scope at all (no --scope passed, cwd matched no pattern) rather than letting it land unscoped. Pass --scope universal for a record that genuinely belongs everywhere — that's the explicit opt-out, not a workaround.

Records written before scoping existed (or written since without a scope) can be backfilled from their tags: node bin/repair-scope-backfill.mjs --store <root> --map tag:scope,tag:scope,... (dry-run by default; --apply writes, with an undo journal). Records whose tags match two different scopes are left untouched and reported ambiguous; records matching nothing are left untouched and counted; operator-sourced records are skipped unless --include-operator.

Store layout

.memspec/
  memory/
    facts/  decisions/  procedures/        # active, agent-tier
    operator/{facts,decisions,procedures}/ # operator-tier (separate path)
    questions/                             # question groups (v0.11)
  observations/                            # raw, unclassified
  evidence/                                # committed evidence attachments (v0.11)
  archive/                                 # superseded + retired
  config.yaml                              # decay, profiles, scopes, stores
  .gitignore                               # usage.jsonl, outcomes.jsonl, local/, logs/ — telemetry, never memory

The .gitignore is written by init and kept current on every write: a store created before 0.11 gets outcomes.jsonl, local/ and logs/ appended on its first 0.11 write (only the missing lines, under a short comment), so git add -A in a synced store never picks up per-machine telemetry.

Frontmatter fields per record: id, kind (claim | observation | question), type, state, source, source_kind, verified_with (anchor | operator | evidence | assertion), tags, check_by, anchors, supersedes, superseded_by, conflicts_with, refines, supports, depends_on, derived_from, optional requires_human (procedures), evidence, answers / closed / resolved_by (questions), valid_from / valid_to. Human-readable, git-diffable, greppable.

CLI reference

| Command | What | |---|---| | memspec init | Create .memspec/, install hooks | | memspec remember <type> <title> --source <who> | Write a fact/decision/procedure | | memspec observe <text> | Capture a point-in-time observation | | memspec search <query> [--expand-edges] [--include-superseded] [--as-of <iso>] | Search; optionally follow linked notes | | memspec context [--query] [--limit] | Token-budgeted memory dump for session-start hooks | | memspec supersede <id> --reason "..." [--body] [--merge-from <ids>] | Replace, retract, or merge records | | memspec relate --from <id> --to <id> --type <kind> | Wire a link between records after the fact (refines\|supports\|depends_on\|derived_from\|conflicts_with) | | memspec question <title\|id> [--answers <ids>] [--closed] [--add\|--close\|--open\|--resolve] | Create or edit a question group (competing answers; closed questions resolve by elimination) | | memspec verify <id> [--evidence "..."] [--check-by <iso\|never>] | Mark a memory still true; checks anchors; --check-by pins the next review date explicitly instead of resetting to the type default | | memspec outcome <id> <useful\|dead_end\|corrected> [--note] [--source] | Record what happened after a retrieved memory was acted on (append-only; never mutates the record) | | memspec anchor <id> <files...> | Link a memory to file SHAs | | memspec reconcile | Find anchored memories with drifted code | | memspec normalize [--source <harness>] | Session logs → local trajectory records (deterministic, local-only) | | memspec distill [--limit <n>] | Trajectories → per-session digests via a cheap LLM | | memspec reduce [--force] | Per-session digests → committed experience digest, routed by claims | | memspec status | Health readout (counts, witness, stale, drift, conflicts, cold records, promotion candidates) | | memspec sweep [--dry-run] [--answers <file>] | Interactively retire stale items (operator-only removal path); --answers reads <id>\t<y\|n> lines non-interactively instead of prompting | | memspec export --format <jsonl\|graphml\|dot> | Export records and links to stdout | | memspec migrate | v0.2/v0.3 → v0.4+ store migration (idempotent, dry-run by default) |

Hooks for Claude Code

memspec init installs two hooks at ~/.claude/hooks/:

• memspec-session-start.js — runs memspec context and injects memory into the session prompt so the agent doesn't have to remember to search; also surfaces unreviewed dream passes (counts + open questions) until a _Reviewed: marker lands (v0.8+)
• memspec-consolidate.js — on commit, prompts the agent to write memories about what just shipped

Configurable in .memspec/config.yaml. Pass --no-install-hooks to skip. See hooks/ for the scripts.

Dream pass

A periodic reflection over the store. Reads the last N days of memspec writes + git log, asks an LLM to surface stale memories, supersede / merge candidates, verify candidates, missing typed relations, and behavioural rules worth promoting to your agent instruction file. Proposals only — never auto-applied.

memspec-dream                          # weekly default (7 days, current .memspec/)
memspec-dream 14                       # custom window
MEMSPEC_DREAM_AUTOCOMMIT=1 memspec-dream

Output lands at <store>/dream/YYYY-MM-DD.md for a human to review. Defaults to invoking claude (Claude Code CLI) headlessly; override with MEMSPEC_LLM_BIN and MEMSPEC_LLM_ARGS for other CLIs.

Cron example (Sunday 22:00 local):

0 22 * * 0  cd /path/to/project && MEMSPEC_DREAM_AUTOCOMMIT=1 memspec-dream

Inspired by Aaron Fulkerson's Exo and the dream-skill prior art.

Transcript ingestion

The dream pass can only consolidate what sessions bothered to write down. Transcript ingestion closes that gap by distilling what sessions actually did (v0.9+):

memspec normalize   # harness logs -> trajectory records   (deterministic, 0 tokens, local/)
memspec distill     # trajectories -> per-session digests   (cheap LLM, incremental, local/)
memspec reduce      # digests -> experience digest           (deterministic, committed, claim-routed)

• normalize reads Claude Code (~/.claude/projects/) and Codex (~/.codex/sessions/) session logs into trajectory-v1-shaped records (after Letta's Trajectory format; own implementation). Adapter per harness — adding one is a small PR.
• distill runs each session through a cheap model (MEMSPEC_DISTILL_BIN/MEMSPEC_DISTILL_ARGS, default claude --model haiku -p) into a ~250-word digest: what happened, decisions, fixes, discoveries, loose ends. Incremental with a per-run cap, so a heavy week never becomes one un-fittable batch. Secret shapes are redacted.
• reduce merges fresh digests into <store>/digests/<date>-<hostname>.md — the only artifact that gets committed. Raw transcripts, trajectories, and per-session digests stay in the gitignored local/ and never leave the machine.
• The dream pass then reads experience digests alongside memspec writes and reports UNRECORDED WORK: things that demonstrably happened but produced no memory — with ready-to-run memspec remember proposals.

Scheduling is wall-clock-free by design: run all three from any wake-driven daily job (macOS launchd fires missed slots on wake; distill and reduce self-gate). Laptops that were off simply catch up on next wake — data is delayed, never lost.

Docs

• SPEC.md — design rationale and frontmatter schema
• SCHEMA.md — generated field reference (regenerated from Zod via npm run schema)
• CHANGELOG.md — release history
• MIGRATION-v0.3.md — v0.2/v0.3 → v0.4+ upgrade path
• AGENTS-ADDON.md — block to paste into AGENTS.md / CLAUDE.md if init couldn't patch your repo

License

MIT