speckit-memory

Persistent, file-first memory for spec-driven development with AI coding assistants. Three markdown trees inside your project, one CLI, one MCP server, one derived SQLite index. Zero runtime dependencies, no install scripts.

Frequently asked questions

Works with Claude Desktop, Cursor, Windsurf and any MCP client.

How do I give my AI coding assistant persistent memory?

Install speckit-memory and register it as an MCP server. Your assistant can then record decisions, worklogs and watchpoints as markdown files inside the project, and read them back in later sessions.

What is spec-driven development memory?

It is a practice of keeping structured project knowledge — governance laws, decisions, worklogs, bug preventions and per-feature watchpoints — in versioned markdown trees. speckit-memory manages those trees and keeps a derived index so search stays fast.

How do I keep context between Claude sessions?

Store context as project memory entries (speckit-memory add). The next session resumes with full knowledge instead of starting cold — the filesystem is the source of truth, so nothing is lost.

How does speckit-memory store project decisions?

Decisions are DEC-#### entries with YAML frontmatter under docs/memory/decisions/. They can be updated, marked resolved, or removed, and governance laws (LAW-####) are immutable by design.

Does speckit-memory need a database or API key?

No. Everything lives in markdown files in your project. The SQLite index is derived and rebuildable. Zero runtime dependencies and no API keys.

How do I search my project memory from the CLI?

Run speckit-memory search <keywords>. You can also list with date filters (--since, --until), export/import bundles, and run speckit-memory doctor to check tree health.

What MCP tools does speckit-memory provide?

memory_add, memory_search, memory_resolve, memory_delete and more over JSON-RPC on stdio — see the MCP server section below.

Related MCP server: gitmem

Memory model

Markdown files carry YAML frontmatter (id, type, title, created, updated, tags, ...). The filesystem is the source of truth; everything in .speckit-memory/ (SQLite when node:sqlite is available — Node >= 22.5 — JSON otherwise) is a derived, rebuildable index.

Governance laws are immutable: update/remove on a LAW- id throws ImmutableLawError. History and feature entries can be updated, resolved (**[RESOLVED YYYY-MM-DD]** marker), or removed.

Docker

Run the MCP server in a container:

docker build -t speckit-memory .
docker run -i --rm -v "$PWD:/project" -w /project speckit-memory

The image uses node:22-alpine and starts the MCP stdio server by default.

Install

npm install speckit-memory

Requires Node.js 22.5 or newer. No postinstall, no native builds, no dependencies.

CLI

speckit-memory init
speckit-memory add law "Never store plaintext private keys" --tag security
speckit-memory add history "Chose argon2id for password hashing" --category decision
speckit-memory add feature "Token expiry drifts under load" --feature auth --kind watchpoint
speckit-memory add feature "Which redirect flow for mobile?" --feature auth --kind open-question
speckit-memory list --type law
speckit-memory list --feature auth --json
speckit-memory list --since 2026-01-01 --until 2026-06-30
speckit-memory show WP-AUTH-0001
speckit-memory search "token expiry" auth --limit 10
speckit-memory remove LOG-0002
speckit-memory resolve OQ-AUTH-0001
speckit-memory export backup.json     # full JSON backup of every entry
speckit-memory import backup.json     # restore (existing ids are skipped)
speckit-memory stats                  # counts by type/category/status
speckit-memory doctor                 # tree + cache health check
speckit-memory synthesize auth        # writes specs/auth/memory.md (~900 words)
speckit-memory synthesize auth --words 600 --stdout
speckit-memory mcp-start              # MCP server on stdio (JSON-RPC 2.0)

All commands accept --root DIR to target a specific project root (default: auto-discover via .specify, package.json, or .git). Exit codes: 0 success, 1 domain/runtime error, 2 usage error.

Synthesis

speckit-memory synthesize <feature> assembles a bounded (~900 word, --words to override) memory document, deterministically and offline:

1. Active watchpoints and open questions for the feature take the largest share of the word budget.

2. Project history is ranked by relevance to the feature (tags/title/ content mentions, feature: references), then recency.

3. Governance laws appear as one-line digests.

4. Anything trimmed for budget is listed by id under Synthesis Notes; nothing is invented — every sentence comes from a stored entry.

MCP server

speckit-memory mcp-start (or node mcp-server.js) speaks MCP over stdio and exposes six tools: memory_add, memory_list, memory_search, memory_synthesize, memory_resolve, memory_delete. The server resolves its engine in this order:

1. SPECKIT_MEMORY_ENGINE env var (path to an engine module)

2. lib/engine.js — canonical engine (shipped; backed by MemoryStore)

3. lib/memory-engine.js — alternate name

4. lib/fallback-engine.js — built-in single-file store (always present)

The canonical engine maps friendly types (decision, pattern, lesson, watchpoint, ...) onto the three trees and honors SPECKIT_MEMORY_ROOT (explicit project root) and SPECKIT_MEMORY_PATH (project directory, or a legacy .json/.db path whose parent directory becomes the project root). CLI and MCP therefore read and write the same memories.

MCP client configuration

Register the server in your MCP client, e.g. claude_desktop_config.json:

{
  "mcpServers": {
    "speckit-memory": {
      "command": "npx",
      "args": ["-y", "speckit-memory", "mcp-start"]
    }
  }
}

Or point command at a local checkout (node /path/to/speckit-memory mcp-start). Set SPECKIT_MEMORY_ROOT in env when the server should bind to a specific project instead of auto-discovering one.

Search semantics

speckit-memory search and memory_search treat the query as OR-ish keywords: a memory matches when the keywords hit, and more hits rank higher. The standalone lib/sqlite-cache.js search helper instead requires all keywords (AND). This is intentional: the CLI/MCP search is a friendly recall tool, while the cache helper is a strict filter.

Programmatic API

const { MemoryStore, synthesize } = require('speckit-memory/lib');

const store = MemoryStore.open(process.cwd()); // or new MemoryStore(rootDir)
store.init();
store.add({ type: 'law', content: '...', tags: ['security'] });
store.add({ type: 'history', content: '...', category: 'decisions', feature: 'auth' });
store.add({ type: 'feature', content: '...', feature: 'auth', kind: 'watchpoint' });
const laws = store.list({ type: 'law' });
const one = store.get('LAW-0001');
store.update('DEC-0001', { content: 'revised' });
store.resolve('OQ-AUTH-0001');
store.remove('LOG-0002');           // throws for LAW-#### ids
const doc = synthesize(store, 'auth'); // { wordCount, body, document, file, ... }

Entry shape: { id, type, category, feature, title, filePath, created, updated, tags, content, status, hash, wordCount }.

Derived index cache (store.cache): replaceAll(entries), query({type, category, feature, tag}), count(), close() — schema version tracked in the meta table (CACHE_SCHEMA_VERSION). Rebuild at any time with store.scan().

Troubleshooting

• "Memory trees are not initialized" — since 0.1.3 the MCP engine no longer silently creates .specify//docs/memory/ trees in whatever directory it was started from. Run speckit-memory init in the project (or point SPECKIT_MEMORY_ROOT at an initialized one) before starting the server.

• "file is not a database" or a corrupt .speckit-memory/index.db — the index is a derived cache. Since 0.1.3 a corrupt index.db is moved aside as index.db.corrupt-<timestamp> and rebuilt automatically; the original markdown trees are never touched. If problems persist, delete .speckit-memory/ and run speckit-memory doctor.

• Windows-authored markdown loses frontmatter — files saved with a UTF-8 BOM are handled correctly since 0.1.3 (the BOM is stripped before parsing).

• no SQLite backend available — lib/sqlite-cache.js and lib/synthesis-engine.js need node:sqlite (Node 22.5+, still marked experimental by Node; you may see an ExperimentalWarning). The core memory store (lib/memory-store.js) falls back to JSON when sqlite is missing, so basic add/list/search keep working everywhere.

Development

npm test            # full suite: core + MCP + SQLite/synthesis + engine contract
node test/mcp-smoke.js

License

MIT

Links

• GitHub: https://github.com/venkatreddygutha9-stack/speckit-memory

• Issues: https://github.com/venkatreddygutha9-stack/speckit-memory/issues

• npm: https://www.npmjs.com/package/speckit-memory