musememory 1.6.0 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. package/.agents/skills/muse-brief/SKILL.md +67 -0
  2. package/.agents/skills/muse-capture/SKILL.md +70 -0
  3. package/.agents/skills/muse-current/SKILL.md +62 -0
  4. package/.agents/skills/muse-graph/SKILL.md +61 -0
  5. package/.agents/skills/muse-ground/SKILL.md +62 -0
  6. package/.agents/skills/muse-wiki/SKILL.md +57 -0
  7. package/README.md +186 -285
  8. package/dist/index.js +1267 -901
  9. package/package.json +4 -1
  10. package/schema.json +60 -0
  11. package/skills/muse-brief/SKILL.md +67 -0
  12. package/skills/muse-capture/SKILL.md +70 -0
  13. package/skills/muse-current/SKILL.md +62 -0
  14. package/skills/muse-graph/SKILL.md +61 -0
  15. package/skills/muse-ground/SKILL.md +62 -0
  16. package/skills/muse-wiki/SKILL.md +57 -0
package/README.md CHANGED
@@ -2,13 +2,21 @@
2
2
 
3
3
  <div align="center">
4
4
 
5
- ![GitHub Release](https://img.shields.io/github/v/release/harshsinghmp/musememory?style=for-the-badge&logo=github&color=blue)
6
- ![NPM Version](https://img.shields.io/npm/v/musememory?style=for-the-badge&logo=npm&color=red)
7
- ![Bun](https://img.shields.io/badge/Bun-1.3.14-black?style=for-the-badge&logo=bun)
8
- ![MCP](https://img.shields.io/badge/MCP-2024--11--05-green?style=for-the-badge&logo=anthropic)
9
- ![CI Tests](https://img.shields.io/badge/Tests-278%20Passed-brightgreen?style=for-the-badge&logo=checkmarx)
10
- ![Docker Ready](https://img.shields.io/badge/Docker-Ready-2496ED?style=for-the-badge&logo=docker)
11
- ![License](https://img.shields.io/badge/License-MIT-purple?style=for-the-badge)
5
+ ![GitHub Release](https://img.shields.io/github/v/release/harshsinghmp/musememory?style=for-the-badge&logo=github&color=2563EB)
6
+ ![NPM Version](https://img.shields.io/npm/v/musememory?style=for-the-badge&logo=npm&color=CB3837)
7
+ ![Bun](https://img.shields.io/badge/Bun-v1.4.0_(Latest)-black?style=for-the-badge&logo=bun)
8
+ ![Node.js](https://img.shields.io/badge/Node.js-≥18.0.0-339933?style=for-the-badge&logo=node.js&logoColor=white)
9
+ ![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
10
+
11
+ ![MCP Protocol](https://img.shields.io/badge/MCP-2024--11--05-green?style=for-the-badge&logo=anthropic)
12
+ ![SQLite Engine](https://img.shields.io/badge/SQLite-Primary_DB-003B57?style=for-the-badge&logo=sqlite&logoColor=white)
13
+ ![AST Graph](https://img.shields.io/badge/AST-CodeGraph_%26_Graphify-orange?style=for-the-badge&logo=diagram-project&logoColor=white)
14
+ ![Architecture](https://img.shields.io/badge/Storage-Zero--Daemon_%2F_Local--First-0D9488?style=for-the-badge)
15
+
16
+ ![CI Tests](https://img.shields.io/badge/Tests-304%20Passed-brightgreen?style=for-the-badge&logo=checkmarx)
17
+ ![Security](https://img.shields.io/badge/Security-Vibeguard_Zero--Leak-DC2626?style=for-the-badge&logo=shield)
18
+ ![Agent Coverage](https://img.shields.io/badge/Agents-80+_Supported-4F46E5?style=for-the-badge&logo=openai)
19
+ ![License](https://img.shields.io/badge/License-MIT-9333EA?style=for-the-badge)
12
20
 
13
21
  **Autonomous, Self-Organizing Cognitive Memory System for AI Agents & Agency Networks**
14
22
 
@@ -55,13 +63,22 @@ Most AI chatbots and coding assistants have **"goldfish memory"**: every time yo
55
63
  └─────────────────────────────────────────────────────────────┘
56
64
  ```
57
65
 
58
- - 👤 **Remembers You (`USER.md`)**: Configures your role (`developer`, `designer`, `marketer`, `casual`, `custom`) and communication preferences so AI models talk your language.
59
- - 📐 **Remembers Active Constraints (`CURRENT.md`)**: Real-time auto-synchronization ensures agents never break hard invariants or lose in-flight task context across session interruptions.
60
- - 💾 **Primary SQLite + Dual YAML Mirror**: Millisecond queries from `.memory/memory.db` with human-readable YAML mirrors in `.memory/memories/` for seamless Git tracking and team diffing.
61
- - ⚖️ **Token Knapsack Retrieval**: Multi-factor scoring and exact prompt token budgeting pack relevant memories into prompts with zero token waste.
62
- - 📚 **Knowledge Compounding**: Compiles memories into Obsidian-compatible Markdown wikis (`memory wiki`), named entity co-occurrence graphs (`memory entities`), and hierarchical PageIndex reasoning trees.
63
- - 🔌 **Zero-Permission Auto-Wiring**: Automatically scans for 80+ coding agent platforms (Claude Code, Cursor, Antigravity, Windsurf, OpenCode, Codex, etc.) and wires them with zero friction.
64
- - 🛡️ **Zero-Leakage Secret Defense (Vibeguard)**: Intercepts and rejects API keys, AWS tokens, private keys, and database passwords before they can touch disk.
66
+ ---
67
+
68
+ ## ✨ Key Feature Highlights
69
+
70
+ - 👤 **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.
71
+ - 📐 **Real-Time Active Constraints (`CURRENT.md`)**: Bi-temporal working constraints and invariant tracking synchronized on every mutation to eliminate amnesia during task handoffs.
72
+ - 💾 **SQLite Primary + Dual-Persisted YAML Mirror**: Sub-millisecond queries via SQLite with transparent human-readable `.yaml` files in `.memory/memories/` for seamless Git diffs.
73
+ - ⚖️ **Token Knapsack Retrieval**: Multi-factor scoring (applicability, verification bonus, AST graph overlap, time decay, due date urgency) tightly packed under prompt token ceilings.
74
+ - 🌐 **Pluggable AST CodeGraph & Symbol Indexing**: Native CodeGraph & Graphify integration that indexes codebase AST symbols, auto-tags memories, and awards graph overlap bonuses.
75
+ - 🌳 **Hierarchical Tree Retrieval & Progressive Disclosure**: Sharded tree partitions with 3-tier progressive disclosure (`L1` abstracts, `L2` summaries, `L3` full context) for massive knowledge bases.
76
+ - 📚 **Obsidian Markdown Wiki & Entity Graph Compiler**: Dual-persistence knowledge compounding compiling linked Markdown pages (`wiki/concepts/`, `wiki/entities/`) with bidirectional `[[wikilinks]]`.
77
+ - 🛡️ **Vibeguard Zero-Leakage Secret Scanner**: Regex-powered memory defense intercepting and rejecting API keys, AWS credentials, private keys, database URIs, and passwords before writes.
78
+ - 🔌 **Zero-Permission Auto-Wiring (80+ Agents)**: Automatically detects and wires Claude Code, Cursor, Antigravity, Windsurf, OpenCode, Codex, Gemini CLI, Hermes, etc.
79
+ - 🔄 **Universal Memory Migrator (29 Engines)**: One-click migration from Letta, Mem0, Supermemory, Cognee, Beads, Mnemosyne, GBrain, and more with state preservation.
80
+ - 🎨 **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.
81
+ - ⏰ **Proactive Nudges & Routines Scheduler**: Cron-invoked daily briefings, staleness policy tracking, and ambient open-loop trackers with zero resident background daemons.
65
82
 
66
83
  ---
67
84
 
@@ -109,7 +126,7 @@ docker build -t musememory .
109
126
 
110
127
  ---
111
128
 
112
- ## 🔄 Complete NPX Lifecycle (Install → Verify → Connect → Uninstall)
129
+ ## 🔄 Complete Lifecycle (Install → Verify → Connect → Uninstall)
113
130
 
114
131
  Every command works with **zero installation** via `npx musememory <cmd>` (or `bunx musememory <cmd>`). Use plain `memory <cmd>` if installed globally.
115
132
 
@@ -148,18 +165,64 @@ npx musememory connect windsurf
148
165
  npx musememory connect opencode
149
166
  ```
150
167
 
151
- ### 4️⃣ Clean Uninstallation
168
+ ### 4️⃣ Clean Uninstallation & Removal
169
+
170
+ <details>
171
+ <summary><b>🗑️ Complete Uninstallation & System Removal Steps</b> — <i>Click to expand</i></summary>
172
+
173
+ Muse Memory can be cleanly and completely removed with zero trace left on your machine.
174
+
175
+ #### Step 1: Unwire Coding Agents (Zero-Trace MCP Cleanup)
176
+ Remove the memory MCP server configuration from all 80+ detected agent config files (`cursor`, `claude-code`, `antigravity`, `windsurf`, `opencode`, `codex`, etc.):
177
+
152
178
  ```bash
153
- # Preview what would be unwired
179
+ # Preview changes before modifying any configuration
154
180
  npx musememory uninstall --dry-run
155
181
 
156
- # Unwire MCP from all agents (preserves .memory/ data)
182
+ # Unwire all detected AI coding agents automatically
157
183
  npx musememory uninstall
158
184
 
159
- # Unwire AND purge local project .memory/ data
185
+ # Or unwire a single specific agent
186
+ npx musememory uninstall cursor
187
+ ```
188
+
189
+ #### Step 2: Purge Memory Data & Stores (Optional)
190
+ By default, `uninstall` preserves your project `.memory/` data. To completely delete all memory files and databases:
191
+
192
+ ```bash
193
+ # Unwire agents AND purge local project .memory/ directory
160
194
  npx musememory uninstall --purge
195
+
196
+ # Remove global user profile and global memory store (~/.memory/)
197
+ npx musememory uninstall --global --purge
198
+
199
+ # Manual cleanup (equivalent):
200
+ rm -rf .memory/ # Local project store
201
+ rm -rf ~/.memory/ # Global user profile & store
161
202
  ```
162
203
 
204
+ #### Step 3: Remove Globally Installed Package
205
+ If you installed `musememory` globally via a package manager:
206
+
207
+ ```bash
208
+ # If installed via npm:
209
+ npm uninstall -g musememory
210
+
211
+ # If installed via bun:
212
+ bun remove -g musememory
213
+
214
+ # If installed via yarn / pnpm:
215
+ pnpm remove -g musememory
216
+ yarn global remove musememory
217
+ ```
218
+
219
+ #### Step 4: Clean Git Hooks & Directives (Optional)
220
+ If you installed the pre-commit transcript harvester hook or injected agent prompt directives:
221
+ - **Git Hook**: Delete `.git/hooks/pre-commit` (or restore your previous hook).
222
+ - **AGENTS.md**: Remove the `<!-- musememory:start --> ... <!-- musememory:end -->` block from your project's `AGENTS.md` file.
223
+
224
+ </details>
225
+
163
226
  ---
164
227
 
165
228
  ## 🏛️ System Capabilities & Architecture
@@ -208,7 +271,7 @@ memory migrate --provider mem0
208
271
  memory migrate --provider beads
209
272
  memory migrate --all
210
273
  ```
211
- > See [`musememory-comparison.html`](file:///home/harsh/Projects/github/musememory/musememory-comparison.html) for the full table-free 30-system architectural dossier.
274
+ > See [`musememory-comparison.html`](musememory-comparison.html) for the full table-free 30-system architectural dossier.
212
275
 
213
276
  ---
214
277
 
@@ -232,169 +295,118 @@ Navigate to `http://localhost:2222` to access:
232
295
 
233
296
  ---
234
297
 
235
- <<<<<<< HEAD
236
- ## 💻 Complete CLI Command Reference
237
- ||||||| f9a7a44
238
- ## ⚡ How Memory Grows, Reloads &amp; Auto-Archives
239
-
240
- ```mermaid
241
- flowchart TD
242
- subgraph HotPath["Active Conversation (Hot Path)"]
243
- User["User asks question / gives task"]
244
- Agent["AI Agent executes turn"]
245
- Recall["1. Auto-Retrieve Top-K Context & Active Constraints"]
246
- Distill["2. Auto-Distill Fixes & Decisions (Harvest)"]
247
- end
248
-
249
- subgraph DefenseGate["Self-Contained Vibeguard"]
250
- Scan["3. Zero-Leakage Secret Scan (Blocks API keys & DB URLs)"]
251
- end
252
-
253
- subgraph StoreLifecycle["Self-Organizing Knowledge Engine (.memory/)"]
254
- Atomic["4. Atomic Write (m_timestamp_slug.yaml)"]
255
- Lifecycle["5. Lifecycle Transitions (Candidate ➔ Confirmed ➔ Superseded)"]
256
- Decay["6. Temporal Staleness Decay & Auto-Archiving"]
257
- end
258
-
259
- User --> Agent
260
- Agent --> Recall
261
- Recall --> Agent
262
- Agent --> Distill
263
- Distill --> Scan
264
- Scan --> Atomic
265
- Atomic --> Lifecycle
266
- Lifecycle --> Decay
267
- ```
268
-
269
- - **Incremental Auto-Growing**: Every decision, bug fix, operational rule, and session checkpoint is saved as a discrete, human-readable YAML document in `.memory/memories/`.
270
- - **Context Reload Continuity**: On a fresh turn or session restart, `get_context` feeds only the Top-$K$ highest-salience, verified knowledge units—reducing context tokens by **85–95%** and eliminating outdated hallucinations.
271
- - **Smart Archiving &amp; Controlled Forgetting**: Old approaches are marked `superseded` with explicit forward/backward links. Time-based staleness policies (e.g. 30 days for temporary discoveries, 90 days for fixes, 365 days for architecture) automatically down-weight decaying knowledge.
272
-
273
- ---
298
+ ## 📖 Deep Technical References & Documentation
274
299
 
275
- ## 👤 User Persona & Preferences (`USER.md`) & Setup Wizard
300
+ <details>
301
+ <summary><b>🔌 Complete MCP Tool Reference (29 Tools)</b> — <i>Click to expand</i></summary>
276
302
 
277
- Muse Memory maintains a persistent user profile (`~/.memory/USER.md` globally, or `.memory/USER.md` locally) to ground AI agents in your working style, communication preferences, and toolchain rules.
278
-
279
- ### 🎭 5 Zero-Fingerprint Role Archetypes
280
-
281
- When running `memory install`, an interactive setup wizard configures your primary archetype (or choose one manually anytime):
282
-
283
- 1. **`developer`** (Default): Code-first, direct, concise, runnable diffs, strict types, fail-fast mechanics.
284
- 2. **`designer`**: Visual hierarchy, CSS/Tailwind systems, GSAP animations, WCAG accessibility, Figma/tokens design tokens.
285
- 3. **`marketer`**: Conversion-rate optimization (CRO), punchy benefit-driven copy, SEO clustering, audience hooks.
286
- 4. **`casual`**: Plain English, jargon-free explanations, step-by-step guidance.
287
- 5. **`custom`**: Clean blank template ready for personalized instructions.
288
-
289
- ```bash
290
- # View active profile
291
- memory user get
292
-
293
- # Initialize with a specific archetype
294
- memory user init developer
295
- memory user init designer --global
296
-
297
- # Update user profile
298
- memory user set "- Prefers TypeScript, Bun, and ultra terse responses"
299
- ```
300
-
301
- ### 🧠 Prompt Injection Hierarchy & Proactive Self-Nudge
302
- When `get_context` or `formatPromptContext()` builds the LLM prompt context, it structures information deterministically:
303
- 1. **`### User Profile & Preferences (USER.md)`** (Tone, role, rules)
304
- 2. **`### Active Working Constraints (CURRENT.md)`** (Project invariants & open loops)
305
- 3. **`### Relevant Memories & Learned Patterns`** (Top-$K$ ranked memories)
306
- 4. **`*Memory Directive: When learning durable facts, bug resolutions, or user preferences, call memory_capture immediately.*`**
303
+ When registered as an MCP server, `musememory` exposes the following native tools:
307
304
 
308
- ---
305
+ | MCP Tool | Execution Phase | Description |
306
+ | :--- | :--- | :--- |
307
+ | `get_context` | **Session Start** | Fetches Top-$K$ ranked memories, `USER.md` profile, and active `CURRENT.md` constraints. |
308
+ | `search` | **Investigation** | Searches memory units with query, token budget, project, type, and verification filters. |
309
+ | `memory_current` | **Constraints** | Reads or appends active project working constraints (`CURRENT.md`). |
310
+ | `memory_get_user_profile` | **Context Loading** | Reads active `USER.md` persona and communication preferences. |
311
+ | `memory_set_user_profile` | **Preferences** | Updates `USER.md` profile with inline secret defense. |
312
+ | `memory_capture` | **During Fixes** | Saves a memory entry with inline Vibeguard secret inspection. |
313
+ | `memory_confirm` | **Decision Approval** | Promotes candidate insight to confirmed status. |
314
+ | `memory_supersede` | **Refactoring** | Marks outdated knowledge superseded by a confirmed replacement. |
315
+ | `memory_link` | **Graph Building** | Connects related memories bidirectionally. |
316
+ | `memory_mark_stale` | **Deprecation** | Flags decaying knowledge with deprecation rationale. |
317
+ | `memory_reject` | **Hypothesis Refutation** | Marks invalidated hypotheses as rejected. |
318
+ | `memory_delete` | **Purge** | Permanently deletes an entry and records audit ledger log. |
319
+ | `memory_tree_search` | **Tree Retrieval** | Hierarchical reasoning search across partitioned memory shards. |
320
+ | `memory_wiki_compile` | **Wiki Compiler** | Compiles confirmed memories into Obsidian-compatible Markdown pages. |
321
+ | `memory_wiki_search` / `get` | **Wiki Reading** | Searches and reads compiled concept and entity wiki pages. |
322
+ | `memory_entities_search` / `get` | **Entity Graph** | Searches extracted entities and inspects co-occurrence strengths. |
323
+ | `memory_pageindex_index` | **Doc Indexing** | Builds a hierarchical reasoning tree from document content. |
324
+ | `memory_pageindex_search` | **Doc Search** | Searches PageIndex document tree with reasoning explanations. |
325
+ | `memory_pageindex_import` | **Doc Knowledge** | Imports PageIndex search insights directly into memory units. |
326
+ | `memory_search_transcripts` | **History Search** | Full-text search over past `.jsonl` transcripts with dialogue context windows. |
327
+ | `memory_harvest` | **Session End** | Distills conversation turns into structured fix/outcome units. |
328
+ | `memory_import_transcript` | **Transcript Sync** | Ingests `.jsonl` transcript and auto-binds memories to session nodes. |
329
+ | `memory_audit` | **Governance** | Queries the append-only operational audit ledger. |
330
+ | `memory_detect_agents` | **Onboarding** | Scans workstation for 80+ coding agent installations. |
331
+ | `memory_connect` | **Setup** | Auto-wires MCP server into detected installed agents with zero permissions. |
332
+ | `memory_detect_providers` | **Migration** | Scans machine for 29 external memory formats. |
333
+ | `memory_migrate` | **Migration** | Ingests external memories with state preservation and secret scrubbing. |
334
+ | `memory_export` / `import` | **Team Sharing** | Exports and imports portable JSON memory snapshots. |
335
+ | `memory_validate` | **Integrity Check** | Verifies database integrity and scans for credential leaks. |
336
+ | `memory_settings_get` / `set` | **Configuration** | Reads and updates unified global or project configuration settings. |
337
+ | `graph_status` | **AST Graph** | Inspects CodeGraph/Graphify symbol overlap provider status. |
338
+ | `graph_index` | **AST Graph** | Indexes AST symbol graph and caches in `.memory/graph-symbols.json`. |
309
339
 
310
- ## 📜 Full-Text Transcript Search with Conversation Bookends
340
+ </details>
311
341
 
312
- Search across past `.jsonl` transcripts (Claude Code, Cursor, Antigravity, Codex) with surrounding dialogue context windows and session start/end bookends:
342
+ <details>
343
+ <summary><b>💻 Full CLI Command Matrix (35 Commands)</b> — <i>Click to expand</i></summary>
313
344
 
314
345
  ```bash
315
- # Search transcript with dialogue window
316
- memory search-transcript "database connection pooling" session.jsonl --window 2 --max 5
346
+ memory <command> [arguments] [flags] # alias: musememory
317
347
  ```
318
348
 
319
- ---
320
-
321
- ## 🛡️ Built-In Vibeguard Secret Defense (Zero External Dependencies)
322
-
323
- `musememory` includes a pure TypeScript, zero-dependency security scanner that protects your repositories:
349
+ | Command | Arguments / Flags | Description |
350
+ | :--- | :--- | :--- |
351
+ | `install` | `[path] [--global]` | **One-line complete setup**: initializes `.memory/`, `USER.md`, and auto-wires coding agents. |
352
+ | `doctor` | `[path] [--global]` | **System diagnostic**: checks SQLite primary, schemas, secrets, and MCP connections. |
353
+ | `uninstall` | `[agent] [--purge] [--dry-run]` | **Clean uninstaller**: unwires MCP configs (and optionally purges `.memory/`). |
354
+ | `init` | `[path] [--legacy] [--global]` | Initialize `.memory/` directory and SQLite database. |
355
+ | `user` | `[get\|init\|set] [args] [--global]` | Manage `USER.md` persona & preferences across 5 clean archetypes. |
356
+ | `connect` | `[agent] [--all] [--force] [--dry-run]` | Auto-wire MCP into detected installed agents with zero permissions. |
357
+ | `agents` | *(none)* | Scan workstation for 80+ coding agents (Cursor, Claude Code, Antigravity, etc.). |
358
+ | `detect` | *(none)* | Scan workstation and local workspace for 29 external memory systems. |
359
+ | `migrate` | `[--provider P] [--all] [--dry-run] [--overwrite]` | Migrate memories into Muse Memory preserving active/archived state. |
360
+ | `ui` | `[--port N] [--global]` | Launch 6-view Cognitive Studio dashboard (default port: `2222`). |
361
+ | `context` | `[query] [--token-budget N] [--limit N]` | Retrieve Top-$K$ ranked active context for prompt injection. |
362
+ | `search` | `<query> [--limit N] [--token-budget N] [--type T]` | Ranked multi-factor token search with score breakdown. |
363
+ | `search-transcript` | `<query> [file.jsonl] [--window N]` | Full-text search past transcripts with dialogue context windows. |
364
+ | `harvest` | `<text\|file> --project P [--confirmed]` | Distill conversation turns into structured fix/decision memory units. |
365
+ | `import-transcript` | `<file.jsonl> [--project P] [--confirmed]` | Ingest raw `.jsonl` session transcripts from coding agents. |
366
+ | `capture` / `propose` | `<text> --project P [--title T] [--type T]` | Propose a memory entry with inline Vibeguard secret inspection. |
367
+ | `recall` | `<query> [--limit N] [--token-budget N]` | Rich recall displaying verification levels and related graph links. |
368
+ | `confirm` | `<id> [--global]` | Promote `candidate`, `disputed`, or `stale` entry to `confirmed`. |
369
+ | `supersede` | `<old_id> --with <new_id>` | Mark old entry superseded by new confirmed replacement. |
370
+ | `mark-stale` | `<id> [--reason <text>]` | Mark an entry stale with deprecation rationale. |
371
+ | `reject` | `<id> [--global]` | Mark an entry rejected. |
372
+ | `delete` | `<id> [--reason <text>]` | Permanently delete a memory entry and record audit event. |
373
+ | `audit` | `[--operation OP] [--entry-id ID] [--limit N]` | Query append-only operational audit trail (`.memory/audit.jsonl`). |
374
+ | `link` | `<id> --related <id1,id2>` | Synchronize bidirectional relation links between entries. |
375
+ | `export` / `import` | `[--out <file.json>]` / `<file.json>` | Export and import portable JSON memory snapshots. |
376
+ | `list` / `ls` | `[--status S] [--type T] [--project P]` | List memory entries with multi-field status and type filtering. |
377
+ | `stats` | `[--global]` | Breakdown statistics of total memories, status, and type metrics. |
378
+ | `briefing` | `[--limit N] [--global]` | Active summary of recent entries, status counts, and due items. |
379
+ | `nudge` | `[--global]` | Proactive attention list: overdue entries, stale policies, open loops. |
380
+ | `routine` | `run <name>` / `install [name]` | Execute `.memory/routines.yaml` steps or print crontab lines. |
381
+ | `wiki` | `compile\|list\|show <slug>` | Compile and browse Obsidian-compatible Markdown wiki pages. |
382
+ | `entities` | `list\|show <id>\|related <id>` | Inspect extracted knowledge graph entities and co-occurrence weights. |
383
+ | `settings` | `get\|set\|reset\|export\|import` | Manage unified settings across retrieval, wiki, PageIndex, and UI. |
384
+ | `current` | `get` / `set <text> --project P` | Read or append hard constraints in `.memory/CURRENT.md`. |
385
+ | `graph` | `status` / `index` | Query active CodeGraph provider status or index AST symbol map. |
386
+ | `mcp` | *(none)* | Start stdio MCP server (Protocol 2024-11-05). |
324
387
 
325
- - **Zero-Leakage Guarantee**: Intercepts OpenAI/Anthropic keys (`sk-*`), GitHub tokens (`ghp_*`), NPM tokens, AWS access keys (`AKIA*`), private key blocks, database connection strings, and plaintext credentials before they can ever be written to disk.
326
- - **100% Standalone**: Does not require any external scripts or system installations.
388
+ </details>
327
389
 
328
- ---
390
+ <details>
391
+ <summary><b>🧠 Shipped Agent Skills (<code>.agents/skills/</code>)</b> — <i>Click to expand</i></summary>
329
392
 
330
- ## 🔮 Scope of Work & Roadmap
393
+ Muse Memory ships with 6 turnkey Agent Skills designed for coding agents (Claude Code, Cursor, Antigravity, OpenCode, Codex, Gemini CLI, etc.) under `.agents/skills/`:
331
394
 
332
- Every Scope-of-Work item is tracked as a GitHub issue and delivered via pull request. Status: ☐ planned · ◐ in progress · ✅ done. Live status: [issue tracker](https://github.com/harshsinghmp/musememory/issues).
333
-
334
- | Status | Item | Tracker |
395
+ | Skill | Trigger Phase | Core Agent Responsibility |
335
396
  | :--- | :--- | :--- |
336
- | ✅ | Dynamic Prompt Token Budgeter (`--token-budget N`) — knapsack packing under hard token ceilings | shipped v1.1.0 |
337
- | ✅ | Scene-Based Hierarchical Consolidation (`memory consolidate`) | [#1](https://github.com/harshsinghmp/musememory/issues/1) |
338
- | ✅ | Autonomous Verification Oracle (`memory verify <id>`) | [#2](https://github.com/harshsinghmp/musememory/issues/2) |
339
- | ✅ | Multi-Hop Causality Graph Tracer (`memory trace <id>`) | [#3](https://github.com/harshsinghmp/musememory/issues/3) |
340
- | ✅ | In-Place Core Memory Partitioning (`memory core`) | [#4](https://github.com/harshsinghmp/musememory/issues/4) |
341
- | ✅ | Automated Post-Turn Transcript Harvester Hook | [#5](https://github.com/harshsinghmp/musememory/issues/5) |
342
- | ✅ | Real-Time Agency WebSocket Hub (`memory daemon`) | [#6](https://github.com/harshsinghmp/musememory/issues/6) |
343
- | ✅ | Local Offline Hybrid Vector Engine | [#7](https://github.com/harshsinghmp/musememory/issues/7) |
344
- | ✅ | Delete Deprecated `MemoryStore` Shim *(target: October 2026)* | [#8](https://github.com/harshsinghmp/musememory/issues/8) |
345
- | ✅ | Self-Evolving Skill Distillation | [#9](https://github.com/harshsinghmp/musememory/issues/9) |
346
- | ✅ | 3-Layer Progressive Disclosure | [#10](https://github.com/harshsinghmp/musememory/issues/10) |
347
- | ✅ | Bi-Temporal Reinforcement Feedback | [#11](https://github.com/harshsinghmp/musememory/issues/11) |
348
- | ✅ | Ambient Open-Loop Tracker | [#12](https://github.com/harshsinghmp/musememory/issues/12) |
349
- | ✅ | Knowledge Graph UI v2 | [#13](https://github.com/harshsinghmp/musememory/issues/13) |
350
- | ✅ | Proactive Nudges & Check-ins (`memory nudge`) — SOW-101 | [#28](https://github.com/harshsinghmp/musememory/issues/28) |
351
- | ✅ | Daily Briefing & Routines Scheduler (cron-invoked, no daemon) — SOW-102 | [#29](https://github.com/harshsinghmp/musememory/issues/29) |
352
- | ✅ | Open-Loop / Task Extraction from Transcripts — SOW-103 | [#30](https://github.com/harshsinghmp/musememory/issues/30) |
353
- | ✅ | Calendar / Time-Aware Follow-ups (`due_at` / `expires_at`) — SOW-104 | [#31](https://github.com/harshsinghmp/musememory/issues/31) |
354
- ## ⚡ How Memory Grows, Reloads &amp; Auto-Archives
355
-
356
- ```mermaid
357
- flowchart TD
358
- subgraph HotPath["Active Conversation (Hot Path)"]
359
- User["User asks question / gives task"]
360
- Agent["AI Agent executes turn"]
361
- Recall["1. Auto-Retrieve Top-K Context & Active Constraints"]
362
- Distill["2. Auto-Distill Fixes & Decisions (Harvest)"]
363
- end
364
-
365
- subgraph DefenseGate["Self-Contained Vibeguard"]
366
- Scan["3. Zero-Leakage Secret Scan (Blocks API keys & DB URLs)"]
367
- end
368
-
369
- subgraph StoreLifecycle["Self-Organizing Knowledge Engine (.memory/)"]
370
- Atomic["4. Atomic Write (m_timestamp_slug.yaml)"]
371
- Lifecycle["5. Lifecycle Transitions (Candidate ➔ Confirmed ➔ Superseded)"]
372
- Decay["6. Temporal Staleness Decay & Auto-Archiving"]
373
- end
374
-
375
- User --> Agent
376
- Agent --> Recall
377
- Recall --> Agent
378
- Agent --> Distill
379
- Distill --> Scan
380
- Scan --> Atomic
381
- Atomic --> Lifecycle
382
- Lifecycle --> Decay
383
- ```
384
-
385
- - **Incremental Auto-Growing**: Every decision, bug fix, operational rule, and session checkpoint is saved as a discrete, human-readable YAML document in `.memory/memories/`.
386
- - **Context Reload Continuity**: On a fresh turn or session restart, `get_context` feeds only the Top-$K$ highest-salience, verified knowledge units—reducing context tokens by **85–95%** and eliminating outdated hallucinations.
387
- - **Smart Archiving &amp; Controlled Forgetting**: Old approaches are marked `superseded` with explicit forward/backward links. Time-based staleness policies (e.g. 30 days for temporary discoveries, 90 days for fixes, 365 days for architecture) automatically down-weight decaying knowledge.
388
-
389
- ---
397
+ | [`muse-ground`](.agents/skills/muse-ground/SKILL.md) | **Session Start** | Retrieves Top-$K$ relevant memories, active `USER.md` persona profile, and `CURRENT.md` constraints before writing code. |
398
+ | [`muse-capture`](.agents/skills/muse-capture/SKILL.md) | **During Fixes & Refactors** | Captures atomic fix/architecture memories, validates evidence, runs Vibeguard secret scan, and supersedes obsolete knowledge. |
399
+ | [`muse-current`](.agents/skills/muse-current/SKILL.md) | **Invariants & Handoffs** | Synchronizes hard constraints into `.memory/CURRENT.md` and persists structured handoffs across context resets. |
400
+ | [`muse-graph`](.agents/skills/muse-graph/SKILL.md) | **AST Code Investigation** | Indexes `.codegraph`/`.graphify` symbols and queries symbol-matching decisions with `+0.2` graph overlap bonus. |
401
+ | [`muse-wiki`](.agents/skills/muse-wiki/SKILL.md) | **Knowledge Compounding** | Compiles confirmed memories into Obsidian-compatible Markdown pages (`[[wikilinks]]`) and entity co-occurrence graphs. |
402
+ | [`muse-brief`](.agents/skills/muse-brief/SKILL.md) | **Daily Hygiene & Loops** | Generates morning briefings, tracks 90/180-day staleness decay, and surfaces unresolved transcript commitments. |
390
403
 
391
- ## 👤 User Persona & Preferences (`USER.md`) & Setup Wizard
404
+ </details>
392
405
 
393
- Muse Memory maintains a persistent user profile (`~/.memory/USER.md` globally, or `.memory/USER.md` locally) to ground AI agents in your working style, communication preferences, and toolchain rules.
406
+ <details>
407
+ <summary><b>👤 5 Zero-Fingerprint Role Archetypes (`USER.md`)</b> — <i>Click to expand</i></summary>
394
408
 
395
- ### 🎭 5 Zero-Fingerprint Role Archetypes
396
-
397
- When running `memory install`, an interactive setup wizard configures your primary archetype (or choose one manually anytime):
409
+ Muse Memory maintains a persistent user profile (`~/.memory/USER.md` globally, or `.memory/USER.md` locally) to ground AI agents in your working style:
398
410
 
399
411
  1. **`developer`** (Default): Code-first, direct, concise, runnable diffs, strict types, fail-fast mechanics.
400
412
  2. **`designer`**: Visual hierarchy, CSS/Tailwind systems, GSAP animations, WCAG accessibility, Figma/tokens design tokens.
@@ -414,38 +426,12 @@ memory user init designer --global
414
426
  memory user set "- Prefers TypeScript, Bun, and ultra terse responses"
415
427
  ```
416
428
 
417
- ### 🧠 Prompt Injection Hierarchy & Proactive Self-Nudge
418
- When `get_context` or `formatPromptContext()` builds the LLM prompt context, it structures information deterministically:
419
- 1. **`### User Profile & Preferences (USER.md)`** (Tone, role, rules)
420
- 2. **`### Active Working Constraints (CURRENT.md)`** (Project invariants & open loops)
421
- 3. **`### Relevant Memories & Learned Patterns`** (Top-$K$ ranked memories)
422
- 4. **`*Memory Directive: When learning durable facts, bug resolutions, or user preferences, call memory_capture immediately.*`**
423
-
424
- ---
425
-
426
- ## 📜 Full-Text Transcript Search with Conversation Bookends
427
-
428
- Search across past `.jsonl` transcripts (Claude Code, Cursor, Antigravity, Codex) with surrounding dialogue context windows and session start/end bookends:
429
-
430
- ```bash
431
- # Search transcript with dialogue window
432
- memory search-transcript "database connection pooling" session.jsonl --window 2 --max 5
433
- ```
434
-
435
- ---
436
-
437
- ## 🛡️ Built-In Vibeguard Secret Defense (Zero External Dependencies)
438
-
439
- `musememory` includes a pure TypeScript, zero-dependency security scanner that protects your repositories:
440
-
441
- - **Zero-Leakage Guarantee**: Intercepts OpenAI/Anthropic keys (`sk-*`), GitHub tokens (`ghp_*`), NPM tokens, AWS access keys (`AKIA*`), private key blocks, database connection strings, and plaintext credentials before they can ever be written to disk.
442
- - **100% Standalone**: Does not require any external scripts or system installations.
443
-
444
- ---
429
+ </details>
445
430
 
446
- ## 🔮 Scope of Work & Roadmap
431
+ <details>
432
+ <summary><b>🔮 SOW & Roadmap Issue Tracker</b> — <i>Click to expand</i></summary>
447
433
 
448
- Every Scope-of-Work item is tracked as a GitHub issue and delivered via pull request. Status: ☐ planned · ◐ in progress · ✅ done. Live status: [issue tracker](https://github.com/harshsinghmp/musememory/issues).
434
+ Every Scope-of-Work item is tracked as a GitHub issue and delivered via pull request. Live status: [issue tracker](https://github.com/harshsinghmp/musememory/issues).
449
435
 
450
436
  | Status | Item | Tracker |
451
437
  | :--- | :--- | :--- |
@@ -457,7 +443,7 @@ Every Scope-of-Work item is tracked as a GitHub issue and delivered via pull req
457
443
  | ✅ | Automated Post-Turn Transcript Harvester Hook | [#5](https://github.com/harshsinghmp/musememory/issues/5) |
458
444
  | ✅ | Real-Time Agency WebSocket Hub (`memory daemon`) | [#6](https://github.com/harshsinghmp/musememory/issues/6) |
459
445
  | ✅ | Local Offline Hybrid Vector Engine | [#7](https://github.com/harshsinghmp/musememory/issues/7) |
460
- | ✅ | Delete Deprecated `MemoryStore` Shim *(target: October 2026)* | [#8](https://github.com/harshsinghmp/musememory/issues/8) |
446
+ | ✅ | Delete Deprecated `MemoryStore` Shim *(shipped v1.5.0)* | [#8](https://github.com/harshsinghmp/musememory/issues/8) |
461
447
  | ✅ | Self-Evolving Skill Distillation | [#9](https://github.com/harshsinghmp/musememory/issues/9) |
462
448
  | ✅ | 3-Layer Progressive Disclosure | [#10](https://github.com/harshsinghmp/musememory/issues/10) |
463
449
  | ✅ | Bi-Temporal Reinforcement Feedback | [#11](https://github.com/harshsinghmp/musememory/issues/11) |
@@ -468,94 +454,9 @@ Every Scope-of-Work item is tracked as a GitHub issue and delivered via pull req
468
454
  | ✅ | Open-Loop / Task Extraction from Transcripts — SOW-103 | [#30](https://github.com/harshsinghmp/musememory/issues/30) |
469
455
  | ✅ | Calendar / Time-Aware Follow-ups (`due_at` / `expires_at`) — SOW-104 | [#31](https://github.com/harshsinghmp/musememory/issues/31) |
470
456
  | ✅ | muse-agents ↔ musememory Integration Contract (`--for-agent`) — SOW-106 | [#33](https://github.com/harshsinghmp/musememory/issues/33) |
471
- | ☐ | AST Symbol Graph Integration (CodeGraph / Graphify provider) — SOW-107 | [#35](https://github.com/harshsinghmp/musememory/issues/35) |
472
-
473
- ---
474
-
475
- ## 💻 Complete CLI Command Reference
476
-
477
- ```bash
478
- memory <command> [arguments] [flags] # alias: musememory
479
- ```
480
-
481
- | Command | Arguments / Flags | Description |
482
- | :--- | :--- | :--- |
483
- | `install` | `[path] [--global]` | **One-line complete setup**: initializes `.memory/`, `USER.md`, and auto-wires coding agents. |
484
- | `doctor` | `[path] [--global]` | **System diagnostic**: checks SQLite primary, schemas, secrets, and MCP connections. |
485
- | `uninstall` | `[agent] [--purge] [--dry-run]` | **Clean uninstaller**: unwires MCP configs (and optionally purges `.memory/`). |
486
- | `init` | `[path] [--legacy] [--global]` | Initialize `.memory/` directory and SQLite database. |
487
- | `user` | `[get\|init\|set] [args] [--global]` | Manage `USER.md` persona & preferences across 5 clean archetypes. |
488
- | `connect` | `[agent] [--all] [--force] [--dry-run]` | Auto-wire MCP into detected installed agents with zero permissions. |
489
- | `agents` | *(none)* | Scan workstation for 80+ coding agents (Cursor, Claude Code, Antigravity, etc.). |
490
- | `detect` | *(none)* | Scan workstation and local workspace for 29 external memory systems. |
491
- | `migrate` | `[--provider P] [--all] [--dry-run] [--overwrite]` | Migrate memories into Muse Memory preserving active/archived state. |
492
- | `ui` | `[--port N] [--global]` | Launch 6-view Cognitive Studio dashboard (default port: `2222`). |
493
- | `context` | `[query] [--token-budget N] [--limit N]` | Retrieve Top-$K$ ranked active context for prompt injection. |
494
- | `search` | `<query> [--limit N] [--token-budget N] [--type T]` | Ranked multi-factor token search with score breakdown. |
495
- | `search-transcript` | `<query> [file.jsonl] [--window N]` | Full-text search past transcripts with dialogue context windows. |
496
- | `harvest` | `<text\|file> --project P [--confirmed]` | Distill conversation turns into structured fix/decision memory units. |
497
- | `import-transcript` | `<file.jsonl> [--project P] [--confirmed]` | Ingest raw `.jsonl` session transcripts from coding agents. |
498
- | `capture` / `propose` | `<text> --project P [--title T] [--type T]` | Propose a memory entry with inline Vibeguard secret inspection. |
499
- | `recall` | `<query> [--limit N] [--token-budget N]` | Rich recall displaying verification levels and related graph links. |
500
- | `confirm` | `<id> [--global]` | Promote `candidate`, `disputed`, or `stale` entry to `confirmed`. |
501
- | `supersede` | `<old_id> --with <new_id>` | Mark old entry superseded by new confirmed replacement. |
502
- | `mark-stale` | `<id> [--reason <text>]` | Mark an entry stale with deprecation rationale. |
503
- | `reject` | `<id> [--global]` | Mark an entry rejected. |
504
- | `delete` | `<id> [--reason <text>]` | Permanently delete a memory entry and record audit event. |
505
- | `audit` | `[--operation OP] [--entry-id ID] [--limit N]` | Query append-only operational audit trail (`.memory/audit.jsonl`). |
506
- | `link` | `<id> --related <id1,id2>` | Synchronize bidirectional relation links between entries. |
507
- | `export` / `import` | `[--out <file.json>]` / `<file.json>` | Export and import portable JSON memory snapshots. |
508
- | `list` / `ls` | `[--status S] [--type T] [--project P]` | List memory entries with multi-field status and type filtering. |
509
- | `stats` | `[--global]` | Breakdown statistics of total memories, status, and type metrics. |
510
- | `briefing` | `[--limit N] [--global]` | Active summary of recent entries, status counts, and due items. |
511
- | `nudge` | `[--global]` | Proactive attention list: overdue entries, stale policies, open loops. |
512
- | `routine` | `run <name>` / `install [name]` | Execute `.memory/routines.yaml` steps or print crontab lines. |
513
- | `wiki` | `compile\|list\|show <slug>` | Compile and browse Obsidian-compatible Markdown wiki pages. |
514
- | `entities` | `list\|show <id>\|related <id>` | Inspect extracted knowledge graph entities and co-occurrence weights. |
515
- | `settings` | `get\|set\|reset\|export\|import` | Manage unified settings across retrieval, wiki, PageIndex, and UI. |
516
- | `current` | `get` / `set <text> --project P` | Read or append hard constraints in `.memory/CURRENT.md`. |
517
- | `graph` | `status` | Query active CodeGraph provider status. |
518
- | `mcp` | *(none)* | Start stdio MCP server (Protocol 2024-11-05). |
457
+ | ✅ | AST Symbol Graph Integration (CodeGraph / Graphify provider) — SOW-107 | [#35](https://github.com/harshsinghmp/musememory/issues/35) |
519
458
 
520
- ---
521
-
522
- ## 🔌 MCP Server Tool Reference
523
-
524
- When registered as an MCP server, `musememory` exposes the following native tools:
525
-
526
- | MCP Tool | Execution Phase | Description |
527
- | :--- | :--- | :--- |
528
- | `get_context` | **Session Start** | Fetches Top-$K$ ranked memories, `USER.md` profile, and active `CURRENT.md` constraints. |
529
- | `search` | **Investigation** | Searches memory units with query, token budget, project, type, and verification filters. |
530
- | `memory_current` | **Constraints** | Reads or appends active project working constraints (`CURRENT.md`). |
531
- | `memory_get_user_profile` | **Context Loading** | Reads active `USER.md` persona and communication preferences. |
532
- | `memory_set_user_profile` | **Preferences** | Updates `USER.md` profile with inline secret defense. |
533
- | `memory_capture` | **During Fixes** | Saves a memory entry with inline Vibeguard secret inspection. |
534
- | `memory_confirm` | **Decision Approval** | Promotes candidate insight to confirmed status. |
535
- | `memory_supersede` | **Refactoring** | Marks outdated knowledge superseded by a confirmed replacement. |
536
- | `memory_link` | **Graph Building** | Connects related memories bidirectionally. |
537
- | `memory_mark_stale` | **Deprecation** | Flags decaying knowledge with deprecation rationale. |
538
- | `memory_reject` | **Hypothesis Refutation** | Marks invalidated hypotheses as rejected. |
539
- | `memory_delete` | **Purge** | Permanently deletes an entry and records audit ledger log. |
540
- | `memory_tree_search` | **Tree Retrieval** | Hierarchical reasoning search across partitioned memory shards. |
541
- | `memory_wiki_compile` | **Wiki Compiler** | Compiles confirmed memories into Obsidian-compatible Markdown pages. |
542
- | `memory_wiki_search` / `get` | **Wiki Reading** | Searches and reads compiled concept and entity wiki pages. |
543
- | `memory_entities_search` / `get` | **Entity Graph** | Searches extracted entities and inspects co-occurrence strengths. |
544
- | `memory_pageindex_index` | **Doc Indexing** | Builds a hierarchical reasoning tree from document content. |
545
- | `memory_pageindex_search` | **Doc Search** | Searches PageIndex document tree with reasoning explanations. |
546
- | `memory_pageindex_import` | **Doc Knowledge** | Imports PageIndex search insights directly into memory units. |
547
- | `memory_search_transcripts` | **History Search** | Full-text search over past `.jsonl` transcripts with dialogue context windows. |
548
- | `memory_harvest` | **Session End** | Distills conversation turns into structured fix/outcome units. |
549
- | `memory_import_transcript` | **Transcript Sync** | Ingests `.jsonl` transcript and auto-binds memories to session nodes. |
550
- | `memory_audit` | **Governance** | Queries the append-only operational audit ledger. |
551
- | `memory_detect_agents` | **Onboarding** | Scans workstation for 80+ coding agent installations. |
552
- | `memory_connect` | **Setup** | Auto-wires MCP server into detected installed agents with zero permissions. |
553
- | `memory_detect_providers` | **Migration** | Scans machine for 29 external memory formats. |
554
- | `memory_migrate` | **Migration** | Ingests external memories with state preservation and secret scrubbing. |
555
- | `memory_export` / `import` | **Team Sharing** | Exports and imports portable JSON memory snapshots. |
556
- | `memory_validate` | **Integrity Check** | Verifies database integrity and scans for credential leaks. |
557
- | `memory_settings_get` / `set` | **Configuration** | Reads and updates unified global or project configuration settings. |
558
- | `graph_status` | **AST Graph** | Inspects CodeGraph symbol overlap provider status. |
459
+ </details>
559
460
 
560
461
  ---
561
462
 
@@ -563,7 +464,7 @@ When registered as an MCP server, `musememory` exposes the following native tool
563
464
 
564
465
  ```bash
565
466
  bun install
566
- bun test # 278 passed across 50 test files (1072 assertions)
467
+ bun test # 304 passed across 55 test files (1248 assertions)
567
468
  bun run typecheck # 0 static type errors
568
469
  bun run build # Clean bundled distribution build (dist/index.js)
569
470
  ```