musememory 2.2.0 → 2.3.0

package/.agents/context/current.md

@@ -1,7 +1,7 @@
 # 📍 Current Shipped State & Active Invariants
 
-> **Version**: `v2.1.0`  
-> **Status**: Production Release (P2P Sync, Studio, and Monorepo Mesh)
+> **Version**: `v2.3.0`  
+> **Status**: Feature Release (Autonomous Memory Optimizer, UI Dashboard Controls & Concurrent Multi-Agent Workstream Tracking)
 
 ---
 
@@ -34,6 +34,13 @@
 25. **Cross-Agent Knowledge Sync & P2P Gossip Protocol (R14)**: Portable sealed `SyncPacket` with SHA-256 integrity, vector clock causal ordering, bidirectional shared pool drop-directory gossip exchange, deduplication, Vibeguard secret scrubbing, and semantic contradiction tagging with mutual `conflict_ids`.
 26. **Full Web Observability Studio & Interactive Visual Dashboard (R15)**: Integrated web studio served over local HTTP (`memory studio`), featuring a 5-pillar health scorecard, overall letter grade, prioritized remediation action checklist, ADR registry with code-to-doc drift inspector, autonomous "Why" reasoner, bug friction clusters heatmap, debt hotspots, and live P2P mesh topology visualizer.
 27. **Multi-Repo & Monorepo Cross-Project Mesh (R16)**: Automatic workspace detection across pnpm, npm, bun, lerna, and multi-repo sibling groups; cross-project memory querying with origin package provenance; cross-package contract and entrypoint export auditing; explicit mesh linking (`mesh_links.json`); and shared invariant propagation across the entire mesh.
+28. **Unified Code & Memory Impact Analysis**: Pre-flight blast radius analysis evaluating AST callers, test suites, governing ADRs, negative warnings, and risk levels (`memory code-impact` / `muse_code_impact`).
+29. **PR & Change Context Generator**: Automatically turns git diffs into rich, memory-grounded GitHub PR descriptions linking touched anchors and active constraints (`memory pr-context` / `muse_pr_context`).
+30. **Interactive Code Anchor Reconciler**: Audits and repairs code anchors across memories, pruning dead references and updating structural hashes (`memory reconcile` / `muse_reconcile_anchors`).
+31. **Latency & Quality Telemetry Suite**: Benchmarks microsecond hot caches, FTS5 BM25 search, knapsack token packing, and ROI in a clean ASCII scoreboard (`memory benchmark`).
+32. **Linus-Style Architectural Hardening (v2.2.1)**: Elimination of shell command injection via `execFileSync`, concurrency-safe `PRAGMA busy_timeout = 5000` on SQLite WAL mode, O(N) stat storm elimination in `list(store)`, structured warnings on YAML dual-write failures, and tightened word-boundary/code-anchor ADR matching.
+33. **Autonomous Memory Optimizer & Auto-Cadence Engine (v2.3.0)**: Multi-factor noise and junk pruning engine with zero-daemon auto-cadence (every 7 days or after 48h idle), SQLite WAL defragmentation (`VACUUM;` + `PRAGMA optimize;`), CLI command `memory optimize`, and dashboard "⚡ Optimize" button.
+34. **Concurrent Multi-Agent Workstream Tracking & Clean `CURRENT.md` (v2.3.0)**: Live `AgentWorkstream` tracking table in `CURRENT.md` enabling multi-agent swarms across separate chat sessions to coordinate active tasks and target scopes; injected into prompt context (`formatPromptContext`, `resolveMuseContext`); sanitized single-pane executive summary for humans with strict grounding rules for agents.
 
 ---
 

package/.agents/context/product.md

@@ -93,7 +93,8 @@ memory audit [--limit 20]
 memory persona [developer|designer|marketer|casual]
 memory current --add "Must use Bun v1.2"
 
-# Diagnostics & Server
+# Diagnostics, Server & Optimization
+memory optimize [--dry-run] [--force] [--project core]
 memory doctor
 memory validate --dry-run
 memory mcp [--profile coding|review|architecture|core|full]

package/.agents/skills/muse-current/SKILL.md

@@ -5,7 +5,36 @@ description: Active working constraints and interruption-proof session handoff m
 
 # 📐 Muse Current (`muse-current`)
 
-> **When to use**: Execute when the user establishes a hard project invariant, when starting a multi-step task, or before context compaction/task switching to record in-flight handoffs.
+> **When to use**: Execute when the user establishes a hard project invariant, when starting a multi-step task, before context compaction/task switching, or when running multiple concurrent agents to record in-flight workstreams and prevent collisions.
+
+---
+
+## 🏛️ Operational Guidelines: Humans vs AI Agents
+
+| Persona | Purpose & Guidelines |
+| :--- | :--- |
+| **For Humans (Founders & Architects)** | Single-pane-of-glass executive dashboard of active project invariants, active handoffs, and active concurrent agent workstreams. **Strictly zero verbose logs, raw terminal dumps, or transcript noise.** |
+| **For AI Agents (Agency Council & Subagents)** | Mandatory grounding contract. Every agent must check `CURRENT.md` at session start (`get_context`) to respect active constraints, register its active task, and check what other parallel agents are modifying to avoid merge conflicts and race conditions. |
+
+---
+
+## 🤖 Concurrent Multi-Agent Coordination Protocol
+
+When multiple agents run simultaneously across different IDE windows or chat sessions, each agent registers its active scope in `CURRENT.md`:
+
+```markdown
+## 🤖 Active Concurrent Agent Workstreams
+| Agent / Session ID | Status | Active Task | Target Scope / Files | Last Active |
+| :--- | :--- | :--- | :--- | :--- |
+| `Agent-Sol` | [IN-PROGRESS] | Next.js API Rate Limiter | `src/api/rate-limit.ts` | 2026-09-03T08:50:00.000Z |
+| `Agent-Nexus` | [IN-PROGRESS] | SQLite WAL Hardening | `src/sqlite.ts` | 2026-09-03T08:51:00.000Z |
+```
+
+### Protocol Rules for Concurrent Agents:
+1. **Pre-flight Scope Audit**: Before editing files, inspect `## 🤖 Active Concurrent Agent Workstreams`. If another agent is actively modifying your target files, coordinate or isolate your work to avoid overwriting changes.
+2. **Workstream Registration**: On starting a multi-turn task, register your agent name, task title, and target file scope.
+3. **Automatic Handoff Sync**: When updating session progress via `checkpointSession` or `updateSessionHandoff`, your workstream row is automatically updated with your latest checkpoint timestamp.
+4. **Task Completion**: Upon finishing the task, mark your workstream `COMPLETED`. Completed entries are automatically pruned after 48 hours.
 
 ---
 
@@ -24,39 +53,40 @@ Call `memory_current` or `memory_capture(type="constraint")`:
 
 This immediately updates `.memory/CURRENT.md` and dual-persists a constraint memory in SQLite.
 
-### Step 2: Record Interruption-Proof Session Handoffs
-When completing a subtask, hitting context limits, or preparing for the next agent:
-Append a structured handoff block to `CURRENT.md`:
-
-```markdown
-## Active Handoff & Session Checkpoint
-- **Goal**: Migrate SQLite WAL connection pool to asynchronous microtask flushes.
-- **Completed**:
-  - Implemented async query worker in `src/sqlite/worker.ts`.
-  - Added unit test suite `test/sqlite_worker.test.ts`.
-- **In-Flight / Next Steps**:
-  - Wire worker into `src/store.ts` save transaction.
-  - Run full suite: `bun test`.
+### Step 2: Register & Checkpoint In-Flight Workstreams
+When starting a task or checkpointing progress:
+```json
+{
+  "action": "checkpoint",
+  "agent": "Sol",
+  "task": "Build OAuth2 Callback Handler",
+  "targetScope": "src/auth/*",
+  "progress": ["Added callback route", "Verified state nonce validation"]
+}
 ```
 
-### Step 3: Clear Resolved Invariants
+### Step 3: Clear Resolved Invariants & Prune Obsolete Rules
 When a temporary constraint or migration phase is complete, update `CURRENT.md` to prune obsolete rules so future context windows stay lightweight.
 
 ---
 
 ## 🛡️ Invariant Rules for Agents
 
-- **High Locality**: `CURRENT.md` must contain only active, high-priority invariants and current handoffs—not historical archives.
+- **High Locality**: `CURRENT.md` must contain only active, high-priority invariants, concurrent workstreams, and current handoffs—never historical terminal transcripts.
 - **Zero Hallucination**: Do not contradict constraints recorded in `CURRENT.md`.
+- **Zero File Collisions**: Always consult the active workstreams table before modifying shared codebase modules.
 
 ---
 
 ## 💻 CLI Equivalents (Zero-MCP Fallback)
 
 ```bash
-# Read active working constraints
+# Read active working constraints & concurrent workstreams
 memory current get
 
 # Append a new active constraint
 memory current set "- Hard constraint description" --project my-project
+
+# Run storage optimization (prunes test noise, junk fragments & defragments SQLite)
+memory optimize
 ```

package/README.md

@@ -13,7 +13,7 @@
 ![AST Graph](https://img.shields.io/badge/AST-CodeGraph_%26_Graphify-orange?style=for-the-badge&logo=diagram-project&logoColor=white)
 ![Architecture](https://img.shields.io/badge/Storage-Zero--Daemon_%2F_Local--First-0D9488?style=for-the-badge)
 
-![CI Tests](https://img.shields.io/badge/Tests-497%20Passed-brightgreen?style=for-the-badge&logo=checkmarx)
+![CI Tests](https://img.shields.io/badge/Tests-502%20Passed-brightgreen?style=for-the-badge&logo=checkmarx)
 ![Security](https://img.shields.io/badge/Security-Vibeguard_Zero--Leak-DC2626?style=for-the-badge&logo=shield)
 ![Agent Coverage](https://img.shields.io/badge/Agents-80+_Supported-4F46E5?style=for-the-badge&logo=openai)
 ![License](https://img.shields.io/badge/License-MIT-9333EA?style=for-the-badge)
@@ -24,60 +24,40 @@
 
 ---
 
-## 🚀 What's New in v2.2.0, v2.1.0 & v2.0.0 (Impact Analysis, PR Context, Reconciler & Telemetry)
-
-### 💥 v2.2.0 Flagship Additions: Code Impact, PR Context & Cognitive Governance
-- **💥 Unified Code & Memory Impact Analysis (`memory code-impact`)**:
-  - Synthesizes AST code callers, affected test suites, linked memories, living ADRs, negative anti-patterns, and active constraints.
-  - Computes a composite Risk Score (0–100) and Risk Level (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`) with pre-flight actionable recommendations before modifying code.
-  - Available via CLI `memory code-impact <file> [--symbol <name>]` and MCP tool `muse_code_impact`.
-- **📋 PR & Change Context Generator (`memory pr-context`)**:
-  - Automatically analyzes git diff against base branch, linking touched code anchors, respected ADRs, active project constraints, and blast radius.
-  - Generates rich GitHub-ready Markdown pull request descriptions with verification checklists and merge promotion proposals.
-  - Available via CLI `memory pr-context [--base main] [--out <file>]` and MCP tool `muse_pr_context`.
-- **⚓ Interactive Code Anchor Reconciler (`memory reconcile`)**:
-  - Audits code anchors across memories, pruning dead anchors, refreshing structural hashes for drifted code, and marking abandoned memories stale.
-  - Supports `--dry-run`, `--prune`, `--mark-stale`, `--update-hashes`, and MCP tool `muse_reconcile_anchors`.
-- **⚡ Repeatable Speed, Quality & ROI Benchmark Suite (`memory benchmark`)**:
-  - Measures microsecond in-process cache reads (P50 < 4µs), SQLite FTS5 BM25 search, knapsack token packing, contradiction rates, and compression ratios in a clean ASCII scoreboard.
-- **🧠 Complete Agent Skills Roster for v2.0–v2.2**:
-  - Added `.agents/skills/muse-health`, `muse-drift`, `muse-why`, `muse-sync`, and `muse-mesh`.
-
-### 🌟 v2.1.0 Flagship Additions: Multi-Agent & Mesh Orchestration
-- **🤝 Cross-Agent Knowledge Sync & P2P Gossip Protocol (R14)**:
-  - Cryptographically sealed, portable `SyncPacket` engine with whole-packet SHA-256 integrity verification and vector clock causal ordering.
-  - Zero-daemon shared filesystem gossip pool (`.memory/sync_pool/`) allowing autonomous subagent teams (frontend, backend, test) to exchange insights asynchronously.
-  - Ingestion deduplication, inline Vibeguard secret scrubbing, and semantic contradiction tagging with mutual `conflict_ids`.
-  - CLI `memory sync` command suite & 4 MCP tools (`muse_sync_broadcast`, `muse_sync_ingest`, `muse_sync_status`, `muse_sync_pool`).
-- **🌐 Full Web Observability Studio (`memory studio`) (R15)**:
-  - Embedded zero-dependency visual web dashboard (`memory studio` or `memory ui`) with interactive control plane.
-  - Live 5-pillar health scorecard (A–F letter grade, PASS/WARN/FAIL gate status, and prioritized remediation checklist).
-  - Interactive ADR registry and bidirectional documentation $\longleftrightarrow$ code drift inspector.
-  - Historical "Why" reasoner query interface, recurring bug friction heatmap, and debt scanner.
-  - Real-time P2P gossip mesh status and interactive broadcast/shared pool sync controls.
-- **🕸️ Multi-Repo & Monorepo Cross-Project Mesh (R16)**:
-  - Passive automatic monorepo discovery across `pnpm`, `npm`, `bun`, `lerna`, and multi-repo sibling directories.
-  - Cross-project memory query resolver (`resolveMeshMemories`) with origin package provenance tags (`[mesh:@scope/package]`).
-  - Shared invariant and working constraint propagation (`propagateConstraintToMesh`) broadcasting critical security rules across all packages.
-  - Cross-package dependency contract and entrypoint export auditor (`auditMeshContracts`) validating cross-package imports and cross-repo code anchors.
-  - CLI `memory mesh` suite & 4 MCP tools (`muse_mesh_status`, `muse_mesh_query`, `muse_mesh_audit`, `muse_mesh_link`).
-
-### 🧠 v2.0.0 Major Cognitive Overhaul:
-- **🏥 Unified 5-Pillar Project Health Gate (`memory health` / `muse_health`)**: Single-call architectural audit across Store Integrity, Code Anchors, Doc-Code Alignment, Negative Sentry, and Technical Debt.
-- **🤔 Autonomous Engineering Cognition & "Why" Reasoner (`muse_why`)**: Reconstructs historical code evolution through past bug workarounds, accepted trade-offs, and timeless rules before refactoring.
-- **🏛️ First-Class Architecture Decision Records (`memory adr` / `memory_adr_record`)**: Living, queryable ADR entities with options considered, consequences, native code anchors, and supersession lineage.
-- **🔄 Bidirectional Documentation $\longleftrightarrow$ Code Drift Engine (`memory_drift_audit`)**: Continuously verifies alignment across 6 states (`DOCUMENTED`, `IMPLEMENTED`, `PARTIAL`, `CONFLICTING`, `STALE`, `MISSING`).
-- **🎯 Flagship Unified Context Orchestrator (`muse_context`)**: Single-call fused context injection with knapsack token budget packing.
-- **⚙️ Task-Focused MCP Profiles**: Dynamic role-based tool filtering (`core`, `coding`, `debugging`, `review`, `architecture`, `maintenance`).
-- **⚓ Native Structural Code Anchors (`src/anchors/`)**: Line-independent structural SHA-256 hashing insensitive to spacing/comments.
-- **🪜 Scoped Promotion & Extended Archival Lifecycle (`src/promotion/`)**: 3-tier promotion ladder (`local` $\rightarrow$ `project` $\rightarrow$ `global`), 5× repeated success policy, universal generalization, and `active` $\rightarrow$ `cold` $\rightarrow$ `dormant` $\rightarrow$ `archived` lifecycle with query rehydration.
-- **⚡ Hot Query Cache & SQLite WAL Optimization**: Microsecond memory lookups and high-throughput concurrent I/O.
+## 🚀 What's New
+
+### v2.3.0
+- **Autonomous Memory Optimizer (`memory optimize`)**: High-precision noise and junk pruning engine with zero-daemon auto-cadence (every 7 days or after 48h idle) and SQLite WAL defragmentation (`VACUUM;` + `PRAGMA optimize;`).
+- **Dashboard "⚡ Optimize" Trigger**: Live visual optimization controls directly inside the Web Observability Studio (`memory ui` / `memory studio`) with real-time feedback on items pruned and bytes reclaimed.
+- **Concurrent Multi-Agent Workstream Tracking**: Live coordination table in `CURRENT.md` enabling multiple agents across parallel chats to monitor active tasks and target scopes without collisions.
+- **Clean Operational Guidelines**: Curated single-pane executive summary for humans and strict grounding/concurrency rules for AI agents.
+
+### v2.2.0
+- **Unified Code & Memory Impact Analysis**: Pre-flight blast radius analysis evaluating AST callers, test suites, governing ADRs, negative warnings, and risk levels (`memory code-impact` / `muse_code_impact`).
+- **PR & Change Context Generator**: Automatically turns git diffs into rich, memory-grounded GitHub PR descriptions linking touched anchors and active constraints (`memory pr-context` / `muse_pr_context`).
+- **Interactive Code Anchor Reconciler**: Audits and repairs code anchors across memories, pruning dead references and updating structural hashes (`memory reconcile` / `muse_reconcile_anchors`).
+- **Latency & Quality Telemetry Suite**: Benchmarks microsecond hot caches, FTS5 BM25 search, knapsack token packing, and ROI in a clean ASCII scoreboard (`memory benchmark`).
+- **Expanded Agent Skills**: Shipped turnkey skills for `muse-health`, `muse-drift`, `muse-why`, `muse-sync`, and `muse-mesh`.
+
+### v2.1.0
+- **Cross-Agent Knowledge Sync & P2P Gossip Protocol**: Sealed portable `SyncPacket` engine with SHA-256 integrity and zero-daemon shared filesystem gossip pool (`memory sync` / `muse_sync_*`).
+- **Web Observability Studio**: Embedded visual dashboard (`memory studio` / `memory ui`) with interactive 5-pillar health, ADR registry, code drift inspector, and sync controls.
+- **Monorepo & Multi-Repo Mesh**: Automatic workspace discovery (pnpm, npm, bun, lerna) with cross-project memory queries and shared constraint propagation (`memory mesh` / `muse_mesh_*`).
+
+### v2.0.0
+- **5-Pillar Project Health Gate**: Architectural health gate evaluating store integrity, code anchors, doc-code alignment, negative sentry, and technical debt (`memory health` / `muse_health`).
+- **Cognitive "Why" Reasoner**: Reconstructs historical code evolution, bug workarounds, and trade-offs before refactoring (`muse_why`).
+- **Living Architecture Decision Records (ADRs)**: Queryable ADRs with options, consequences, native code anchors, and supersession lineage (`memory adr` / `memory_adr_record`).
+- **Doc ⟷ Code Drift Engine**: Continuously audits documentation against AST code implementations across 6 drift states (`memory drift` / `memory_drift_audit`).
+- **Unified Context Orchestrator & MCP Profiles**: Single-call fused context injection with knapsack token packing (`muse_context`) and task-specific tool profiles.
+- **Native Structural Code Anchors**: Line-independent structural SHA-256 hashing for files, symbols, and routes.
+- **Scoped Promotion & Archival Lifecycle**: 3-tier promotion ladder (`local` → `project` → `global`) and cold/dormant/archived storage tiers.
 
 ---
 
 ## 📑 Table of Contents
 
-- [🚀 What's New in v2.1.0 & v2.0.0](#-whats-new-in-v210--v200-autonomous-cognitive-engine-p2p-sync--monorepo-mesh)
+- [🚀 What's New](#-whats-new)
 - [💡 What is Muse Memory? (TL;DR)](#-what-is-muse-memory-tldr)
 - [✨ Key Feature Highlights](#-key-feature-highlights)
 - [⚡ Quick Start & Installation](#-quick-start--installation)