From c81b5576f7f0b8796da7223f22f871201d1d2372 Mon Sep 17 00:00:00 2001 From: Harsh Singh Date: Mon, 26 Oct 2026 02:19:02 +0530 Subject: [PATCH] fix(cli): guard boolean --pool flag in sync and mandate @latest install in readme MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Why: - In `src/cli/sync.ts`, passing `memory sync --pool` without an argument evaluated `parsed.flags.pool` as string `"true"`, causing path resolution to create a stray `./true` directory. - Documentation in `README.md` needed to mandate `@latest` across package managers and outline 3-tier upgrade workflows (global, project, storage). - Backlog in `.agents/context/` required Wave 23–29 tickets and the local Agent OS (Rashin) research artifact. What: - In `src/cli/sync.ts`: filter out `"true"` and empty strings so `poolDir` defaults to standard pool path when no explicit path is given. - In `test/sync.test.ts`: add regression test verifying no `./true` directory is created when `--pool` is passed as boolean `"true"`. - In `README.md`: mandate `@latest` for bun/npm/pnpm/yarn/npx and document 3-tier update guides. - In `CHANGELOG.md`: record CLI sync fix and README updates under `[Unreleased]`. - In `.agents/context/`: track Wave 23–29 tickets and commit research artifact. Verification: - `bun test test/sync.test.ts`: 18/18 pass. - `bun test test/marketing_claims.test.ts test/published_copy_contracts.test.ts`: 38/38 pass. - `bun run scripts/showreel-hash.ts --check`: in sync. - `bun run scripts/check-doc-links.ts`: 150/150 markdown links resolve. - `bun run typecheck` (tsc --noEmit): clean. --- ...aul-rashin-research-and-wave-23-tickets.md | 234 ++++++++++++++++++ .agents/context/current.md | 10 +- .agents/context/roadmap.md | 9 + .agents/context/ticket-plan.md | 93 ++++++- CHANGELOG.md | 7 + README.md | 130 ++++++---- src/cli/sync.ts | 5 +- test/sync.test.ts | 17 ++ 8 files changed, 452 insertions(+), 53 deletions(-) create mode 100644 .agents/artifacts/2026-10-26-dashboard-rehaul-rashin-research-and-wave-23-tickets.md diff --git a/.agents/artifacts/2026-10-26-dashboard-rehaul-rashin-research-and-wave-23-tickets.md b/.agents/artifacts/2026-10-26-dashboard-rehaul-rashin-research-and-wave-23-tickets.md new file mode 100644 index 0000000..d506f5a --- /dev/null +++ b/.agents/artifacts/2026-10-26-dashboard-rehaul-rashin-research-and-wave-23-tickets.md @@ -0,0 +1,234 @@ +# 🧭 Deep Research: Ryoku Rashin Agent OS & Architectural Blueprint for Muse Memory Dashboard 2.0 + +> **Date**: October 26, 2026 +> **Author**: Muse (Chief Agency Orchestrator) & Sol (Product Architect & Full-Stack Automator) +> **Source Target**: Local Agent OS (Ryoku Rashin `http://127.0.0.1:3600`, Arch Linux, CachyOS / AMD Ryzen AI) +> **Application Target**: Muse Memory v3.1.0 (`/home/harsh/Projects/github/musememory`) +> **Classification**: Research, Competitive Teardown & Engineering Blueprint (Wave 23) + +--- + +## 1. Executive Summary + +A deep research investigation was conducted on the locally operating **Ryoku Rashin** Agent OS dashboard (`http://127.0.0.1:3600`) and its underlying knowledge architecture (`/home/harsh/.local/share/ryoku/rashin/`). + +Rashin presents an extraordinarily refined, high-speed, local-first agent system. Its primary strength lies in **"pre-indexing terrain"**: generating deterministic, bounded markdown files (`desktop.md`, `habits.md`, `logs.md`, `ownership.md`, `packages.md`, `ryoku-repo.md`, `system.md`, `user.md`) so that coding agents do not waste hundreds of thousands of tokens exploring the filesystem or guessing system configs. Furthermore, its user interface demonstrates remarkable speed and aesthetic polish through a fixed cyber-minimalist Japanese poster left rail, a 60fps canvas force-directed graph with auto-settling kinetic physics, live activity heatmaps, an auto-detecting agent wiring center, and an architecture-first About poster. + +While Rashin is optimized for a single Arch Linux desktop environment, **Muse Memory** is designed as the universal cognitive memory engine for multi-agent agency networks and heterogeneous repositories. By distilling Rashin's best UI paradigms and pre-indexed terrain architecture, Muse Memory can leapfrog existing memory dashboards: +1. **Dual-Scope Toggle**: Seamless switching between **Local Project Scope** (`./.memory`), **Global User Scope** (`~/.memory`), and **Cross-Project Mesh**. +2. **Instant Graph / List View Toggle**: Real-time switching between a 60fps settling force canvas and a structured, searchable data grid. +3. **Terrain Vault System**: Auto-generating repo and workspace terrain maps (`stack.md`, `habits.md`, `ownership.md`, `packages.md`, `repo.md`, `logs.md`). +4. **Universal Agents Hub**: 1-click MCP wiring, live status detection across 10+ agents (Antigravity, OpenCode, Claude Code, Cursor, Copilot, Hermes, Goose, Codex), and instant copyable system prompt snippets. +5. **Poster-Style Mission Control & Quick-Start**: High-impact About panel, multi-agent onboarding guide, and searchable CLI command deck. +6. **Sub-10ms UI Performance**: Fast-exit polling, zero-framework vanilla ES modularity, and in-memory read projections. + +--- + +## 2. In-Depth Teardown: Ryoku Rashin Agent OS + +### 2.1 Aesthetic & Visual Design Language +- **Color Palette**: + - Background: `--paper: #0e0d0b` (Deep obsidian/warm black), `--paper-2: #14120f` + - Text & Accents: `--ink: #e8d8c9` (Warm parchment cream), `--ink-dim: #8f8378` + - Functional Accents: Vermillion Red (`#C94E44`), Rust (`#9F4125`), Teal (`#3E6868`), Orange (`#f3701e`), Slate (`#4b607f`), Tan (`#CDA47B`). +- **Typography**: + - Display: `Archivo Black` (Heavy industrial brutalism) + - Data / Code: `JetBrains Mono` + - Typography Principle: Clean English-only typography throughout; zero Japanese kanji or extraneous font bloat. +- **Layout Architecture**: + - Fixed 76px vertical left rail with numbered navigation items (`01 OVERVIEW`, `02 VAULT`, `03 MEMORY`, `04 SKILLS`, `05 AGENTS`, `06 CHAT`, `07 ABOUT`). + - Fluid stage area with generous padding (`padding-bottom: 96px`) ensuring content never abuts screen boundaries. + - Zero framework runtime: No React, Vue, or heavy dependencies; pure native ES modules (`router.js`, `vault.js`, `memory.js`, `agents.js`, `skills.js`, `about.js`, `vitals.js`, `code.js`). + +### 2.2 The Terrain Vault (`/home/harsh/.local/share/ryoku/rashin`) +The vault is a curated, pre-indexed set of markdown files representing ground truth: +1. `AGENTS.md`: The single rule contract for all coding agents. Mandates reading terrain maps before filesystem exploration. +2. `desktop.md`: Maps every desktop subsystem to config paths, owning binary, and reload commands. +3. `habits.md`: Mined local developer habits (active shell, editor, terminal, frecent zoxide directories, aliased tools). +4. `logs.md`: Structured lookup table of systemd user units and bounded journal capture commands. +5. `ownership.md`: Explicit ownership rules (shipped packages vs. user overrides vs. generated files) preventing agents from corrupting upstream configs. +6. `packages.md`: Exact counts of explicitly installed packages and pending updates. +7. `ryoku-repo.md`: Pre-indexed monorepo layout, commit SHA, file counts, and folder purposes. +8. `system.md`: Hardware, CPU cores, GPU PCI bus IDs, kernel version, display resolutions. +9. `user.md`: Exact diff of where user files deviate from the baseline. + +### 2.3 The High-Speed Force-Directed Memory Canvas (`memory.js`) +- **Deterministic Ring Seeding**: Nodes are initialized in a circle (`R = 140`) to avoid chaotic initial states. +- **Physics Equations**: + - Repulsion: $F_r = \frac{k_{\text{repulsion}}}{d^2}$ (with minimum jitter to avoid $d=0$ singularity). + - Springs: $F_s = k_{\text{spring}} \cdot (d - d_{\text{rest}})$. + - Center Gravity: $F_g = (c - p) \cdot k_{\text{gravity}}$. + - Damping: $v_{t+1} = (v_t + F) \cdot 0.85$. +- **Automatic Kinetic Settling (Zero CPU Burn)**: + - Total kinetic energy is tracked: $E = \sum (v_x^2 + v_y^2)$. + - If $E < \text{SETTLE}$ for consecutive frames (`settleFrames > 40`), the requestAnimationFrame loop **halts completely**. + - Wakes up only on pointer drag, window resize, or tab visibility change. +- **Reduced Motion Support**: Runs 120 headless layout steps synchronously on load and halts if `prefers-reduced-motion` is detected. + +### 2.4 The Universal Agents Wiring Hub (`agents.js`) +- Inspects detected agents from standard locations (`.cursor`, `.claude`, `.omp`, `hermes`, `opencode`, `copilot`). +- Displays live status chips: `WIRED`, `UNWIRED`, `ABSENT`. +- Dedicated `WIRE` / `UNWIRE` action buttons calling `/api/agents/wire`. +- **Point Any Agent**: Displays a clear manifest table of exposed filesystem paths, owners, and permissions. +- **Copy Agent Snippet**: One-click clipboard button that copies a drop-in agent instruction prompt block. + +--- + +## 3. Gap Analysis: Muse Memory v3.0.0 vs. Ryoku Rashin + +| Dimension | Ryoku Rashin | Muse Memory (Current v3.0.0) | Muse Memory 2.0 Target (Wave 23) | +|---|---|---|---| +| **Primary Scope** | Single Linux Desktop OS | Multi-Repo / Polyglot Agency Ecosystem | Multi-Repo + Local Desktop + Team Mesh | +| **Navigation Shell** | Fixed 76px sleek left rail with clean numbered links | 11 horizontal crowded top tabs | Fixed 76px cyber-minimalist left rail (English-only) | +| **Memory View** | Canvas graph only (no list view) | 3D/2D Canvas graph only | **Toggle Switch: Interactive Graph ↔ Filterable Data Grid** | +| **Scope Switching** | Vault-only (no scope switcher) | Active project store only in UI | **Dual-Scope Switcher: Project Scope \| Global Scope \| Mesh** | +| **Terrain Vault** | 9 pre-indexed markdown maps | Only raw `.memory/` + `CURRENT.md` | **6 Auto-Generated Workspace Terrain Maps (`stack.md`, `habits.md`, etc.)** | +| **Activity Telemetry** | 52-week activity heatmap + sessions | Audit list only | **52-Week Activity Heatmap + Agent Session Ledger** | +| **Agent Wiring Hub** | Detected agents + 1-click wire + snippet | CLI-only agent connectors (`connect.ts`) | **Full UI Agent Hub: Status, 1-Click MCP Wire, Snippet Copier** | +| **About / Quick Start**| Poster-style About with live facts & CLI tips | Missing About tab | **Poster-Style Architecture Mission Control & Agent Quick Start** | +| **Graph Performance** | Auto-settles and stops rAF (0% idle CPU) | Unbounded animation ticks | **Kinetic settling threshold, ETag caching, sub-10ms endpoints** | + +--- + +## 4. Wave 23: Production Implementation Roadmap (PRs & GitHub Issues) + +Below is the complete 18-ticket specification (T-405 through T-422), grouped into 6 production pull requests / GitHub issues for Muse Memory. + +``` +Wave 23 (v3.1.0): Dashboard Overhaul, Terrain Maps & High-Speed Agent Hub +├── PR 1: Left-Rail Cyber-Minimalist Shell, Typography & Dual-Scope Switcher [T-405, T-406, T-407] +├── PR 2: Memory Studio 2.0: Instant Graph/List View Toggle, Physics Settling & Activity Heatmap [T-408, T-409, T-410] +├── PR 3: Workspace Terrain Vault: Auto-Generated Context Maps & Split Markdown Reader [T-411, T-412, T-413] +├── PR 4: Universal Agents Hub: Detection, 1-Click MCP Wiring & Prompt Snippets [T-414, T-415, T-416] +├── PR 5: About & Cognitive Mission Control: Architecture Specs, Quick Start & CLI Cheatsheet [T-417, T-418, T-419] +└── PR 6: System Speed, In-Memory Caching & Performance Hardening [T-420, T-421, T-422] +``` + +--- + +### PR 1 / Issue #1: Left-Rail Cyber-Minimalist Shell, Typography & Dual-Scope Switcher +**Goal**: Transform the UI into a distraction-free, ultra-responsive workstation with instant scope switching. + +- **T-405 · UI Shell**: Replace top horizontal tabs with a fixed 76px vertical left rail featuring: + - Brand Mark: Pulsing obsidian disc with glowing indigo rim. + - Numbered Navigation: `01 OVERVIEW`, `02 VAULT`, `03 MEMORY`, `04 AGENTS`, `05 OBSERVABILITY`, `06 ABOUT`. + - Palette: `#0b0d10` canvas, `#e8d8c9` warm text, JetBrains Mono font, and high-contrast status stamps (English-only, zero kanji). + - *Files*: `src/ui.ts` · *Gate*: F +- **T-406 · Dual-Scope Memory Switcher**: Add a top header segment switch: + - `[ Local Project Scope (./.memory) | Global User Scope (~/.memory) | Cross-Project Mesh ]` + - Dynamically updates active store query without page reload. + - Color-codes entries by scope: Local (Indigo), Global (Amber), Mesh (Emerald). + - *Files*: `src/ui.ts`, `src/store.ts`, `src/root.ts` · *Gate*: F +- **T-407 · Sub-10ms UI Route Architecture**: Refactor `src/ui.ts` to serve modular static assets with ETag headers, pre-compressed gzip buffers, and instantaneous route transitions. + - *Files*: `src/ui.ts` · *Gate*: F + +--- + +### PR 2 / Issue #2: Memory Studio 2.0: Instant Graph/List View Toggle, Physics Settling & Activity Heatmap +**Goal**: Combine the intuitive spatial awareness of graphs with the high-density filtering of data grids. + +- **T-408 · Graph vs List Toggle Switch**: Implement an instant segment control in the Memory panel: + - **Graph View**: Canvas force-directed graph. + - **List View**: Dense, searchable data table displaying ID, Type Badge (Decision, Constraint, Bugfix, Discovery, Invariant), Title, Salience Meter, Verification Stamp, and Last Accessed. + - Real-time client-side search input with 100ms debounce. + - *Files*: `src/ui.ts` · *Gate*: F +- **T-409 · Energy-Settling Canvas Physics Engine**: Port Rashin's kinetic settling algorithm into Muse Memory's canvas: + - Ring seed initialization for deterministic first render. + - O(N^2) repulsion with 0.01 jitter protection. + - Spring tension and center gravity damping. + - Kinetic energy monitoring: halts `requestAnimationFrame` when $E < \text{SETTLE}$ for 40 frames (reducing idle CPU from 15% to 0%). + - Smooth pointer drag with pointer capture and node click-to-focus. + - *Files*: `src/ui.ts` · *Gate*: F +- **T-410 · Activity Calendar Heatmap & Agent Sessions Card**: + - 52-week GitHub-style commit heatmap rendered via SVG/Canvas reflecting memory creation, updates, and confirmations. + - Recent agent sessions card showing agent name, model ID, started timestamp, and message volume. + - *Files*: `src/ui.ts`, `src/audit.ts` · *Gate*: F + +--- + +### PR 3 / Issue #3: Workspace Terrain Vault: Auto-Generated Context Maps & Split Markdown Reader +**Goal**: Eliminate agent token waste by maintaining deterministic, pre-indexed maps of the project terrain. + +- **T-411 · Workspace Terrain Generator Engine**: Add `src/vault/` engine that compiles and maintains: + - `stack.md`: Detected package manager, Node/Bun runtime, framework versions, build targets, and pinned toolchains. + - `habits.md`: User/team conventions, test commands, lint scripts, git branch patterns. + - `ownership.md`: Directory boundaries, DOX contracts, critical protected files (never edit). + - `packages.md`: Explicit production dependencies, dev tooling, audit status. + - `repo.md`: Structural AST overview, LOC counts per directory, critical entry points. + - `logs.md`: Recent test failure patterns, audit events, and error signatures. + - *Files*: `src/vault/index.ts`, `src/cli.ts` · *Gate*: F +- **T-412 · Terrain Vault Split-Pane UI**: + - Left pane: File listing with `GEN` badges for auto-compiled files and byte sizes. + - Right pane: Rendered markdown document viewer with typography styling. + - `REINDEX` button with animated scanline sweep calling `/api/vault/reindex`. + - *Files*: `src/ui.ts` · *Gate*: F +- **T-413 · Terrain Token-Efficiency Test & Benchmark**: + - Test suite asserting that terrain maps are generated deterministically and contain zero leaked credentials or absolute home path traps. + - *Files*: `test/vault_terrain.test.ts` · *Gate*: F + +--- + +### PR 4 / Issue #4: Universal Agents Hub: Detection, 1-Click MCP Wiring & Prompt Snippets +**Goal**: Make configuring and verifying agent connections effortless for any human or orchestrator. + +- **T-414 · Coding Agent Auto-Discovery**: + - Auto-detect installed agents: Antigravity, OpenCode, Claude Code, Cursor, Copilot CLI, Hermes, Crush, Goose, Aider, Codex. + - Status indicator: `WIRED` (MCP registered), `UNWIRED` (detected but unlinked), `ABSENT` (not found). + - *Files*: `src/connect.ts`, `src/ui.ts` · *Gate*: F +- **T-415 · 1-Click Wire / Unwire API**: + - Endpoints `POST /api/agents/wire` and `POST /api/agents/unwire`. + - Safely modifies target config files (`~/.config/opencode/opencode.json`, `~/.claude/settings.json`, `~/.cursor/mcp.json`, etc.) with atomic backup safeguards (`.bak`). + - *Files*: `src/ui.ts`, `src/connect.ts` · *Gate*: F +- **T-416 · "Point Any Agent" Manifest & One-Click Copy Snippet**: + - Display exposed paths: SQLite database, MCP stdio/HTTP endpoints, CURRENT.md invariants, AGENTS.md contract. + - `COPY AGENT SNIPPET` button: Copies ready-to-paste markdown prompt block for custom LLMs. + - *Files*: `src/ui.ts` · *Gate*: F + +--- + +### PR 5 / Issue #5: About & Cognitive Mission Control: Architecture Specs, Quick Start & CLI Cheatsheet +**Goal**: Provide an unshakeable architectural single source of truth inside the visual studio. + +- **T-417 · Poster-Style About Panel**: + - **WHAT**: Core philosophy of Muse Memory (continuous intent engineering & agency memory compounding). + - **THE PIECES**: Live facts table displaying: SQLite Store status, Active Scope, Memory count, Active Constraints, MCP Tools registered, Wiki Pages compiled, and Audit integrity. + - **PRIVACY & SOVEREIGNTY**: Formal verification statement of local-only storage, zero telemetry egress, and Vibeguard secret scrubbing. + - *Files*: `src/ui.ts` · *Gate*: F +- **T-418 · Quick-Start Interactive Onboarding**: + - Step-by-step interactive setup cards for leading agents (Antigravity, OpenCode, Claude Code, Cursor). + - Terminal command copy blocks and instant connection status check. + - *Files*: `src/ui.ts` · *Gate*: F +- **T-419 · "Go Deeper" Interactive Command Deck**: + - Searchable CLI cheatsheet: `muse recall`, `muse capture`, `muse current`, `muse brief`, `muse doctor`, `muse adr`, `muse sync`. + - Single-click command copy with usage flags. + - *Files*: `src/ui.ts` · *Gate*: F + +--- + +### PR 6 / Issue #6: System Speed, In-Memory Caching & Performance Hardening +**Goal**: Guarantee sub-10ms UI interactions and 60fps rendering without system strain. + +- **T-420 · In-Memory SQLite Read Projection Cache**: + - Cache projected UI payloads in memory (`WeakMap` / bounded memory store). + - Auto-invalidate on any mutating store transaction. + - Direct response time drops from ~12ms to <0.5ms. + - *Files*: `src/ui.ts`, `src/cache.ts` · *Gate*: F +- **T-421 · Fast-Exit & Visibility Sensors**: + - Add document `visibilitychange` listeners to stop all polling intervals and animation frames when the user switches tabs. + - *Files*: `src/ui.ts` · *Gate*: F +- **T-422 · Automated UI Performance Benchmark Suite**: + - Headless benchmark asserting: + - Route response times under 10ms. + - Zero memory retention after 100 tab switches. + - Zero unhandled rejections or CSS rendering errors. + - *Files*: `test/ui_performance.test.ts` · *Gate*: F + +--- + +## 5. Summary & Next Steps + +By incorporating these 18 tickets across Wave 23, Muse Memory will deliver an unrivaled developer and agent experience: +- **Instant visual navigation** inspired by high-speed cyberpunk poster designs. +- **Dramatically reduced token consumption** via pre-indexed workspace terrain maps. +- **Effortless multi-agent setup** with 1-click wiring and drop-in prompt snippets. +- **Blazing fast performance** with zero idle CPU burn. diff --git a/.agents/context/current.md b/.agents/context/current.md index 465a727..33deed7 100644 --- a/.agents/context/current.md +++ b/.agents/context/current.md @@ -126,7 +126,15 @@ on any blocking failure, so CI runs it. Report: --- ## ⏭️ Next Up (Post-Release Focus) -- **Production-Grade Showcase Demo**: Re-record high-fidelity terminal demo video/GIF reflecting v3.0.0 capabilities (failure attribution, HOT.md compounding, memory branch/checkout, MCP context recall) to replace removed legacy demo.- **Wave 24 remainder**: `T-316` (Hebbian co-activation edges into write-time `linked_memory_ids` seeding — **unblocked**, dep `T-095` landed; note the ticket premise is partly stale: `T-307` already landed the retrieval-expansion side) and `T-318` (retrieval weight auto-tuner from ROI telemetry — **unblocked**, deps `T-127` + `T-140` both landed). `T-317` (query-seeded PPR restart set) stays **blocked** on `T-178` (graph retrieval A/B gate). +- **Wave 23: Dashboard Overhaul, Terrain Maps & High-Speed Agent Hub (`T-405`–`T-422`)**: + - Full UI overhaul inspired by Ryoku Rashin (`http://127.0.0.1:3600`): fixed 76px left-rail cyber-minimalist navigation, instant Canvas Graph ↔ Filterable List toggle, 60fps kinetic-settling physics loop, and 52-week activity calendar heatmap. + - Multi-scope switcher: Project Scope (`./.memory`) vs Global User Scope (`~/.memory`) vs Cross-Project Mesh. + - Workspace Terrain Maps (`stack.md`, `habits.md`, `ownership.md`, `packages.md`, `repo.md`, `logs.md`) for token-efficient agent orientation. + - Universal Agents Hub: Auto-discovery, 1-click MCP wiring, and drop-in prompt snippets for 10+ agents (Antigravity, OpenCode, Claude Code, Cursor, Copilot, Hermes). + - Poster-style About panel with live architectural facts, interactive quick start onboarding, and CLI command deck. + - Sub-10ms UI serving performance with in-memory SQLite read caching and visibility-based zero-CPU idling. +- **Production-Grade Showcase Demo**: Re-record high-fidelity terminal demo video/GIF reflecting v3.0.0 capabilities to replace removed legacy demo. +- **Wave 24 remainder**: `T-316` (Hebbian co-activation edges into write-time `linked_memory_ids` seeding — **unblocked**, dep `T-095` landed; note the ticket premise is partly stale: `T-307` already landed the retrieval-expansion side) and `T-318` (retrieval weight auto-tuner from ROI telemetry — **unblocked**, deps `T-127` + `T-140` both landed). `T-317` (query-seeded PPR restart set) stays **blocked** on `T-178` (graph retrieval A/B gate). - **Consolidate the remaining duplicated tables** (deferred from this session as behaviour-changing; full detail with exact locations in [`docs/roadmap.md`](../../docs/roadmap.md) → *Engineering debt*): the three divergent per-type TTL tables (`src/retention.ts` **and** `src/retention/expiry_policy.ts` — only two of the three are in `retention.ts`), the **nine** separate token estimators (across nine files, plus six inline expressions — the collapse is *not* behaviour-neutral, because `src/orchestrator/context.ts` deliberately consumes the pessimistic measure), the divergent limit-clamping ceilings across retrieval paths (**seven** sites in `src/mcp.ts` alone), and the remaining zero-caller exports (twelve genuinely dead; 74 exported with no external caller). - **Remove the legacy `web/` directory** — done in this session. It was a second, hand-written copy of the site that `apps/website/` superseded; keeping it was the same "second copy that gets forgotten" failure mode this session fixed everywhere else. diff --git a/.agents/context/roadmap.md b/.agents/context/roadmap.md index 485ff2e..cdb5d8a 100644 --- a/.agents/context/roadmap.md +++ b/.agents/context/roadmap.md @@ -379,3 +379,12 @@ Exploded ticket plan: `.agents/context/ticket-plan.md` (269 tracked tickets, 21 - `T-153`: Multi-DB topology (shared team store + personal DBs) - `T-387`: Client configuration recipes & shared+personal scoping governance +9. **Wave 23: Dashboard Overhaul, Workspace Terrain Maps & High-Speed Agent Hub (v3.1.0 Roadmap)** + - `T-405`–`T-407`: Cyber-minimalist left-rail poster navigation shell, dual-scope switcher (`project` | `global` | `mesh`), and sub-10ms UI static route serving + - `T-408`–`T-410`: Memory Studio 2.0 with instant Canvas Graph ↔ Filterable List toggle, 60fps kinetic-settling physics loop, and 52-week activity calendar heatmap + - `T-411`–`T-413`: Workspace Terrain Generator (`stack.md`, `habits.md`, `ownership.md`, `packages.md`, `repo.md`, `logs.md`) & split-pane markdown reader with scanline reindexing + - `T-414`–`T-416`: Universal Agents Hub with live auto-discovery (Antigravity, OpenCode, Claude Code, Cursor, Copilot, Hermes), 1-click MCP wiring, and drop-in prompt snippets + - `T-417`–`T-419`: Poster-style About panel (WHAT, THE PIECES live facts table, PRIVACY guarantee), multi-agent quick start guide, and interactive CLI command deck + - `T-420`–`T-422`: In-memory SQLite read projection cache, tab visibility sensors for zero idle CPU burn, and headless UI performance benchmark suite + + diff --git a/.agents/context/ticket-plan.md b/.agents/context/ticket-plan.md index 3d02aa0..c35ea38 100644 --- a/.agents/context/ticket-plan.md +++ b/.agents/context/ticket-plan.md @@ -550,12 +550,97 @@ Canonical detailed artifact: `.agents/artifacts/audit-and-realigned-roadmap-2026 19. **Wave 18: Ingestion, Suppression & Curation Gates** (`T-106`–`T-113`) — [x] Landed on dev 20. **Wave 19: Scoring Refinements & Abstract Sidecars** (`T-118`–`T-125`) — [x] Landed on dev 21. **Wave 20: Quality Telemetry, Honesty Gates & Retrieval Fault Signals** (`T-127`–`T-135`) — [x] Landed on dev +22. **Wave 21: Invariant Mutation Safety & Constitutional Immunity** (`T-050`, `T-313`) — [x] Landed on dev +23. **Wave 22: Failure Attribution & Negative Mining** (`T-144`, `T-314`, `T-315`) — [x] Landed on dev +24. **Wave 23: Dashboard Overhaul, Terrain Maps & High-Speed Agent Hub** (`T-405`–`T-422`) — [ ] Active Roadmap -## v12 Totals +--- + +# v13 — DASHBOARD OVERHAUL, TERRAIN MAPS & HIGH-SPEED AGENT HUB (WAVE 23, 2026-10-26) + +Source: Deep research on local Agent OS (Ryoku Rashin `http://127.0.0.1:3600`) and architectural design blueprint (`.agents/artifacts/2026-10-26-dashboard-rehaul-rashin-research-and-wave-23-tickets.md`). + +## PR 1 / Issue #1: Left-Rail Cyber-Minimalist Shell, Typography & Dual-Scope Switcher +- [ ] T-405 · UI Shell: Fixed 76px vertical left rail with clean brand mark, numbered sections (`01 OVERVIEW`..`06 ABOUT`), warm-dark aesthetic, JetBrains Mono & Archivo Black typography (English-only, zero kanji) · src/ui.ts · F +- [ ] T-406 · Dual-Scope Memory Switcher: Header segment toggle `[ Local Project Scope (./.memory) | Global User Scope (~/.memory) | Cross-Project Mesh ]` with instant live refetch · src/ui.ts, src/store.ts, src/root.ts · F +- [ ] T-407 · Sub-10ms UI Route Architecture: Split single embedded HTML into modular static cached templates with ETag headers and pre-compressed buffers · src/ui.ts · F + +## PR 2 / Issue #2: Memory Studio 2.0: Instant Graph/List View Toggle, Physics Settling & Activity Heatmap +- [ ] T-408 · Graph vs List Toggle Switch: Instant segment toggle between interactive Canvas Graph and filterable/sortable data table with live 100ms debounced search · src/ui.ts · F +- [ ] T-409 · Energy-Settling Canvas Physics Engine: Ring-seeded 60fps force-directed graph with auto-settling kinetic loop (`energy < SETTLE` halts rAF) and pointer capture · src/ui.ts · F +- [ ] T-410 · Activity Calendar Heatmap & Agent Sessions Card: 52-week activity commit-style calendar for memory mutations + agent session log cards with model tags, timestamps, message counts · src/ui.ts, src/audit.ts · F + +## PR 3 / Issue #3: Workspace Terrain Vault: Auto-Generated Context Maps & Split Markdown Reader +- [ ] T-411 · Workspace Terrain Generator Engine: Compile deterministic workspace maps: `stack.md`, `habits.md`, `ownership.md`, `packages.md`, `repo.md`, `logs.md` · src/vault/index.ts, src/cli.ts · F +- [ ] T-412 · Terrain Vault Split-Pane UI: Left file tree with `GEN` badges and right rendered markdown viewer with scanline animation on `REINDEX` · src/ui.ts · F +- [ ] T-413 · Terrain Token-Efficiency Test & Benchmark: Test suite verifying deterministic generation, zero secret leaks, and token savings · test/vault_terrain.test.ts · F + +## PR 4 / Issue #4: Universal Agents Hub: Detection, 1-Click MCP Wiring & Prompt Snippets +- [ ] T-414 · Coding Agent Auto-Discovery: Detect installed agents (Antigravity, OpenCode, Claude Code, Cursor, Copilot CLI, Hermes, Crush, Goose, Aider, Codex) with `WIRED`/`UNWIRED`/`ABSENT` status · src/connect.ts, src/ui.ts · F +- [ ] T-415 · 1-Click Wire / Unwire API: `POST /api/agents/wire` and `POST /api/agents/unwire` writing safe native MCP configs with backup protection · src/ui.ts, src/connect.ts · F +- [ ] T-416 · "Point Any Agent" Manifest & One-Click Copy Snippet: Display exposed filesystem paths, MCP endpoints, and one-click copyable system prompt snippet for custom LLMs · src/ui.ts · F + +## PR 5 / Issue #5: About & Cognitive Mission Control: Architecture Specs, Quick Start & CLI Cheatsheet +- [ ] T-417 · Poster-Style About Panel: Architectural poster with WHAT (mission), THE PIECES live facts table (SQLite, Scope, Constraints, Tools, Wiki, Audit), and PRIVACY zero-cloud guarantee · src/ui.ts · F +- [ ] T-418 · Quick-Start Interactive Onboarding: Multi-step interactive setup cards for leading agents (Antigravity, OpenCode, Claude Code, Cursor) with copyable commands · src/ui.ts · F +- [ ] T-419 · "Go Deeper" Interactive Command Deck: Searchable CLI command palette with copyable one-liners (`muse recall`, `muse capture`, `muse current`, `muse brief`, `muse doctor`, `muse adr`, `muse sync`) · src/ui.ts · F + +## PR 6 / Issue #6: System Speed, In-Memory Caching & Performance Hardening +- [ ] T-420 · In-Memory SQLite Read Projection Cache: Cache UI list and graph responses in memory, invalidated automatically on write transactions · src/ui.ts, src/cache.ts · F +- [ ] T-421 · Fast-Exit & Visibility Sensors: Document `visibilitychange` listeners to stop all background polling intervals and animation frames when browser tab is inactive · src/ui.ts · F +- [ ] T-422 · Automated UI Performance Benchmark Suite: Headless benchmark asserting sub-10ms UI responses, 60fps graph rendering, and zero memory leaks · test/ui_performance.test.ts · F + +--- + +# v14 — STRATEGIC HORIZONS & SOVEREIGN LIFEOS RETIREMENT (WAVES 24–29, 2026-10-26) + +Source: Strategic roadmaps, developer experience assets, R17–R20 tri-cognitive horizons, and LifeOS sovereignty audit. + +## Wave 24: Showcase, Interactive Playground & DX Assets +- [ ] T-423 · Terminal Showreel & GIF Recording: Script and record high-fidelity terminal demo (`showreel.mp4`, `muse-memory-demo.gif`) on v3.0.0 highlighting failure attribution, negative mining, and HOT.md compounding · assets/, docs/ · N +- [ ] T-424 · Interactive WASM/SQLite Web Playground: In-browser memory studio preview on `apps/website` with zero backend server dependencies · apps/website · F +- [ ] T-425 · Competitive Benchmark Showcase: Real-time latency, recall accuracy, and token-cost comparison matrix vs Mem0, Zep, and Letta · apps/website, docs/ · N +- [ ] T-426 · Multi-Agent Interactive Demos: Interactive agent switcher in website docs demonstrating context injection across Antigravity, OpenCode, Claude Code, and Cursor · apps/website · N + +## Wave 25: R17 Tri-Cognitive Playbooks & Episodic Narrative Horizon +- [ ] T-427 · Procedural Playbook Engine (`ProceduralMemory`): Model and persist executable step trajectories, pre-conditions, verification assertions, and rollback recipes · src/cognition/playbooks.ts · F +- [ ] T-428 · Episodic Causal Narrative Horizon: Group linear observations into causal episodes (`Goal ➔ Hypothesis ➔ Trajectory ➔ Verification ➔ Retrospective`) · src/cognition/episodes.ts · F +- [ ] T-429 · Bi-Temporal Validity Windows: Stored dual timestamps (`asserted_at` vs `valid_from`/`valid_until`) allowing historical queries without clobbering active state · src/schema.ts, src/store.ts · F +- [ ] T-430 · Ebbinghaus Utility-Reinforced Cognitive Forgetting Curve: Exponential decay for unverified candidate notes; reinforcement for green test executions · src/quality/decay.ts · F +- [ ] T-431 · CLI & MCP Playbook Commands: Wire `memory playbook --run `, `memory playbook --list`, and `muse_playbook_recall` / `muse_playbook_record` MCP tools · src/cli/playbook.ts, src/mcp.ts · F + +## Wave 26: R18 AST Associative Callgraph Retrieval & Speculative Pre-Flight +- [ ] T-432 · Recursive SQLite CTE Associative Expansion (Zero-Daemon HippoRAG): 2-hop associative graph traversal using in-process SQLite recursive CTEs (`WITH RECURSIVE call_tree AS (...)`) · src/sqlite.ts, src/retrieval/ · F +- [ ] T-433 · Speculative Pre-Flight Context Push: Git and editor hooks pre-calculating token-budgeted memory knapsacks on file opening or branch switching · src/hooks/preflight.ts · F +- [ ] T-434 · Cross-File Symbol Blast-Radius Risk Scoring: AST identifier cross-reference scoring to rate modification risk for proposed code changes · src/anchors/blast_radius.ts · F +- [ ] T-435 · AST-Anchored Invariant Auto-Recall: Bind exported symbols and route interfaces directly to governing ADRs and architectural invariants · src/retrieval/anchors.ts · F + +## Wave 27: R19 Git-Branchable Memories & Multi-Tenant Agency Enclaves +- [ ] T-436 · Branchable Memory Overlays (`memory branch` / `branch-merge`): Branch-isolated memory layers tracking git feature branch lifecycles · src/store/branch.ts · F +- [ ] T-437 · Multi-Tenant Agency Enclaves (`scope: client`): Cryptographically segregated client vaults across Council divisions (Sol, Jasper, Crew, Nexus) · src/store/enclaves.ts · F +- [ ] T-438 · Zero-Knowledge Memory Attestation: Cryptographic SHA-256 signing of SyncPackets with tamper-evident audit chains for client handoffs · src/sync/attestation.ts · F +- [ ] T-439 · Semantic Contradiction Merge Resolver: Interactive 3-way semantic conflict resolution on branch merge into `main` · src/quality/branch_merge.ts · F + +## Wave 28: R20 Test-Driven Reinforcement & Regression Sentry +- [ ] T-440 · Automated CI / Test Harness Integration: Bind memory utility directly to real test outcomes (`bun test`, `vitest`, `cargo test`); increment ROI on green, decay on red · src/quality/test_feedback.ts · F +- [ ] T-441 · Negative Anti-Pattern Regression Sentry: Proactive watchdog matching test failures against `BUG_PRONE_PATTERN` and `DO_NOT_USE` records · src/cognition/sentry.ts · F +- [ ] T-442 · Flaky Test & Environment Drift Detector: Correlate test flakiness and failure bursts with dependency updates and environmental churn · src/doctor/flaky.ts · F +- [ ] T-443 · Autonomous Remediation Playbook Generator: Automatically synthesize recurring test fix sequences into verified reusable playbooks · src/cognition/remediation.ts · F + +## Wave 29: Sovereign LifeOS Migration & Complete Decommissioning +- [ ] T-444 · Sovereign LifeOS Ingestion Engine: `muse import-lifeos` CLI tool to automatically ingest `~/.config/LIFEOS/USER/` into `~/.memory/` and `~/.memory/USER.md` · src/cli/import_lifeos.ts · F +- [ ] T-445 · Native Vibeguard CLI (`muse scan-secrets`): Standalone secret scanning binary in `musememory` eliminating dependency on `~/.config/LIFEOS/runtime/TOOLS/SecretScan.ts` · src/cli/secrets.ts · F +- [ ] T-446 · Machine Terrain Collector in `src/vault/` & `muse-skills`: Incorporate LifeOS Atlas hardware, daemon, and package scans into unified workspace maps · src/vault/system.ts · F +- [ ] T-447 · Global `~/.agents/AGENTS.md` De-LifeOSification: Remove all `@LIFEOS` imports and rewrite governance directives to point purely to Muse Memory and Muse Skills · ~/.agents/AGENTS.md · N +- [ ] T-448 · LifeOS Decommissioning & Retirement Gate: Verification audit confirming zero dangling runtime dependencies before safely backing up and removing `~/.config/LIFEOS` · docs/lifeos_retirement.md · N + +## v14 Totals | Section | Tickets | |---|---| -| Total Tracked Tickets | 290 | -| Landed on dev | 212 | -| Active Remaining | 78 | +| Total Tracked Tickets | 334 | +| Landed on dev | 217 | +| Active Remaining | 117 | + + diff --git a/CHANGELOG.md b/CHANGELOG.md index a7e2aa1..885efcb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed +- **CLI sync `--pool` boolean flag handling**: `memory sync --pool` without a value passed `--pool "true"`, causing the path resolver to evaluate `./true` as a relative directory. `handleSyncCommand` now filters out boolean `"true"` and empty strings, falling back to the standard pool path unless an explicit directory string is provided. + +### Documentation +- **Mandatory `@latest` package installation standards**: Updated README to enforce `@latest` across all package managers (`bun`, `npm`, `pnpm`, `yarn`, `npx`) and documented 3-tier update workflows (CLI/workstation, project/workspace, and storage self-healing). +- **Wave 23–29 Architectural Backlog**: Added exploded ticket plans and research specifications for dashboard overhaul, workspace terrain maps, universal agent hub, and tri-cognitive retrieval. + ## [3.1.2] - 2026-10-25 **Full Changelog**: https://github.com/harshsinghmp/musememory/compare/v3.1.1...v3.1.2 diff --git a/README.md b/README.md index f115dd2..a94ff85 100644 --- a/README.md +++ b/README.md @@ -257,13 +257,13 @@ to delete the memory. ## Start with one command -> [!TIP] -> ### Install without a global package -> Set up the memory store and connect your local AI agents with one command: +> [!IMPORTANT] +> ### Always install and run with `@latest` +> To ensure you never execute an outdated or cached version, always explicitly append `@latest` when installing or invoking via NPX or Bun: > > ```bash -> npx musememory install -> # (or with Bun: bunx musememory install) +> npx musememory@latest install +> # (or with Bun: bunx musememory@latest install) > ``` > > This command automatically: @@ -272,23 +272,34 @@ to delete the memory. > 3. Auto-wires the memory MCP server into installed agents with zero-permission auto-approval. > 4. Scans for existing memory stores (Letta, Mem0, Beads, Supermemory, etc.) for instant migration. > -> **Verify anytime**: `npx musememory doctor` -> **Explore Studio UI**: `npx musememory ui` (Opens cognitive studio on port 2222) +> **Verify anytime**: `npx musememory@latest doctor` +> **Explore Studio UI**: `npx musememory@latest ui` (Opens cognitive studio on port 2222) --- ### 📦 Persistent Installation Options -```bash -# Option A: Global Install with NPM or Bun (Recommended) -npm install -g musememory -# or with Bun: -bun add -g musememory +Always specify `@latest` across every package manager to ensure you run the newest engine capabilities and security patches: -# Option B: One-Line Shell Installer +```bash +# Option A: Global Workstation Install (Always use @latest) +bun add -g musememory@latest +# or with NPM: +npm install -g musememory@latest +# or with PNPM: +pnpm add -g musememory@latest +# or with Yarn: +yarn global add musememory@latest + +# Option B: Local Project Dependency (Pinned in package.json) +bun add musememory@latest +# or with NPM: +npm install musememory@latest + +# Option C: One-Line Shell Installer (Pulls latest release binary) curl -fsSL https://raw.githubusercontent.com/harshsinghmp/musememory/main/scripts/install.sh | bash -# Option C: Docker Container +# Option D: Docker Container git clone https://github.com/harshsinghmp/musememory.git && cd musememory docker build -t musememory . ``` @@ -328,18 +339,27 @@ prose paragraph to learn a flag name. --- -## 🔄 Upgrading & Self-Healing Maintenance - -Keep Muse Memory and all your connected AI coding agents at peak cognitive performance with automated updates and self-healing environment repairs. +## 🔄 Updating the System, Project & Packages -### ⚡ 1-Command Autonomous Upgrade (`memory upgrade`) +Keep Muse Memory and all your connected AI coding agents at peak cognitive performance with automated updates, self-healing environment repairs, and consistent `@latest` versioning. -Run `memory upgrade` (or `npx musememory upgrade`) to trigger the **Gamified Level-Up Matrix**: +### 1️⃣ Updating the Global Package / Workstation CLI +Always use `@latest` across every package manager to pull the newest releases: ```bash +# ⚡ Method 1: Autonomous Self-Healing Updater (Recommended) memory upgrade # or with NPX zero-install: -npx musememory upgrade +npx musememory@latest upgrade + +# 📦 Method 2: Explicit Package Manager Upgrade (Always specify @latest) +bun add -g musememory@latest # Bun (Fastest) +npm install -g musememory@latest # NPM +pnpm add -g musememory@latest # PNPM +yarn global add musememory@latest # Yarn + +# 🌐 Method 3: One-Line Shell Script Update +curl -fsSL https://raw.githubusercontent.com/harshsinghmp/musememory/main/scripts/install.sh | bash ``` #### What `memory upgrade` automatically handles: @@ -350,67 +370,83 @@ npx musememory upgrade --- -### 📦 Manual Package Manager Upgrades +### 2️⃣ Updating a Project / Workspace +To upgrade and synchronize memory inside a specific project repository: -| Toolchain / Runtime | Upgrade Command | Verification | -| :--- | :--- | :--- | -| **Bun** (Ultra-Fast) | `bun add -g musememory@latest` | `memory doctor` | -| **NPM** (Standard Node) | `npm install -g musememory@latest` | `memory doctor` | -| **PNPM** | `pnpm add -g musememory@latest` | `memory doctor` | -| **Yarn** | `yarn global add musememory@latest` | `memory doctor` | -| **NPX** (Zero-Install) | `npx musememory@latest upgrade` | `npx musememory doctor` | +```bash +# Update project-level dependency (pinned in package.json) +bun add musememory@latest +# or with NPM: +npm install musememory@latest + +# Re-scan and re-wire all local project agent configurations +memory connect all + +# Re-index symbol callgraphs and recompile Markdown wiki +memory reindex +memory wiki compile + +# Inspect and verify active working constraints +memory current get +memory briefing +``` + +--- + +### 3️⃣ Updating the System & Memory Storage (Self-Healing & Migrations) +To audit, repair, or defragment the underlying SQLite database and knowledge files: ```bash -# Check if updates are available without applying (exits 0 if up to date, 1 if registry fails) -memory upgrade --check +# Full ecosystem diagnostic and automated schema healing +memory doctor -# Enforce up-to-date installation in CI pipelines (exits 1 if update is available) -memory upgrade --check --strict +# Optimize memory storage: prunes test noise, removes duplicates, runs SQLite VACUUM +memory optimize -# Preview upgrade actions in dry-run mode -memory upgrade --dry-run +# Scan and migrate legacy stores (Letta, Mem0, Beads, Supermemory) +memory migrate -# Force re-installation and complete platform re-wiring -memory upgrade --force +# Check for updates without applying (exits 0 if up to date, 1 if update available) +memory upgrade --check ``` --- ## 🔄 Complete Lifecycle (Install → Verify → Connect → Uninstall) -Every command works with **zero installation** via `npx musememory ` (or `bunx musememory `). Use plain `memory ` if installed globally. +Every command works with **zero installation** via `npx musememory@latest ` (or `bunx musememory@latest `). Use plain `memory ` if installed globally. ### 1️⃣ Install & Auto-Wire ```bash # Full setup: init .memory/, detect agents, wire MCP, scan for migratable stores -npx musememory install +npx musememory@latest install # Initialize workspace only (no agent wiring) -npx musememory init +npx musememory@latest init ``` ### 2️⃣ Verify & Health Check ```bash # Comprehensive ecosystem diagnostic (storage, schemas, secrets, MCP wiring) -npx musememory doctor +npx musememory@latest doctor # Memory store breakdown and active briefing -npx musememory stats -npx musememory briefing +npx musememory@latest stats +npx musememory@latest briefing ``` ### 3️⃣ Connect Coding Agents (the majority of platforms) ```bash # Scan workstation for installed AI coding agents -npx musememory agents +npx musememory@latest agents # Auto-wire all detected agents with zero permissions -npx musememory connect all +npx musememory@latest connect all # Wire one specific agent explicitly -npx musememory connect claude-code -npx musememory connect cursor -npx musememory connect antigravity +npx musememory@latest connect claude-code +npx musememory@latest connect cursor +npx musememory@latest connect antigravity npx musememory connect windsurf npx musememory connect opencode diff --git a/src/cli/sync.ts b/src/cli/sync.ts index c5d5037..437e899 100644 --- a/src/cli/sync.ts +++ b/src/cli/sync.ts @@ -65,7 +65,10 @@ export async function handleSyncCommand(parsed: ParsedArgs): Promise { // 3. Shared pool sync action if (parsed.flags.pool || (!parsed.flags.status && !parsed.flags.broadcast && !parsed.flags.ingest)) { - const poolDir = typeof parsed.flags.pool === "string" ? resolve(process.cwd(), parsed.flags.pool) : undefined; + const rawPool = parsed.flags.pool; + const poolDir = typeof rawPool === "string" && rawPool !== "true" && rawPool.trim() !== "" + ? resolve(process.cwd(), rawPool) + : undefined; const report = syncWithSharedPool(store, root, poolDir, agentId); if (parsed.flags.json) { diff --git a/test/sync.test.ts b/test/sync.test.ts index ec38023..006cbe8 100644 --- a/test/sync.test.ts +++ b/test/sync.test.ts @@ -304,6 +304,23 @@ describe("R14: Cross-Agent Knowledge Sync & P2P Gossip Protocol", () => { expect(get(storeB, "m_cli_sync_test")).toBeDefined(); }); + + it("does not create a stray ./true directory when --pool flag is passed as boolean string 'true'", async () => { + const origCwd = process.cwd(); + const testCwd = mkdtempSync(join(tmpdir(), "muse-cwd-test-")); + process.chdir(testCwd); + try { + const code = await handleSyncCommand({ + positional: ["sync"], + flags: { dir: tmpRootA, pool: "true", json: "true" }, + }); + expect(code).toBe(0); + expect(existsSync(join(testCwd, "true"))).toBe(false); + } finally { + process.chdir(origCwd); + rmSync(testCwd, { recursive: true, force: true }); + } + }); }); describe("MCP Tools Execution for Gossip Sync", () => {