musememory 3.0.0 → 3.0.2

package/docs/agent-reference.md

@@ -0,0 +1,199 @@
+# Agent Reference
+
+> **Audience**: AI coding agents. Human-readable narrative lives in
+> [`user-guide.md`](./user-guide.md) and the [README](../README.md); this file
+> is the exact contract — commands, flags, file layout, lifecycle states and
+> failure semantics — with no prose padding.
+>
+> **Machine-readable companions**:
+> - [`mcp-tool-matrix.json`](./mcp-tool-matrix.json) — the full list of registered MCP tools.
+> - [`../claims.json`](../claims.json) — every countable claim, generated from `src/`.
+> - `https://harshsinghmp.github.io/musememory/llms.txt` — the site, for agents.
+> - `https://harshsinghmp.github.io/musememory/llms-full.txt` — the site as plain text.
+
+---
+
+## 1. Install
+
+```bash
+npx musememory connect        # wire every detected coding agent over MCP
+```
+
+Requirements: Node.js >= 18 or Bun >= 1.2. No account, no API key, no
+configuration file, no background daemon. The package installs a single
+executable, `memory` (alias `musememory`).
+
+Equivalent explicit install:
+
+```bash
+npm install -g musememory     # or: bun add -g musememory
+```
+
+## 2. Where state lives
+
+| Path | Scope | Contents |
+| --- | --- | --- |
+| `.memory/` | project | `memory.db` (SQLite, WAL + FTS5), `memories/*.yaml`, `CURRENT.md`, `USER.md`, `observations.jsonl`, `audit.jsonl`, `sources.json`, `claims.json`, `sync_pool/`, `mesh_links.json` |
+| `~/.memory/` | global | Same layout. Project scope wins on conflict. |
+
+Both are plain files. There is no server, no port, and no service to keep
+alive. Delete the directory to delete the memory.
+
+## 3. Mandatory session protocol
+
+An agent integrating Muse must follow this order.
+
+1. **First turn of any session** — call `get_context`. It returns the `USER.md`
+   persona profile, the `CURRENT.md` active constraints, and the top-K ranked
+   memories relevant to the task, under one token budget.
+2. **Before editing** — if a hard constraint, invariant or open loop is
+   established or changed, record it with `memory_capture --type constraint` or
+   `memory_current set`.
+3. **After a fix or a decision** — call `memory_capture`. Capture is the
+   mechanism that makes the next session cheaper than this one.
+4. **When knowledge is replaced** — call `memory_supersede`, never `delete`.
+   Superseding keeps lineage; deleting loses the audit trail.
+
+`muse_context` is the higher-fidelity variant of `get_context`: it fuses
+constraints, ranked memories, negative lessons and code anchors, and is what
+task-shaped profiles (`coding`, `debugging`, `review`, `architecture`) expose.
+
+## 4. CLI
+
+```
+memory <command> [arguments] [options]
+```
+
+Full matrix: [`cli-reference.md`](./cli-reference.md).
+
+### Commands an agent uses most
+
+| Command | Purpose |
+| --- | --- |
+| `memory context [query] --token-budget N` | Top-ranked context for prompt injection. |
+| `memory search <query> --limit N` | Ranked multi-factor search with a score breakdown. |
+| `memory capture "<text>" --project P` | Persist a memory. Vibeguard-scanned and citation-verified. |
+| `memory propose "<text>" --project P` | Propose a candidate (does not auto-confirm). |
+| `memory confirm <id>` | Promote a candidate to confirmed. |
+| `memory supersede <old_id> --with <new_id>` | Replace outdated knowledge, preserving lineage. |
+| `memory current get` / `memory current set "<text>" --project P` | Read/write active constraints. |
+| `memory link <id> --related <id1,id2>` | Bidirectional relation between entries. |
+| `memory audit [--operation OP] [--entry-id ID]` | Query the append-only audit ledger. |
+| `memory doctor` | Full ecosystem health diagnostic. |
+| `memory harvest "<text>" --project P` | Distil a turn into a fix/decision unit. |
+| `memory verify <id> --strict` | Run an entry's verification command, or the full integrity gate. |
+
+### Global flags that change behaviour
+
+| Flag | Effect |
+| --- | --- |
+| `--project <name>` | Scopes a write to a project. Required by `capture`, `propose`, `harvest`. |
+| `--token-budget <n>` | Hard ceiling on returned tokens. The engine never exceeds it. |
+| `--limit <n>` | Maximum candidates. Clamped by the engine, not by the caller. |
+| `--global` | Operates on `~/.memory/` instead of `.memory/`. |
+| `--dry-run` | Required default for destructive operations; nothing is written. |
+| `--harness <name>` | Opt-in for harness-specific config paths (e.g. `claude` → `~/.claude*`). Without it, those paths are reported as skipped and nothing is written. |
+
+## 5. MCP
+
+The server speaks MCP over stdio. Protocol versions accepted:
+`2024-11-05`, `2025-06-18`.
+
+`claims.json` records the live totals; read them rather than trusting prose:
+
+| Claim | Source of truth |
+| --- | --- |
+| Registered tools | `docs/mcp-tool-matrix.json` |
+| Profiles | `src/orchestrator/profiles.ts` |
+| Agent platforms auto-wired | `src/agents/registry.ts` |
+| Import formats | `src/migrator/detect.ts` |
+| Credential rule families | `src/secrets.ts` |
+
+### Profiles
+
+Tools are exposed through task-focused profiles so an agent is never handed
+the whole surface. Select with `MUSE_MCP_PROFILE` or the server's `profile`
+argument.
+
+| Profile | Use it for |
+| --- | --- |
+| `core` | Minimal footprint: context injection and rapid capture. |
+| `coding` | Active development, code anchors, contextual fusion. |
+| `debugging` | Bug diagnosis, error resolution, observations, negative lessons. |
+| `review` | Code review, architectural audit, conflict verification. |
+| `architecture` | System design, promotions, entity wiki, tree indexing. |
+| `maintenance` | Repository health, deduplication, archival sweeps. |
+| `full` | Everything. |
+
+`muse_profile_list` returns the live profile→tool mapping.
+
+### Tools that are mandatory, optional, and forbidden
+
+| Kind | Tools |
+| --- | --- |
+| Must call on session start | `get_context` |
+| Use when state changes | `memory_capture`, `memory_current`, `memory_supersede`, `memory_confirm` |
+| Use for investigation | `search`, `memory_tree_search`, `muse_why`, `muse_code_impact` |
+| Use for governance | `memory_audit`, `memory_verify_strict`, `memory_drift_audit` |
+| Never available to a model | Anything that writes outside the store. There is no shell-execution tool. `memory verify` runs a **template-gated** command: only `bun test <relative test file>`, `bunx tsc --noEmit`, and `node --check <relative path>` are permitted, and nothing is executed outside those shapes. Refusals are audit-logged as `verify_refused`. |
+
+## 6. Memory lifecycle
+
+```
+propose → candidate → confirmed → superseded
+                ↘ stale → archived
+                ↘ rejected
+                ↘ conflicted (kept-both, resolved by supersede/historical/reject)
+                ↘ deleted (tombstone; restorable with `memory restore`)
+```
+
+- `confirmed` is the only state served by default.
+- `stale` entries decay; per-type half-lives are trust-tiered.
+- `deleted` is a tombstone (`deleted_at`, `deleted_by`), excluded from every
+  read path, restorable, and replayable from `audit.jsonl`.
+- `conflicted` keeps both sides. Resolution verbs: `supersede`, `historical`,
+  `reject`, `keep_both`.
+
+## 7. Trust gates
+
+| Gate | When | Behaviour on violation |
+| --- | --- | --- |
+| Secret scan (Vibeguard) | every write | The write is **refused** and the rule name is reported. Nothing is stored. |
+| Citation verification | every write with a code anchor | The write is **refused** under the default `fail_fast` policy if the cited file/symbol does not exist. Drift is flagged and stamped. |
+| Freshness gate | every recall | Memories whose anchors drifted are **withheld** and reported via `withheld_memories` + `freshness_notice`. They are never silently served. `include_drifted: true` returns them with a `⚠ FRESHNESS` provenance warning. |
+| Ingest sanitisation | import / harvest | Injected `<memory-context>` blocks and base64 payloads are stripped before the text is considered. |
+
+## 8. Failure semantics
+
+| Condition | Result |
+| --- | --- |
+| Secret detected | Write refused. Non-zero exit. Rule name only — never the value. |
+| Citation does not resolve | Write refused (`fail_fast`) or stamped as drifted (`warn` policy). |
+| `memory.db` schema version ahead of the binary | The read is refused; run `memory upgrade`. |
+| SQLite lock held longer than the busy timeout | The operation fails loudly. It does not silently skip the write. |
+| Store circuit breaker open (5 consecutive failures) | Degraded mode: reads fall back, writes are refused, and the state is reported. `memory doctor` shows it. |
+| Unknown MCP tool name | Tool-not-found error. Tool names are exact. |
+
+## 9. Constraints on the agent
+
+- **No shell execution from memory.** A stored memory can never cause an
+  arbitrary command to run. `memory verify` is template-gated.
+- **Paths are contained.** Wiki, PageIndex, pool and mesh paths are resolved
+  with `resolveWithin` (strict containment). `resolveExternal` is an explicit
+  opt-out for intentionally external directories.
+- **No network by default.** Semantic embeddings are opt-in and require an
+  explicitly configured endpoint. Everything else runs in-process.
+- **Writes are auditable.** Every write appends to `audit.jsonl` and the
+  tamper-evident hash chain.
+
+## 10. Verifying the installation
+
+```bash
+memory doctor            # storage, schemas, secrets, agent wiring
+memory health            # 5-pillar health gate, letter grade
+memory stats             # counts by status and type
+memory context --query "how does auth work" --budget 2000
+```
+
+A healthy install reports: SQLite reachable, schema version current, no
+secrets in the store, and the expected agents wired.

package/docs/cli-reference.md

@@ -0,0 +1,263 @@
+# CLI & MCP Reference
+
+> **Generated file** — produced by `scripts/generate-cli-reference.ts` from `src/cli.ts` and `src/mcp.ts`. Do not hand-edit: regenerate it after any CLI or MCP change (`bun run scripts/generate-cli-reference.ts`).
+
+This is the complete machine-facing surface. For narrative guidance see [`agent-reference.md`](./agent-reference.md); for the human walkthrough see [`user-guide.md`](./user-guide.md).
+
+## Command line
+
+```bash
+memory <command> [arguments] [options]   # alias: musememory
+```
+
+```
+Muse Memory (memory / musememory) -- Autonomous Persistent Memory for AI Agents & Agency Networks
+
+Usage:
+  memory <command> [arguments] [options]
+
+Core Memory Lifecycle Commands:
+  install [dir]                 Run interactive onboarding wizard & auto-wire installed agents
+  upgrade / update [--check]    Auto-fetch latest release, self-heal, and sync agent platforms
+  doctor [dir]                  Run comprehensive ecosystem health diagnostic
+  uninstall [agent] [--purge]   Disconnect agents and optionally purge .memory data
+  init [dir]                    Initialize .memory/ in workspace or current dir
+  capture <text> --project P    Capture new memory unit with Vibeguard secret inspection
+  propose <text> --project P    Propose a candidate memory entry
+  confirm <id>                  Promote candidate or stale memory to confirmed status
+  supersede <old_id> --with <new_id> Replace outdated knowledge with confirmed target
+  link <id> --related <id,...>  Link related memories bidirectionally
+  mark-stale <id> [--reason R]  Deprecate decaying knowledge
+  reject <id>                   Reject candidate entry
+  delete <id> [--reason R]      Tombstone entry (soft delete), log audit, restorable
+  restore <id> [--replay [--apply]]  Restore a tombstoned entry; --replay rebuilds content from audit.jsonl
+  list / ls [--status S] [--type T] [--project P] List memory entries with multi-field filtering
+  stats                         Display total memory counts and status/type distribution
+  stale [--days N]              List entries exceeding staleness policy
+  consolidate [--project P] [--dry-run]  Cluster confirmed memories into scene rollups
+  optimize [--dry-run] [--project P] [--force] Prune test noise, junk, duplicates & vacuum SQLite DB
+  trace <id> [--depth N]        Walk causal graph pathways from an entry (default depth 5)
+  loops                         Prioritized open-loop report: git state, stale candidates, constraints
+  nudge                         Proactive attention list: overdue/due-soon entries, stale-by-policy, open loops
+  routine run <name>            Execute a routine's steps from .memory/routines.yaml
+  routine install [name]        Print crontab line(s) for routines (user installs; no system mutation)
+  distill [--min-count N] [--dry-run]  Distill recurring fix patterns into .agents/skills/ folders
+  verify <id> [--timeout S] [--strict] Execute test_command or run full strict integrity gate
+  briefing [--limit N]          Executive summary of active and stale memories
+
+Evidence, Provenance & Cognitive Governance:
+  source [add|list|show]        Manage external documentation and URLs in provenance Source Ledger
+  claim [record|list|show]      Record verifiable claims with confidence tags ([RAW], [FETCH], [SEARCH], [INFER])
+  freeze --task <task> [--run-id R] Capture immutable execution snapshot with file inventory & sha-256 hashes
+  prompt [list|show|run <name>] Manage and run structured prompt templates with live context injection
+  rollup --period week|month|quarter Multi-scale temporal compounding & HOT.md working cache generation
+  loop [record|status|clear]    Gauntlet iteration ledger & plateau/regression detector
+
+Context & Retrieval Commands:
+  context [query] [--limit N] [--token-budget N] [--depth L1|L2|L3] [--tier 0|1|2] Top-ranked prompt context
+  search <query> [--limit N] [--token-budget N] [--hybrid] [--tree] Scored token retrieval (hybrid: vector+BM25, tree: hierarchical reasoning)
+  reindex                       Rebuild the local vector index (.memory/index.json) for hybrid search
+  embed [status|build|reindex]  Manage semantic embeddings (llama.cpp / OpenAI-compatible endpoint; opt-in)
+  recall [query]                Search active/confirmed memories with filters
+  search-transcript <query> [file.jsonl] [--window N] Full-text transcript search with bookends
+
+Wiki & Entity Knowledge Compounding:
+  wiki [compile|list|show]      Compile memories into structured Obsidian-compatible markdown wiki pages
+  extract-entities [--dry-run]  Extract named entities (persons, products, orgs, files, concepts) from memories
+  entities [list|show|related]  Inspect extracted knowledge graph entities and co-occurrences
+
+Persona, Settings & Constraints Commands:
+  settings [get|set|reset|export|import] Manage unified global and project configuration
+  user [get|init|set] [--global] Manage USER.md persona & working preferences
+  current [get|set]             Manage CURRENT.md active project constraints
+  core [tier] [--set T|--remove|--show] Manage CORE.md permanent partitions (identity|directives|conventions|context)
+
+Ecosystem, Migration & Connectivity:
+  connect [agent|all] [--force] [--with-hooks] [--harness H]
+                                 Auto-wire MCP into detected coding agents; --with-hooks also installs
+                                 the lifecycle hook pack (SessionStart/PostToolUse/Stop) into .agents/hooks.json;
+                                 --harness claude is the explicit opt-in for harness-specific paths like ~/.claude
+  agents / detect-agents        Scan workstation for detected coding agent platforms
+  detect                        Scan machine for external memory formats to migrate
+  migrate [--from P] [--all]    Ingest external memories with state preservation & secret scrubbing
+  learn / sync-chats [--confirm] Auto-discover and harvest memories from all agent chats across machine
+  harvest <file|text> --project P Distill conversation transcripts into structured memory units
+  harvest-auto [--from <glob>] [--project P] Harvest inbox transcripts as candidates and archive them
+  hook install --git            Install the harvester as a git pre-commit hook (never clobbers)
+  import-transcript <file.jsonl> Universal JSONL transcript ingestion with session binding
+  export [--out file.json]      Export portable JSON memory snapshot
+  import <file.json>            Import portable JSON memory snapshot
+  validate [--dry-run]          Validate YAML schemas and referential integrity
+  graph [status|index]          Inspect or index CodeGraph/Graphify AST provider symbols
+  ui / dashboard [--port 2222]  Launch embedded visual knowledge graph UI
+  daemon [--port N]             Real-time agency hub (SSE event stream + publish API, default port 7878)
+  sync [status|broadcast|ingest|pool] Cross-agent knowledge sync & P2P gossip mesh
+  mesh [query|check|link|unlink|propagate] Multi-repo & monorepo cross-project mesh
+  health                        Run unified 5-pillar architectural health evaluation
+  reconcile [--prune] [--stale] Reconcile orphaned & drifted code anchors across memories
+  benchmark [--iterations N]    Run microsecond speed, quality & token economy benchmark suite
+  code-impact <file> [--symbol] Synthesize code callers, ADRs, negative warnings & risk score
+  pr-context [--base B] [--out] Generate memory-verified PR description from git diff
+  mcp                           Run stdio MCP server for agent platforms
+
+Version Control (R23):
+  branch <id> --path <path> [--label L] Tag a memory with semantic dotted-path addressing
+  checkout <path|id>              Retrieve memory by mem_path or entry id
+  blame <id>                      Show access history & staleness metadata for a memory
+  ls-branches [--project P]       List all branch references
+```
+
+## MCP tools
+
+**115 tools** are registered, exposed through **7 task-focused profiles** (`core`, `coding`, `debugging`, `review`, `architecture`, `maintenance`, `full`). The authoritative machine-readable list is [`mcp-tool-matrix.json`](./mcp-tool-matrix.json).
+
+Select a profile with the `MUSE_MCP_PROFILE` environment variable. Call `muse_profile_list` for the live mapping.
+
+### Context & recall
+
+| Tool | Required parameters | Description |
+| --- | --- | --- |
+| `memory_read` | `id` | Read a full memory entry by id |
+| `get_context` | `query` | MANDATORY ON SESSION START: Fetch Top-K relevant memories, active user profile (USER.md), and active hard constraints (CURRENT.md) for prompt injection. MUST be called on the first turn of any task or session. |
+| `search` | `query` | Ranked search over memory entries |
+| `memory_recall` | `query` | Recall active and confirmed memories for a query, with verification levels and related graph links |
+| `memory_get_user_profile` | `content` | Read the active user profile and preferences (USER.md) |
+| `memory_search_transcripts` | `query`, `transcript` | Full-text search over conversation transcripts (.jsonl or text) with conversation bookends (start/end) and context window |
+| `memory_tree_search` | `query` | Hierarchical tree-indexed reasoning search across partitioned memory shards |
+| `memory_wiki_get` | `slug` | Read a compiled wiki page (concept, entity, index, or log) |
+| `memory_wiki_search` | `id` | List compiled wiki pages with optional filtering |
+| `memory_entities_get` | `id` | Get detailed information about an extracted entity and its relationships |
+| `memory_entities_search` | `content`, `project` | List extracted entities by type or project |
+| `memory_code_intel_status` | `query` | Inspect registered code intelligence providers and their workspace availability status |
+| `memory_code_intel_symbols` | `query` | Resolve symbols (functions, classes, types) across active code intelligence providers with fallback |
+| `memory_code_intel_blast_radius` | `target` | Calculate ripple effect and blast radius of modifying a symbol or file |
+| `memory_ranked_retrieval` | `query` | Multi-factor ranked retrieval fusing symbol matching, BM25, graph overlap, blast radius, recency, utility ROI, and negative warnings |
+| `muse_context` | `memory_id` | FLAGSHIP UNIFIED CONTEXT ORCHESTRATOR: Single-call fusion of active constraints, ranked memories, code anchors, and negative lessons under a strict token budget with actionable next steps. |
+| `muse_code_for_memory` | `memory_id` | Bidirectional lookup: Given a memory ID, return all anchored code references, files, and symbols |
+| `muse_memory_for_code` | `file_path` | Bidirectional lookup: Given a file path or symbol, return all associated memories, architectural decisions, bug fixes, constraints, and negative lessons |
+
+### Capture & lifecycle
+
+| Tool | Required parameters | Description |
+| --- | --- | --- |
+| `memory_capture` | `content` | Create a new memory entry with inline secret scan (refuses probable secrets). When type='constraint', automatically appends to CURRENT.md. |
+| `memory_current` | `action` | Read or append active working constraints and hard invariants in CURRENT.md for the active project |
+| `memory_get_constraints` | `query` | Read the active working constraints and hard invariants recorded in CURRENT.md for the active project |
+| `memory_set_constraints` | `query` | Append a working constraint or hard invariant to CURRENT.md for the active project |
+| `memory_harvest` | `id` | Distill conversation/text into structured outcome, fix, decision, and failure memories |
+| `memory_confirm` | `id` | Promote a candidate, disputed, or stale entry to confirmed |
+| `memory_supersede` | `id` | Mark old memory entry superseded by new confirmed memory entry |
+| `memory_lifecycle` | `verb`, `id` | T-084: Five-verb canonical memory lifecycle mutation (change, end, correct, revert, forget) |
+| `memory_link` | `id`, `related` | Two-way link related memory entries |
+| `memory_mark_stale` | `id` | Mark a memory entry stale |
+| `memory_reject` | `id` | Reject a memory entry |
+| `memory_delete` | `id` | Soft-delete a memory entry by single point ID (tombstone, reversible via memory_restore). Dry-run by default unless confirm: true or dry_run: false. |
+| `memory_restore` | `id` | Restore a tombstoned memory entry by ID. Fails on an unknown or never-deleted entry. Set replay=true to rebuild the content from the audit ledger when the row is gone, and apply=true to write it back |
+| `memory_audit` | `transcript` | Query the append-only audit trail of memory operations |
+| `memory_import_transcript` | `transcript` | Ingest a JSONL transcript or raw log into structured outcome and fix memories |
+| `memory_export` | `entries` | Export memory snapshot for agency team synchronization |
+| `memory_import` | `entries` | Import memory snapshot entries into the store |
+| `confirm_fix` | `id` | Confirm a disputed entry as fixed (disputed -> confirmed) |
+| `record_session` | `project` | Record a session start entry |
+| `memory_checkpoint` | `content` | Record a real-time progress checkpoint or task handoff to CURRENT.md to prevent loss on interruption |
+| `memory_validate` | `content` | Validate the memory store for schema violations, secrets, broken links, and integrity |
+| `memory_set_user_profile` | `content` | Update the user profile and preferences (USER.md) with inline secret scanning |
+| `memory_core` | `id` | Read or edit permanent core memory partitions (CORE.md) with tiers: identity, directives, conventions, context |
+| `memory_consolidate` | `id` | Cluster confirmed memories into scene rollup entries (architecture summaries linked to members); idempotent |
+| `memory_trace` | `id` | Walk causal pathways (supersedes/superseded_by + related links) from a memory entry as a cycle-safe tree |
+| `memory_loops` | `id` | Read-only prioritized open-loop report: uncommitted git changes, unmerged branches, stale candidates, disputed entries, and CURRENT.md constraints |
+| `memory_distill` | `id` | Distill recurring confirmed fix patterns into .agents/skills/<slug>/SKILL.md folders (never overwrites existing skills) |
+| `memory_distill_route` | `id` | Multi-channel knowledge distillation router: triages memories across system (rules/fixes), content (architecture concepts), and health (contradictions/staleness) lanes with deduplication |
+| `memory_verify` | `id` | Verification oracle: execute a fix entry's test_command; exit 0 promotes candidates to confirmed and stamps independently-verified |
+| `memory_settings_get` | `settings` | Read unified global or project configuration settings |
+| `memory_settings_set` | `settings` | Update unified global or project configuration settings |
+| `memory_compress` | `text` | Compress formatted prompt context losslessly, stripping header whitespace and boilerplate while preserving all architectural facts. |
+| `memory_source_add` | `url`, `title` | Record external documentation, research paper, RFC, or URL into the provenance Source Ledger |
+| `memory_source_list` | `claim` | List recorded external sources in the Source Ledger |
+| `memory_claim_record` | `claim` | Record an evidence-backed claim into the Claim Ledger connected to sources and confidence tags ([RAW], [FETCH], [SEARCH], [INFER]) |
+| `memory_claim_list` | `task` | List recorded claims in the Claim Ledger |
+| `memory_freeze_run` | `task` | Capture an immutable execution snapshot (active task, file inventory, git SHA, CURRENT constraints, memory SHA-256 hashes) in .memory/runs/<run-id>/ |
+| `memory_freeze_list` | `name` | List recorded frozen execution snapshots in .memory/runs/ |
+| `memory_prompt_list` | `name` | List available structured prompt templates in .memory/prompts/ |
+| `memory_prompt_get` | `name` | Get prompt template by name |
+| `memory_prompt_run` | `name` | Render prompt template with variable substitution and live memory context injection |
+| `memory_rollup` | `period` | Multi-scale temporal compounding: aggregate atomic memories into weekly, monthly, or quarterly synthesis wiki pages and update HOT.md cache |
+| `memory_loop_record` | `iteration_index`, `critic_verdict`, `largest_fix_identified`, `test_results` | Record an iteration round in the multi-agent Gauntlet Iteration Ledger (.memory/iterations.jsonl) |
+| `memory_loop_status` | `memory_id`, `success` | Inspect multi-round iteration status, plateau warnings, and regression signals |
+| `memory_verify_strict` | `memory_id`, `success` | Execute Strict Integrity & Health Gate: audits zero secrets, referential link integrity, wikilinks, orphaned candidates, and claim sources |
+| `memory_feedback` | `memory_id`, `success` | Record application outcome for a memory (success, failure, or regression) to train utility and calculate memory ROI |
+| `memory_resolve_conflict` | `winning_id`, `losing_id`, `strategy`, `reason` | Resolve a contradiction between two memories using a deterministic strategy (supersede, historical, reject, or keep_both) |
+| `memory_roi` | `raw`, `source`, `project` | Calculate memory utility, reuse success rates, and return-on-investment across the store |
+| `memory_observe` | `raw`, `source`, `project` | Ingest an ephemeral raw observation (tool output, test error, build log, review feedback) to .memory/observations.jsonl |
+| `memory_distill_observations` | `project` | Distill unprocessed raw observations into structured candidate memories and negative lessons |
+| `memory_negative_capture` | `title`, `failed_approach`, `failure_reason`, `project` | Record a first-class negative memory (DO_NOT_USE, FAILED_APPROACH, BUG_PRONE_PATTERN) to prevent recurring mistakes |
+| `memory_enrich` | `id` | Enrich an existing memory entry with code intelligence symbol evidence |
+| `memory_compaction_check` | `used_tokens` | Evaluate context usage against the 70% threshold and prompt if compaction is needed |
+| `memory_compact_handoff` | `high_level_goal`, `current_architecture`, `completed_tasks`, `open_tasks`, `next_concrete_task` | Lock the 5 mandatory invariants and write an interruption-proof session handoff to CURRENT.md before context reset |
+| `memory_harvest_turn` | `text`, `project` | Continuous conversational harvester: automatically extract architectural decisions, fixes, and negative lessons from turn text |
+| `memory_evaluate_promotion` | `id` | Evaluate a memory entry for promotion along the ladder: LOCAL -> PROJECT -> GLOBAL (5x success rule, zero regressions, zero conflicts, generalization) |
+| `memory_promote` | `id` | Execute promotion of a memory entry (LOCAL -> PROJECT or PROJECT -> GLOBAL) with generalization and audit logging. Can optionally stage in pending tier for session-end flush. |
+| `memory_flush_pending` | `id` | Two-tier promotion protocol (T-107): Flushes staged pending promotions at session close or manual trigger, executing promotion for qualifying entries. |
+| `memory_curate` | `id` | Curator protocol (T-106): appends empirical evidence or application outcomes to an existing memory. Deterministic promotion rules evaluate eligibility and trigger promotion when criteria are satisfied. |
+| `memory_generalize` | `content` | Test and preview generalization of memory content: scrubs project-specific paths and extracts universal principles |
+| `memory_archive` | `id`, `tier`, `reason` | Transition a memory entry to cold, dormant, or archived tier with reason |
+| `memory_rehydrate` | `id` | Restore an archived, dormant, or cold memory back to active/confirmed status upon relevance |
+| `memory_lifecycle_status` | `memory_id`, `file_path` | Inspect store-wide memory lifecycle metrics: counts across active, cold, dormant, archived, scopes, and promotion readiness |
+
+### Code anchors, drift & decisions
+
+| Tool | Required parameters | Description |
+| --- | --- | --- |
+| `memory_pageindex_index` | `content`, `project` | Build a PageIndex-style hierarchical tree index from document/text for reasoning-based retrieval |
+| `memory_pageindex_search` | `query` | Search a PageIndex tree index with reasoning-based retrieval |
+| `memory_pageindex_import` | `query`, `project` | Import PageIndex search results/insights as memory entries |
+| `memory_disconnect_pageindex` | `settings` | Disconnect PageIndex MCP tools and remove associated indexes |
+| `memory_drift` | `text` | Scan the local Git workspace for modified or deleted code files and AST symbols referenced by memories. Flags drifted memories for re-verification or supersession. |
+| `memory_anchor_create` | `memory_id`, `file_path` | Create and attach a line-independent structural code anchor to a memory entry (repository, file, module, symbol, route, test) |
+| `memory_anchor_verify` | `memory_id` | Verify all code anchors attached to a memory entry against the live codebase to detect drift or orphaned references |
+| `memory_anchor_audit` | `memory_id` | Run repository-wide audit of all code anchors across all memories: reports integrity score, valid, drifted, and orphaned counts |
+| `memory_adr_record` | `title`, `context_and_drivers`, `decision`, `consequences` | Record a first-class Architecture Decision Record (ADR) as an active, queryable memory with drivers, decision, consequences, options, and code anchors |
+| `memory_adr_list` | `target` | List all Architecture Decision Records (ADRs) recorded in the memory store, optionally filtered by status |
+| `memory_drift_audit` | `target` | Run bidirectional documentation <-> code drift audit: verifies if documented decisions are implemented in code and flags missing/stale/conflicting code or docs |
+| `muse_why` | `target` | Autonomous Engineering Cognition: Explain WHY code was designed or modified the way it is by tracing historical bug fixes, ADRs, trade-offs, and invariants |
+| `muse_bug_clusters` | `packet` | Analyze and cluster recurring bug fixes, negative lessons, and failures into architectural fragility hotspots with root-cause hypotheses |
+| `muse_tech_debt` | `packet` | Scan repository and memory store for technical debt indicators (TODO/FIXME/HACK, unsafe 'as any' casts, drifted code anchors) and generate refactoring priorities |
+| `muse_health` | `packet` | Unified 5-Pillar Project Health Gate: audit memory store integrity, code anchor validity, documentation drift, anti-pattern sentry, and technical debt with overall grade (A-F) and pass/fail gate status |
+| `muse_code_impact` | `file_path` | Evaluates comprehensive code and memory impact before editing: callers, test suites, ADRs, negative warnings, active constraints, and composite risk level |
+| `muse_pr_context` | — | Generates rich GitHub PR descriptions from git diff linking touched code anchors, respected ADRs, tested invariants, and composite risk assessment |
+| `muse_reconcile_anchors` | — | Interactively audits, prunes, or updates drifted and orphaned code anchors across memories when code is refactored or deleted |
+
+### Knowledge compounding
+
+| Tool | Required parameters | Description |
+| --- | --- | --- |
+| `memory_wiki_compile` | `id` | Compile confirmed memories into structured wiki markdown pages |
+
+### Sync, mesh & team
+
+| Tool | Required parameters | Description |
+| --- | --- | --- |
+| `muse_sync_broadcast` | `packet` | Exports a portable, signed SyncPacket containing confirmed memories, active constraints, and supersessions for P2P gossip sync across peer agents |
+| `muse_sync_ingest` | `packet` | Ingests a peer agent's SyncPacket with Vibeguard secret inspection, deduplication, and contradiction resolution |
+| `muse_sync_status` | `path` | Inspects peer synchronization status, known peer agents, vector clocks, and pending outgoing knowledge |
+| `muse_sync_pool` | `path` | Performs two-way P2P gossip synchronization with an in-process filesystem shared pool folder |
+| `muse_mesh_status` | `path` | Inspects multi-repo and monorepo cross-project mesh topology, workspace type, and discovered package stores |
+| `muse_mesh_query` | `path` | Queries memories across the entire monorepo or multi-repo cross-project mesh with origin package provenance |
+| `muse_mesh_audit` | `path` | Audits monorepo cross-package dependency contracts, entrypoint exports, and cross-repo code anchors |
+| `muse_mesh_link` | `path` | Explicitly links or unlinks an external repository or package directory path into the project mesh |
+
+### Onboarding & environment
+
+| Tool | Required parameters | Description |
+| --- | --- | --- |
+| `memory_detect_providers` | `entries` | Scan the machine and local workspace for existing external memory systems (24+ providers) |
+| `memory_detect_agents` | `entries` | Scan the machine for installed coding agents (Claude Code, Cursor, Hermes, OpenCode, OpenClaw, Codex, etc.) |
+| `memory_connect` | `entries` | Auto-wire Muse Memory MCP into installed coding agents or a specified agent |
+| `memory_migrate` | `entries` | Auto-detect and migrate memories from external providers preserving active/superseded state |
+| `graph_status` | `query` | Check the status of the project graph provider (e.g. codegraph) |
+| `graph_index` | `query` | Index AST symbols from the project's CodeGraph/Graphify provider and cache in .memory/ |
+| `muse_profile_list` | `title`, `context_and_drivers`, `decision`, `consequences` | List all available task-focused MCP profiles (core, coding, debugging, review, architecture, maintenance, full) and their exposed tools |
+
+---
+
+Counts in this file are generated from the same source as [`claims.json`](../claims.json): 115 tools, 7 profiles, 30 import formats, 8 credential rule families.

package/docs/mcp-tool-matrix.json

@@ -0,0 +1,121 @@
+{
+  "$comment": "Generated by scripts/generate-claims.ts — the authoritative MCP tool list.",
+  "count": 115,
+  "tools": [
+    "confirm_fix",
+    "get_context",
+    "graph_index",
+    "graph_status",
+    "memory_adr_list",
+    "memory_adr_record",
+    "memory_anchor_audit",
+    "memory_anchor_create",
+    "memory_anchor_verify",
+    "memory_archive",
+    "memory_audit",
+    "memory_capture",
+    "memory_checkpoint",
+    "memory_claim_list",
+    "memory_claim_record",
+    "memory_code_intel_blast_radius",
+    "memory_code_intel_status",
+    "memory_code_intel_symbols",
+    "memory_compact_handoff",
+    "memory_compaction_check",
+    "memory_compress",
+    "memory_confirm",
+    "memory_connect",
+    "memory_consolidate",
+    "memory_core",
+    "memory_curate",
+    "memory_current",
+    "memory_delete",
+    "memory_detect_agents",
+    "memory_detect_providers",
+    "memory_disconnect_pageindex",
+    "memory_distill",
+    "memory_distill_observations",
+    "memory_distill_route",
+    "memory_drift",
+    "memory_drift_audit",
+    "memory_enrich",
+    "memory_entities_get",
+    "memory_entities_search",
+    "memory_evaluate_promotion",
+    "memory_export",
+    "memory_feedback",
+    "memory_flush_pending",
+    "memory_freeze_list",
+    "memory_freeze_run",
+    "memory_generalize",
+    "memory_get_constraints",
+    "memory_get_user_profile",
+    "memory_harvest",
+    "memory_harvest_turn",
+    "memory_import",
+    "memory_import_transcript",
+    "memory_lifecycle",
+    "memory_lifecycle_status",
+    "memory_link",
+    "memory_loop_record",
+    "memory_loop_status",
+    "memory_loops",
+    "memory_mark_stale",
+    "memory_migrate",
+    "memory_negative_capture",
+    "memory_observe",
+    "memory_pageindex_import",
+    "memory_pageindex_index",
+    "memory_pageindex_search",
+    "memory_promote",
+    "memory_prompt_get",
+    "memory_prompt_list",
+    "memory_prompt_run",
+    "memory_ranked_retrieval",
+    "memory_read",
+    "memory_recall",
+    "memory_rehydrate",
+    "memory_reject",
+    "memory_resolve_conflict",
+    "memory_restore",
+    "memory_roi",
+    "memory_rollup",
+    "memory_search_transcripts",
+    "memory_set_constraints",
+    "memory_set_user_profile",
+    "memory_settings_get",
+    "memory_settings_set",
+    "memory_source_add",
+    "memory_source_list",
+    "memory_supersede",
+    "memory_trace",
+    "memory_tree_search",
+    "memory_validate",
+    "memory_verify",
+    "memory_verify_strict",
+    "memory_wiki_compile",
+    "memory_wiki_get",
+    "memory_wiki_search",
+    "muse_bug_clusters",
+    "muse_code_for_memory",
+    "muse_code_impact",
+    "muse_context",
+    "muse_health",
+    "muse_memory_for_code",
+    "muse_mesh_audit",
+    "muse_mesh_link",
+    "muse_mesh_query",
+    "muse_mesh_status",
+    "muse_pr_context",
+    "muse_profile_list",
+    "muse_reconcile_anchors",
+    "muse_sync_broadcast",
+    "muse_sync_ingest",
+    "muse_sync_pool",
+    "muse_sync_status",
+    "muse_tech_debt",
+    "muse_why",
+    "record_session",
+    "search"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musememory",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Autonomous, self-organizing cognitive memory system for AI agents and agency networks",
   "main": "dist/index.js",
   "type": "module",
@@ -15,12 +15,19 @@
     "site:build": "bun run --cwd apps/website build",
     "site:preview": "bun run --cwd apps/website preview",
     "site:showreel": "bun run --cwd apps/website scripts/build-showreel.ts",
+    "site:brand": "bun run --cwd apps/website brand",
+    "site:audit:a11y": "bun run --cwd apps/website scripts/audit-a11y.ts",
+    "site:audit:visual": "bun run --cwd apps/website scripts/audit-visual.ts",
     "build:gif": "bun run --cwd apps/website scripts/build-readme-gif.ts",
+    "claims:generate": "bun scripts/generate-claims.ts && bun scripts/generate-cli-reference.ts",
+    "claims:check": "bun scripts/generate-claims.ts --check",
+    "docs:check": "bun scripts/check-doc-links.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
     "validate": "bun run dist/index.js validate --dry-run",
     "start": "bun run dist/index.js mcp",
-    "prepublishOnly": "bun run build && bun test"
+    "prepublishOnly": "bun run build && bun test",
+    "site:qa": "bun run --cwd apps/website scripts/qa-gate.ts"
   },
   "bin": {
     "memory": "dist/index.js",
@@ -31,6 +38,10 @@
     "skills",
     ".agents",
     "schema.json",
+    "claims.json",
+    "docs/agent-reference.md",
+    "docs/cli-reference.md",
+    "docs/mcp-tool-matrix.json",
     "README.md",
     "LICENSE",
     "package.json"

package/schema.json

@@ -93,6 +93,7 @@
       "additionalProperties": false
     },
     "fingerprint": { "type": "string" },
+    "stale_embedder": { "type": "boolean" },
     "temporal_mode": { "type": "string", "enum": ["current", "historical", "timeless"] },
     "quality": { "type": "string", "enum": ["LOW", "MEDIUM", "HIGH", "VERIFIED", "CONFLICTED", "STALE"] },
     "utility": {