mnemos-capture 1.2.0 → 1.3.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 (11) hide show
  1. package/README.md +315 -223
  2. package/dist/cli/config.js +34 -15
  3. package/dist/cli/hooks.js +3 -3
  4. package/dist/cli/index.js +22 -20
  5. package/dist/cli/kos.js +8 -8
  6. package/dist/cli/mcp-server.js +68 -33
  7. package/dist/cli/version-check.js +1 -1
  8. package/package.json +18 -10
  9. package/dist/cli/__tests__/config.test.js +0 -49
  10. package/dist/cli/__tests__/hooks.test.js +0 -276
  11. package/dist/cli/__tests__/kos.test.js +0 -65
package/README.md CHANGED
@@ -1,347 +1,439 @@
1
- <p align="center">
2
- <img src="public/logo.png" alt="Mnemos" width="120" />
3
- </p>
1
+ <div align="center">
2
+ <br>
3
+ <a href="https://mnemos-capture.vercel.app">
4
+ <picture>
5
+ <source media="(prefers-color-scheme: dark)" srcset="public/mnemos-hero-dark.gif">
6
+ <img src="public/mnemos-hero-light.gif" width="160" height="160" alt="Xmu">
7
+ </picture>
8
+ </a>
9
+ <br>
10
+ <br>
11
+ <p>
12
+ <a href="https://www.npmjs.com/package/mnemos-capture"><img src="https://img.shields.io/npm/v/mnemos-capture?color=1c74d8&labelColor=000820&style=flat" alt="npm" /></a>
13
+ <img src="https://img.shields.io/badge/MCP-compatible-9dd8f5?labelColor=000820&style=flat" alt="MCP" />
14
+ <img src="https://img.shields.io/badge/license-MIT-f0f4f8?labelColor=000820&style=flat" alt="MIT" />
15
+ </p>
16
+ </div>
17
+
18
+ ## Xmu
19
+
20
+ Humans are constantly exposed to useful knowledge, domain expertise, and external input. But there is no bridge between what humans know and what their AI workers know and do.
21
+
22
+ Xmu is the knowledge graph for AI workers that bridges human knowledge into context they can use.
23
+
24
+ ## Table of Contents
25
+
26
+ - [Xmu](#xmu)
27
+ - [How it works](#how-it-works)
28
+ - [Start here](#start-here)
29
+ - [Connect your AI workers](#connect-your-ai-workers)
30
+ - [On the web](#on-the-web)
31
+ - [Claude](#claude)
32
+ - [ChatGPT](#chatgpt)
33
+ - [Grok](#grok)
34
+ - [In the terminal](#in-the-terminal)
35
+ - [Cursor](#cursor)
36
+ - [VS Code](#vs-code)
37
+ - [Codex](#codex)
38
+ - [Gemini CLI](#gemini-cli)
39
+ - [Claude Code](#claude-code)
40
+ - [Claude Desktop](#claude-desktop)
41
+ - [Anything MCP](#anything-mcp)
42
+ - [Workflow](#workflow)
43
+ - [What's inside](#whats-inside)
44
+ - [Your context stays in GitHub](#your-context-stays-in-github)
45
+ - [CLI](#cli)
46
+ - [Roadmap](#roadmap)
47
+ - [License](#license)
4
48
 
5
- <h1 align="center">Mnemos</h1>
49
+ ## How it works
6
50
 
7
- <p align="center">
8
- <img src="https://img.shields.io/npm/v/mnemos-capture" alt="npm" />
9
- <img src="https://img.shields.io/badge/license-MIT-blue" alt="License" />
10
- <img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP" />
11
- </p>
51
+ You find useful stuff, you capture through the web app, then Xmu connects it into a knowledge graph, and makes it available to the AI workers you already use.
12
52
 
13
- <p align="center"><strong>Capture anything. Your agents apply it.</strong></p>
53
+ Xmu will continuously compound that knowledge over time — keeping AI workers' context up to date as human knowledge evolves.
14
54
 
15
- <p align="center">A knowledge pipeline that ingests the outside world and makes it directly actionable by any AI agent — over MCP.</p>
55
+ > [!IMPORTANT]
56
+ > We are migrating from **mnemos** to **Xmu**. The app URL, this GitHub repo, and the npm package still say `mnemos-capture`. Sorry for the inconvenience.
16
57
 
17
- Your agent only knows what it was trained on. It doesn't know the article you read this morning, the framework you found last week, or the decision you made last sprint. **Your AI agent finally knows what you've been reading.**
58
+ ## Start here
18
59
 
19
- Mnemos is the pipeline between the two. Capture any insight once — Mnemos extracts it, stores it as plain Markdown in your own GitHub repo, and serves it to your agent over MCP. Then it goes further: at session start it briefs your agent on what matters right now, turns insights into implementation plans, and hands them to whatever assistant you run — Claude Code, Codex, Cursor, Gemini, anything MCP-compatible.
60
+ You do not need a terminal to start.
20
61
 
21
- It's not a second brain, a vault, or a note-taking app — those store knowledge for *you* to read later. Mnemos makes knowledge your **agent acts on now**.
62
+ ### 1. Create your account
22
63
 
64
+ Open **[mnemos-capture.vercel.app](https://mnemos-capture.vercel.app)** and sign in with GitHub.
23
65
 
24
- ## Get started
66
+ Xmu will:
25
67
 
26
- ### 1. Sign up (30 seconds)
68
+ 1. Create a **private** GitHub repo for your knowledge (you can opt to make it public)
69
+ 2. Ask for your LLM provider API key — Anthropic, OpenAI, or Google. Your key, your cost.
70
+ 3. Let you set a PIN (6+ characters) for quick unlock on this device
71
+ 4. Show your **Xmu API key** once — save it if you want to connect an AI worker
27
72
 
28
- Go to **[mnemos-capture.vercel.app](https://mnemos-capture.vercel.app)** → **Sign in with GitHub**.
73
+ That's the whole setup. No repo to clone. No database. No CLI required.
29
74
 
30
- During setup, Mnemos will:
75
+ ### 2. Capture something
31
76
 
32
- - Create a knowledge repo in your GitHub account — plain Markdown files, no proprietary format
33
- - Ask for your API key (your provider, your key — Mnemos never pays for your API calls)
34
- - Set a PIN so you can unlock the app quickly on mobile
77
+ In the app, paste a URL, a note, a doc excerpt, a transcript, or an idea, then hit **Capture**.
35
78
 
36
- No config files. No repos to clone. No CLI setup required.
79
+ Xmu extracts the **core idea**, **key takeaways**, **where to apply it**, and the **capture type**, then commits Markdown to your GitHub repo.
37
80
 
38
- ### 2. Connect to your AI assistant
81
+ On a phone: open the app → **Share → Add to Home Screen**. It runs like a native app.
39
82
 
40
- When you finish onboarding, Mnemos generates a personal **MCP API key** — copy it.
83
+ ### 3. Connect a worker (optional)
41
84
 
42
- **Claude Code:**
43
- ```bash
44
- claude mcp add mnemos -- npx -y mnemos-capture@latest serve-mcp --key <your-mcp-key>
85
+ Skip this if you only want the app today. When you're ready, pick your tool under [Connect your AI workers](#connect-your-ai-workers). Capture now, connect later — the knowledge is already in your repo.
86
+
87
+ ## Connect your AI workers
88
+
89
+ Xmu is LLM-agnostic. Any worker that speaks MCP can use the same knowledge.
90
+
91
+ Two primitives:
92
+
93
+ ```text
94
+ https://mnemos-capture.vercel.app/api/mcp
45
95
  ```
46
96
 
47
- **Any MCP-compatible client** (Cursor, Continue, Gemini CLI, etc.) — point it at the stdio proxy:
48
97
  ```bash
49
- npx -y mnemos-capture@latest serve-mcp --key <your-mcp-key>
98
+ npx -y mnemos-capture@latest serve-mcp --key YOUR_API_KEY
50
99
  ```
51
100
 
52
- The proxy forwards your agent's MCP tool calls to the hosted Mnemos API. Nothing is stored locally — your knowledge lives in your GitHub repo.
101
+ The CLI binary is **`xmu`** (also `mnemos-capture`). `npx` still uses the package name until a standalone `xmu` package ships. An MCP server already registered as `mnemos` keeps working.
53
102
 
54
- ### 3. Capture something
103
+ **On the web** — paste the URL (no terminal). **In the terminal** — run the command. Finish Xmu onboarding first, then ask: *list my inbox* or *brief me*.
55
104
 
56
- Open the app on any device — phone, tablet, or desktop. Paste any content and hit **Capture**. Or capture directly from your agent:
105
+ ### On the web
57
106
 
58
- ```
59
- capture "The Mom Test — don't ask if your idea is good, ask about their life."
60
- ```
107
+ Name the connector `Xmu`, paste `https://mnemos-capture.vercel.app/api/mcp`, sign in with GitHub when asked.
61
108
 
62
- That's it. Your knowledge is now indexed and available to every agent session.
109
+ #### Claude
63
110
 
111
+ 1. Settings → Connectors → Add custom connector
64
112
 
65
- ## How it works
113
+ #### ChatGPT
66
114
 
67
- ```mermaid
68
- flowchart TD
69
- A["Article / research /\ntranscript / idea"] -->|paste| B["Mnemos\n(web / mobile / agent)"]
70
- B -->|extracts insight| C["Structured Markdown\ncommitted to your repo"]
71
- C -->|session start| D["Briefing\nranked suggestions + plan"]
72
- D -->|generate_plan| E["Implementation plan\nsaved to plans/"]
73
- E -->|mnemos kos| F["Your AI assistant\nexecutes in isolated worktree"]
74
- F -->|verify| G["Branch ready\nto review & merge"]
75
-
76
- style A fill:#1a1a2e,stroke:#444,color:#fff
77
- style B fill:#2A62C6,stroke:#1a4a9e,color:#fff
78
- style C fill:#2d8a4e,stroke:#1e6b3a,color:#fff
79
- style D fill:#d4a843,stroke:#b8912e,color:#fff
80
- style E fill:#2A62C6,stroke:#1a4a9e,color:#fff
81
- style F fill:#1a1a2e,stroke:#444,color:#fff
82
- style G fill:#2d8a4e,stroke:#1e6b3a,color:#fff
83
- ```
115
+ 1. Settings → Plugins → Browse plugins
116
+ 2. Name it Xmu
117
+ 3. Paste `https://mnemos-capture.vercel.app/api/mcp`
118
+ 4. Sign in with GitHub when asked
84
119
 
85
- 1. **Capture** — paste anything text-based. Mnemos extracts the core idea, key takeaways, where to apply it, and auto-detects whether it's a URL, short note, or long paste. Committed to your GitHub repo as structured Markdown.
86
- 2. **Brief** — at session start, the `--briefing` flag sends your project context (branch, recent commits, CLAUDE.md) to Mnemos. It returns ranked suggestions — *why* each insight matters now, *what* applying it achieves, *where* in your codebase.
87
- 3. **Plan** — `generate_plan` reads your selected captures and produces a structured Markdown plan: Codebase Mapping table, per-file steps with effort tiers (`simple` / `complex` / `architectural`), and a Verification Checklist.
88
- 4. **Execute** — `mnemos kos` (coming) creates an isolated git worktree, launches your configured AI assistant with the plan as its contract, and runs the verification checklist when it's done.
120
+ #### Grok
89
121
 
122
+ 1. Open [grok.com/connectors](https://grok.com/connectors) → New Connector → Custom
90
123
 
91
- ## What you can feed it
124
+ ### In the terminal
92
125
 
93
- If it's text, Mnemos can extract insight from it. No manual tagging required.
126
+ The same command works in every CLI — Cursor, Codex, Gemini CLI, VS Code, Claude Code, or anything that can launch a local MCP server:
94
127
 
95
- - **Research papers and preprints** — new models, architectures, evaluation methods
96
- - **Framework and library docs** — patterns, APIs, integration approaches worth keeping
97
- - **Technical threads and writeups** — the argument or finding, not the noise
98
- - **Optimization techniques** — prompt engineering, caching strategies, latency improvements
99
- - **Your own ideas** — architecture decisions, workflow changes, things you want your agents to act on later
100
- - **Transcripts and talks** — signal extracted, ready to apply
128
+ ```bash
129
+ npx -y mnemos-capture@latest serve-mcp --key YOUR_API_KEY
130
+ ```
101
131
 
132
+ Register that command in the tool you use.
102
133
 
103
- ## Example capture
134
+ #### Cursor
104
135
 
105
- Paste a research post about error observability. This is what lands in your repo:
136
+ Add this to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (all projects):
106
137
 
107
- ```markdown
108
- ---
109
- date: 2026-06-05
110
- source: Error Context First — Observability for AI Systems
111
- url: https://example.com/error-context
112
- type: post
113
- source_type: url
114
- tags: observability, error-handling, ai-agents, debugging
115
- status: inbox
116
- lowConfidence: false
117
- ---
138
+ ```json
139
+ {
140
+ "mcpServers": {
141
+ "xmu": {
142
+ "command": "npx",
143
+ "args": ["-y", "mnemos-capture@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
144
+ }
145
+ }
146
+ }
147
+ ```
118
148
 
119
- # Error Context First — Observability for AI Systems
149
+ Or Cursor Settings → MCP → Add new MCP server, same command.
120
150
 
121
- ## Core idea
122
- Opaque error messages make every fix a guess. Adding source context to every
123
- error — which handler, which step, which input — turns debugging from archaeology
124
- into a directed search.
151
+ #### VS Code
125
152
 
126
- ## Key takeaways
127
- - Every catch block should prefix messages with where it came from
128
- - "The string did not match the expected pattern" is useless; "[github-write] ..." is actionable
129
- - Instrument before you fix — opaque errors cause repeated misdiagnoses
153
+ Add this to `.vscode/mcp.json`:
130
154
 
131
- ## Applied to
132
- Add handler-name prefixes to every catch block in your agent's tool pipeline.
155
+ ```json
156
+ {
157
+ "servers": {
158
+ "xmu": {
159
+ "command": "npx",
160
+ "args": ["-y", "mnemos-capture@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
161
+ }
162
+ }
163
+ }
133
164
  ```
134
165
 
135
- `source_type` is auto-detected (`url` / `note` / `paste`). `lowConfidence` flags short or ambiguous input for review before acting on it.
166
+ GitHub Copilot Chat in VS Code uses the same file.
136
167
 
168
+ #### Codex
137
169
 
138
- ## Knowledge lifecycle
170
+ Codex CLI — add this to `~/.codex/config.toml`:
139
171
 
140
- ```
141
- ┌─────────┐
142
- │ Capture │
143
- └────┬─────┘
144
- ▼
145
- ┌─────────┐ ┌──────────┐
146
- │ Inbox │────▶│ Applied │ Insight used — plan executed, rule added, code changed
147
- └────┬─────┘ └──────────┘
148
- │
149
- ├──────────▶┌──────────┐
150
- │ │ Archived │ Reviewed, not actionable right now
151
- │ └──────────┘
152
- │
153
- └──────────▶┌──────────┐
154
- │ Deleted │ Not useful, permanently removed
155
- └──────────┘
172
+ ```toml
173
+ [mcp_servers.xmu]
174
+ command = "npx"
175
+ args = ["-y", "mnemos-capture@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
156
176
  ```
157
177
 
158
- All captures are tracked in `INDEX.md` — a master table your agents search across your entire knowledge base. Generated plans land in `plans/`.
178
+ Codex App: Settings → MCP → add the same `npx` command.
159
179
 
180
+ #### Gemini CLI
160
181
 
161
- ## Session hooks
182
+ ```bash
183
+ gemini mcp add xmu npx -y mnemos-capture@latest serve-mcp --key YOUR_API_KEY
184
+ ```
162
185
 
163
- `serve-mcp` writes a `SessionStart` hook to `~/.claude/settings.json` on first run. Every session opens with your inbox count:
186
+ #### Claude Code
164
187
 
165
- ```
166
- Mnemos: 4 captures in inbox — run list_inbox to review
188
+ ```bash
189
+ claude mcp add xmu -- npx -y mnemos-capture@latest serve-mcp --key YOUR_API_KEY
167
190
  ```
168
191
 
169
- ### Briefing mode
192
+ Or the URL, no API key:
170
193
 
171
- Opt in for a structured briefing instead of a count:
194
+ ```bash
195
+ claude mcp add --transport http xmu https://mnemos-capture.vercel.app/api/mcp
196
+ ```
197
+
198
+ Optional session hooks (MCP works without them):
172
199
 
173
200
  ```bash
174
- npx -y mnemos-capture@latest setup-hooks --key YOUR_KEY --briefing
201
+ npx -y mnemos-capture@latest setup-hooks --key YOUR_API_KEY --briefing --vault
175
202
  ```
176
203
 
177
- At session start, Mnemos collects your project context — branch, recent commits, CLAUDE.md excerpt — and returns:
204
+ Hooks are local files — they run in the CLI and editor extensions, not in the browser.
205
+
206
+ #### Claude Desktop
178
207
 
179
- 1. Ranked suggestions with `why`, `benefit`, `where`, and whether to apply now
180
- 2. Relevant synthesized rules
181
- 3. A `generate_plan` prompt pre-loaded with the captures to apply
208
+ Settings → Developer → Edit Config. Add the same `npx` block to `claude_desktop_config.json`, then fully restart:
182
209
 
210
+ ```json
211
+ {
212
+ "mcpServers": {
213
+ "xmu": {
214
+ "command": "npx",
215
+ "args": ["-y", "mnemos-capture@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
216
+ }
217
+ }
218
+ }
183
219
  ```
184
- 3 insights to apply now:
185
220
 
186
- 1. error-context-first → src/app/api/capture/route.ts
187
- Why: Your current branch rewrites the capture pipeline and all catch blocks are opaque
188
- Benefit: Every error will identify its source in < 1 line
221
+ #### Anything MCP
189
222
 
190
- Run generate_plan with selected_captures: ["inbox/2026-06-05-error-context-first.md"]
223
+ If the tool can launch a local process, register the same `npx` command. If it has **custom connectors** instead, paste the URL (that's the [web](#on-the-web) path).
224
+
225
+ ```json
226
+ {
227
+ "mcpServers": {
228
+ "xmu": {
229
+ "command": "npx",
230
+ "args": ["-y", "mnemos-capture@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
231
+ }
232
+ }
233
+ }
191
234
  ```
192
235
 
193
- ### Vault mode (PreToolCall hook)
236
+ No MCP support yet? Capture in the [Xmu app](https://mnemos-capture.vercel.app) and connect later.
194
237
 
195
- Surfaces relevant captures *before* you edit a file — not just at session start:
238
+ ## Workflow
196
239
 
197
- ```bash
198
- npx -y mnemos-capture@latest setup-hooks --key YOUR_KEY --vault
199
- ```
240
+ <p align="center">
241
+ <img src="public/flow-workflow.svg" width="720" alt="Docs and notes → Capture → GitHub Markdown → Brief → Plan → Execute → Mark applied" />
242
+ </p>
200
243
 
201
- Before every `Edit`, `Write`, or `MultiEdit` tool call, Mnemos scans your vault for captures scoring ≥ 0.7 relevance to the file you're about to touch. Each capture is surfaced at most once per session.
244
+ 1. **Capture** — Paste anything text-based: papers, docs, posts, GitHub repos, notes, decisions, ideas, transcripts. Xmu detects a URL, a short note, or longer text. No manual tagging.
202
245
 
203
- Opt-in only — not installed by default because it fires on every file edit.
246
+ From a connected worker:
204
247
 
205
- ### Compatibility
248
+ ```text
249
+ capture "The Mom Test: don't ask if your idea is good. Ask about the person's real behavior, current workflow, and past spending."
250
+ ```
206
251
 
207
- | Surface | Hook fires |
208
- |---|---|
209
- | Claude Code CLI, VS Code / JetBrains extensions, desktop app | Yes |
210
- | Claude Code on the web | No — `~/.claude/settings.json` is local only |
211
- | Cursor / other MCP clients | No — distinct hook systems |
252
+ 2. **Brief** — At the start of a work session, ask your worker for a briefing. Xmu looks at your project (branch, recent commits, `CLAUDE.md`, repo context) and ranks captures that could help now: **why** it matters, **what** applying it could achieve, **where** it could land. You decide what to apply.
212
253
 
213
- MCP tools work everywhere. For unsupported surfaces, add to `CLAUDE.md`:
254
+ 3. **Plan** — Select the captures you want and ask your worker to call `generate_plan`. Each plan is Markdown: codebase mapping, implementation steps with effort tiers (`simple`, `complex`, `architectural`), and a verification checklist.
214
255
 
215
- > At session start, call `list_inbox` to surface pending captures.
256
+ 4. **Execute** — Hand the plan to your worker in the current session, or run it in an isolated git worktree:
216
257
 
258
+ ```bash
259
+ npx -y mnemos-capture@latest config set agent "claude -p"
260
+ npx -y mnemos-capture@latest kos --key YOUR_API_KEY
261
+ ```
217
262
 
218
- ## MCP tools
263
+ `kos` creates a worktree, loads the plan as the contract, launches the assistant you configured, and prints the verification checklist when it finishes.
219
264
 
220
- Mnemos exposes 15 tools via MCP:
265
+ ```bash
266
+ npx -y mnemos-capture@latest config set agent "codex exec"
267
+ ```
221
268
 
222
- ### Capture
269
+ ### Example capture
223
270
 
224
- | Tool | What it does |
225
- |------|-------------|
226
- | `capture` | Extracts insight from any pasted content. Auto-detects source type, flags low-confidence input, auto-links to related captures. |
271
+ ```text
272
+ The Mom Test: don't ask if your idea is good. Ask about the person's real behavior, current workflow, and past spending.
273
+ ```
227
274
 
228
- ### Discover
275
+ ```markdown
276
+ ---
277
+ date: 2026-06-05
278
+ source: The Mom Test note
279
+ type: note
280
+ tags: customer-discovery, product, research
281
+ status: inbox
282
+ ---
229
283
 
230
- | Tool | What it does |
231
- |------|-------------|
232
- | `list_inbox` | Unprocessed captures with summaries — title, type, tags, core idea. |
233
- | `search_captures` | Keyword + tag search across inbox, applied, and archived. |
234
- | `read_capture` | Full Markdown of any capture. |
235
- | `recall` | Semantic search — describe your task, get the most relevant captures back. More powerful than keyword search. |
284
+ # The Mom Test
236
285
 
237
- ### Apply
286
+ ## Core idea
238
287
 
239
- | Tool | What it does |
240
- |------|-------------|
241
- | `apply_capture` | Moves inbox → applied. Records how and where knowledge was used, which plan drove it, and what changed. Triggers rule re-synthesis. |
242
- | `archive_capture` | Moves inbox → archived. Reviewed but not actionable now. |
243
- | `delete_capture` | Permanently removes a capture and its index entry. |
244
- | `apply_to_context` | Paste task + stack + code snippet → get concrete, file-level suggestions for applying your captured knowledge. |
288
+ Do not ask people to judge your idea. Ask about their real life,
289
+ recent behavior, current workaround, and what they have already
290
+ tried or paid for.
245
291
 
246
- ### Plan
292
+ ## Key takeaways
247
293
 
248
- | Tool | What it does |
249
- |------|-------------|
250
- | `briefing` | Session-start briefing: ranked suggestions with `applyNow` flags, relevant rules, and a `generate_plan` prompt. Requires `project_context`. |
251
- | `generate_plan` | Reads selected captures + optional codebase files → structured Markdown plan with Codebase Mapping table, effort tiers per step, and Verification Checklist. Saved to `plans/`. |
252
- | `list_plans` | Lists saved plans, or reads a specific plan in full. |
294
+ - Avoid compliments and future promises
295
+ - Ask about specific past behavior
296
+ - Look for existing pain, workarounds, and spending
253
297
 
254
- ### Synthesize
298
+ ## Where to apply
255
299
 
256
- | Tool | What it does |
257
- |------|-------------|
258
- | `synthesize` | Distills captures on a tag into actionable rules. Updates `RULES.md`. |
259
- | `get_rules` | Returns synthesized rules — filtered by tag or all. Use to populate `CLAUDE.md` or a system prompt. |
300
+ Discovery interview scripts, landing page tests, and product
301
+ validation prompts.
302
+ ```
260
303
 
261
- ### Curate
304
+ Plain Markdown in a repo you own. Readable, editable, versioned, portable.
262
305
 
263
- | Tool | What it does |
264
- |------|-------------|
265
- | `curate` | Validates inbox captures: HEAD-checks URLs (404/410 → stale), flags low-confidence extractions. Optional `auto_archive`. Batch cap: 20 files. |
266
- | `vault_scan` | Scans the full vault for captures relevant to your current activity (score ≥ 0.7). Used by the vault hook. |
306
+ ## What's inside
267
307
 
308
+ You don't have to memorize these. Ask in plain language: "save this", "what do I have on payments?", "brief me for this repo".
309
+
310
+ | Tool | What it does |
311
+ | --- | --- |
312
+ | `capture` | Save new knowledge from pasted text or a URL |
313
+ | `list_inbox` | List captures waiting for review |
314
+ | `search_captures` | Keyword search across your captures |
315
+ | `read_capture` | Read a capture in full |
316
+ | `recall` | Find relevant context from a description of your task |
317
+ | `briefing` | Get project-specific recommendations |
318
+ | `generate_plan` | Turn selected captures into an implementation plan |
319
+ | `list_plans` | List or read saved plans |
320
+ | `apply_capture` | Mark a capture as applied |
321
+ | `archive_capture` | Archive a capture |
322
+ | `delete_capture` | Delete a capture |
323
+ | `apply_to_context` | Get file-level suggestions for the current task |
324
+ | `synthesize` | Combine related captures into reusable rules |
325
+ | `get_rules` | Retrieve those rules |
326
+ | `curate` | Review and clean up captures |
327
+ | `vault_scan` | Find relevant context for what you're about to edit |
268
328
 
269
329
  ## CLI
270
330
 
331
+ No global install required. The binary is **`xmu`** (also `mnemos-capture`). Via npx:
332
+
333
+ ```bash
334
+ npx -y mnemos-capture@latest <command>
271
335
  ```
272
- mnemos-capture Open hosted app
273
- mnemos-capture serve-mcp --key KEY Run local MCP proxy (auto-installs hook)
274
- mnemos-capture setup-hooks --key KEY [--briefing] [--vault] Install session hooks
275
- mnemos-capture inbox-check --key KEY [--briefing] Debug what the hook runs
276
- mnemos-capture vault-check --key KEY Debug what the vault hook runs
277
- mnemos-capture help Show help
278
- ```
279
336
 
280
- All commands run via `npx -y mnemos-capture@latest <subcommand>`. `@latest` forces npm to resolve against the registry on every invocation.
337
+ | Command | What it does |
338
+ | --- | --- |
339
+ | `npx -y mnemos-capture@latest` | Open the hosted app |
340
+ | `serve-mcp --key YOUR_API_KEY` | Run the local MCP proxy |
341
+ | `setup-hooks --key YOUR_API_KEY [--briefing] [--vault]` | Install Claude Code hooks |
342
+ | `config set agent "claude -p"` | Set which assistant `kos` should drive |
343
+ | `kos --key YOUR_API_KEY` | Implement the latest plan in an isolated worktree |
344
+ | `inbox-check --key YOUR_API_KEY [--briefing]` | Debug the session hook |
345
+ | `vault-check --key YOUR_API_KEY` | Debug the vault hook |
346
+ | `help` | Show help |
347
+
348
+ ## Your context stays in GitHub
349
+
350
+ Captures live as structured Markdown in **your** GitHub repository. Private by default.
281
351
 
352
+ - **No lock-in** — clone it, move it, delete Xmu, keep the files
353
+ - **No proprietary format** — every capture is a readable `.md` file
354
+ - **No training on your data** — captures are sent only to the LLM provider you chose, with the key you supplied, to extract the insight you asked for
355
+ - **Any tool can read it** — anything that reads Git or speaks MCP
356
+ - **BYOK** — your provider, your key, your cost
357
+ - **Never commit your Xmu API key** to source control
282
358
 
283
- ## Mobile
359
+ ### What Xmu stores, and where
284
360
 
285
- Open Mnemos in your phone's browser → **Share → Add to Home Screen**. Runs full-screen like a native app. Capture while reading — your agents have it by the time you sit down to work.
361
+ The whole point of this repo being public is that you can check these claims rather than trust them.
286
362
 
363
+ **Your captures are never stored by Xmu.** They are written straight to your own GitHub repo as Markdown (`src/lib/github.ts`). There is no captures table. Delete the app and your knowledge is untouched.
287
364
 
288
- ## Your data, your storage
365
+ **The database holds only account plumbing** (`src/lib/db.ts`):
289
366
 
290
- Your knowledge lives in a GitHub repo you own. Plain Markdown files, version-controlled, portable.
367
+ | Stored | What it is |
368
+ | --- | --- |
369
+ | `github_id`, `github_username` | who you are |
370
+ | `github_token` | encrypted (`src/lib/crypto.ts`) |
371
+ | `github_repo` | the *name* of your hub, not its contents |
372
+ | `pin_hash` | salted scrypt (`src/lib/pin.ts`) |
373
+ | `api_key` | hashed — not recoverable |
374
+ | `llm_provider`, `llm_api_key` | encrypted |
375
+ | `token_version` | bumped to revoke everything |
376
+ | login attempts, OAuth clients/codes, refresh-token ids | auth plumbing |
291
377
 
292
- - **No lock-in** — clone it, move it, delete Mnemos and your repo stays exactly where it is
293
- - **No proprietary format** — every capture is a readable `.md` file
294
- - **No training on your data** — Mnemos never reads your captures for any purpose other than serving them back to you
295
- - **Any tool can access it** — anything that reads Git or speaks MCP works with your knowledge base
296
- - **BYOK** — your provider, your key, your cost
378
+ When you capture, the server talks to exactly three kinds of destination:
379
+
380
+ 1. **GitHub** — to write the capture into your repo
381
+ 2. **Your LLM provider**, with *your* key — Anthropic, OpenAI, or Google
382
+ 3. **The page you captured** — if you paste a bare URL, so the model reads real content. Only http/https, never an internal address
383
+
384
+ No analytics, no telemetry, no third-party tracking.
297
385
 
386
+ ### How your credentials are stored
387
+
388
+ | Secret | How it's stored |
389
+ | --- | --- |
390
+ | GitHub token | Encrypted at rest (AES-256-GCM). Uses the `repo` scope, required to read and write a **private** knowledge hub |
391
+ | Your LLM API key | Encrypted at rest (AES-256-GCM) |
392
+ | Your MCP API key | Hashed — never recoverable, not even by Xmu |
393
+ | Your PIN | Salted scrypt hash |
394
+
395
+ Your MCP key is shown exactly once. If you lose it, generate a new one.
396
+
397
+ **PIN unlock is device-bound.** It only works on a device that has already signed in with GitHub. A PIN on its own is not enough to reach your account.
398
+
399
+ **Revoking access.** Generating a new MCP key invalidates the old key, every signed-in session, and every connected MCP client. Sessions also expire after 30 days.
298
400
 
299
401
  ## Cost
300
402
 
301
- Mnemos is BYOK — you bring your own API key, Mnemos never charges you for inference.
403
+ Xmu is BYOK. You bring your own API key. Xmu never charges you for inference.
302
404
 
303
- Extraction runs on a fast, low-cost model (Claude Haiku 4.5 by default) with prompt caching and input truncation:
405
+ Extraction runs on a fast, low-cost model (Claude Haiku 4.5 by default):
304
406
 
305
407
  | Usage | Estimated monthly cost |
306
- |-------|----------------------|
408
+ | --- | --- |
307
409
  | 50 captures/month | ~$0.15 |
308
410
  | 100 captures/month | ~$0.30 |
309
411
  | 200 captures/month | ~$0.60 |
310
412
 
311
- Briefing and plan generation use your configured model and only run when you explicitly invoke them.
312
-
313
-
314
- ## Tech stack
315
-
316
- Next.js · TypeScript · Vercel Postgres · GitHub OAuth · GitHub Content API · MCP protocol · Anthropic SDK · Tailwind CSS · Vitest
317
-
413
+ Briefing, planning, and synthesis only run when you ask for them.
318
414
 
319
415
  ## Roadmap
320
416
 
321
- - **`mnemos kos`** — CLI orchestrator: creates isolated git worktree, launches your configured AI assistant with the plan as its contract, runs the Verification Checklist, reports the branch
322
- - **Provider abstraction** — bring your OpenAI, Google, or any OpenAI-compatible key; Mnemos routes accordingly
323
- - **Chrome extension** — one-click capture from anywhere in the browser
324
- - Voice memo capture
417
+ - **Learning Graph** — Applied work feeds the next brief. The graph compounds.
418
+ - **Knowledge Graph for Teams** — One graph the team and their AI workers share and compound.
419
+ - **Chrome extension** — Capture from the page you are on, without leaving the browser.
420
+ - **Voice memo** — Speak it. Xmu turns it into a capture.
325
421
 
422
+ Working on the code? See [CONTRIBUTING.md](CONTRIBUTING.md).
326
423
 
327
- ## Built by
328
-
329
- [Sofía Padrón Valdez](https://github.com/Soph20) — builder, AI systems architect.
424
+ ## License
330
425
 
426
+ [MIT License](./LICENSE)
331
427
 
332
- ## Citation
428
+ If you use Xmu in published work:
333
429
 
334
- ```
430
+ ```bibtex
335
431
  @misc{2026mnemos,
336
- title = {Mnemos: A Knowledge Pipeline for AI Agents},
337
- author = {Sofia Padron Valdez},
338
- year = 2026,
339
- journal = {GitHub repository},
340
- publisher = {GitHub},
341
- howpublished = {\url{https://github.com/Soph20/mnemos-capture}}
342
- }
432
+ title = {Xmu: A Knowledge Graph for AI workers},
433
+ author = {Sofia Padron Valdez},
434
+ year = 2026,
435
+ journal = {GitHub repository},
436
+ publisher = {GitHub},
437
+ howpublished = {\url{https://github.com/Soph20/mnemos-capture}}
438
+ }
343
439
  ```
344
-
345
- ## License
346
-
347
- [MIT License - see LICENSE file for details](./LICENSE)