musememory 2.0.0 → 2.2.0

package/.agents/context/architecture.md

@@ -65,7 +65,8 @@ musememory/
 │   ├── harvester.ts        # Universal agent transcript discovery and auto-learner engine
 │   ├── intelligence/       # Pluggable code intelligence providers (CodeGraph, Graphify, LSP, AST)
 │   ├── learning/           # Observation, candidate distillation, negative anti-patterns
-│   ├── mcp.ts              # Model Context Protocol stdio server (61 tools with profiles)
+│   ├── mcp.ts              # Model Context Protocol stdio server (69 tools with profiles)
+│   ├── mesh/               # Multi-repo & monorepo workspace discovery, query resolver, contracts
 │   ├── orchestrator/       # Flagship muse_context fusion, bidirectional lookups, MCP profiles
 │   ├── promotion/          # 3-tier promotion ladder, 5x success rule, archival lifecycle
 │   ├── quality/            # Deduplication, semantic contradiction engine, utility & ROI
@@ -74,12 +75,14 @@ musememory/
 │   ├── schema.ts           # JSON Schema & store referential validator
 │   ├── secrets.ts          # Vibeguard zero-leakage secret scanner & redactor
 │   ├── store.ts            # Dual-scope storage layout & lifecycle state machine
+│   ├── sync/               # Cross-agent knowledge sync, P2P gossip protocol, shared pool
 │   ├── transcript.ts       # Universal JSONL parser, dialogue windowing & search
 │   ├── types.ts            # Core TypeScript interfaces & enums
+│   ├── ui.ts               # Full Web Observability Studio & 3D knowledge graph
 │   ├── user.ts             # Persona & working preference engine
 │   ├── agents/             # Workstation coding agents detection & registry (80+ platforms)
 │   └── migrator/           # Multi-provider auto-detection & migration engine (24+ formats)
-├── test/                   # Automated Vitest/Bun test suites (480 tests across 79 suites)
+├── test/                   # Automated Bun test suites (498 tests across 81 suites)
 ├── package.json            # Package metadata & dependencies (v2.0.0)
 └── dist/                   # Compiled Node/Bun bundle
 ```

package/.agents/context/current.md

@@ -1,7 +1,7 @@
 # 📍 Current Shipped State & Active Invariants
 
-> **Version**: `v2.0.0`  
-> **Status**: Production Release (Autonomous Cognitive Engine Overhaul)
+> **Version**: `v2.1.0`  
+> **Status**: Production Release (P2P Sync, Studio, and Monorepo Mesh)
 
 ---
 
@@ -31,6 +31,9 @@
 22. **First-Class Architecture Decision Records (ADRs) & Bidirectional Drift Engine**: ADRs as living memory entities (`proposed`, `accepted`, `superseded`, `rejected`) with native code anchors and supersession lineage; bidirectional documentation ↔ code drift engine classifying alignment (`DOCUMENTED`, `IMPLEMENTED`, `PARTIAL`, `CONFLICTING`, `STALE`, `MISSING`) and scoring repository health.
 23. **Autonomous Engineering Cognition & "Why" Reasoner**: Historical "Why" explanation engine synthesizing ADRs, bug fixes, trade-offs, and invariants; recurring bug and fragility clustering across 5 root causes; and technical debt scanner detecting TODOs/FIXMEs, `as any` type bypasses, and drifted anchors.
 24. **Unified 5-Pillar Project Health Gate (`muse_health`)**: Comprehensive architectural health evaluation auditing store integrity, native code anchors, doc/code alignment, anti-pattern sentry, and technical debt; computes composite grade (A-F), gate status (PASS/WARN/FAIL), prioritized remediation checklist, and CLI dashboard.
+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.
 
 ---
 

package/.agents/context/product.md

@@ -31,6 +31,12 @@ Muse Memory is a zero-daemon, file-backed cognitive memory engine designed to gi
 | `memory_promote_scope` | **Scoped Promotion** | Promotes memory along 3-tier ladder (`local` $\rightarrow$ `project` $\rightarrow$ `global`) with 5× repeated success policy and universal generalization. |
 | `memory_archive` / `rehydrate` | **Archival Lifecycle** | Evaluates and manages `active` $\rightarrow$ `cold` $\rightarrow$ `dormant` $\rightarrow$ `archived` lifecycle with query rehydration. |
 | `anchor_create` / `verify` / `audit` | **Code Identity** | Creates, verifies, and audits line-independent structural code anchors. |
+| `muse_sync_broadcast` / `ingest` | **P2P Gossip Mesh** | Broadcasts and ingests portable sealed SyncPackets with deduplication and contradiction flagging. |
+| `muse_sync_status` / `pool` | **Sync Coordination** | Tracks peer vector clocks and synchronizes memories bidirectionally via shared drop-directory pool. |
+| `muse_mesh_status` | **Monorepo Topology** | Discovers monorepo workspaces and multi-repo sibling groups with package dependencies and stores. |
+| `muse_mesh_query` | **Cross-Project Query** | Queries memories across the entire workspace mesh with origin package provenance tags. |
+| `muse_mesh_audit` | **Contract Verification** | Audits cross-package dependency contracts, entrypoint exports, and cross-repo code anchors. |
+| `muse_mesh_link` | **Mesh Linking** | Explicitly links or unlinks external repository paths into the workspace mesh registry. |
 
 ### 🛠️ Core Memory & Lifecycle Tools
 | MCP Tool | Execution Phase | Agent Purpose |

package/.agents/context/roadmap.md

@@ -2,11 +2,18 @@
 
 ---
 
-## 🚀 Active Roadmap
-
-1. **Enhanced AST CodeGraph Indexing**:
-   - Deepen coupling with active project symbol graphs to boost dynamic symbol score weighting.
-2. **Autonomous Compounding Loops**:
-   - Background rollup triggers for weekly/monthly milestone synthesis.
-3. **Cross-Agent Knowledge Sync**:
-   - Peer-to-peer memory gossip protocol for isolated agency subagent teams.
+## ✅ Completed Milestones
+- **R14: Cross-Agent Knowledge Sync & P2P Gossip Protocol**: Sealed SyncPackets, vector clock causal tracking, filesystem shared pool drop-directory synchronization, contradiction tagging.
+- **R15: Full Web Observability Studio**: Embedded visual web dashboard (`memory studio`) featuring 5-pillar health scorecards, ADR drift inspection, autonomous "Why" reasoner, and live mesh visualization.
+- **R16: Multi-Repo & Monorepo Cross-Project Mesh**: Monorepo auto-discovery (pnpm, npm, bun, lerna), cross-project memory resolution with origin provenance, cross-package contract integrity auditing.
+
+---
+
+## 🚀 Active Roadmap & Future Horizons
+
+1. **Distributed Agentic Swarm Telemetry**:
+   - Aggregate multi-agent task traces and memory application telemetry across distributed agency clusters.
+2. **Autonomous Semantic Refactoring Engine**:
+   - Proactive codebase refactoring recommendations driven by historical bug friction clusters and ADR drift patterns.
+3. **Enterprise Role-Based Access & Secret Boundary Enclaves**:
+   - Cryptographic memory encryption and tenant-isolated compartmentalization for multi-client agency delivery.

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

@@ -0,0 +1,70 @@
+---
+name: muse-drift
+description: Living Architecture Decision Records (ADRs) and bidirectional documentation-to-code drift auditor. Investigates architectural drift, records living decisions, and maintains doc-code harmony.
+---
+
+# 🏛️ Muse Drift (`muse-drift`)
+
+> **When to use**: Execute when introducing architectural changes, making technology choices, refactoring system boundaries, or checking if documentation matches actual implementation.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Audit Documentation $\longleftrightarrow$ Code Alignment
+Call the `memory_drift_audit` MCP tool (or run `memory drift`):
+
+```json
+{
+  "dir": "."
+}
+```
+
+The auditor classifies documented items across 6 mutually exclusive states:
+- `DOCUMENTED`: Architectural guidelines described in docs/ADRs.
+- `IMPLEMENTED`: Verified clean match between doc and code AST.
+- `PARTIAL`: Incomplete implementation or missing export.
+- `CONFLICTING`: Code directly contradicts documented architecture.
+- `STALE`: Document references removed modules or legacy abstractions.
+- `MISSING`: Code exists with zero architectural documentation.
+
+### Step 2: Record Living Architecture Decision Records (ADRs)
+When establishing or changing an architectural design decision, record a first-class ADR using `memory_adr_record`:
+
+```json
+{
+  "title": "Use SQLite WAL and Microsecond In-Process Memory Cache",
+  "decision": "All memory read/write operations must use in-process SQLite WAL mode with an L0 hot cache. No resident background daemons.",
+  "status": "accepted",
+  "context_and_drivers": [
+    "Zero-daemon constraint",
+    "Sub-millisecond latency requirement for CLI commands"
+  ],
+  "consequences": {
+    "positive": ["Microsecond hot cache lookups", "Concurrent multi-process reads"],
+    "negative": ["Requires file locking management on write"]
+  },
+  "anchors": [
+    { "kind": "file", "file_path": "src/store.ts" },
+    { "kind": "file", "file_path": "src/cache.ts" }
+  ]
+}
+```
+
+### Step 3: Supersede Obsolete Decisions
+When replacing an existing ADR, provide the `supersedes` parameter with the old ADR ID. The engine automatically marks the old decision as `superseded` and records full provenance in the audit ledger.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# Check repository documentation vs code drift
+memory drift
+
+# List all living Architecture Decision Records
+memory adr list
+
+# Record a new Architecture Decision Record
+memory adr record "Decision Title" --decision "..." --positive "..." --negative "..."
+```

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

@@ -0,0 +1,56 @@
+---
+name: muse-health
+description: Unified 5-pillar project health gate governor. Audits store integrity, code anchors, doc/code alignment, negative sentry, and technical debt to enforce production hardening gates.
+---
+
+# 🏥 Muse Health (`muse-health`)
+
+> **When to use**: Execute before completing features, opening pull requests, or cutting releases to verify repository hardening and architectural health.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Run 5-Pillar Health Gate
+Call the `muse_health` MCP tool (or execute `memory health`):
+
+```json
+{
+  "dir": "."
+}
+```
+
+### Step 2: Evaluate 5-Pillar Scorecard
+The engine evaluates 5 distinct hardening dimensions, outputting an overall letter grade (**A–F**) and a gate status (**PASS**, **WARN**, or **FAIL**):
+
+1. **Pillar 1: Store Integrity**:
+   - Validates referential integrity, YAML schema conformances, bidirectional links, and missing target memory IDs.
+2. **Pillar 2: Native Code Anchors**:
+   - Verifies whether files, functions, and symbols referenced by code anchors exist on disk, flagging drifted structural hashes or orphaned anchors.
+3. **Pillar 3: Doc $\longleftrightarrow$ Code Alignment**:
+   - Audits living ADRs and documented invariants against actual code implementations, identifying conflicting, stale, or missing code.
+4. **Pillar 4: Negative Anti-Pattern Sentry**:
+   - Checks if any known `DO_NOT_USE` patterns, regression bug fixes, or failed approaches have resurfaced in the active working tree.
+5. **Pillar 5: Technical Debt & Workaround Sentry**:
+   - Detects unresolved `TODO`/`FIXME`/`HACK` comments, dangerous type casts (`as any`), and drifted architectural commitments.
+
+### Step 3: Execute Actionable Remediation Checklist
+If the gate status is **WARN** or **FAIL**, the engine outputs an ordered remediation checklist. Execute the prioritized items:
+- Prune or re-link orphaned code anchors via `memory reconcile --prune`.
+- Adhere to active ADR decisions.
+- Resolve flagged type assertions or negative pattern recurrences.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# Full terminal health dashboard
+memory health
+
+# Output raw JSON for CI/CD gating (exits 1 on FAIL)
+memory health --json
+
+# Interactively audit and prune orphaned code anchors
+memory reconcile --prune
+```

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

@@ -0,0 +1,66 @@
+---
+name: muse-mesh
+description: Multi-repo and monorepo cross-project knowledge mesh. Resolves memories across package boundaries, broadcasts shared invariants, and audits cross-package dependency contract integrity.
+---
+
+# 🕸️ Muse Mesh (`muse-mesh`)
+
+> **When to use**: Execute in monorepo environments (pnpm, npm, bun, lerna) or multi-repo projects when code spans multiple package boundaries or microservices.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Discover Monorepo Topology
+Call the `muse_mesh_status` MCP tool (or run `memory mesh overview`):
+
+```json
+{
+  "dir": "."
+}
+```
+
+Automatically inspects `pnpm-workspace.yaml`, `package.json` workspaces, or `lerna.json`, listing all detected package nodes and explicit mesh links.
+
+### Step 2: Query Knowledge Across Package Boundaries
+Call `muse_mesh_query` to search memories across all connected packages:
+
+```json
+{
+  "query": "authentication session store",
+  "scope": "all"
+}
+```
+
+Results include origin package provenance badges (e.g. `[mesh:@scope/core]`), preventing agents in frontend apps from hallucinating backend contract violations.
+
+### Step 3: Broadcast Shared Invariants to All Packages
+When establishing a monorepo-wide rule (e.g., "All microservices must use JWT v2 tokens"):
+- Use `memory mesh propagate --constraint "Use JWT v2 tokens across all services"`.
+- The invariant is atomically stamped into every package's `.memory/CURRENT.md`.
+
+### Step 4: Audit Cross-Package Contracts
+Call `muse_mesh_audit` (or run `memory mesh check`):
+- Verifies that cross-package imports match valid export entrypoints.
+- Flags drifted cross-repo code anchors.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# Display monorepo mesh topology and linked packages
+memory mesh overview
+
+# Query memories across all monorepo packages
+memory mesh query "database pool" --scope all
+
+# Audit cross-package contract integrity
+memory mesh check
+
+# Propagate a critical security constraint across all packages
+memory mesh propagate --constraint "Never expose database connection strings"
+
+# Explicitly link an external sibling repository
+memory mesh link ../external-service
+```

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

@@ -0,0 +1,63 @@
+---
+name: muse-sync
+description: Cross-agent knowledge sync and P2P gossip mesh protocol. Enables multi-agent swarms and isolated subagent teams to exchange insights, deduplicate knowledge, and resolve contradictions asynchronously.
+---
+
+# 🤝 Muse Sync (`muse-sync`)
+
+> **When to use**: Execute when coordinating multi-agent workflows (e.g., frontend, backend, and test subagents), sharing verified bug fixes between worktrees, or consolidating swarm learnings.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Check Peer Mesh & Vector Clock Status
+Call the `muse_sync_status` MCP tool (or run `memory sync --status`):
+
+```json
+{
+  "dir": "."
+}
+```
+
+Returns peer agent vector clocks, tracked packet generations, and pending incoming packets.
+
+### Step 2: Broadcast a Sealed Knowledge Packet
+To export recent confirmed memories, bug fixes, and active constraints into a portable packet:
+
+```json
+{
+  "project": "my-project",
+  "export_constraints": true
+}
+```
+
+The engine creates a cryptographically sealed `SyncPacket` with:
+- Whole-packet SHA-256 checksum verification.
+- Vector clock causal sequencing (`sender_id` + logical sequence).
+- Automatic Vibeguard secret inspection prior to packaging.
+
+### Step 3: Synchronize via Zero-Daemon Shared Pool
+Call `muse_sync_pool` (or run `memory sync --pool`):
+- Broadcasts un-synced memories into `.memory/sync_pool/`.
+- Ingests new packets dropped by peer subagents.
+- Eliminates duplicate entries automatically.
+- Flags semantic contradictions with mutual `conflict_ids` and triggers dispute resolution.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# View peer agent sync status and vector clocks
+memory sync --status
+
+# Broadcast confirmed memories to an exported packet
+memory sync --broadcast --out ./shared_sync.json
+
+# Ingest peer knowledge packet with secret scrubbing
+memory sync --ingest ./shared_sync.json
+
+# Bidirectionally sync with the shared filesystem gossip pool
+memory sync --pool
+```

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

@@ -0,0 +1,60 @@
+---
+name: muse-why
+description: Historical rationale and code evolution explainer. Synthesizes past ADRs, bug fixes, trade-offs, and invariants to explain why code was written the way it is before refactoring.
+---
+
+# 🤔 Muse Why (`muse-why`)
+
+> **When to use**: Execute before modifying unfamiliar code, refactoring complex logic, or when encountering code patterns that look unusual or overly defensive.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Query Code Rationale ("Why is this code like this?")
+Call the `muse_why` MCP tool:
+
+```json
+{
+  "target": "src/mcp.ts",
+  "symbol": "createServer",
+  "query": "Why do we filter tools dynamically by profile?"
+}
+```
+
+The "Why" reasoner traces backwards through history and synthesizes:
+1. **Governing Architecture Decisions**: Living ADRs that authorized or mandated this structure.
+2. **Historical Bug Fixes**: Edge cases and production regressions that necessitated defensive checks.
+3. **Accepted Trade-offs**: Documented compromises between performance, complexity, and safety.
+4. **Timeless Constraints**: Core architectural laws that must remain invariant.
+
+### Step 2: Audit Fragility & Bug Friction Clusters
+Call the `muse_bug_clusters` MCP tool:
+
+```json
+{
+  "dir": "."
+}
+```
+
+Clusters recurring issues across 5 core root causes:
+- `concurrency_race`: Race conditions, lock timeouts, async synchronization.
+- `type_mismatch`: Dangerous type bypasses, undefined property access.
+- `state_drift`: Out-of-sync cache entries, missing invalidation.
+- `resource_leak`: Unclosed file descriptors, runaway memory consumption.
+- `edge_case`: Boundary errors, empty array handling, malformed input.
+
+### Step 3: Check Pre-Flight Code & Memory Impact
+Call `muse_code_impact` (or run `memory code-impact <file> --symbol <sym>`) to check direct callers, affected test suites, and composite risk levels before editing.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# Query unified code & memory impact before editing
+memory code-impact src/mcp.ts --symbol createServer
+
+# View technical debt hotspots
+memory tech-debt
+```