musememory 1.5.0 → 1.6.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.
- package/README.md +305 -264
- package/dist/index.js +21916 -20407
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
|
|
8
8
|
|
|
9
|
-
|
|
10
10
|
|
|
11
11
|
|
|
12
12
|
|
|
@@ -18,54 +18,72 @@
|
|
|
18
18
|
|
|
19
19
|
## 💡 What is Muse Memory? (TL;DR)
|
|
20
20
|
|
|
21
|
-
Most AI chatbots and coding assistants have **"goldfish memory"**: every time you close a
|
|
21
|
+
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.
|
|
22
22
|
|
|
23
|
-
**Muse Memory gives your AI assistants a persistent, self-organizing notebook directly on your machine.**
|
|
23
|
+
**Muse Memory gives your AI assistants a persistent, self-organizing cognitive notebook directly on your machine.**
|
|
24
24
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
25
|
+
```
|
|
26
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
27
|
+
│ AI Agents & IDE Platforms │
|
|
28
|
+
│ (Claude Code, Cursor, Antigravity, Windsurf, Codex, CLI) │
|
|
29
|
+
└──────────────────────────────┬──────────────────────────────┘
|
|
30
|
+
│ MCP stdio / Terminal CLI
|
|
31
|
+
┌──────────────────────────────▼──────────────────────────────┐
|
|
32
|
+
│ Muse Memory Core Engine │
|
|
33
|
+
│ │
|
|
34
|
+
│ ┌───────────────────┐ ┌──────────────────┐ ┌──────────────┐ │
|
|
35
|
+
│ │ Retrieval Engine │ │ Vibeguard Secret │ │ Auto-Migrate │ │
|
|
36
|
+
│ │ (Token Knapsack) │ │ Defense Scanner │ │ (29 Engines)│ │
|
|
37
|
+
│ └───────────────────┘ └──────────────────┘ └──────────────┘ │
|
|
38
|
+
│ ┌───────────────────┐ ┌──────────────────┐ ┌──────────────┐ │
|
|
39
|
+
│ │ LifeCycle Machine │ │ Knowledge Wiki │ │ Audit Ledger │ │
|
|
40
|
+
│ │(State Transitions)│ │ (Obsidian/Entities│ │(audit.jsonl) │ │
|
|
41
|
+
│ └───────────────────┘ └──────────────────┘ └──────────────┘ │
|
|
42
|
+
└──────────────────────────────┬──────────────────────────────┘
|
|
43
|
+
│ Atomic I/O
|
|
44
|
+
┌──────────────────────────────▼──────────────────────────────┐
|
|
45
|
+
│ Dual-Scope Storage Engine (.memory/) │
|
|
46
|
+
│ │
|
|
47
|
+
│ .memory/ │
|
|
48
|
+
│ ├── memory.db # Primary SQLite cognitive database │
|
|
49
|
+
│ ├── CURRENT.md # Active hard constraints & handoff │
|
|
50
|
+
│ ├── USER.md # Persona & developer preferences │
|
|
51
|
+
│ ├── audit.jsonl # Append-only operational audit trail│
|
|
52
|
+
│ └── memories/ # Dual-persisted YAML export mirror │
|
|
53
|
+
│ ├── m_1700000001000_auth.yaml │
|
|
54
|
+
│ └── m_1700000002000_arch.yaml │
|
|
55
|
+
└─────────────────────────────────────────────────────────────┘
|
|
56
|
+
```
|
|
34
57
|
|
|
35
|
-
- **
|
|
36
|
-
- **
|
|
37
|
-
- **
|
|
38
|
-
- **
|
|
39
|
-
- **
|
|
40
|
-
- **
|
|
41
|
-
- **
|
|
42
|
-
- **Universal Transcript Ingestion**: Ingest raw `.jsonl` conversation transcripts (`memory import-transcript <file.jsonl>`) from Claude Code, Antigravity, Cursor, and Codex.
|
|
43
|
-
- **Operational Audit Ledger**: Append-only compliance log (`.memory/audit.jsonl` / `memory audit`) tracking all memory mutations.
|
|
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.
|
|
44
65
|
|
|
45
66
|
---
|
|
46
67
|
|
|
47
|
-
##
|
|
68
|
+
## ⚡ Quick Start & Installation
|
|
48
69
|
|
|
49
70
|
> [!TIP]
|
|
50
|
-
>
|
|
51
71
|
> ### ⚡ Instant 5-Second Setup (Zero-Install NPX / BunX)
|
|
52
|
-
>
|
|
53
|
-
> **No global installation required. No package clutter.** Set up your memory system and wire your AI agents with a single command:
|
|
72
|
+
> **No global installation required.** Set up your memory system and wire your AI agents with a single command:
|
|
54
73
|
>
|
|
55
74
|
> ```bash
|
|
56
75
|
> npx musememory install
|
|
57
76
|
> # (or with Bun: bunx musememory install)
|
|
58
77
|
> ```
|
|
59
78
|
>
|
|
60
|
-
> This
|
|
61
|
-
>
|
|
62
|
-
>
|
|
63
|
-
> 2. Auto-detects all installed AI coding agents (Claude Code, Cursor, Antigravity, Windsurf, Codex, Gemini CLI, Hermes Agent, OpenCode, OpenClaw, etc.).
|
|
79
|
+
> This command automatically:
|
|
80
|
+
> 1. Initializes the SQLite primary database (`.memory/memory.db`) and `CURRENT.md` constraints file.
|
|
81
|
+
> 2. Auto-detects all installed AI coding agents on your machine.
|
|
64
82
|
> 3. Auto-wires the memory MCP server into installed agents with zero-permission auto-approval.
|
|
65
|
-
> 4. Scans for existing memory stores (
|
|
83
|
+
> 4. Scans for existing memory stores (Letta, Mem0, Beads, Supermemory, etc.) for instant migration.
|
|
66
84
|
>
|
|
67
85
|
> **Verify anytime**: `npx musememory doctor`
|
|
68
|
-
> **
|
|
86
|
+
> **Explore Studio UI**: `npx musememory ui` (Opens cognitive studio on port 2222)
|
|
69
87
|
|
|
70
88
|
---
|
|
71
89
|
|
|
@@ -85,167 +103,138 @@ git clone https://github.com/harshsinghmp/musememory.git && cd musememory
|
|
|
85
103
|
docker build -t musememory .
|
|
86
104
|
```
|
|
87
105
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
memory doctor # Comprehensive system health check
|
|
92
|
-
memory connect --all # Auto-wire all detected AI coding agents
|
|
93
|
-
memory briefing # Summarize active knowledge & constraints
|
|
94
|
-
```
|
|
106
|
+
> [!NOTE]
|
|
107
|
+
> ### 📊 How does Muse Memory compare to other solutions?
|
|
108
|
+
> Explore our interactive, table-free **[30-System Architectural Comparison Dossier](musememory-comparison.html)** (`musememory-comparison.html`) to inspect concrete architectural differentials and one-click migration recipes against 29 external memory engines (Letta, Mem0, Supermemory, Cognee, Beads, Mnemosyne, GBrain, etc.).
|
|
95
109
|
|
|
96
110
|
---
|
|
97
111
|
|
|
98
|
-
## 🔄 Complete NPX Lifecycle (Install → Verify → Uninstall)
|
|
112
|
+
## 🔄 Complete NPX Lifecycle (Install → Verify → Connect → Uninstall)
|
|
99
113
|
|
|
100
|
-
Every command
|
|
114
|
+
Every command works with **zero installation** via `npx musememory <cmd>` (or `bunx musememory <cmd>`). Use plain `memory <cmd>` if installed globally.
|
|
101
115
|
|
|
102
116
|
### 1️⃣ Install & Auto-Wire
|
|
103
|
-
|
|
104
117
|
```bash
|
|
105
118
|
# Full setup: init .memory/, detect agents, wire MCP, scan for migratable stores
|
|
106
119
|
npx musememory install
|
|
107
120
|
|
|
108
|
-
# Initialize
|
|
121
|
+
# Initialize workspace only (no agent wiring)
|
|
109
122
|
npx musememory init
|
|
110
123
|
```
|
|
111
124
|
|
|
112
|
-
### 2️⃣ Verify
|
|
113
|
-
|
|
125
|
+
### 2️⃣ Verify & Health Check
|
|
114
126
|
```bash
|
|
115
|
-
#
|
|
127
|
+
# Comprehensive ecosystem diagnostic (storage, schemas, secrets, MCP wiring)
|
|
116
128
|
npx musememory doctor
|
|
117
129
|
|
|
118
|
-
#
|
|
130
|
+
# Memory store breakdown and active briefing
|
|
119
131
|
npx musememory stats
|
|
120
132
|
npx musememory briefing
|
|
121
133
|
```
|
|
122
134
|
|
|
123
|
-
### 3️⃣ Connect Agents
|
|
124
|
-
|
|
135
|
+
### 3️⃣ Connect Coding Agents (80+ Platforms)
|
|
125
136
|
```bash
|
|
126
|
-
# Scan workstation for
|
|
137
|
+
# Scan workstation for installed AI coding agents
|
|
127
138
|
npx musememory agents
|
|
128
139
|
|
|
129
|
-
# Auto-wire all detected agents
|
|
140
|
+
# Auto-wire all detected agents with zero permissions
|
|
130
141
|
npx musememory connect all
|
|
131
142
|
|
|
132
|
-
# Wire one specific agent
|
|
143
|
+
# Wire one specific agent explicitly
|
|
133
144
|
npx musememory connect claude-code
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
npx musememory connect
|
|
145
|
+
npx musememory connect cursor
|
|
146
|
+
npx musememory connect antigravity
|
|
147
|
+
npx musememory connect windsurf
|
|
148
|
+
npx musememory connect opencode
|
|
137
149
|
```
|
|
138
150
|
|
|
139
|
-
### 4️⃣
|
|
140
|
-
|
|
151
|
+
### 4️⃣ Clean Uninstallation
|
|
141
152
|
```bash
|
|
142
153
|
# Preview what would be unwired
|
|
143
154
|
npx musememory uninstall --dry-run
|
|
144
155
|
|
|
145
|
-
# Unwire MCP from all agents (
|
|
156
|
+
# Unwire MCP from all agents (preserves .memory/ data)
|
|
146
157
|
npx musememory uninstall
|
|
147
158
|
|
|
148
|
-
# Unwire AND purge project .memory/ data
|
|
159
|
+
# Unwire AND purge local project .memory/ data
|
|
149
160
|
npx musememory uninstall --purge
|
|
150
|
-
|
|
151
|
-
# Remove a persistent global install (if you used Option A above)
|
|
152
|
-
npm uninstall -g musememory # or: bun remove -g musememory
|
|
153
|
-
rm -f ~/.local/bin/memory ~/.local/bin/musememory
|
|
154
161
|
```
|
|
155
162
|
|
|
156
|
-
### 🛠️ Troubleshooting
|
|
157
|
-
|
|
158
|
-
| Symptom | Check | Fix |
|
|
159
|
-
|---|---|---|
|
|
160
|
-
| `command not found: memory` | You skipped global install, or `~/.local/bin` is not on PATH | Use `npx musememory <cmd>` instead, or add `~/.local/bin` to PATH |
|
|
161
|
-
| `npx` hangs or prompts to install | Package not cached yet | Confirm prompt with `y`, or pre-install: `npm install -g musememory` |
|
|
162
|
-
| Bun vs npm mismatch / broken binary | `which memory` points at stale symlink | `rm -f ~/.local/bin/memory ~/.local/bin/musememory`, reinstall via npm/bun |
|
|
163
|
-
| Agent doesn't show the MCP server | Run `npx musememory doctor` and re-check agent config | `npx musememory connect <agent> --force` to rewrite config |
|
|
164
|
-
| MCP configured but tools missing | Agent session started before wiring | Restart the agent session so it reloads MCP config |
|
|
165
|
-
| Permission errors during connect/uninstall | Config files owned by another user | Fix ownership of the agent config dir, then retry |
|
|
166
|
-
| Store seems empty / wrong scope | You may be in a subdirectory; root detection walks up | Run from project root, or set an explicit dir: `npx musememory stats <dir>` |
|
|
167
|
-
| Stale/partial install after upgrade | Old dist cached by npx | Clear npx cache (`npx clear-npx-cache`) or reinstall globally |
|
|
168
|
-
|
|
169
163
|
---
|
|
170
164
|
|
|
171
|
-
|
|
165
|
+
## 🏛️ System Capabilities & Architecture
|
|
172
166
|
|
|
173
|
-
|
|
167
|
+
### 1. Dual-Scope Storage (Local vs Global)
|
|
168
|
+
- **Local Workspace (`<project>/.memory/`)**: Repository-specific architectural decisions, bug fixes, active `CURRENT.md` constraints, and session timeline nodes.
|
|
169
|
+
- **Global System (`~/.memory/` via `--global` / `-g`)**: Universal developer preferences, cross-repo coding conventions, and global prompt patterns.
|
|
174
170
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
memory agents
|
|
178
|
-
|
|
179
|
-
# 2. Auto-wire all installed agents with zero-permission auto-approval
|
|
180
|
-
memory connect --all
|
|
181
|
-
|
|
182
|
-
# 3. Or wire a specific agent explicitly
|
|
183
|
-
memory connect claude-code # Auto-approves tools in ~/.claude/settings.json
|
|
184
|
-
memory connect cursor # Auto-approves memory in ~/.cursor/mcp.json
|
|
185
|
-
memory connect hermes # Auto-wires MCP in ~/.hermes/config.yaml
|
|
186
|
-
memory connect opencode # Auto-wires local MCP in ~/.config/opencode/opencode.json
|
|
187
|
-
memory connect openclaw # Auto-wires MCP in ~/.openclaw/openclaw.json
|
|
188
|
-
memory connect antigravity # Configures Antigravity CLI MCP
|
|
189
|
-
memory connect windsurf # Configures Windsurf MCP config
|
|
190
|
-
memory connect codex # Configures Codex CLI MCP
|
|
191
|
-
memory connect gemini-cli # Configures Gemini CLI MCP
|
|
171
|
+
### 2. Deterministic 7-State Lifecycle Machine & Audit Ledger
|
|
172
|
+
All memory entries transition through a guarded state machine:
|
|
192
173
|
```
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
"args": ["mcp"]
|
|
202
|
-
}
|
|
203
|
-
}
|
|
204
|
-
}
|
|
174
|
+
[propose] ──► candidate ──► confirm() ──► confirmed ──► supersede() ──► superseded
|
|
175
|
+
│ │
|
|
176
|
+
├──► markStale() ───────────┤
|
|
177
|
+
│ │ │
|
|
178
|
+
│ ▼ ▼
|
|
179
|
+
└──► stale rejected
|
|
180
|
+
│
|
|
181
|
+
└──► delete() ──► [Purged from Disk + audit.jsonl logged]
|
|
205
182
|
```
|
|
183
|
+
Every mutation (`propose`, `confirm`, `supersede`, `mark_stale`, `reject`, `delete`, `link`) writes an immutable log record to `.memory/audit.jsonl`.
|
|
206
184
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
**Do I need to start Muse Memory manually?**
|
|
185
|
+
### 3. Knapsack Token Budgeting & Multi-Factor Scoring
|
|
186
|
+
Retrieval dynamically ranks knowledge using a calibrated multi-factor formula:
|
|
187
|
+
$$\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}}}$$
|
|
188
|
+
The engine greedily packs ranked memories up to the requested `--token-budget` to guarantee zero prompt overflow.
|
|
212
189
|
|
|
213
|
-
|
|
190
|
+
### 4. Real-Time `CURRENT.md` Synchronization & Session Handoff
|
|
191
|
+
- Active constraint memories automatically mirror into `CURRENT.md`.
|
|
192
|
+
- In-flight task states, agent checkpoints, and active loops persist across terminal restarts, context compactions, and sudden interruptions.
|
|
214
193
|
|
|
215
|
-
|
|
194
|
+
### 5. Unified Compounding: Obsidian Wiki & Entity Graph
|
|
195
|
+
- **Obsidian Wiki Compiler (`memory wiki`)**: Compiles confirmed memory clusters into linked Markdown pages (`wiki/concepts/`, `wiki/entities/`) with bidirectional `[[slug]]` wikilinks.
|
|
196
|
+
- **Named Entity Extraction (`memory entities`)**: Automatically extracts persons, products, organizations, tools, and code symbols with co-occurrence edge weights.
|
|
197
|
+
- **PageIndex Reasoning Engine (`memory pageindex`)**: Indexes unstructured documents into hierarchical reasoning trees.
|
|
216
198
|
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
199
|
+
### 6. Universal Migration Engine (29 Memory Formats)
|
|
200
|
+
Auto-detects and ingests existing memory stores across 29 external engines:
|
|
201
|
+
```bash
|
|
202
|
+
# Auto-detect all external memory stores on your machine
|
|
203
|
+
memory detect
|
|
204
|
+
|
|
205
|
+
# Ingest and preserve state mappings
|
|
206
|
+
memory migrate --provider letta
|
|
207
|
+
memory migrate --provider mem0
|
|
208
|
+
memory migrate --provider beads
|
|
209
|
+
memory migrate --all
|
|
210
|
+
```
|
|
211
|
+
> See [`musememory-comparison.html`](file:///home/harsh/Projects/github/musememory/musememory-comparison.html) for the full table-free 30-system architectural dossier.
|
|
228
212
|
|
|
229
213
|
---
|
|
230
214
|
|
|
231
|
-
## 🌐
|
|
215
|
+
## 🌐 Cognitive Studio Dashboard (`memory ui`)
|
|
232
216
|
|
|
233
|
-
Muse Memory includes
|
|
217
|
+
Muse Memory includes an embedded, zero-dependency visual graph studio:
|
|
234
218
|
|
|
235
219
|
```bash
|
|
236
220
|
memory ui
|
|
237
|
-
# or specify a custom port
|
|
238
|
-
memory ui --port
|
|
221
|
+
# or specify a custom port (default: 2222)
|
|
222
|
+
memory ui --port 2222
|
|
239
223
|
```
|
|
240
224
|
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
-
|
|
244
|
-
-
|
|
245
|
-
-
|
|
225
|
+
Navigate to `http://localhost:2222` to access:
|
|
226
|
+
- 🌐 **3D Force-Directed Knowledge Graph**: Orbital canvas physics, degree-scaled node radii, and link relationship viewer.
|
|
227
|
+
- ⚡ **Active Invariants & Real-Time Handoff**: Live `CURRENT.md` monitor tracking in-flight session status and agent checkpoints.
|
|
228
|
+
- 📚 **Obsidian Wiki Browser**: Concept and entity page reader with full Markdown rendering.
|
|
229
|
+
- 👤 **Persona Studio (`USER.md`)**: 5 archetype picker (`developer`, `designer`, `marketer`, `casual`, `custom`) and live editor.
|
|
230
|
+
- 🔍 **Knapsack Retrieval Sandbox**: Interactive token budget simulator (500–6,000 tokens) with live prompt context generation.
|
|
231
|
+
- 📜 **Compliance Audit Ledger**: Live tabular feed of state transitions and audit logs.
|
|
246
232
|
|
|
247
233
|
---
|
|
248
234
|
|
|
235
|
+
<<<<<<< HEAD
|
|
236
|
+
## 💻 Complete CLI Command Reference
|
|
237
|
+
||||||| f9a7a44
|
|
249
238
|
## ⚡ How Memory Grows, Reloads & Auto-Archives
|
|
250
239
|
|
|
251
240
|
```mermaid
|
|
@@ -362,159 +351,211 @@ Every Scope-of-Work item is tracked as a GitHub issue and delivered via pull req
|
|
|
362
351
|
| ✅ | Daily Briefing & Routines Scheduler (cron-invoked, no daemon) — SOW-102 | [#29](https://github.com/harshsinghmp/musememory/issues/29) |
|
|
363
352
|
| ✅ | Open-Loop / Task Extraction from Transcripts — SOW-103 | [#30](https://github.com/harshsinghmp/musememory/issues/30) |
|
|
364
353
|
| ✅ | Calendar / Time-Aware Follow-ups (`due_at` / `expires_at`) — SOW-104 | [#31](https://github.com/harshsinghmp/musememory/issues/31) |
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
354
|
+
## ⚡ How Memory Grows, Reloads & 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 & 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.
|
|
372
388
|
|
|
373
389
|
---
|
|
374
390
|
|
|
375
|
-
##
|
|
391
|
+
## 👤 User Persona & Preferences (`USER.md`) & Setup Wizard
|
|
392
|
+
|
|
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.
|
|
394
|
+
|
|
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):
|
|
398
|
+
|
|
399
|
+
1. **`developer`** (Default): Code-first, direct, concise, runnable diffs, strict types, fail-fast mechanics.
|
|
400
|
+
2. **`designer`**: Visual hierarchy, CSS/Tailwind systems, GSAP animations, WCAG accessibility, Figma/tokens design tokens.
|
|
401
|
+
3. **`marketer`**: Conversion-rate optimization (CRO), punchy benefit-driven copy, SEO clustering, audience hooks.
|
|
402
|
+
4. **`casual`**: Plain English, jargon-free explanations, step-by-step guidance.
|
|
403
|
+
5. **`custom`**: Clean blank template ready for personalized instructions.
|
|
376
404
|
|
|
377
405
|
```bash
|
|
378
|
-
|
|
406
|
+
# View active profile
|
|
407
|
+
memory user get
|
|
408
|
+
|
|
409
|
+
# Initialize with a specific archetype
|
|
410
|
+
memory user init developer
|
|
411
|
+
memory user init designer --global
|
|
412
|
+
|
|
413
|
+
# Update user profile
|
|
414
|
+
memory user set "- Prefers TypeScript, Bun, and ultra terse responses"
|
|
379
415
|
```
|
|
380
416
|
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
| `user` | `[get\|init\|set] [args] [--global]` | Manage `USER.md` persona & preferences across 5 clean archetypes (`developer`, `designer`, `marketer`, etc.). |
|
|
388
|
-
| `connect` | `[agent] [--all] [--force] [--dry-run]` | Auto-wire MCP server into detected installed agents (skipping uninstalled ones to keep files clean). |
|
|
389
|
-
| `agents` | *(none)* | Scan machine for 80+ coding agents (Claude Code, Cursor, Hermes, OpenCode, OpenClaw, Codex, etc.). |
|
|
390
|
-
| `detect` | *(none)* | Scan workstation and local workspace for existing memory systems across 24+ formats. |
|
|
391
|
-
| `migrate` | `[--from P] [--all] [--dry-run] [--overwrite] [--project P]` | Auto-detect and migrate memories into Muse Memory preserving active/archived state & secrets. |
|
|
392
|
-
| `ui` | `[--port N] [--global]` | Launch zero-dependency visual knowledge graph dashboard. |
|
|
393
|
-
| `context` | `[query] [--limit N] [--token-budget N] [--project P] [--type T] [--status S] [--verified] [--global]` | Retrieve Top-$K$ ranked active context (with token budget limit). |
|
|
394
|
-
| `search` | `<query> [--limit N] [--token-budget N] [--include-superseded] [--type T] [--status S] [--global]` | Ranked token search with scores and status indicators. |
|
|
395
|
-
| `search-transcript` | `<query> [file.jsonl] [--window N] [--max N]` | Search transcript with dialogue context window and start/end conversation bookends. |
|
|
396
|
-
| `harvest` | `<text\|file> --project P [--confirmed] [--global]` | Distill raw text/transcripts into structured outcome/fix memory units. |
|
|
397
|
-
| `import-transcript` | `<file.jsonl\|text> [--project P] [--confirmed] [--global]` | Ingest `.jsonl` session transcript from Claude Code / Antigravity / Cursor into memories (alias: `import-jsonl`). |
|
|
398
|
-
| `capture` | `<text> --project P [--title T] [--tags a,b] [--type T] [--confirmed] [--global]` | Fast proposal with inline zero-leakage secret scan. |
|
|
399
|
-
| `propose` | `<text> --project P [--title T] [--tags a,b] [--type T] [--confirmed] [--global]` | Create a candidate memory entry. |
|
|
400
|
-
| `recall` | `<query> [--limit N] [--token-budget N] [--project P] [--type T] [--status S] [--verified] [--global]` | Rich recall displaying verification levels and related graph links. |
|
|
401
|
-
| `confirm` | `<id> [--global]` | Promote `candidate`, `disputed`, or `stale` entry to `confirmed`. |
|
|
402
|
-
| `supersede` | `<old_id> --with <new_id> [--global]` | Mark old entry superseded by new confirmed entry. |
|
|
403
|
-
| `mark-stale` | `<id> [--reason <text>] [--global]` | Mark an entry stale and append deprecation reason. |
|
|
404
|
-
| `reject` | `<id> [--global]` | Mark an entry rejected. |
|
|
405
|
-
| `delete` | `<id> [--reason <text>] [--global]` | Permanently delete a memory entry and record audit event. |
|
|
406
|
-
| `audit` | `[--operation OP] [--entry-id ID] [--limit N] [--global]` | Query append-only operational audit trail (`.memory/audit.jsonl`). |
|
|
407
|
-
| `link` | `<id> --related <id1,id2> [--global]` | Synchronize bidirectional relation links between entries. |
|
|
408
|
-
| `export` | `[--out <file.json>] [--global]` | Export memory snapshot for agency network sync. |
|
|
409
|
-
| `import` | `<file.json> [--overwrite] [--global]` | Import and validate memory snapshot into local store. |
|
|
410
|
-
| `list` / `ls` | `[--status S] [--type T] [--project P] [--global]` | List memory entries with multi-field status, type, and project filtering. |
|
|
411
|
-
| `stats` | `[--global]` | Display breakdown statistics of total memories, status distribution, and type metrics. |
|
|
412
|
-
| `briefing` | `[--limit N] [--global]` | Active summary of recent entries, status counts, and due/overdue items. |
|
|
413
|
-
| `nudge` | `[--global]` | Proactive attention list: overdue/due-soon entries, stale-by-policy, open loops (exit code = nudge count). |
|
|
414
|
-
| `routine` | `run <name>` / `install [name]` | Execute `.memory/routines.yaml` steps or print crontab lines (cron-invoked, no daemon). |
|
|
415
|
-
| `stale` | `[--days N] [--global]` | Audit active entries exceeding per-type staleness policies. |
|
|
416
|
-
| `session` | `start --project P [--note T]` / `end <id>` | Record session start/end timeline nodes. |
|
|
417
|
-
| `wiki` | `compile\|list\|show <slug> [--project P] [--type T]` | Compile and browse Obsidian-compatible Markdown wiki pages (`wiki/concepts/`, `wiki/entities/`). |
|
|
418
|
-
| `extract-entities` | `[--project P] [--dry-run]` | Extract named entities (persons, products, orgs, files, concepts) from confirmed memories into `entities.json`. |
|
|
419
|
-
| `entities` | `list\|show <id>\|related <id> [--type T] [--project P]` | Inspect extracted knowledge graph entities and co-occurrence relationship strengths. |
|
|
420
|
-
| `settings` | `get\|set\|reset\|export\|import [key] [val] [--project P]` | Manage unified configuration across retrieval, wiki, PageIndex, extraction, and UI subsystems. |
|
|
421
|
-
| `current` | `get` / `set <text> --project P` | Read or append hard constraints to `.memory/CURRENT.md`. |
|
|
422
|
-
| `graph` | `status` | Query active CodeGraph provider status. |
|
|
423
|
-
| `mcp` | *(none)* | Start stdio MCP server. |
|
|
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.*`**
|
|
424
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
|
+
```
|
|
425
434
|
|
|
426
435
|
---
|
|
427
436
|
|
|
428
|
-
##
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
| MCP Tool | Description |
|
|
434
|
-
| :-------------------------- | :--------------------------------------------------------------------------------------------------- |
|
|
435
|
-
| `get_context` | Fetches Top-$K$ ranked memories tailored for active prompt injection with optional `token_budget`. |
|
|
436
|
-
| `search` | Searches memory units with query, token budget, project, type, and verification filters. |
|
|
437
|
-
| `memory_tree_search` | Hierarchical tree-indexed reasoning search across partitioned memory shards. |
|
|
438
|
-
| `memory_wiki_compile` | Compiles confirmed memories into structured Obsidian-compatible Markdown wiki pages. |
|
|
439
|
-
| `memory_wiki_search` | Lists compiled wiki pages with optional project/type filtering. |
|
|
440
|
-
| `memory_wiki_get` | Reads a compiled wiki page (concept, entity, index, or log). |
|
|
441
|
-
| `memory_entities_search` | Lists extracted entities with type/project filtering. |
|
|
442
|
-
| `memory_entities_get` | Inspects extracted entity details and related co-occurrence connections. |
|
|
443
|
-
| `memory_pageindex_index` | Builds a PageIndex hierarchical reasoning tree from document/text (up to 10MB). |
|
|
444
|
-
| `memory_pageindex_search` | Searches a PageIndex tree index with reasoning explanations and depth budgeting. |
|
|
445
|
-
| `memory_pageindex_import` | Imports PageIndex insights directly as memory units. |
|
|
446
|
-
| `memory_disconnect_pageindex`| Disconnects and cleans up PageIndex tree indexes. |
|
|
447
|
-
| `memory_settings_get` | Reads unified global or project configuration settings. |
|
|
448
|
-
| `memory_current` | Reads or appends active project working constraints (`CURRENT.md`). |
|
|
449
|
-
| `memory_get_user_profile` | Reads the active user persona and preferences (`USER.md`). |
|
|
450
|
-
| `memory_set_user_profile` | Updates `USER.md` persona and preferences with inline secret defense. |
|
|
451
|
-
| `memory_search_transcripts` | Full-text search over past `.jsonl` transcripts with conversation bookends and context window. |
|
|
452
|
-
| `memory_detect_agents` | Scans machine for 80+ coding agents (Claude Code, Cursor, Hermes, OpenCode, OpenClaw, Codex, etc.). |
|
|
453
|
-
| `memory_connect` | Auto-wires MCP into installed agents or a specified agent with zero permissions. |
|
|
454
|
-
| `memory_detect_providers` | Scans workspace and machine for external memory formats (24+ providers). |
|
|
455
|
-
| `memory_migrate` | Migrates memories from detected providers with state preservation and secret scrubbing. |
|
|
456
|
-
| `memory_harvest` | Distills conversation turns into structured fix/outcome units. |
|
|
457
|
-
| `memory_import_transcript` | Ingests JSONL transcripts into structured memory units. |
|
|
458
|
-
| `memory_capture` | Saves memory with strict inline secret scanning. |
|
|
459
|
-
| `memory_recall` | Rich inspection of knowledge units, verification, relations, and token budgeting. |
|
|
460
|
-
| `memory_confirm` | Promotes candidate or stale memories to confirmed status. |
|
|
461
|
-
| `memory_supersede` | Supersedes outdated knowledge with a confirmed target. |
|
|
462
|
-
| `memory_link` | Connects related memory units bidirectionally. |
|
|
463
|
-
| `memory_mark_stale` | Flags decaying knowledge units. |
|
|
464
|
-
| `memory_reject` | Marks rejected or refuted hypotheses. |
|
|
465
|
-
| `memory_delete` | Permanently deletes a memory unit and logs audit record. |
|
|
466
|
-
| `memory_audit` | Queries the append-only operational audit ledger. |
|
|
467
|
-
| `memory_export` | Exports full memory snapshot JSON. |
|
|
468
|
-
| `memory_import` | Imports validated memories from a snapshot. |
|
|
469
|
-
| `memory_validate` | Audits store integrity and detects credential leaks. |
|
|
470
|
-
| `graph_status` | Inspects CodeGraph AST integration status. |
|
|
437
|
+
## 🛡️ Built-In Vibeguard Secret Defense (Zero External Dependencies)
|
|
438
|
+
|
|
439
|
+
`musememory` includes a pure TypeScript, zero-dependency security scanner that protects your repositories:
|
|
471
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.
|
|
472
443
|
|
|
473
444
|
---
|
|
474
445
|
|
|
475
|
-
##
|
|
446
|
+
## 🔮 Scope of Work & Roadmap
|
|
447
|
+
|
|
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).
|
|
476
449
|
|
|
477
|
-
|
|
450
|
+
| Status | Item | Tracker |
|
|
451
|
+
| :--- | :--- | :--- |
|
|
452
|
+
| ✅ | Dynamic Prompt Token Budgeter (`--token-budget N`) — knapsack packing under hard token ceilings | shipped v1.1.0 |
|
|
453
|
+
| ✅ | Scene-Based Hierarchical Consolidation (`memory consolidate`) | [#1](https://github.com/harshsinghmp/musememory/issues/1) |
|
|
454
|
+
| ✅ | Autonomous Verification Oracle (`memory verify <id>`) | [#2](https://github.com/harshsinghmp/musememory/issues/2) |
|
|
455
|
+
| ✅ | Multi-Hop Causality Graph Tracer (`memory trace <id>`) | [#3](https://github.com/harshsinghmp/musememory/issues/3) |
|
|
456
|
+
| ✅ | In-Place Core Memory Partitioning (`memory core`) | [#4](https://github.com/harshsinghmp/musememory/issues/4) |
|
|
457
|
+
| ✅ | Automated Post-Turn Transcript Harvester Hook | [#5](https://github.com/harshsinghmp/musememory/issues/5) |
|
|
458
|
+
| ✅ | Real-Time Agency WebSocket Hub (`memory daemon`) | [#6](https://github.com/harshsinghmp/musememory/issues/6) |
|
|
459
|
+
| ✅ | 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) |
|
|
461
|
+
| ✅ | Self-Evolving Skill Distillation | [#9](https://github.com/harshsinghmp/musememory/issues/9) |
|
|
462
|
+
| ✅ | 3-Layer Progressive Disclosure | [#10](https://github.com/harshsinghmp/musememory/issues/10) |
|
|
463
|
+
| ✅ | Bi-Temporal Reinforcement Feedback | [#11](https://github.com/harshsinghmp/musememory/issues/11) |
|
|
464
|
+
| ✅ | Ambient Open-Loop Tracker | [#12](https://github.com/harshsinghmp/musememory/issues/12) |
|
|
465
|
+
| ✅ | Knowledge Graph UI v2 | [#13](https://github.com/harshsinghmp/musememory/issues/13) |
|
|
466
|
+
| ✅ | Proactive Nudges & Check-ins (`memory nudge`) — SOW-101 | [#28](https://github.com/harshsinghmp/musememory/issues/28) |
|
|
467
|
+
| ✅ | Daily Briefing & Routines Scheduler (cron-invoked, no daemon) — SOW-102 | [#29](https://github.com/harshsinghmp/musememory/issues/29) |
|
|
468
|
+
| ✅ | Open-Loop / Task Extraction from Transcripts — SOW-103 | [#30](https://github.com/harshsinghmp/musememory/issues/30) |
|
|
469
|
+
| ✅ | Calendar / Time-Aware Follow-ups (`due_at` / `expires_at`) — SOW-104 | [#31](https://github.com/harshsinghmp/musememory/issues/31) |
|
|
470
|
+
| ✅ | 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) |
|
|
478
472
|
|
|
479
|
-
|
|
480
|
-
Export a portable JSON snapshot before removing data:
|
|
481
|
-
```bash
|
|
482
|
-
# Export local workspace memories
|
|
483
|
-
memory export --out my-memories-backup.json
|
|
473
|
+
---
|
|
484
474
|
|
|
485
|
-
|
|
486
|
-
memory export --global --out global-memories-backup.json
|
|
487
|
-
```
|
|
475
|
+
## 💻 Complete CLI Command Reference
|
|
488
476
|
|
|
489
|
-
### Step 2: Unwire MCP from Coding Agents
|
|
490
|
-
Unwire the Muse Memory MCP server from all configured AI coding agents (Claude Code, Cursor, Hermes, OpenCode, Codex, etc.):
|
|
491
477
|
```bash
|
|
492
|
-
#
|
|
493
|
-
|
|
478
|
+
memory <command> [arguments] [flags] # alias: musememory
|
|
479
|
+
```
|
|
494
480
|
|
|
495
|
-
|
|
496
|
-
|
|
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). |
|
|
497
519
|
|
|
498
|
-
|
|
499
|
-
memory uninstall claude-code
|
|
500
|
-
```
|
|
520
|
+
---
|
|
501
521
|
|
|
502
|
-
|
|
503
|
-
```bash
|
|
504
|
-
# Unwire MCP agents AND purge the project .memory/ directory
|
|
505
|
-
memory uninstall --purge
|
|
522
|
+
## 🔌 MCP Server Tool Reference
|
|
506
523
|
|
|
507
|
-
|
|
508
|
-
rm -rf .memory/ # Local workspace store
|
|
509
|
-
rm -rf ~/.memory/ # Global system store
|
|
524
|
+
When registered as an MCP server, `musememory` exposes the following native tools:
|
|
510
525
|
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
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. |
|
|
518
559
|
|
|
519
560
|
---
|
|
520
561
|
|
|
@@ -522,8 +563,8 @@ rm -f ~/.local/bin/memory ~/.local/bin/musememory
|
|
|
522
563
|
|
|
523
564
|
```bash
|
|
524
565
|
bun install
|
|
525
|
-
bun test #
|
|
526
|
-
|
|
566
|
+
bun test # 278 passed across 50 test files (1072 assertions)
|
|
567
|
+
bun run typecheck # 0 static type errors
|
|
527
568
|
bun run build # Clean bundled distribution build (dist/index.js)
|
|
528
569
|
```
|
|
529
570
|
|
|
@@ -531,4 +572,4 @@ bun run build # Clean bundled distribution build (dist/index.js)
|
|
|
531
572
|
|
|
532
573
|
## 📜 License
|
|
533
574
|
|
|
534
|
-
MIT License.
|
|
575
|
+
MIT License. Built for the AI Developer Ecosystem.
|