musememory 3.2.0 → 3.4.0

package/docs/agent-reference.md

@@ -39,6 +39,13 @@ npm install -g musememory     # or: bun add -g musememory
 Both are plain files. There is no server, no port, and no service to keep
 alive. Delete the directory to delete the memory.
 
+The per-entry `memories/*.yaml` mirror is the export/rollback copy of SQLite. It
+is written eagerly by default; set `MUSE_YAML_MIRROR=0` (or pass
+`yamlMirror: false` to `openStore`) to skip it when the store is only read
+through this engine. SQLite stays authoritative either way. The WAL is bounded
+to a 2 MiB autocheckpoint interval and a 64 MiB journal size limit, and
+`memory io` reports the current footprint.
+
 ## 3. Mandatory session protocol
 
 An agent integrating Muse must follow this order.
@@ -207,7 +214,9 @@ propose → candidate → confirmed → superseded
 - **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.
+  tamper-evident hash chain. At 5 MiB the active file rolls into
+  `audit-archive/`; the chain continues across segments, and pruning records an
+  anchor hash so `verifyAuditChain` still validates the retained window.
 
 ## 10. Verifying the installation
 

package/docs/cli-reference.md

@@ -33,6 +33,7 @@ Core Memory Lifecycle Commands:
   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
+  io [--json]                   Process read/write counters and on-disk store usage
   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
@@ -44,6 +45,10 @@ Core Memory Lifecycle Commands:
   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
+  test-feedback --command C --exit-code N [--memory ID,...]  Reinforce/penalize applied memories from a real test run
+  sentry --command C --exit-code N [--input F|-]  Read-only regression sentry against negative memories
+  flaky [--json]                Flaky tests, failure bursts and dependency-file drift from recorded runs
+  remediation [--apply]         Synthesize reusable playbooks from recurring, resolved test failures
 
 Evidence, Provenance & Cognitive Governance:
   source [add|list|show]        Manage external documentation and URLs in provenance Source Ledger
@@ -59,6 +64,8 @@ Context & Retrieval Commands:
   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
+  preflight [files...]           Speculative context for the files being edited
+  project [name]                 Show or set the configured project identity
   search-transcript <query> [file.jsonl] [--window N] Full-text transcript search with bookends
 
 Wiki & Entity Knowledge Compounding:
@@ -97,8 +104,9 @@ Ecosystem, Migration & Connectivity:
   conflicts [--dry-run]        Inspect recorded contradictions; --dry-run previews what would be flagged
   reconcile [--prune] [--stale] Reconcile orphaned & drifted code anchors across memories
   benchmark [--iterations N]    Run microsecond speed, quality & token economy benchmark suite
+  playbook [--list|--tag T|<id>] [--success|--fail] Procedural playbooks: list, inspect or record an outcome
   scan-secrets [dir] [--json]   Native Vibeguard secret scanner (zero external dependencies)
-  terrain [--out file.md]       Collect machine hardware, toolchain & agent ecosystem map
+  terrain [--workspace] [--out]  Machine terrain, or --workspace for the six workspace maps
   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
@@ -112,7 +120,7 @@ Version Control (R23):
 
 ## 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).
+**126 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.
 
@@ -223,12 +231,12 @@ Select a profile with the `MUSE_MCP_PROFILE` environment variable. Call `muse_pr
 | `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_bug_clusters` | — | Analyze and cluster recurring bug fixes, negative lessons, and failures into architectural fragility hotspots with root-cause hypotheses |
+| `muse_tech_debt` | — | 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` | — | 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 |
+| `muse_pr_context` | `command`, `exit_code` | Generates rich GitHub PR descriptions from git diff linking touched code anchors, respected ADRs, tested invariants, and composite risk assessment |
+| `muse_reconcile_anchors` | `command`, `exit_code` | Interactively audits, prunes, or updates drifted and orphaned code anchors across memories when code is refactored or deleted |
 
 ### Knowledge compounding
 
@@ -261,6 +269,22 @@ Select a profile with the `MUSE_MCP_PROFILE` environment variable. Call `muse_pr
 | `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 |
 
+### Other
+
+| Tool | Required parameters | Description |
+| --- | --- | --- |
+| `muse_preflight` | — | Read-only pre-flight: anchored invariants, blast-radius risk and a token-budgeted context pack for the files about to be edited |
+| `muse_episodes` | `packet` | Recall recent episodic narratives (goal → hypothesis → trajectory → verification → retrospective) built from observations |
+| `muse_playbook_recall` | `packet` | Recall procedural playbooks: list by tag, or fetch one by id/title |
+| `muse_playbook_record` | `packet` | Save a playbook trajectory, or record success/failure for an existing playbook |
+| `memory_test_feedback` | `command`, `exit_code` | Bind a real test run to the memories that were applied: green runs reinforce them, red runs record a failed application and a regression strike for anchor-relevant memories. Returns the parsed run plus regression-sentry matches. |
+| `muse_regression_sentry` | `client` | Read-only: match failing tests against recorded BUG_PRONE_PATTERN / DO_NOT_USE / failed-approach memories and return remediation playbooks |
+| `muse_flaky_tests` | `client` | Read-only: flaky tests, failure bursts and dependency-file drift derived from recorded test_feedback runs |
+| `muse_remediation_playbooks` | `client` | Read-only: synthesize remediation playbook candidates from recurring, resolved test failures (nothing is persisted) |
+| `muse_enclave_recall` | `client` | Read-only: decrypt and return entries from one client enclave vault. Requires an explicit client; every read is audit-logged. |
+| `muse_overlay_status` | `public_key` | Read-only: list branch memory overlays and their entry counts, or inspect one branch overlay's entries |
+| `muse_attestation_verify` | `public_key` | Read-only: verify an Ed25519 packet attestation or an attestation chain against an inline public key |
+
 ---
 
-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.
+Counts in this file are generated from the same source as [`claims.json`](../claims.json): 126 tools, 7 profiles, 30 import formats, 8 credential rule families.

package/docs/mcp-tool-matrix.json

@@ -1,6 +1,6 @@
 {
   "$comment": "Generated by scripts/generate-claims.ts — the authoritative MCP tool list.",
-  "count": 115,
+  "count": 126,
   "tools": [
     "confirm_fix",
     "get_context",
@@ -88,6 +88,7 @@
     "memory_source_add",
     "memory_source_list",
     "memory_supersede",
+    "memory_test_feedback",
     "memory_trace",
     "memory_tree_search",
     "memory_validate",
@@ -96,19 +97,29 @@
     "memory_wiki_compile",
     "memory_wiki_get",
     "memory_wiki_search",
+    "muse_attestation_verify",
     "muse_bug_clusters",
     "muse_code_for_memory",
     "muse_code_impact",
     "muse_context",
+    "muse_enclave_recall",
+    "muse_episodes",
+    "muse_flaky_tests",
     "muse_health",
     "muse_memory_for_code",
     "muse_mesh_audit",
     "muse_mesh_link",
     "muse_mesh_query",
     "muse_mesh_status",
+    "muse_overlay_status",
+    "muse_playbook_recall",
+    "muse_playbook_record",
     "muse_pr_context",
+    "muse_preflight",
     "muse_profile_list",
     "muse_reconcile_anchors",
+    "muse_regression_sentry",
+    "muse_remediation_playbooks",
     "muse_sync_broadcast",
     "muse_sync_ingest",
     "muse_sync_pool",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musememory",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Autonomous, self-organizing cognitive memory system for AI agents and agency networks",
   "main": "dist/index.js",
   "type": "module",
@@ -10,6 +10,7 @@
   ],
   "scripts": {
     "bench:graph": "bun scripts/bench-graph.ts",
+    "agents:terrain": "bun run bin/musememory.ts terrain --workspace --out .agents/terrain",
     "build": "bun build bin/musememory.ts --outfile dist/index.js --target node",
     "site:dev": "bun run --cwd apps/website dev",
     "site:build": "bun run --cwd apps/website build",

package/schema.json

@@ -15,6 +15,7 @@
     "salience": { "type": "number", "minimum": 0, "maximum": 1 },
     "created_at": { "type": "string", "format": "date-time" },
     "updated_at": { "type": "string", "format": "date-time" },
+    "asserted_at": { "type": "string", "format": "date-time" },
     "valid_from": { "type": "string", "format": "date-time" },
     "valid_to": { "type": "string", "format": "date-time" },
     "valid_to_exact": { "type": "boolean" },