Fast, token-budgeted working memory (default 8 KB brief, configurable) outside your repository. Prevents commit pollution, stops repeating bug traps across sessions, and keeps your product clones clean.
npm install -g github:jpolvora/spec-memo
Product repositories belong to your product: clean source code, tests, and documentation. Agent scratchpads, execution logs, and repetitive traps belong in an external vault.
.agents/plans/, MEMORY.md) clutter git status and bloating commits.bootstrap delivers ranked anti-regression traps, active decisions, and code drift warnings. Raise the cap in ~/.spec-memo/config.json (bootstrap.maxBytes) or per call via maxBytes.vaultGit.atomic (default batched). When hybrid HTTP and vault-git are both enabled, memo sync and session_end flush both channels in parallel—fail-open, never crashing the MCP server.spec-memo runs as a standard Model Context Protocol (MCP) server. Configure it in seconds for your favorite coding assistant.
{
"mcpServers": {
"spec-memo": {
"command": "memo",
"args": ["serve"]
}
}
}{
"mcpServers": {
"spec-memo": {
"command": "npx",
"args": ["-y", "github:jpolvora/spec-memo", "serve"]
}
}
}{
"mcpServers": {
"spec-memo": {
"command": "memo",
"args": ["serve"]
}
}
}{
"mcpServers": {
"spec-memo": {
"command": "memo",
"args": ["serve"]
}
}
}# Run session bootstrap brief in any repository
memo bootstrap
# Start HTTP / SSE server on :3123 + Status Monitor on :3124
memo serve --sse --port 3123 --status-port 3124
# Run repository pollution diagnostic & cleanup
memo doctor --fixEvery memory entry is stored as a clean Markdown file with YAML frontmatter, typed and indexed for precision retrieval.
Captures tricky pitfalls, concurrency races, and platform quirks. Path-matched globbing and 70% automatic superseding prevents duplicate warnings.
memo upsert --kind trap --title "SQLite WAL Lock" --severity high --path-patterns "src/db/*.ts"
Documents system design choices, trade-offs, and invariants. Can be promoted into human product docs on-demand via memo promote.
memo upsert --kind decision --title "Use SQLite FTS5 for Search" --body "ADR: Zero daemon overhead"
Feature definitions with linked paths and verified commit SHAs. Automatic drift detection flags when source code changes away from the spec.
memo upsert --kind spec --slug "auth-jwt" --body "Spec: JWT Auth Flow"
Task graphs, DAG execution state, and progress trackers. Garbage collection automatically compacts completed plans to save vault space.
memo upsert --kind plan --slug "auth-dag" --body "Tasks: 1. DB 2. Route 3. Test"
Chronological task events and milestone markers. Never pollutes context briefs, but fully searchable and rolled up monthly.
memo append --event "Refactored token verification and passed 196 tests"
Temporary code review notes and prompt scratchpads. Auto-purged via curator GC with 7-day (scratch) and 14-day (reviews) TTL retention.
memo gc --dry-run # Cleans expired scratch & reviews
Every tool is available through MCP for AI agents and matching CLI commands for developers.
Binds repository working directory to project identity; returns a token-budgeted brief (default 8 KB; config.json bootstrap.maxBytes or --maxBytes) with top-ranked traps, active decisions, live slug, and SHA drift warnings.
memo bootstrap --slug feature-auth --path src/auth.ts
Full-text search across all vault records using Porter stemming, tags filter, path pattern globbing, and recurrence-weighted ranking.
memo search "database lock" --kind trap --path src/db/*.ts
Fetches a single record by exact ID or kind+slug combination with full YAML frontmatter and markdown body.
memo get --id trap-sqlite-wal-lock
Writes or updates a memory record. Validates schema, redacts secrets, checks token overlap for deduplication, and updates index views.
memo upsert --kind trap --title "Close statement before connection"
Appends a timestamped audit event or task execution milestone without polluting the primary context brief.
memo append --event "Passed all 196 test suites"
Soft-archives a memory record (marks status=archived) or permanently purges it from disk with the purge flag.
memo forget --id scratch-old-notes --purge
Applies TTL retention (7-day scratch, 14-day review), compacts completed execution plans, and rolls up monthly logs.
memo gc --dry-run
Promotes a vault record into the product repository as documentation (e.g. ADR or MADR template). Default-deny without destination.
memo promote decision-01 --to docs/adr/001.md --format adr
Compares the active spec-memo package version against the latest npm registry release. Soft-fails cleanly when offline.
memo check-version --json
Installs packaged runtime agent skills (such as ws-memo) directly into a consumer product's .agents/skills/ directory.
memo install-skills --product-root /path/to/project --force
Ingests prompt turns and session lifecycles into the vault; supports FTS search, activity reports, AI rule derivation, and intent-story export. session_end also flushes hybrid HTTP and batched vault-git when enabled. Aliases: memo prompts, memo session, memo activity.
memo session end s1 --summary "Shipped auth refresh"
Runs the MCP server in stdio mode (default) or HTTP/SSE mode on port :3123 with a live status companion UI on port :3124. Graceful shutdown flushes batched vault-git and hybrid sync when enabled.
memo serve --sse --port 3123 --status-port 3124
Queries live daemon reachability (SSE, Status, Canvas, Remote), project bindings, record counts breakdown, and vault storage footprint.
memo status --check
Validates vault structure, checks SQLite FTS5 integrity, and scans the product tree for forbidden workflow residue with automated --fix.
memo doctor --fix --rebuild
Ranks active anti-regression traps by occurrence frequency, filters by architectural layer, and exports to reusable skills.
memo rank --layer web --limit 10
Starts an interactive visual node graph viewer and REST API on port :3125 (configurable in config.json) for browsing memory relationships.
memo canvas --port 3125
Configures vault deployment mode (local, hybrid, remote) and automatically writes or prints host MCP configuration snippets.
memo setup --mode hybrid --url http://127.0.0.1:3123 --write-mcp
Safely wipes memory databases and unlinks compiled markdown while creating an automatic timestamped backup snapshot in backups/.
memo reset --force
Restores full vault state from timestamped pre-wipe ZIP backups or raw archives. Use memo backups to list saved snapshots.
memo restore --latest --overwrite
Installs a git pre-commit write-block hook into the consumer repository to prevent accidental commits of in-repo memory files.
memo hook install --productRoot /path/to/repo
Flushes hybrid HTTP delta sync and/or vault-git commit + pull/push. Dual-mode (mode: hybrid + vaultGit.enabled) runs both channels in parallel. Batched vault-git (atomic: false, default) does not commit on every upsert—flush here, on session_end, or graceful serve shutdown.
memo sync --dry-run --json
Exports or restores encrypted portable vault archives using AES-256-GCM and PBKDF2 key derivation.
memo export-vault --password "secret" -o ~/vault-backup.json
A hybrid architecture combining human-readable Markdown files, disposable SQLite FTS5 search, and zero-friction MCP protocol bridges.
┌────────────────────────────────────────────────────────────────────────┐
│ AI CODING AGENT SESSION │
│ (Cursor, Claude Desktop, Antigravity, VS Code) │
└───────────────────────────────────┬────────────────────────────────────┘
│ Model Context Protocol (MCP)
▼ Stdio / SSE Transport (:3123)
┌────────────────────────────────────────────────────────────────────────┐
│ SPEC-MEMO ENGINE │
│ ┌─────────────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Secret Redaction │ │ Trap Deduplication Engine │ │
│ │ Write-Block Guard │ │ Recurrence Ranking & TTL GC │ │
│ └────────────┬────────────┘ └──────────────────┬──────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Disposable SQLite │ │ Markdown Source of Truth │ │
│ │ FTS5 Index (memo.db) │ │ (~/.spec-memo/projects/<id>/) │ │
│ └─────────────────────────┘ └─────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────┘
│
ZERO IN-REPO ARTIFACTS
▼
┌────────────────────────────────────────────────────────────────────────┐
│ PRODUCT GIT REPOSITORY │
│ (Pure source code, tests, and documentation) │
└────────────────────────────────────────────────────────────────────────┘Every memory record is stored as an individual Markdown file with structured YAML frontmatter. Human-auditable, diffable, and resilient.
Search is powered by SQLite FTS5 with Porter stemming. If deleted or corrupted, the entire index automatically rebuilds from markdown in milliseconds.
Projects are automatically identified by normalized git remote URL. Multiple local checkouts share identical working memory seamlessly. Optional vaultGit backs up the vault root to a private git remote with batched or atomic commit cadence.
How to configure the memo CLI on PATH across Windows, Linux, and macOS, handle rebuilds, and troubleshoot agent execution.
memo to PATH on Windows & Linux?spec-memo declares its binary in package.json ("bin": { "memo": "./dist/cli.js" }) with a Node shebang.
Option 1: Global link (Recommended for Dev)
On Windows, this links memo, memo.cmd, and memo.ps1 in %AppData%\Roaming\npm (already on PATH). On Linux/macOS, it links into /usr/local/bin or your nvm global prefix.
Option 2: Global Install from Local Path
Option 3: Manual Shims (Standalone Wrapper)
~/.local/bin/memo:exec node "/path/to/spec-memo/dist/cli.js" "$@"C:\bin\memo.cmd):node "C:\path\to\spec-memo\dist\cli.js" %*No. The npm link and shims point directly to dist/cli.js.
Whenever you make changes and run npm run build (or run in watch mode via npm run watch), TypeScript compiles output directly to dist/cli.js. The global memo command immediately uses the updated code without requiring you to run npm link again.
IDE MCP Configuration: AI editors (Cursor, VS Code, Claude Desktop, Antigravity) use MCP stdio (memo serve or node /path/to/dist/cli.js serve) to call the 11 MCP tools natively inside prompt context.
Terminal CLI (on PATH): Adding memo to PATH enables developers and terminal subagents to run quick commands like memo bootstrap, memo doctor --fix, memo rank, and memo search directly from any shell.
memo: command not foundIf running memo --help returns command not found:
%AppData%\Roaming\npm (or npm config get prefix) is in your User or System Environment Variables under PATH.export PATH="$PATH:$(npm config get prefix)/bin:~/.local/bin" to your ~/.bashrc or ~/.zshrc.node /path/to/spec-memo/dist/cli.js --help to confirm the build succeeded.spec-memo services use the following default ports:
memo serve --sse): 3123/status): 3124memo canvas): 3125You can override ports via CLI flags (e.g. --port 8080 --status-port 8081) or persist them globally in ~/.spec-memo/config.json under the "ports" key:
Aliases mcp (for sse) and ui (for status) are also automatically recognized.
spec-memo is open source under the MIT license. We welcome contributions from developers and AI practitioners building the future of coding agent infrastructure.