musememory 1.11.0 → 2.0.0

package/.agents/context/architecture.md

@@ -0,0 +1,137 @@
+# 🏗️ Muse Memory Architecture & System Design
+
+---
+
+## 🏛️ System Architecture Snapshot
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    AI Agents & IDE Platforms                │
+│  (Claude Code, Cursor, Antigravity, Windsurf, Codex, CLI)   │
+└──────────────────────────────┬──────────────────────────────┘
+                               │ MCP stdio / Terminal CLI
+┌──────────────────────────────▼──────────────────────────────┐
+│                    Muse Memory Core Engine                  │
+│                                                             │
+│ ┌───────────────────┐ ┌──────────────────┐ ┌──────────────┐ │
+│ │  Retrieval Engine │ │ Vibeguard Secret │ │ Auto-Migrate │ │
+│ │ (Token Knapsack)  │ │ Defense Scanner  │ │  (24+ Formats)│ │
+│ └───────────────────┘ └──────────────────┘ └──────────────┘ │
+│ ┌───────────────────┐ ┌──────────────────┐ ┌──────────────┐ │
+│ │ LifeCycle Machine │ │ JSONL Harvester  │ │ Audit Ledger │ │
+│ │(State Transitions)│ │(Transcript Parser│ │(audit.jsonl) │ │
+│ └───────────────────┘ └──────────────────┘ └──────────────┘ │
+└──────────────────────────────┬──────────────────────────────┘
+                               │ Atomic File I/O
+┌──────────────────────────────▼──────────────────────────────┐
+│              Dual-Scope Storage Engine (.memory/)           │
+│                                                             │
+│  .memory/                                                   │
+│  ├── memory.db          # Primary SQLite cognitive database │
+│  ├── CURRENT.md         # Active hard constraints & handoff │
+│  ├── USER.md            # Persona & developer preferences   │
+│  ├── HOT.md             # Working memory cache (rollups)    │
+│  ├── sources.json       # Provenance Source Ledger          │
+│  ├── claims.json        # Evidence-grounded Claim Ledger    │
+│  ├── audit.jsonl        # Append-only operational audit trail│
+│  └── memories/          # Dual-persisted YAML export mirror │
+│      ├── m_1700000001000_auth.yaml                          │
+│      └── m_1700000002000_arch.yaml                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📁 Repository Layout
+
+```
+musememory/
+├── bin/                    # Command-line entry points (memory.ts, musememory.ts)
+├── src/                    # Core TypeScript source code
+│   ├── adrs/               # Living Architecture Decision Records & Drift Engine
+│   ├── anchors/            # Native structural code anchors & live drift verification
+│   ├── audit.ts            # Append-only compliance audit ledger
+│   ├── cache.ts            # L0 hot cache, query cache, & SQLite WAL tuning
+│   ├── claims.ts           # Evidence-backed claim ledger & confidence tags
+│   ├── cli.ts              # Command router & dispatcher
+│   ├── cli/                # Modular domain command handlers (health, wiki, etc.)
+│   ├── cognition/          # Autonomous "Why" reasoner, bug clustering, tech debt
+│   ├── compaction/         # 70% context compaction engine & session handoffs
+│   ├── compounding/        # Unified knowledge compounding (temporal & clustering)
+│   ├── connect.ts          # Declarative zero-permission auto-wiring across 80+ agent platforms
+│   ├── current.ts          # CURRENT.md read/append constraints engine
+│   ├── doctor.ts           # Ecosystem diagnostic & health check engine
+│   ├── health/             # Unified 5-Pillar Project Health Gate engine
+│   ├── 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)
+│   ├── 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
+│   ├── retrieval/          # 11-dimension multi-factor scoring & token knapsack packing
+│   ├── root.ts             # Hierarchical root detection & auto-bootstrap
+│   ├── schema.ts           # JSON Schema & store referential validator
+│   ├── secrets.ts          # Vibeguard zero-leakage secret scanner & redactor
+│   ├── store.ts            # Dual-scope storage layout & lifecycle state machine
+│   ├── transcript.ts       # Universal JSONL parser, dialogue windowing & search
+│   ├── types.ts            # Core TypeScript interfaces & enums
+│   ├── 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)
+├── package.json            # Package metadata & dependencies (v2.0.0)
+└── dist/                   # Compiled Node/Bun bundle
+```
+
+---
+
+## 🔄 Memory LifeCycle State Machine
+
+```
+  [propose] ──► candidate ──► confirm() ──► active / confirmed ──► supersede() ──► superseded
+                    │                             │                      │
+                    ├──► markStale() ─────────────┤                      ├──► cold ──► dormant ──► archived
+                    │         │                   │                      │                           │
+                    │         ▼                   ▼                      └────────◄── rehydrate() ───┘
+                    └──►    stale             conflicted
+                              │                   │
+                              └──► delete() ◄─────┘
+                                      │
+                                      ▼
+                           [Purged from SQLite/YAML + audit.jsonl logged]
+```
+
+### Invariant Rules:
+1. **Confirmation Gate**: Only `candidate`, `disputed`, or `stale` entries can be promoted to `confirmed`.
+2. **Supersession Requirement**: When calling `supersede(old_id, new_id)`, the `new_id` entry must already exist and have `confirmed` status. Self-supersession (`old_id === new_id`) is strictly prohibited.
+3. **Contradiction Management**: Contradictory evidence creates explicit `conflicted` status with mutual `conflict_ids` instead of silently clobbering truth.
+4. **Scoped Promotion Ladder**: Promotions move `local` $\rightarrow$ `project` $\rightarrow$ `global` following the 5× repeated success policy and universal generalization (stripping local paths and project-specific artifacts).
+5. **Archival Rehydration**: Cold and archived memories dynamically rehydrate to `active` upon high-relevance queries.
+6. **Audit Ledger Logging**: Every mutation automatically writes an immutable log record to `.memory/audit.jsonl`.
+
+---
+
+## ⏳ Per-Type Staleness Policy
+
+| Memory Type | Policy Lifetime | Description & Agent Guidance |
+| :--- | :--- | :--- |
+| `fix` | **90 days** | Bug workarounds, dependency patches, edge-case fixes. |
+| `operation` | **180 days** | Build scripts, deployment instructions, local dev commands. |
+| `architecture` | **365 days** | System architecture, database schemas, core abstractions. |
+| `discovery` | **30 days** | Ephemeral research notes, transient experiments. |
+| `preference` | **Permanent (`null`)** | User coding preferences, tone/style rules, agency stances. |
+| `constraint` | **Active** | Immediate hard constraints synced directly to `CURRENT.md`. |
+| `session` | **Permanent (`null`)** | Session start/end timeline nodes in the cognition graph. |
+
+---
+
+## 🛡️ Built-in Vibeguard Secret Defense (`src/secrets.ts`)
+
+Every write transaction (`store.propose`, `store.save`, `setUserProfile`, `importSnapshot`, and `importTranscript`) automatically scans content and rejects writes if any of the following are detected:
+- OpenAI / Anthropic / AI API keys (`sk-...`)
+- GitHub Personal Access Tokens (`ghp_...`, `github_pat_...`)
+- NPM tokens (`npm_...`)
+- AWS Access Key IDs (`AKIA...`, `ASIA...`)
+- Private Key blocks (`-----BEGIN ... PRIVATE KEY-----`)
+- Database connection strings with embedded credentials (`postgres://...`)

package/.agents/context/brand.md

@@ -0,0 +1,19 @@
+# 🎨 Brand, Persona & Voice Guidelines
+
+---
+
+## 1. Product Identity & Voice
+- **Name**: Muse Memory (`musememory`)
+- **Tone**: Technical, authoritative, razor-sharp, zero-fluff.
+- **Audience**: Elite software engineers, agency founders, and autonomous AI agents.
+
+---
+
+## 2. Terminal UI & CLI Output Conventions
+- Format CLI tables cleanly with ASCII borders.
+- Prepend informative CLI banners with appropriate emojis:
+  - 🧠 Memory operations
+  - 🛡️ Security / Vibeguard alerts
+  - ⚡ High-speed actions
+  - 📍 Active working state
+- Strip ANSI codes when output is piped to files or non-interactive terminals.

package/.agents/context/current.md

@@ -0,0 +1,41 @@
+# 📍 Current Shipped State & Active Invariants
+
+> **Version**: `v2.0.0`  
+> **Status**: Production Release (Autonomous Cognitive Engine Overhaul)
+
+---
+
+## 🚀 Shipped Capabilities
+
+1. **Dual-Scope Cognitive Engine**: Project-local `.memory/` and global `~/.memory/`.
+2. **Deterministic Lifecycle Machine**: Propose → Candidate → Confirm → Supersede → Stale → Delete.
+3. **Model Context Protocol (MCP)**: Native stdio server implementing MCP 2024-11-05.
+4. **Universal Agent Detection**: Auto-detects and connects 80+ coding agent platforms.
+5. **Universal Migrator**: Imports memories from 24+ external formats (AgentMemory, Mem0, Letta, etc.).
+6. **Vibeguard Secret Defense**: Built-in regex scanner preventing credential commits to memory.
+7. **Compounding & Rollups**: Temporal rollups and token-bag centroid clustering.
+8. **In-Process L0 Hot Memory Cache & L1 Context Cache**: Sub-50 microsecond entry lookups, O(1) query caching, and mtime-synchronized dual persistence.
+9. **SQLite FTS5 BM25 Engine**: Integrated full-text search virtual tables with sub-2ms lexical search.
+10. **Memory Quality & Deduplication**: Deterministic SHA-256 content fingerprinting, canonical memory consolidation with supporting evidence arrays, and temporal mode inference (`current`, `historical`, `timeless`).
+11. **Contradiction Engine**: Semantic conflict detection, first-class `conflicted` state machine with mutual `conflict_ids`, and multi-strategy resolution (`supersede`, `historical`, `reject`, `keep_both`).
+12. **Utility Tracking & Memory ROI**: Operational feedback loop tracking `application_count`, `successful_applications`, `regressions`, `reuse_success_rate`, and automated dispute escalation.
+13. **Ephemeral Observation Tier**: Structured append-only event logging in `.memory/observations.jsonl` from tool results, test outputs, build errors, and review comments.
+14. **First-Class Negative Memories**: Explicit capture of `DO_NOT_USE`, `FAILED_APPROACH`, and `BUG_PRONE_PATTERN` with reproduction commands and timeless salience.
+15. **Autonomous Distillation & Outcome Feedback Loop**: Distills raw observation streams into candidate fixes/architecture, coupled with automatic session command evaluation and memory reinforcement.
+16. **Pluggable Code Intelligence Architecture**: Pluggable provider registry with zero-crash fallback chain (CodeGraph → Graphify → LSP → Heuristic AST scanner → Safe Empty) and automated symbol evidence memory enrichment.
+17. **Multi-Factor Ranking Engine**: 11-dimension scoring model combining exact symbol matching, path proximity, FTS5 BM25, graph overlap, blast radius, recency decay, utility ROI, negative warning boosts, and knapsack token budget packing.
+18. **Context Compaction & Session Handoff Engine**: 70% context usage threshold detector, 5-invariant lockdown protocol, interruption-proof CURRENT.md checkpoint compilation, and continuous conversational knowledge harvesting.
+19. **Scoped Promotion, Generalization & Archival Lifecycle Engine**: 3-tier scope ladder (`local` → `project` → `global`), 5× repeated success policy gate, structural generalization of project specifics into universal principles, and extended archival lifecycle (`active` → `cold` → `dormant` → `archived`) with dynamic query rehydration.
+20. **Native Code Anchors & Stable Structural Code Identity**: First-class code anchors (`repository`, `file`, `module`, `symbol`, `route`, `test`), line-independent structural fingerprinting with comment/spacing normalization, and live drift/orphan verification (`valid`, `drifted`, `orphaned`) with repository audit scoring.
+21. **Flagship Unified Context Orchestrator & Task-Focused MCP Profiles**: Flagship `muse_context` tool fusing active constraints, code anchors, ranked memories, and negative lessons under strict token budgets with suggested next actions; bidirectional code ↔ memory lookups (`muse_code_for_memory`, `muse_memory_for_code`); and 6 task-focused MCP profiles (`core`, `coding`, `debugging`, `review`, `architecture`, `maintenance`) preventing agent tool bloat.
+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.
+
+---
+
+## 🔒 Active System Invariants
+
+- **Zero External Daemons**: All operations must execute in-process via SQLite (`memory.db`) or flat files. Never depend on background servers.
+- **Fail Fast**: Throw loudly on secret detection, invalid schema shapes, or unconfirmed supersessions.
+- **Verification Gate**: Before declaring changes complete, `bun test`, `bun run build`, and `tsc --noEmit` must pass.

package/.agents/context/decisions.md

@@ -0,0 +1,25 @@
+# 🏛️ Locked Architectural Decisions (ADRs)
+
+> **Directive**: These decisions are binding. Do not casually reopen or refactor away from these foundations.
+
+---
+
+### ADR-001: Zero-Daemon, File-Backed Engine
+- **Decision**: All storage and indexing run in-process using embedded SQLite (`bun:sqlite` / SQLite3) and flat Markdown/JSON files.
+- **Rationale**: Developers and AI agents must not be blocked by disconnected Docker containers or background server crashes.
+
+### ADR-002: Dual-Persistence (SQLite + YAML Mirror)
+- **Decision**: Memory entries are stored in indexed SQLite for sub-millisecond retrieval and simultaneously mirrored to `.memory/memories/*.yaml`.
+- **Rationale**: Enables lightning-fast programmatic queries while preserving 100% human and Git diff readability.
+
+### ADR-003: MCP Stdio Protocol
+- **Decision**: Implement Model Context Protocol via standard I/O (`stdio`).
+- **Rationale**: Cleanest, lowest-overhead integration across all AI agent harnesses (Claude Code, Cursor, Antigravity, OpenCode).
+
+### ADR-004: In-Flight Secret Interception (Vibeguard)
+- **Decision**: Secrets are scanned in-memory before file writes and rejected immediately.
+- **Rationale**: Once a secret enters a local database or git repository, rotating and purging it causes severe disruption.
+
+### ADR-005: Bun-First Runtime & Toolchain
+- **Decision**: Use Bun as the primary test runner, bundler, and local runtime, compiling to portable Node.js binaries for npm distribution.
+- **Rationale**: Instant test iteration (`bun test`) and seamless zero-dependency distribution.

package/.agents/context/index.md

@@ -0,0 +1,16 @@
+# 📖 Muse Memory Context Index
+
+> **Reading Directive**: Durable project truth for Muse Memory lives in `./.agents/context/`. Start at this index, then load **only** the specific context file your active task requires.
+
+---
+
+## Context Navigation Map
+
+| File | Scope & Contents | When to Read |
+| :--- | :--- | :--- |
+| [`product.md`](./product.md) | Product scope, CLI tools (`memory`, `musememory`), and MCP tool matrix | Understanding user commands, capabilities, and MCP protocols |
+| [`architecture.md`](./architecture.md) | Dual-Scope storage (`.memory/`), SQLite DB, retrieval scoring formula, and file layout | System design, file locations, state machine, and data flow |
+| [`brand.md`](./brand.md) | Persona profiles (`USER.md` archetypes), voice, and presentation rules | Writing prompts, terminal output copy, and user documentation |
+| [`current.md`](./current.md) | Current shipped state (v2.0.0), test coverage, and active constraints | Before starting work on bugs, features, or refactors |
+| [`decisions.md`](./decisions.md) | Locked architectural decisions (zero-daemon, file-backed SQLite, atomic I/O) | Evaluating technical choices or refactors |
+| [`roadmap.md`](./roadmap.md) | Planned improvements, ecosystem expansions, and backlog | Scoping new capabilities |

package/.agents/context/product.md

@@ -0,0 +1,94 @@
+# 📦 Muse Memory Product Scope & Capabilities
+
+> **Binary Names**: `memory` (primary), `musememory` (alias), `npx musememory` (zero-install)  
+> **MCP Protocol**: MCP 2024-11-05 (stdio transport)  
+> **Runtime**: Bun / TypeScript (Node-compatible bundle)
+
+---
+
+## 🎯 Executive Overview
+
+Muse Memory is a zero-daemon, file-backed cognitive memory engine designed to give AI agents (Claude Code, Cursor, Antigravity, Windsurf, Codex, Gemini CLI, Hermes, OpenCode, OpenClaw, etc.) persistent, self-organizing memory across sessions without external database daemons or cloud servers.
+
+---
+
+## 🔌 Comprehensive MCP Tool Matrix
+
+### 🎯 Flagship Orchestration & Intelligence Tools
+| MCP Tool | Execution Phase | Agent Purpose |
+| :--- | :--- | :--- |
+| `muse_context` | **Flagship Orchestration** | Unified context fusion: single-call query combining search, active file, symbol, error messages, and task intent under strict knapsack token budgets. |
+| `muse_health` | **Quality Gate** | 5-Pillar Project Health Gate: single-call audit of store integrity, code anchors, doc/code alignment, anti-pattern sentry, and technical debt with A-F grading and PASS/WARN/FAIL status. |
+| `muse_why` | **Cognition / "Why" Reasoner** | Traces code evolution backwards through past bug fixes, ADRs, trade-offs, and invariants to explain *why* code is designed the way it is before refactoring. |
+| `muse_bug_clusters` | **Fragility Hotspots** | Clusters recurring bugs into 5 root-cause categories with subsystem fragility scoring. |
+| `muse_tech_debt` | **Technical Debt Registry** | Scans code and memory for TODO/FIXME markers, unsafe `as any` casts, and drifted anchors with remediation advice. |
+| `muse_memory_for_code`| **Code-to-Memory** | Queries all memories, ADRs, constraints, and bugs associated with a code file and symbol. |
+| `muse_code_for_memory`| **Memory-to-Code** | Resolves all native code anchors and affected source files for a given memory entry. |
+| `memory_adr_record` | **Architecture Decisions**| Records first-class ADRs with drivers, decision, consequences, options considered, and native code anchors. |
+| `memory_adr_list` | **ADR Discovery** | Lists architecture decision records filtered by status (`proposed`, `accepted`, `superseded`, `rejected`). |
+| `memory_drift_audit` | **Drift Detection** | Bi-directional documentation $\longleftrightarrow$ code drift engine across 6 alignment states. |
+| `memory_capture_negative` | **Negative Sentry** | Records failed approaches, anti-patterns, and reproduction commands to prevent repeating mistakes. |
+| `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. |
+
+### 🛠️ Core Memory & Lifecycle Tools
+| MCP Tool | Execution Phase | Agent Purpose |
+| :--- | :--- | :--- |
+| `get_context` | **Session Start / Init** | Fast token-budgeted prompt context injection: retrieves `USER.md`, active `CURRENT.md` constraints, and top-$K$ scored memories. |
+| `memory_capture` | **Learning / Task End** | Capture new durable facts, verified architectural decisions, operational rules, or bug resolutions directly into memory. |
+| `memory_propose` | **Speculative Learning** | Propose a candidate memory requiring confirmation before permanent indexing. |
+| `memory_confirm` | **Validation Phase** | Promote a `candidate` or `disputed` memory to `confirmed` status. |
+| `memory_supersede` | **Refactoring / Updates** | Formally link an obsolete memory to a newer confirmed memory so agents never hallucinate deprecated patterns. |
+| `memory_search` | **Targeted Lookups** | Query the SQLite store and YAML mirrors using multi-factor similarity matching and tags. |
+| `memory_conflicts` | **Conflict Audit** | Lists conflicting memories detected by the semantic contradiction engine. |
+| `memory_resolve_conflict` | **Conflict Resolution**| Resolves contradictions via `supersede`, `historical`, `reject`, or `keep_both`. |
+| `memory_roi` | **Utility & ROI** | Computes memory reuse metrics, application success rates, and regression penalties. |
+| `memory_search_transcripts` | **Historical Archaeology** | Full-text dialogue search across past JSONL conversation transcripts with conversation bookends. |
+| `memory_audit` | **Compliance Check** | Inspect the append-only operational ledger (`.memory/audit.jsonl`). |
+| `profile_list` / `switch` | **Tool Management** | Lists and activates task-focused MCP profiles to eliminate agent tool bloat. |
+
+---
+
+## ⚙️ Task-Focused MCP Profiles
+
+Muse Memory prevents agent context bloat by providing 6 pre-configured tool profiles:
+
+- **`core`** (Minimal): `get_context`, `memory_search`, `memory_capture`, `memory_current`, `profile_list`, `profile_switch`.
+- **`coding`**: Core tools + `muse_context`, `muse_why`, `muse_code_for_memory`, `muse_memory_for_code`, `anchor_*`.
+- **`debugging`**: Core tools + `muse_why`, `muse_bug_clusters`, `memory_capture_negative`, `memory_verify`.
+- **`review`**: Core tools + `muse_health`, `muse_tech_debt`, `memory_drift_audit`, `anchor_audit`.
+- **`architecture`**: Core tools + `muse_context`, `muse_health`, `memory_adr_*`, `memory_drift_audit`, `muse_why`.
+- **`maintenance`**: Core tools + `muse_health`, `memory_promote_scope`, `memory_archive`, `memory_archive_sweep`, `memory_lifecycle_stats`.
+- **`full`**: Unrestricted exposure of all 61 MCP tools.
+
+---
+
+## 💻 CLI Command Surface
+
+```bash
+# Health & Observability (5-Pillar Quality Gate)
+memory health [--json] [--global]
+
+# Retrieval & Context
+memory context [--query "..."] [--budget 2000] [--tier 0|1|2]
+memory search "<query>" [--tags arch,auth]
+memory recall "<id>"
+
+# Knowledge Lifecycle
+memory capture --title "..." --type architecture --content "..."
+memory propose --title "..." --content "..."
+memory confirm <id>
+memory supersede <old-id> <new-id>
+memory stale <id>
+memory audit [--limit 20]
+
+# Personas & Constraints
+memory persona [developer|designer|marketer|casual]
+memory current --add "Must use Bun v1.2"
+
+# Diagnostics & Server
+memory doctor
+memory validate --dry-run
+memory mcp [--profile coding|review|architecture|core|full]
+```

package/.agents/context/roadmap.md

@@ -0,0 +1,12 @@
+# 🗺️ Muse Memory Roadmap & Backlog
+
+---
+
+## 🚀 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.

package/.agents/research/research-brief-agent-memory-migrator.md

@@ -0,0 +1,245 @@
+# Research Brief: Autonomous Multi-Provider Agent Memory Migrator & State Preservation Architecture
+
+**Depth**: deep  
+**Date**: 2026-08-22  
+**Target Repository**: `harshsinghmp/musememory`  
+**Primary Deliverable**: Interactive Dashboard at [`musemeory-comparison.html`](file:///home/harsh/Projects/musememory/musemeory-comparison.html) & Autonomous First-Install Migrator
+
+---
+
+## 1. Executive Summary
+
+Autonomous AI coding agents (Claude Code, Cursor, Antigravity, Windsurf, Codex, Gemini CLI) frequently experience fragmented context across sessions. While over 24 different memory engines, graph RAG platforms, and agent harnesses have emerged, they suffer from four critical architectural liabilities:
+1. **Infrastructure Bloat**: Heavy dependencies on external vector databases (Milvus, Qdrant, Chroma, Neo4j, LanceDB) or background daemon processes (Rust, Python).
+2. **Zero-Leakage Security Vulnerabilities**: Lack of inline secret/credential interception before disk or cloud persistence.
+3. **Context Window Flooding**: Retrieval based on unbounded Top-$K$ dumps rather than exact prompt token knapsack budgeting.
+4. **Scope Contamination**: Shared global state without clean per-repository workspace isolation (`.memory/`).
+
+**Muse Memory** solves these issues with a zero-dependency, pure TypeScript, dual-scoped (`.memory/` vs `~/.memory/`), atomic YAML/JSONL architecture with inline **Vibeguard** credential interception and exact **Token Budgeting**.
+
+This research brief defines the **Autonomous First-Install Migrator** (`memory migrate` / `memory init --auto-import`) capable of auto-detecting and ingesting memories across all 24 popular providers while strictly preserving active vs. archived/superseded state hierarchies and workspace isolation.
+
+---
+
+## 2. Comprehensive 24-Provider Landscape & Feature Comparison
+
+| # | Provider / System | Storage Backend | Scoping Model | Active vs. Archive Mapping | Secret Protection | Token Budgeting | Permission-Free Auto-Wiring | Offline / Air-Gapped |
+|---|---|---|---|---|---|---|---|---|
+| **★** | **🧠 Muse Memory** | Atomic YAML + JSONL Ledger | Dual (`.memory/` + `~/.memory/`) | `confirmed` / `superseded` / `CURRENT.md` | ✅ **Vibeguard Inline** | ✅ **Exact Knapsack** | ✅ **1-Click Auto-Approve** | ✅ **100% Standalone** |
+| 1 | **Supermemory** | Temporal Vector-Graph (SQLite / Cloudflare KV) | Global Spaces + Tags | `is_archived: false` ➔ `confirmed`, `true` ➔ `superseded` | ⚠️ Basic | ❌ Unbounded Top-K | ⚠️ Manual API | ⚠️ Hybrid Cloud |
+| 2 | **Cognee** | Graph RAG (LanceDB / Kuzu / Neo4j / SQLite) | Global Dataset Namespaces | Pruned/Deprecated Edges ➔ `superseded` | ❌ None | ⚠️ Chunk Limits | ⚠️ Python Lib | ✅ Self-Hostable |
+| 3 | **Beads** | Git JSON Issue Beads (`.beads/`) | Local Workspace Only | `open/in_progress` ➔ `CURRENT.md`, `closed` ➔ `superseded` | ❌ None | ❌ Full Bead Dump | ⚠️ CLI Init | ✅ 100% Local |
+| 4 | **Memori** | SQLite / Postgres Episodic Graph | Global with Session IDs | `active` ➔ `confirmed`, `decayed` ➔ `stale/superseded` | ❌ None | ⚠️ Top-K Items | ⚠️ Middleware | ✅ Local SQLite |
+| 5 | **memU** | Hierarchical 3-Layer FS (Item/Category) | Global Categories + Local | `working_memory` ➔ `CURRENT.md`, `archival` ➔ `superseded` | ⚠️ Basic | ⚠️ Category Limit | ⚠️ Manual | ✅ Local Files |
+| 6 | **EverOS** | Markdown Files + LanceDB / SQLite | Dual (`.everos/` + `~/.everos/`) | `active` ➔ `confirmed`, `archived` ➔ `superseded` | ⚠️ Basic | ⚠️ BM25 + Top-K | ⚠️ Manual Config | ✅ 100% Local |
+| 7 | **Semantica** | Graph Triples & Reasoning Ledger | Global Graph + Project Tags | `valid_until: null` ➔ `confirmed`, `invalid` ➔ `superseded` | ❌ None | ⚠️ Graph Depth | ⚠️ Manual API | ✅ Self-Hosted |
+| 8 | **Honcho** | Dialectic Metamodels (Postgres/SQLite) | Global User/Agent Dialectics | `current_representation` ➔ `confirmed`, `history` ➔ `superseded` | ❌ None | ✅ Reasoned Compression | ⚠️ MCP/SDK | ✅ Local Server |
+| 9 | **Kungfu** | Local Checkpoint Ledger (`.kungfu/`) | Local Workspace | `current_task` ➔ `CURRENT.md`, `completed` ➔ `confirmed` | ❌ None | ❌ Full Checkpoint Dump | ⚠️ CLI Init | ✅ 100% Local |
+| 10 | **Letta Code** | Core Memory + Archival SQLite | Global Agent Identity | `core_memory` ➔ `CURRENT.md`, `archival` ➔ `confirmed/superseded` | ❌ None | ⚠️ Fixed Char Blocks | ⚠️ Agent Server | ✅ Local Docker/Server |
+| 11 | **MemSearch** | 3-Tier Markdown + Milvus Vector Store | Global Vector Index | `tier: summary` ➔ `confirmed`, `transcript` ➔ `session` | ❌ None | ⚠️ Layer Selection | ⚠️ Python API | ⚠️ Requires Milvus |
+| 12 | **ACE (Kayba)** | AST Token Compression & Playbooks | Workspace Playbooks | `active_strategy` ➔ `confirmed`, `refuted` ➔ `rejected` | ❌ None | ✅ AST Token Budget | ⚠️ MCP Bridge | ✅ Local Engine |
+| 13 | **Actx0** | Cloud API Session History & Cache | Cloud API Tenant | `active_session` ➔ `confirmed`, `expired` ➔ `stale` | ⚠️ Cloud Managed | ✅ Dynamic Prompt Cache | ⚠️ API Key | ❌ Cloud Only |
+| 14 | **ByteRover** | Markdown Context Tree (Domain/Topic) | Local Workspace | `live` ➔ `confirmed`, `archived` ➔ `superseded` | ❌ None | ⚠️ Subtree Pruning | ⚠️ CLI Init | ✅ 100% Local |
+| 15 | **Clawdi** | Cloud VM Shared State & Persistent Files | Cloud Agent Fleet | `pinned_rules` ➔ `CURRENT.md`, `history` ➔ `confirmed` | ℹ️ TEE Encrypted | ❌ Unbounded Dump | ⚠️ Cloud Auth | ❌ Cloud Only |
+| 16 | **Pensieve** | Enterprise Knowledge Graph | Global Enterprise Vault | `active` ➔ `confirmed`, `obsolete` ➔ `superseded` | ⚠️ RBAC | ⚠️ Subgraph Limit | ⚠️ Enterprise | ⚠️ Hybrid |
+| 17 | **Liminary** | AI-Native Semantic Document Layer | Corpus Workspaces | `active_cluster` ➔ `confirmed`, `archived` ➔ `superseded` | ⚠️ Cloud Encrypted | ⚠️ Chunk Top-K | ⚠️ API Key | ❌ Cloud Only |
+| 18 | **Dvina** | Cross-App Dynamic Vector Sync | Multi-App Global | `focus_context` ➔ `CURRENT.md`, `history` ➔ `confirmed/superseded`| ⚠️ OAuth | ⚠️ App Scoped | ⚠️ OAuth Setup | ❌ Cloud SaaS |
+| 19 | **Mem0** | Scoped Vector + Graph Store (Qdrant) | Global with `user_id`/`agent_id` | `is_active: true` ➔ `confirmed`, `deleted` ➔ `superseded` | ❌ None | ❌ Unbounded Top-K | ⚠️ Python/MCP | ✅ Local SQLite Mode |
+| 20 | **Second Brain** | Cloudflare Workers + D1 + Obsidian | Global Obsidian Vault | `tags: [active]` ➔ `confirmed`, `tags: [archive]` ➔ `superseded` | ❌ None | ⚠️ Vector Top-K | ⚠️ Worker Setup | ⚠️ Cloudflare Edge |
+| 21 | **Rory Plans** | Agentic Work Execution & Task Plans | Workspace Plans | `in_progress` ➔ `CURRENT.md`, `completed` ➔ `confirmed` | ⚠️ Workspace ACL | ❌ Full Plan Dump | ⚠️ Web Portal | ❌ Cloud Only |
+| 22 | **Minimi** | Ambient Desktop Context & Open Loops | Desktop User-Wide | `open_loops` ➔ `CURRENT.md`, `resolved` ➔ `confirmed` | ⚠️ Sandbox | ⚠️ Active Loop Limit | ⚠️ Mac Helper | ✅ 100% Local (macOS) |
+| 23 | **Mem.ai** | AI-First Associative Note Graph | Global User Notes | `is_archived: false` ➔ `confirmed`, `true` ➔ `superseded` | ⚠️ SOC2 / Cloud | ❌ Cloud Search Dump | ⚠️ OAuth Sync | ❌ Cloud SaaS |
+| 24 | **AgentMemory** | Rust `iii-engine` + SQLite State Store | Global (`~/.local/share/agentmemory`)| `crystal/lesson` ➔ `confirmed`, `superseded` ➔ `superseded` | ❌ None (Raw SQL) | ❌ Unbounded SQL | ⚠️ Daemon Required | ✅ Local Binary |
+
+---
+
+## 3. Structural Preservation & State Transition Rules
+
+When migrating memories from external providers into Muse Memory, the migrator executes strict deterministic state preservation:
+
+```
+┌────────────────────────────────────────────────────────┐
+│               Source Provider Memory State             │
+└──────────────────────────┬─────────────────────────────┘
+                           │
+         ┌─────────────────┼─────────────────┐
+         ▼                 ▼                 ▼
+   [Live / Active]    [Deprecated]     [Active Loops]
+   [Confirmed / Open] [Archived]       [Human / Core]
+         │                 │                 │
+         ▼                 ▼                 ▼
+┌─────────────────┐┌─────────────────┐┌─────────────────┐
+│ status: confirmed││status: superseded││ CURRENT.md      │
+│ (or active)     ││ (or stale)      ││ (Hard Pin)      │
+└─────────────────┘└─────────────────┘└─────────────────┘
+```
+
+1. **Active / Valid Knowledge**:
+   - Mapped to `status: confirmed` (or `status: active`).
+   - If tagged with verification metadata, mapped to `verification: { level: "independently-verified", verified_by: "migrator" }`.
+2. **Archived / Deprecated / Superseded Knowledge**:
+   - Mapped to `status: superseded` (or `status: stale`).
+   - Retains historical links and deprecation reason (e.g. `reason: "Imported as archived from <provider>"`).
+3. **Core Persona / Open Loops / In-Progress Tasks**:
+   - Appended directly to `.memory/CURRENT.md` (or `~/.memory/CURRENT.md`) as active working constraints.
+4. **Scope Isolation**:
+   - Workspace-specific providers (Beads, Kungfu, ByteRover, local `.everos/`) ➔ Imported to `.memory/` in the active repository.
+   - User-wide providers (Mem0, Letta, Supermemory, AgentMemory) ➔ Imported to `~/.memory/` globally.
+5. **Zero-Leakage Interception**:
+   - All extracted memory texts pass through `scanSecrets(text)` before write. If credentials are detected, the payload is either redacted or blocked with an audit warning.
+
+---
+
+## 4. Autonomous Migrator Architecture & Engine Design
+
+### Pipeline Modules
+
+```
+musememory/
+├── src/
+│   ├── migrator/
+│   │   ├── types.ts          # Migrator interfaces & provider signatures
+│   │   ├── detect.ts         # Fast scanner detecting active providers
+│   │   ├── engine.ts         # Ingestion pipeline & Vibeguard sanitizer
+│   │   └── adapters/
+│   │       ├── sqlite.ts     # Generic SQLite reader (AgentMemory, Mem0, Memori)
+│   │       ├── markdown.ts   # Markdown parser (ByteRover, EverOS, Beads, SecondBrain)
+│   │       ├── json.ts       # Structured JSON parser (Letta, Kungfu, ACE, Minimi)
+│   │       └── logs.ts       # Log & session transcript extractor (Supermemory)
+```
+
+### Detection Heuristics Table
+
+```typescript
+export const PROVIDER_DETECTORS = [
+  {
+    id: "agentmemory",
+    name: "AgentMemory",
+    paths: [
+      "~/.local/share/agentmemory/state_store.db",
+      "~/.agentmemory/standalone.json"
+    ],
+    adapter: "agentmemory"
+  },
+  {
+    id: "supermemory",
+    name: "Supermemory",
+    paths: [
+      "~/.supermemory",
+      "~/.opencode-supermemory.log"
+    ],
+    adapter: "supermemory"
+  },
+  {
+    id: "beads",
+    name: "Beads",
+    paths: [
+      ".beads/beads.json",
+      ".beads"
+    ],
+    adapter: "beads",
+    scope: "local"
+  },
+  {
+    id: "mem0",
+    name: "Mem0",
+    paths: [
+      "~/.mem0/mem0.db",
+      ".mem0/mem0.json"
+    ],
+    adapter: "mem0"
+  },
+  {
+    id: "letta",
+    name: "Letta Code / MemGPT",
+    paths: [
+      "~/.letta",
+      "~/.memgpt",
+      ".letta"
+    ],
+    adapter: "letta"
+  },
+  {
+    id: "everos",
+    name: "EverOS",
+    paths: [
+      ".everos/memories",
+      "~/.everos"
+    ],
+    adapter: "everos"
+  },
+  {
+    id: "byterover",
+    name: "ByteRover",
+    paths: [
+      ".byterover",
+      "~/.byterover"
+    ],
+    adapter: "byterover",
+    scope: "local"
+  },
+  {
+    id: "kungfu",
+    name: "Kungfu",
+    paths: [
+      ".kungfu/checkpoints",
+      "~/.kungfu"
+    ],
+    adapter: "kungfu",
+    scope: "local"
+  },
+  {
+    id: "minimi",
+    name: "Project Minimi",
+    paths: [
+      "~/Library/Application Support/Minimi",
+      "~/.minimi"
+    ],
+    adapter: "minimi"
+  }
+];
+```
+
+---
+
+## 5. Implementation Phases & Roadmap
+
+- **Phase 2.1: Migrator Detection & Adapter Engine**:
+  - Implement `src/migrator/detect.ts` to scan local workspace and home directories.
+  - Implement adapters for SQLite, Markdown trees, JSON dumps, and JSONL transcripts.
+- **Phase 2.2: First-Install Auto-Detection Hook**:
+  - In `src/cli.ts` (`memory init` & `memory connect`), detect existing providers and offer 1-command migration (`memory migrate --all`).
+- **Phase 2.3: State Preservation & Audit Integration**:
+  - Map active, archived, and working constraints accurately.
+  - Log audit events in `.memory/audit.jsonl` with `operation: "import"` / `operation: "migration"`.
+- **Phase 2.4: Verification & Automated Test Suites**:
+  - End-to-end tests for multi-provider import and secret redaction.
+
+---
+
+## 6. Sources & References
+
+1. Supermemory: `https://github.com/supermemoryai/supermemory`
+2. Cognee: `https://github.com/topoteretes/cognee`
+3. Beads: `https://github.com/gastownhall/beads`
+4. Memori: `https://github.com/MemoriLabs/Memori`
+5. memU: `https://github.com/NevaMind-AI/memU`
+6. EverOS: `https://github.com/EverMind-AI/EverOS`
+7. Semantica: `https://github.com/semantica-agi/semantica`
+8. Honcho: `https://github.com/plastic-labs/honcho`
+9. Kungfu: `https://github.com/kungfu-systems/kungfu`
+10. Letta Code: `https://github.com/letta-ai/letta-code`
+11. MemSearch: `https://github.com/zilliztech/memsearch`
+12. ACE: `https://github.com/kayba-ai/agentic-context-engine`
+13. Actx0: `https://actx0.com/`
+14. ByteRover: `https://www.byterover.dev/`
+15. Clawdi: `https://www.clawdi.ai/`
+16. Pensieve: `https://pensieve.uk/`
+17. Liminary: `https://liminary.io/`
+18. Dvina: `https://dvina.ai/`
+19. Mem0: `https://mem0.ai/`
+20. Second Brain Cloudflare: `https://github.com/rahilp/second-brain-cloudflare`
+21. Rory Plans: `https://www.roryplans.ai/`
+22. Project Minimi: `https://www.projectminimi.com/`
+23. Mem.ai: `https://get.mem.ai/`
+24. AgentMemory: `https://github.com/rohitg00/agentmemory`