🧠 Muse Memory

Autonomous, Self-Organizing Cognitive Memory System for AI Agents & Agency Networks

🚀 What's New

v2.3.0

• Autonomous Memory Optimizer (memory optimize): High-precision noise and junk pruning engine with zero-daemon auto-cadence (every 7 days or after 48h idle) and SQLite WAL defragmentation (VACUUM; + PRAGMA optimize;).
• Dashboard "⚡ Optimize" Trigger: Live visual optimization controls directly inside the Web Observability Studio (memory ui / memory studio) with real-time feedback on items pruned and bytes reclaimed.
• Concurrent Multi-Agent Workstream Tracking: Live coordination table in CURRENT.md enabling multiple agents across parallel chats to monitor active tasks and target scopes without collisions.
• Clean Operational Guidelines: Curated single-pane executive summary for humans and strict grounding/concurrency rules for AI agents.

v2.2.0

• Unified Code & Memory Impact Analysis: Pre-flight blast radius analysis evaluating AST callers, test suites, governing ADRs, negative warnings, and risk levels (memory code-impact / muse_code_impact).
• PR & Change Context Generator: Automatically turns git diffs into rich, memory-grounded GitHub PR descriptions linking touched anchors and active constraints (memory pr-context / muse_pr_context).
• Interactive Code Anchor Reconciler: Audits and repairs code anchors across memories, pruning dead references and updating structural hashes (memory reconcile / muse_reconcile_anchors).
• Latency & Quality Telemetry Suite: Benchmarks microsecond hot caches, FTS5 BM25 search, knapsack token packing, and ROI in a clean ASCII scoreboard (memory benchmark).
• Expanded Agent Skills: Shipped turnkey skills for muse-health, muse-drift, muse-why, muse-sync, and muse-mesh.

v2.1.0

• Cross-Agent Knowledge Sync & P2P Gossip Protocol: Sealed portable SyncPacket engine with SHA-256 integrity and zero-daemon shared filesystem gossip pool (memory sync / muse_sync_*).
• Web Observability Studio: Embedded visual dashboard (memory studio / memory ui) with interactive 5-pillar health, ADR registry, code drift inspector, and sync controls.
• Monorepo & Multi-Repo Mesh: Automatic workspace discovery (pnpm, npm, bun, lerna) with cross-project memory queries and shared constraint propagation (memory mesh / muse_mesh_*).

v2.0.0

• 5-Pillar Project Health Gate: Architectural health gate evaluating store integrity, code anchors, doc-code alignment, negative sentry, and technical debt (memory health / muse_health).
• Cognitive "Why" Reasoner: Reconstructs historical code evolution, bug workarounds, and trade-offs before refactoring (muse_why).
• Living Architecture Decision Records (ADRs): Queryable ADRs with options, consequences, native code anchors, and supersession lineage (memory adr / memory_adr_record).
• Doc ⟷ Code Drift Engine: Continuously audits documentation against AST code implementations across 6 drift states (memory drift / memory_drift_audit).
• Unified Context Orchestrator & MCP Profiles: Single-call fused context injection with knapsack token packing (muse_context) and task-specific tool profiles.
• Native Structural Code Anchors: Line-independent structural SHA-256 hashing for files, symbols, and routes.
• Scoped Promotion & Archival Lifecycle: 3-tier promotion ladder (local → project → global) and cold/dormant/archived storage tiers.

📑 Table of Contents

• 🚀 What's New
• 💡 What is Muse Memory? (TL;DR)
• ✨ Key Feature Highlights
• ⚡ Quick Start & Installation
• 🔄 Upgrading & Self-Healing Maintenance
• 🧠 Shipped Agent Skills (.agents/skills/)
• 👤 5 Role Archetypes (USER.md)
• 🔌 Full CLI Command Matrix
• 🛡️ Vibeguard Zero-Leakage Protocol
• 🧪 Testing & Verification
• 🔮 Sprint & Roadmap Board
• 📜 License

💡 What is Muse Memory? (TL;DR)

Most AI chatbots and coding assistants have "goldfish memory": every time you close a session, switch tasks, or start a new prompt, they forget your project invariants, coding habits, and the hard-fought bug workarounds you solved yesterday.

Muse Memory gives your AI assistants a persistent, self-organizing cognitive notebook directly on your machine.

┌─────────────────────────────────────────────────────────────────────────────┐
│                 AI Agents, Subagent Pods & Autonomous Swarms                 │
│        (Claude Code, Cursor, Antigravity, Windsurf, Codex, CLI)             │
└───────────────────────┬─────────────────────────────────────┬───────────────┘
                        │ MCP stdio / Terminal CLI            │ Local HTTP
┌───────────────────────▼─────────────────────────────────────▼───────────────┐
│                           Muse Memory Core Engine                           │
│                                                                             │
│ ┌──────────────────────┐ ┌──────────────────────┐ ┌───────────────────────┐ │
│ │  Unified Context &   │ │ 5-Pillar Health Gate │ │ Autonomous Cognition  │ │
│ │  Knapsack Retrieval  │ │  & ADR Drift Sentry  │ │   & "Why" Reasoner    │ │
│ └──────────────────────┘ └──────────────────────┘ └───────────────────────┘ │
│ ┌──────────────────────┐ ┌──────────────────────┐ ┌───────────────────────┐ │
│ │   P2P Gossip Sync    │ │  Monorepo Workspace  │ │   Web Observability   │ │
│ │  (Vector Clock Mesh) │ │  Cross-Project Mesh  │ │ Studio (memory studio)│ │
│ └──────────────────────┘ └──────────────────────┘ └───────────────────────┘ │
│ ┌──────────────────────┐ ┌──────────────────────┐ ┌───────────────────────┐ │
│ │ Vibeguard Credential │ │ Dynamic Code Anchors │ │ Universal Migrator    │ │
│ │    Secret Defense    │ │ & Structural Hashes  │ │     (29 Engines)      │ │
│ └──────────────────────┘ └──────────────────────┘ └───────────────────────┘ │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │ Atomic SQLite & File I/O
┌──────────────────────────────────────▼──────────────────────────────────────┐
│                     Dual-Scope Storage Engine (.memory/)                    │
│                                                                             │
│  .memory/                                                                   │
│  ├── memory.db          # Primary SQLite database (WAL + FTS5 BM25)         │
│  ├── CURRENT.md         # Real-time working constraints & session handoffs  │
│  ├── USER.md            # Persona archetypes & working style preferences    │
│  ├── sync_pool/         # Zero-daemon shared P2P gossip pool drop folder    │
│  ├── mesh_links.json    # Explicit multi-repo cross-project mesh links      │
│  ├── sync_peers.json    # Peer agent vector clock causal tracking ledger    │
│  ├── audit.jsonl        # Append-only operational audit & compliance trail  │
│  └── memories/          # Dual-persisted human-readable YAML mirror         │
│      ├── m_1700000001000_auth.yaml                                          │
│      └── m_1700000002000_mesh.yaml                                          │
└─────────────────────────────────────────────────────────────────────────────┘

✨ Key Feature Highlights

• 👤 Persona & Style Grounding (USER.md): Configures your role (developer, designer, marketer, casual, custom) and communication preferences so AI models write code that matches your style.
• 📐 Real-Time Active Constraints (CURRENT.md): Bi-temporal working constraints and invariant tracking synchronized on every mutation to eliminate amnesia during task handoffs.
• 💾 SQLite Primary + Dual-Persisted YAML Mirror: Sub-millisecond queries via SQLite with transparent human-readable .yaml files in .memory/memories/ for seamless Git diffs.
• ⚖️ Token Knapsack Retrieval: Multi-factor scoring (applicability, verification bonus, AST graph overlap, time decay, due date urgency) tightly packed under prompt token ceilings.
• 🌐 Pluggable AST CodeGraph & Symbol Indexing: Native CodeGraph & Graphify integration that indexes codebase AST symbols, auto-tags memories, and awards graph overlap bonuses.
• 🌳 Hierarchical Tree Retrieval & Progressive Disclosure: Sharded tree partitions with 3-tier progressive disclosure (L1 abstracts, L2 summaries, L3 full context) for massive knowledge bases.
• 📚 Obsidian Markdown Wiki & Entity Graph Compiler: Dual-persistence knowledge compounding compiling linked Markdown pages (wiki/concepts/, wiki/entities/) with bidirectional [[wikilinks]].
• 🛡️ Vibeguard Zero-Leakage Secret Scanner: Regex-powered memory defense intercepting and rejecting API keys, AWS credentials, private keys, database URIs, and passwords before writes.
• 🔌 Zero-Permission Auto-Wiring (80+ Agents): Automatically detects and wires Claude Code, Cursor, Antigravity, Windsurf, OpenCode, Codex, Gemini CLI, Hermes, etc.
• 🔄 Universal Memory Migrator (29 Engines): One-click migration from Letta, Mem0, Supermemory, Cognee, Beads, Mnemosyne, GBrain, and more with state preservation.
• 🎨 Cognitive Studio Visual Dashboard (memory ui): Embedded zero-dependency web interface featuring 3D force-directed knowledge graphs, live CURRENT.md monitor, wiki reader, and persona editor.
• ⏰ Proactive Nudges & Routines Scheduler: Cron-invoked daily briefings, staleness policy tracking, and ambient open-loop trackers with zero resident background daemons.

⚡ Quick Start & Installation

[!TIP]

⚡ Instant 5-Second Setup (Zero-Install NPX / BunX)

No global installation required. Set up your memory system and wire your AI agents with a single command:

npx musememory install
# (or with Bun: bunx musememory install)

This command automatically:

1. Initializes the SQLite primary database (.memory/memory.db) and CURRENT.md constraints file.
2. Auto-detects all installed AI coding agents on your machine.
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)

📦 Persistent Installation Options

# Option A: Global Install with NPM or Bun (Recommended)
npm install -g musememory
# or with Bun:
bun add -g musememory

# Option B: One-Line Shell Installer
curl -fsSL https://raw.githubusercontent.com/harshsinghmp/musememory/main/scripts/install.sh | bash

# Option C: Docker Container
git clone https://github.com/harshsinghmp/musememory.git && cd musememory
docker build -t musememory .

[!NOTE]

📊 How does Muse Memory compare to other solutions?

🔄 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.

⚡ 1-Command Autonomous Upgrade (memory upgrade)

Run memory upgrade (or npx musememory upgrade) to trigger the Gamified Level-Up Matrix:

memory upgrade
# or with NPX zero-install:
npx musememory upgrade

What memory upgrade automatically handles:

1. Package Manager Auto-Detection: Detects whether your workstation runs bun, npm, pnpm, or yarn and pulls the latest published binary.
2. Self-Healing Storage Repair: Recovers missing .memory/, CURRENT.md constraints, or USER.md persona files if corrupted or deleted.
3. 80+ Agent Platform Re-Discovery: Scans for newly installed coding agents (Cursor, Claude Code, Windsurf, OpenCode, Codex, Gemini CLI, Hermes, etc.) and auto-wires them with zero permissions.
4. AST Symbol Graph Re-Indexing: Re-synchronizes CodeGraph/Graphify symbol caches under .memory/graph-symbols.json.

📦 Manual Package Manager Upgrades

| 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 |

# Check if updates are available without applying
memory upgrade --check

# Force re-installation and complete platform re-wiring
memory upgrade --force

🔄 Complete Lifecycle (Install → Verify → Connect → Uninstall)

Every command works with zero installation via npx musememory <cmd> (or bunx musememory <cmd>). Use plain memory <cmd> if installed globally.

1️⃣ Install & Auto-Wire

# Full setup: init .memory/, detect agents, wire MCP, scan for migratable stores
npx musememory install

# Initialize workspace only (no agent wiring)
npx musememory init

2️⃣ Verify & Health Check

# Comprehensive ecosystem diagnostic (storage, schemas, secrets, MCP wiring)
npx musememory doctor

# Memory store breakdown and active briefing
npx musememory stats
npx musememory briefing

3️⃣ Connect Coding Agents (80+ Platforms)

# Scan workstation for installed AI coding agents
npx musememory agents

# Auto-wire all detected agents with zero permissions
npx musememory connect all

# Wire one specific agent explicitly
npx musememory connect claude-code
npx musememory connect cursor
npx musememory connect antigravity
npx musememory connect windsurf
npx musememory connect opencode

4️⃣ Clean Uninstallation & Removal

Muse Memory can be cleanly and completely removed with zero trace left on your machine.

Step 1: Unwire Coding Agents (Zero-Trace MCP Cleanup)

Remove the memory MCP server configuration from all 80+ detected agent config files (cursor, claude-code, antigravity, windsurf, opencode, codex, etc.):

# Preview changes before modifying any configuration
npx musememory uninstall --dry-run

# Unwire all detected AI coding agents automatically
npx musememory uninstall

# Or unwire a single specific agent
npx musememory uninstall cursor

Step 2: Purge Memory Data & Stores (Optional)

By default, uninstall preserves your project .memory/ data. To completely delete all memory files and databases:

# Unwire agents AND purge local project .memory/ directory
npx musememory uninstall --purge

# Remove global user profile and global memory store (~/.memory/)
npx musememory uninstall --global --purge

# Manual cleanup (equivalent):
rm -rf .memory/           # Local project store
rm -rf ~/.memory/          # Global user profile & store

Step 3: Remove Globally Installed Package

If you installed musememory globally via a package manager:

# If installed via npm:
npm uninstall -g musememory

# If installed via bun:
bun remove -g musememory

# If installed via yarn / pnpm:
pnpm remove -g musememory
yarn global remove musememory

Step 4: Clean Git Hooks & Directives (Optional)

If you installed the pre-commit transcript harvester hook or injected agent prompt directives:

• Git Hook: Delete .git/hooks/pre-commit (or restore your previous hook).
• AGENTS.md: Remove the <!-- musememory:start --> ... <!-- musememory:end --> block from your project's AGENTS.md file.

🏛️ System Capabilities & Architecture

1. Dual-Scope Storage (Local vs Global)

• Local Workspace (<project>/.memory/): Repository-specific architectural decisions, bug fixes, active CURRENT.md constraints, and session timeline nodes.
• Global System (~/.memory/ via --global / -g): Universal developer preferences, cross-repo coding conventions, and global prompt patterns.

2. Deterministic 7-State Lifecycle Machine & Audit Ledger

All memory entries transition through a guarded state machine:

  [propose] ──► candidate ──► confirm() ──► confirmed ──► supersede() ──► superseded
                    │                           │
                    ├──► markStale() ───────────┤
                    │         │                 │
                    │         ▼                 ▼
                    └──►    stale            rejected
                              │
                              └──► delete() ──► [Purged from Disk + audit.jsonl logged]

Every mutation (propose, confirm, supersede, mark_stale, reject, delete, link) writes an immutable log record to .memory/audit.jsonl.

3. Knapsack Token Budgeting & Multi-Factor Scoring

Retrieval dynamically ranks knowledge using a calibrated multi-factor formula: $$\text{Score} = 1.0 \times \text{Applicability} + \text{StatusBonus} + \text{VerificationBonus} + \text{GraphBonus} + \text{SalienceBonus} + 0.3 \times e^{-\frac{\Delta t}{90\text{ days}}}$$ The engine greedily packs ranked memories up to the requested --token-budget to guarantee zero prompt overflow.

4. Real-Time CURRENT.md Synchronization & Session Handoff

• Active constraint memories automatically mirror into CURRENT.md.
• In-flight task states, agent checkpoints, and active loops persist across terminal restarts, context compactions, and sudden interruptions.

5. Unified Compounding: Obsidian Wiki & Entity Graph

• Obsidian Wiki Compiler (memory wiki): Compiles confirmed memory clusters into linked Markdown pages (wiki/concepts/, wiki/entities/) with bidirectional [[slug]] wikilinks.
• Named Entity Extraction (memory entities): Automatically extracts persons, products, organizations, tools, and code symbols with co-occurrence edge weights.
• PageIndex Reasoning Engine (memory pageindex): Indexes unstructured documents into hierarchical reasoning trees.

6. Universal Migration Engine (29 Memory Formats)

Auto-detects and ingests existing memory stores across 29 external engines:

# Auto-detect all external memory stores on your machine
memory detect

# Ingest and preserve state mappings
memory migrate --provider letta
memory migrate --provider mem0
memory migrate --provider beads
memory migrate --all

See musememory-comparison.html for the full table-free 30-system architectural dossier.

🌐 Cognitive Studio Dashboard (memory ui / memory studio)

Muse Memory includes an embedded, zero-dependency visual graph studio and observability dashboard:

memory studio
# or alias:
memory ui --port 2222

Navigate to http://localhost:2222 to access:

• 🌐 3D Force-Directed Knowledge Graph: Orbital canvas physics, degree-scaled node radii, and link relationship viewer.
• 🏥 5-Pillar Project Health Gate: Live architectural scorecard (Store Integrity, Native Anchors, Doc-Code Alignment, Anti-Pattern Sentry, Technical Debt) with A-F grading and PASS/WARN/FAIL status.
• 🏛️ ADR Registry & Drift Inspector: First-class Architecture Decision Records and bi-directional code ↔ documentation drift auditor.
• 🤔 Autonomous "Why" Reasoner: Traces historical evolution of symbols/files backwards through past bug fixes and trade-offs to explain architectural rationale before refactoring.
• 🤝 P2P Gossip Mesh Topology: Real-time peer vector clocks, local agent identity, and one-click broadcast/shared pool sync.
• 🕸️ Monorepo & Cross-Project Mesh: Workspace monorepo topology (pnpm, npm, bun, lerna), discovered package nodes, cross-project memory query, and contract drift audit.
• ⚡ Active Invariants & Real-Time Handoff: Live CURRENT.md monitor tracking in-flight session status and agent checkpoints.
• 📚 Obsidian Wiki Browser: Concept and entity page reader with full Markdown rendering.
• 👤 Persona Studio (USER.md): 5 archetype picker (developer, designer, marketer, casual, custom) and live editor.
• 🔍 Knapsack Retrieval Sandbox: Interactive token budget simulator (500–6,000 tokens) with live prompt context generation.
• 📜 Compliance Audit Ledger: Live tabular feed of state transitions and audit logs.

📖 Deep Technical References & Documentation

When registered as an MCP server, musememory exposes the following native tools (filtered dynamically into role-tailored profiles to eliminate tool bloat):

| MCP Tool | Execution Phase | Description | | :--- | :--- | :--- | | muse_context | Flagship Fusion | Single-call fused orchestrator combining search, active file, symbol, error messages, and task intent under strict knapsack token budgets. | | muse_health | Quality Gate | 5-Pillar Project Health Gate: audits store integrity, code anchors, doc/code alignment, anti-pattern sentry, and technical debt with A-F grading and pass/fail status. | | muse_why | Cognition / "Why" | Explains why code was designed the way it is by reconstructing past ADRs, bug fixes, trade-offs, and timeless rules. | | muse_bug_clusters | Fragility Hotspots | Categorizes recurring bugs into 5 root causes with subsystem fragility scoring. | | muse_tech_debt | Technical Debt | Scans code and memory for TODO/FIXME markers, unsafe as any casts, and drifted anchors. | | 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 / list | Architecture Decisions | Records and queries first-class Architecture Decision Records with native code anchors and options considered. | | memory_drift_audit | Drift Engine | Audits bi-directional documentation $\longleftrightarrow$ code drift across 6 alignment states (DOCUMENTED, IMPLEMENTED, PARTIAL, CONFLICTING, STALE, MISSING). | | 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. | | memory_lifecycle_stats / sweep | Lifecycle Sweeper | Reports store-wide lifecycle statistics and executes sweep transitions for aging memories. | | 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. | | profile_list / profile_switch | Tool Management | Lists and switches task-focused MCP profiles (core, coding, debugging, review, architecture, maintenance). | | get_context | Session Start | Fetches Top-$K$ ranked memories, USER.md profile, active CURRENT.md constraints, and supports --tier 0|1|2. | | search | Investigation | Searches memory units with query, token budget, project, type, and verification filters. | | memory_current | Constraints | Reads or appends active project working constraints (CURRENT.md). | | memory_get_user_profile | Context Loading | Reads active USER.md persona and communication preferences. | | memory_set_user_profile | Preferences | Updates USER.md profile with inline secret defense. | | memory_capture | During Fixes | Saves a memory entry with inline Vibeguard secret inspection. | | memory_confirm | Decision Approval | Promotes candidate insight to confirmed status. | | memory_supersede | Refactoring | Marks outdated knowledge superseded by a confirmed replacement. | | memory_link | Graph Building | Connects related memories bidirectionally. | | memory_mark_stale | Deprecation | Flags decaying knowledge with deprecation rationale. | | memory_reject | Hypothesis Refutation | Marks invalidated hypotheses as rejected. | | memory_delete | Purge | Permanently deletes an entry and records audit ledger log. | | memory_source_add / list | Provenance | Records external docs/RFCs/URLs into .memory/sources.json and queries sources. | | memory_claim_record / list | Claim Ledger | Records evidence-backed claims tagged with [RAW], [FETCH], [SEARCH], [INFER]. | | memory_freeze_run / list | Execution Snapshots | Freezes immutable task snapshots with file inventory and SHA-256 memory hashes. | | memory_prompt_list / get / run | Prompt Templates | Manages and executes native structured prompt templates with live context injection. | | memory_rollup | Temporal Compounding | Aggregates atomic memories into weekly, monthly, and quarterly rollups and updates HOT.md. | | memory_loop_record / status | Gauntlet Loops | Multi-agent iteration ledger and plateau/regression detector (.memory/iterations.jsonl). | | memory_verify_strict | Integrity Gate | Zero-tolerance audit verifying secrets, referential links, wikilinks, claims, and candidates. | | memory_tree_search | Tree Retrieval | Hierarchical reasoning search across partitioned memory shards. | | memory_wiki_compile | Wiki Compiler | Compiles confirmed memories into Obsidian-compatible Markdown pages. | | memory_wiki_search / get | Wiki Reading | Searches and reads compiled concept and entity wiki pages. | | memory_entities_search / get | Entity Graph | Searches extracted entities and inspects co-occurrence strengths. | | memory_pageindex_index | Doc Indexing | Builds a hierarchical reasoning tree from document content. | | memory_pageindex_search | Doc Search | Searches PageIndex document tree with reasoning explanations. | | memory_pageindex_import | Doc Knowledge | Imports PageIndex search insights directly into memory units. | | memory_search_transcripts | History Search | Full-text search over past .jsonl transcripts with dialogue context windows. | | memory_harvest | Session End | Distills conversation turns into structured fix/outcome units. | | memory_import_transcript | Transcript Sync | Ingests .jsonl transcript and auto-binds memories to session nodes. | | memory_audit | Governance | Queries the append-only operational audit ledger. | | memory_detect_agents | Onboarding | Scans workstation for 80+ coding agent installations. | | memory_connect | Setup | Auto-wires MCP server into detected installed agents with zero permissions. | | memory_detect_providers | Migration | Scans machine for 29 external memory formats. | | memory_migrate | Migration | Ingests external memories with state preservation and secret scrubbing. | | memory_export / import | Team Sharing | Exports and imports portable JSON memory snapshots. | | memory_validate | Integrity Check | Verifies database integrity and scans for credential leaks. | | memory_settings_get / set | Configuration | Reads and updates unified global or project configuration settings. | | graph_status | AST Graph | Inspects CodeGraph/Graphify symbol overlap provider status. | | graph_index | AST Graph | Indexes AST symbol graph and caches in .memory/graph-symbols.json. |

memory <command> [arguments] [flags]  # alias: musememory

| Command | Arguments / Flags | Description | | :--- | :--- | :--- | | health | [--json] [--global] | Unified 5-Pillar Project Health Gate: audits Store Integrity, Code Anchors, Drift, Sentry, and Tech Debt with A-F grading and pass/fail gate. | | studio / ui | [--port N] [--global] | Web Observability Studio: visual dashboard with 5-pillar health, ADR drift, why reasoner, and live mesh (default port: 2222). | | sync | [status\|broadcast\|ingest\|pool] [flags] | P2P Gossip Mesh: peer vector clock status, packet export, ingestion, and shared pool gossip sync. | | mesh | [overview\|query\|check\|link\|unlink\|propagate] [flags] | Monorepo & Multi-Repo Mesh: workspace discovery, cross-project memory query, and contract drift audit. | | adr | [record\|list\|supersede] [args] | Architecture Decision Records: record, list, and supersede living architecture decisions. | | anchor | [create\|verify\|audit] [args] | Code Anchors: create, verify, and audit line-independent structural code anchors. | | install | [path] [--global] | One-line complete setup: initializes .memory/, USER.md, and auto-wires coding agents. | | doctor | [path] [--global] | System diagnostic: checks SQLite primary, schemas, secrets, and MCP connections. | | uninstall | [agent] [--purge] [--dry-run] | Clean uninstaller: unwires MCP configs (and optionally purges .memory/). | | init | [path] [--legacy] [--global] | Initialize .memory/ directory and SQLite database. | | user | [get\|init\|set] [args] [--global] | Manage USER.md persona & preferences across 5 clean archetypes. | | connect | [agent] [--all] [--force] [--dry-run] | Auto-wire MCP into detected installed agents with zero permissions. | | agents | (none) | Scan workstation for 80+ coding agents (Cursor, Claude Code, Antigravity, etc.). | | detect | (none) | Scan workstation and local workspace for 29 external memory systems. | | migrate | [--provider P] [--all] [--dry-run] [--overwrite] | Migrate memories into Muse Memory preserving active/archived state. | | context | [query] [--token-budget N] [--limit N] [--tier 0\|1\|2] | Retrieve Top-$K$ ranked active context for prompt injection. | | search | <query> [--limit N] [--token-budget N] [--type T] | Ranked multi-factor token search with score breakdown. | | search-transcript | <query> [file.jsonl] [--window N] | Full-text search past transcripts with dialogue context windows. | | learn / sync-chats | [--confirm] [--force] [--max N] | Universal auto-learner: auto-discovers and distills memories from all agent chats across host machine. | | harvest | <text\|file> --project P [--confirmed] | Distill conversation turns into structured fix/decision memory units. | | import-transcript | <file.jsonl> [--project P] [--confirmed] | Ingest raw .jsonl session transcripts from coding agents. | | capture / propose | <text> --project P [--title T] [--type T] | Propose a memory entry with inline Vibeguard secret inspection. | | recall | <query> [--limit N] [--token-budget N] | Rich recall displaying verification levels and related graph links. | | confirm | <id> [--global] | Promote candidate, disputed, or stale entry to confirmed. | | supersede | <old_id> --with <new_id> | Mark old entry superseded by new confirmed replacement. | | mark-stale | <id> [--reason <text>] | Mark an entry stale with deprecation rationale. | | reject | <id> [--global] | Mark an entry rejected. | | delete | <id> [--reason <text>] | Permanently delete a memory entry and record audit event. | | source | add\|list\|show <url> [--title T] [--type T] | Manage external documentation and URLs in provenance Source Ledger (.memory/sources.json). | | claim | record\|list\|show <text> [--confidence RAW\|FETCH\|SEARCH\|INFER] | Record and query verifiable claims connected to sources (.memory/claims.json). | | freeze | --task <task.md\|text> [--run-id R] | Capture immutable execution snapshot with file inventory and SHA-256 memory hashes. | | prompt | list\|show\|run <name> [--args k=v,...] | Manage and run structured prompt templates with live context injection. | | rollup | --period week\|month\|quarter [--date YYYY-MM-DD] | Multi-scale temporal compounding and .memory/HOT.md working memory cache compiler. | | loop | record\|status\|clear | Multi-agent Gauntlet iteration ledger and plateau/regression detector. | | verify | <id> [--timeout S] [--strict] | Execute a fix entry's test command or run full strict integrity gate. | | audit | [--operation OP] [--entry-id ID] [--limit N] | Query append-only operational audit trail (.memory/audit.jsonl). | | link | <id> --related <id1,id2> | Synchronize bidirectional relation links between entries. | | export / import | [--out <file.json>] / <file.json> | Export and import portable JSON memory snapshots. | | list / ls | [--status S] [--type T] [--project P] | List memory entries with multi-field status and type filtering. | | stats | [--global] | Breakdown statistics of total memories, status, and type metrics. | | briefing | [--limit N] [--global] | Active summary of recent entries, status counts, and due items. | | nudge | [--global] | Proactive attention list: overdue entries, stale policies, open loops. | | routine | run <name> / install [name] | Execute .memory/routines.yaml steps or print crontab lines. | | wiki | compile\|list\|show <slug> | Compile and browse Obsidian-compatible Markdown wiki pages. | | entities | list\|show <id>\|related <id> | Inspect extracted knowledge graph entities and co-occurrence weights. | | settings | get\|set\|reset\|export\|import | Manage unified settings across retrieval, wiki, PageIndex, and UI. | | current | get / set <text> --project P | Read or append hard constraints in .memory/CURRENT.md. | | graph | status / index | Query active CodeGraph provider status or index AST symbol map. | | mcp | (none) | Start stdio MCP server (Protocol 2024-11-05). |

Muse Memory ships with 11 turnkey Agent Skills designed for coding agents (Claude Code, Cursor, Antigravity, OpenCode, Codex, Gemini CLI, etc.) under .agents/skills/:

| Skill | Trigger Phase | Core Agent Responsibility | | :--- | :--- | :--- | | muse-ground | Session Start | Retrieves Top-$K$ relevant memories, active USER.md persona profile, and CURRENT.md constraints before writing code. | | muse-capture | During Fixes & Refactors | Captures atomic fix/architecture memories, validates evidence, runs Vibeguard secret scan, and supersedes obsolete knowledge. | | muse-current | Invariants & Handoffs | Synchronizes hard constraints into .memory/CURRENT.md and persists structured handoffs across context resets. | | muse-health | Hardening Gates & PRs | Evaluates 5-pillar architectural health (store, anchors, doc/code alignment, negative sentry, debt) and outputs remediation checklists. | | muse-drift | System Architecture & ADRs | Audits documentation $\longleftrightarrow$ code drift across 6 states, records living ADRs, and supersedes legacy architectural decisions. | | muse-why | Refactoring & Historical Context | Reconstructs historical rationale, synthesizes past bug fixes and accepted trade-offs, and audits recurring bug friction clusters. | | muse-sync | Multi-Agent & Swarm Gossip | Coordinates cross-agent knowledge sync with whole-packet SHA-256 integrity, vector clocks, and P2P gossip mesh pool. | | muse-mesh | Monorepo & Multi-Repo Mesh | Discovers monorepo workspaces, resolves cross-package memories with badges, and propagates shared security constraints. | | muse-graph | AST Code Investigation | Indexes .codegraph/.graphify symbols and queries symbol-matching decisions with +0.2 graph overlap bonus. | | muse-wiki | Knowledge Compounding | Compiles confirmed memories into Obsidian-compatible Markdown pages ([[wikilinks]]) and entity co-occurrence graphs. | | muse-brief | Daily Hygiene & Loops | Generates morning briefings, tracks 90/180-day staleness decay, and surfaces unresolved transcript commitments. |

Muse Memory maintains a persistent user profile (~/.memory/USER.md globally, or .memory/USER.md locally) to ground AI agents in your working style:

1. developer (Default): Code-first, direct, concise, runnable diffs, strict types, fail-fast mechanics.
2. designer: Visual hierarchy, CSS/Tailwind systems, GSAP animations, WCAG accessibility, Figma/tokens design tokens.
3. marketer: Conversion-rate optimization (CRO), punchy benefit-driven copy, SEO clustering, audience hooks.
4. casual: Plain English, jargon-free explanations, step-by-step guidance.
5. custom: Clean blank template ready for personalized instructions.

# View active profile
memory user get

# Initialize with a specific archetype
memory user init developer
memory user init designer --global

# Update user profile
memory user set "- Prefers TypeScript, Bun, and ultra terse responses"

🧪 Testing & Verification

bun install
bun test          # 497 passed across 84 test files (2190 assertions)
bun run typecheck # 0 static type errors
bun run build     # Clean bundled distribution build (dist/index.js)

🔮 Sprint & Roadmap Board

Muse Memory features are developed in structured sprints moving across 4 deterministic lifecycle phases following strict vX.Y.Z semantic versioning. Every sprint is delivered via PR from dev to main with associated GitHub milestones. Live tracking: GitHub Issues & Milestones.

[ 📋 Requested ] ──► [ 📅 Planned ] ──► [ ⚡ In Progress ] ──► [ ✅ Done ]
 (Issues / PRs)     (Sprint Backlog)    (Active PR / Milestone)  (Shipped to Main)

🏷️ Semantic Versioning Protocol (vX.Y.Z)

• X (Major): Breaking architectural changes, core schema shifts, or protocol overhauls (vX.0.0).
• Y (Feature): Substantive new agent capabilities, MCP tools, or CLI subcommands (vX.Y.0).
• Z (Minor / Hotfix / Critical Fix): Bug remediations, security patches, performance, and urgent hotfixes (vX.Y.Z).

📋 Phase 1: Requested (Backlog)

Incoming community proposals, agent adapters, and feature requests pending sprint triage:

• [ ] Multi-Agent Consensus Verification Protocol (cross-agent memory agreement)
• [ ] Continuous Background Memory Compaction & Pruning Cron
• [ ] Export to Local Vector GGUF Embedding Index

📅 Phase 2: Planned

Confirmed high-leverage features scheduled for upcoming sprints:

• [ ] Tiered Retrieval Engine: Deterministic Tier 0 (manifest), Tier 1 (invariants), Tier 2 (bounded bodies) knapsack retrieval
• [ ] Provenance & Claim Ledgers: Direct memory citations with [RAW], [FETCH], [SEARCH], and [INFER] confidence tagging
• [ ] Frozen Context Snapshots: Immutable SHA-256 state tracking for reproducible agent execution
• [ ] Native Prompt Registry: Declarative prompt library & runner (.memory/prompts/*.md, memory prompt run)
• [ ] Temporal Compounding: Multi-scale Day $\to$ Week $\to$ Quarter wiki rollups & .memory/HOT.md cache
• [ ] Gauntlet Iteration Ledger: Multi-turn improvement loop tracking and plateau detection
• [ ] Strict Health Gate: Comprehensive memory verify --strict referential, link, and secret validator

⚡ Phase 3: In Progress (Active Sprint / PR)

Currently under active development on dedicated feature branches:

• (None — Sprint SOW-200 completed and shipped)

✅ Phase 4: Done (Shipped to Production)

All completed, tested, and released milestones: | Status | Milestone / Feature | Shipped Release / Tracker | | :--- | :--- | :--- | | ✅ | SOW-201: Live Runtime File & Symbol Verification Gate (STRONG/WEAK/STALE) | shipped v1.8.0 | | ✅ | SOW-202: Deterministic Relevance Cutoff Gate (hard score threshold $\ge 0.45$) | shipped v1.8.0 | | ✅ | SOW-203: Git Code-Drift Scanner CLI (memory drift / memory check) | shipped v1.8.0 | | ✅ | SOW-204: Gradient-Free Hebbian Co-Activation Plasticity (synaptic link reinforcement) | shipped v1.8.0 | | ✅ | SOW-205: Semantic Memory Prompt Compression (memory compress lossless prompt packer) | shipped v1.8.0 | | ✅ | Turnkey Agent Skills Suite (muse-ground, muse-capture, etc.) | shipped v1.7.0 | | ✅ | AST Symbol Graph Integration (CodeGraph / Graphify) | #35 / v1.7.0 | | ✅ | Zero-Friction Installation Lifecycle Fix | shipped v1.7.1 | | ✅ | Proactive Nudges & Check-ins (memory nudge) — SOW-101 | #28 | | ✅ | Daily Briefing & Routines Scheduler (cron-invoked, no daemon) — SOW-102 | #29 | | ✅ | Open-Loop / Task Extraction from Transcripts — SOW-103 | #30 | | ✅ | Calendar / Time-Aware Follow-ups (due_at / expires_at) — SOW-104 | #31 | | ✅ | muse-agents ↔ musememory Integration Contract (--for-agent) — SOW-106 | #33 | | ✅ | Dynamic Prompt Token Budgeter (--token-budget N) | shipped v1.1.0 | | ✅ | Scene-Based Hierarchical Consolidation (memory consolidate) | #1 | | ✅ | Autonomous Verification Oracle (memory verify <id>) | #2 | | ✅ | Multi-Hop Causality Graph Tracer (memory trace <id>) | #3 | | ✅ | In-Place Core Memory Partitioning (memory core) | #4 | | ✅ | Automated Post-Turn Transcript Harvester Hook | #5 | | ✅ | Real-Time Agency WebSocket Hub (memory daemon) | #6 | | ✅ | Local Offline Hybrid Vector Engine | #7 | | ✅ | Delete Deprecated MemoryStore Shim | #8 / v1.5.0 | | ✅ | Self-Evolving Skill Distillation | #9 | | ✅ | 3-Layer Progressive Disclosure | #10 | | ✅ | Bi-Temporal Reinforcement Feedback | #11 | | ✅ | Ambient Open-Loop Tracker | #12 | | ✅ | Knowledge Graph UI v2 | #13 |

📜 License

MIT License. Built for the AI Developer Ecosystem.