monomind 2.20.0 → 2.22.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 +28 -24
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
8
|
<strong>An open-source MCP server that extends Claude Code with a codebase knowledge graph, persistent memory, and multi-agent coordination.</strong><br/>
|
|
9
|
-
Apache 2.0 licensed ·
|
|
9
|
+
Apache 2.0 licensed · Monomind keeps its own state on your machine; the AI tools it drives send prompts and code to their model providers — see [Trust & Security](#trust--security)
|
|
10
10
|
</p>
|
|
11
11
|
|
|
12
12
|
<p align="center">
|
|
@@ -36,21 +36,25 @@ Monomind is an **open-source CLI and MCP server** that plugs into Claude Code, [
|
|
|
36
36
|
- **Codebase knowledge graph** — tree-sitter parses your code into a SQLite-backed graph of files, functions, classes, and their relationships. Query imports, callers, and blast radius before making changes.
|
|
37
37
|
- **Persistent memory** — a JSON pattern store with episodic recall that survives across sessions. Agents and orgs share context without re-prompting.
|
|
38
38
|
- **Multi-agent coordination** — in-session, spawn ad-hoc agent teams via Claude Code's Task tool; for persistent background work, `monomind org run` starts a real SDK-backed daemon with policy-gated role agents and a live dashboard.
|
|
39
|
-
- **Agents, skills and picking** — ships <!-- doc-count:pickable-agents -->
|
|
40
|
-
- **Reusable slash commands** — <!-- doc-count:mastermind-commands -->
|
|
39
|
+
- **Agents, skills and picking** — ships <!-- doc-count:pickable-agents -->83<!-- /doc-count:pickable-agents --> pickable agents, <!-- doc-count:pickable-skills -->82<!-- /doc-count:pickable-skills --> skills and <!-- doc-count:org-skills -->376<!-- /doc-count:org-skills --> Org skills, and you add your own as Markdown files. One index of all of them ranks the best fit for each task; the prompt hook puts it in Claude's context as a `[PICK]` line, and `monomind pick` or the `pick` MCP tool return it on request. See [Agents & Skills](doc/concepts/agents-and-skills.md) and [Routing](doc/concepts/routing.md).
|
|
40
|
+
- **Reusable slash commands** — <!-- doc-count:mastermind-commands -->40<!-- /doc-count:mastermind-commands --> workflows (plan, execute, review, debug, release, research, worktree) available as `/mastermind:*` commands inside Claude Code.
|
|
41
41
|
|
|
42
42
|
```bash
|
|
43
|
-
npm install -g monomind # Apache 2.0 licensed
|
|
43
|
+
npm install -g monomind # Apache 2.0 licensed; runs locally and keeps its state locally
|
|
44
44
|
cd your-project && monomind init
|
|
45
45
|
claude mcp add monomind -- npx -y monomind@latest mcp start
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
-
`monomind init`
|
|
48
|
+
`monomind init` installs the **core pack**: the everyday `/mastermind:*` workflows (plan, execute, review, debug, do, …), 20 core agents and the memory, GitHub and browser toolkits, small enough that Claude Code shows every description. Everything else ships as opt-in packs (`orgs`, `org-admin`, `swarm`, `github`, `testing`, `specialists`, `business`, `extras`): pick them with `monomind init --packs orgs,github` or `--all-packs`, or add one later with `monomind packs add <pack>`. `monomind packs list` shows each pack and how much of the listing it uses.
|
|
49
|
+
|
|
50
|
+
`monomind init` sets up only the coding systems installed on your machine: Claude Code, Antigravity, OpenCode, Kimi Code and Codex each count when their CLI is on your `PATH` or their config directory is in your home, and Claude Code is the default when none is found. A re-run also keeps every system the project already has. It prints what it detected; `--platforms claude,codex` names the systems yourself and `--all-platforms` writes all five. It never runs `npm install` or edits your `package.json`: the code graph uses the `@monoes/monograph` copy bundled with the CLI.
|
|
51
|
+
|
|
52
|
+
`monomind init` itself writes `.mcp.json` (and the configs of the other coding systems it sets up) pinned to the installed version, so a start reuses the npx cache instead of re-resolving `@latest`; `--pin latest` keeps the floating `monomind@latest`, and `monomind init --force` re-pins after an upgrade.
|
|
49
53
|
|
|
50
54
|
<details>
|
|
51
55
|
<summary><strong>Using Antigravity (agy)?</strong></summary>
|
|
52
56
|
|
|
53
|
-
Nothing extra to do
|
|
57
|
+
Nothing extra to do when Antigravity is installed (`agy`/`gemini` on PATH or `~/.gemini`): `monomind init` then writes `GEMINI.md`, `.gemini/rules/`, and a live status bar wired through `.gemini/settings.json`. The MCP server config is shared with Claude Code (`.mcp.json`). See [Antigravity guide →](doc/concepts/antigravity.md).
|
|
54
58
|
|
|
55
59
|
</details>
|
|
56
60
|
|
|
@@ -61,7 +65,7 @@ Nothing extra to do — agy output is part of **default** `monomind init`: `GEMI
|
|
|
61
65
|
monomind init --target opencode # initialize only OpenCode
|
|
62
66
|
```
|
|
63
67
|
|
|
64
|
-
`monomind init`
|
|
68
|
+
`monomind init` sets up the coding systems it detects on your machine (CLI on PATH or config directory in your home), OpenCode included when it is installed. `--target opencode` initializes only OpenCode; the legacy `--opencode` flag remains an alias. You get the same MCP tools, agent roster, commands, skills, and security gates, plus a `/monomind-status` command. See [OpenCode guide →](doc/concepts/opencode.md).
|
|
65
69
|
|
|
66
70
|
</details>
|
|
67
71
|
|
|
@@ -72,7 +76,7 @@ monomind init --target opencode # initialize only OpenCode
|
|
|
72
76
|
monomind init --target kimicode # initialize only Kimi Code
|
|
73
77
|
```
|
|
74
78
|
|
|
75
|
-
`monomind init` includes Kimi Code
|
|
79
|
+
`monomind init` includes Kimi Code when it is installed (`kimi` on PATH or `~/.kimi`). `--target kimicode` initializes only Kimi Code; the legacy `--kimicode` flag remains an alias. You get the same MCP tools, agent roster, skills, and commands (as project-level flow skills). Install the generated plugin once for `/monomind:*` slash commands and security gates: `/plugins install ./.kimi-code/plugin`. See [Kimi Code guide →](doc/concepts/kimicode.md).
|
|
76
80
|
|
|
77
81
|
</details>
|
|
78
82
|
|
|
@@ -90,7 +94,7 @@ project before it loads project-scoped configuration. To run persistent
|
|
|
90
94
|
Monomind organizations through Codex, set `"runtime": "codex"` in the org
|
|
91
95
|
definition.
|
|
92
96
|
|
|
93
|
-
|
|
97
|
+
Plain `monomind init` sets up only the coding systems installed on your machine (Codex when `codex` is on PATH or `~/.codex` exists), and Claude Code when it finds none; `--all-platforms` sets up all five and `--platforms claude,codex` names them. Init never runs `npm install` in your project.
|
|
94
98
|
Use `monomind init --target codex` (or `--codex`) to initialize only Codex. See [Codex guide →](doc/concepts/codex.md).
|
|
95
99
|
|
|
96
100
|
</details>
|
|
@@ -100,8 +104,8 @@ Use `monomind init --target codex` (or `--codex`) to initialize only Codex. See
|
|
|
100
104
|
| Concern | Answer |
|
|
101
105
|
|---|---|
|
|
102
106
|
| **License** | [Apache 2.0](LICENSE) — use it however you want |
|
|
103
|
-
| **Data privacy** |
|
|
104
|
-
| **Dependencies** | Standard npm packages
|
|
107
|
+
| **Data privacy** | Monomind runs locally and stores its state locally: memory, code graph, document index and org state, embedded by a local model. The AI tools it drives (Claude Code, Codex, OpenCode, Kimi Code, Antigravity, and org roles, whose model calls monomind makes itself when a role uses an AI-SDK provider) send your prompts and code to their model providers, including the memory and Second Brain excerpts injected into those prompts. Monomind itself also makes a few outbound calls: the one-time embedding model download, the first-use installs of the Claude SDK and (without an installed browser) Chrome, the npm update check, and opt-in features; launching it through `npx monomind@latest` adds an npm registry lookup on every start, and opening the dashboard loads its scripts and fonts from public CDNs. See [doc/privacy.md](doc/privacy.md) for the complete list of what's sent, when, and how to opt out of each. |
|
|
108
|
+
| **Dependencies** | Standard npm packages. A fresh `npm install monomind` (Linux x64) adds 263 packages and 938 MB of `node_modules`, most of it `onnxruntime-node` (548 MB, local embeddings) and `onnxruntime-web` (141 MB). Four packages run install scripts, and two of them download binaries: `onnxruntime-node` (CUDA libraries from NuGet on Linux x64; `ONNXRUNTIME_NODE_INSTALL=skip` skips them) and `better-sqlite3` (a prebuilt addon from GitHub). Two heavy pieces are installed on first use instead, once, into `~/.monomind/deps` and never into your project: the Claude Agent SDK with its Claude binary (about 300 MB, on the first Claude org role or `agent exec --runtime claude`), and Chrome for `monomind browse` (about 400 MB, only when no Chrome, Chromium or Edge is installed). `MONOMIND_NO_AUTO_INSTALL=1` turns that off and prints the install command instead. Native addons: better-sqlite3 and onnxruntime-node; tree-sitter (`web-tree-sitter`) and sql.js are WASM. Full breakdown: [doc/privacy.md](doc/privacy.md#install-time-downloads). |
|
|
105
109
|
| **Permissions** | Registers as an MCP server — Claude Code controls what tools are available and prompts you before executing anything sensitive. |
|
|
106
110
|
| **Source** | Fully open. Read every line at [github.com/monoes/monomind](https://github.com/monoes/monomind). |
|
|
107
111
|
| **Maintenance** | Active development, regular releases on npm. |
|
|
@@ -159,7 +163,7 @@ monomind org stop content-team # request a graceful stop
|
|
|
159
163
|
monomind org list # every org + roles, schedule, status
|
|
160
164
|
```
|
|
161
165
|
|
|
162
|
-
### Observe, steer, and
|
|
166
|
+
### Observe, steer, and carry context between runs
|
|
163
167
|
|
|
164
168
|
```bash
|
|
165
169
|
monomind org logs content-team --follow # live event stream in the terminal
|
|
@@ -171,7 +175,7 @@ monomind org validate blog # schema + structural checks before
|
|
|
171
175
|
monomind org run blog --dry-run # preview each role's exact briefing
|
|
172
176
|
```
|
|
173
177
|
|
|
174
|
-
Orgs
|
|
178
|
+
Orgs carry context between runs: the coordinator records every run's outcome (`org_complete`), the next run is briefed on it, and all agents can query accumulated cross-run memory with `org_recall` — a scheduled org starts each cycle with what earlier cycles recorded instead of starting cold. Crashed agent sessions restart automatically with backoff.
|
|
175
179
|
|
|
176
180
|
### What runs under the hood
|
|
177
181
|
|
|
@@ -195,7 +199,7 @@ monomind org delete <name> # remove an org
|
|
|
195
199
|
monomind org memory <name> # cross-run KG memory: stats (default) | search <q> | rules | rollback <run-ref>
|
|
196
200
|
```
|
|
197
201
|
|
|
198
|
-
`org` has <!-- doc-count:org-subcommands -->
|
|
202
|
+
`org` has <!-- doc-count:org-subcommands -->39<!-- /doc-count:org-subcommands --> subcommands total (skills, run, stop, pause, resume, reload, status, serve, supervisor, test-loop, logs, events, watch, report, memory, costs, inbox, flow, questions, approvals, answer, approve, deny, gates, gate-approve, gate-reject, replay, resume-from, branch, decisions, create, validate, migrate, list, delete, mark-complete, role, sign, approve-paths).
|
|
199
203
|
|
|
200
204
|
> **Note:** `/mastermind:runorg` delegates directly to the Org Runtime daemon (the same path as `monomind org run`) — there is no boss agent, no monotask board, and no manual curl calls in this path. `/mastermind:runorg` converts legacy-format org config files with `monomind org migrate` before starting the daemon. New orgs should use `monomind org run` (or `/mastermind:runorg`) against a hand-authored `.monomind/orgs/<name>.json`.
|
|
201
205
|
|
|
@@ -243,7 +247,7 @@ monomind doctor --fix
|
|
|
243
247
|
|
|
244
248
|
> **Native module install blocked?** If `doctor` reports a missing `better-sqlite3` binding (`Could not locate the bindings file`, or npm logs an install script that was "blocked because it is not covered by allowScripts"), your npm's `allowScripts` policy blocked its native build — this isn't a Monomind bug. Run `npm install-scripts approve better-sqlite3 && npm rebuild better-sqlite3`, then re-run `monomind doctor --fix`.
|
|
245
249
|
|
|
246
|
-
Open Claude Code.
|
|
250
|
+
Open Claude Code. The core `/mastermind:*` workflows are available (all <!-- doc-count:mastermind-commands -->40<!-- /doc-count:mastermind-commands --> come with `monomind packs add` or `init --all-packs`):
|
|
247
251
|
|
|
248
252
|
```bash
|
|
249
253
|
/mastermind:review --tillend # review and fix until nothing is left
|
|
@@ -255,7 +259,7 @@ monomind org run sample-team # run your first AI org (init writes a runnabl
|
|
|
255
259
|
|
|
256
260
|
## 📚 Second Brain — Your Documents, Retrieved by Meaning
|
|
257
261
|
|
|
258
|
-
Drop documents (Markdown, TXT, PDF, DOCX) anywhere in your project and run `monomind init` — the Second Brain activates itself. No flags, no configuration, no accounts.
|
|
262
|
+
Drop documents (Markdown, TXT, PDF, DOCX) anywhere in your project and run `monomind init` — the Second Brain activates itself. No flags, no configuration, no accounts. Indexing and search run on your machine: a local embedding model (`Alibaba-NLP/gte-modernbert-base`, 768-dim, via transformers.js) and a local SQLite vector store. **Your notes are indexed and stored locally** — but the excerpts search returns are injected into your AI tool's prompts, and go to its model provider with the rest of the prompt.
|
|
259
263
|
|
|
260
264
|
From then on, every substantive prompt you type in Claude Code is automatically answered *with your own knowledge in context* — a hook retrieves the most relevant excerpts semantically (the always-on dashboard keeps the model warm, ~60ms per lookup) and injects them before Claude starts thinking. Ask "when do new parents get time off" and the parental-leave section of your handbook is already on the table, even though you never used the word "leave".
|
|
261
265
|
|
|
@@ -268,11 +272,11 @@ monomind doc export # portable OKF bundle — move your brain bet
|
|
|
268
272
|
|
|
269
273
|
> **Optional spreadsheet support:** `monomind init` never downloads SheetJS. To extract `.xlsx`, `.xls`, or `.ods` files, install it only when you need it: run `pnpm add xlsx` in a project using a local/npx Monomind install, or `npm install -g xlsx` when Monomind is installed globally. Until then, spreadsheet files are skipped while the rest of document ingestion continues.
|
|
270
274
|
|
|
271
|
-
**And it follows you across projects.** Ingest a path from *outside* the current project (`monomind doc ingest ~/notes`, or add `--global`) and it lands in your personal global brain at `~/.monomind/global-brain` (override with `MONOMIND_GLOBAL_BRAIN_DIR`) — kept as a sibling of `~/.monomind/projects` specifically so `monomind cleanup --data` can never prune it — searchable from every project on the machine. All retrieval (CLI search, per-prompt injection, the dashboard) merges both stores automatically, with project knowledge winning ties and global hits labeled `[global]`. `doc export --global` moves your whole brain between machines as an OKF bundle —
|
|
275
|
+
**And it follows you across projects.** Ingest a path from *outside* the current project (`monomind doc ingest ~/notes`, or add `--global`) and it lands in your personal global brain at `~/.monomind/global-brain` (override with `MONOMIND_GLOBAL_BRAIN_DIR`) — kept as a sibling of `~/.monomind/projects` specifically so `monomind cleanup --data` can never prune it — searchable from every project on the machine. All retrieval (CLI search, per-prompt injection, the dashboard) merges both stores automatically, with project knowledge winning ties and global hits labeled `[global]`. `doc export --global` moves your whole brain between machines as an OKF bundle — a file you move yourself, with no cloud service involved.
|
|
272
276
|
|
|
273
277
|
Retrieval quality is a tested invariant, not a hope: a golden-set eval (paraphrase queries against notes written in different vocabulary) runs in CI with an 80% recall bar.
|
|
274
278
|
|
|
275
|
-
> **Privacy note:** the embedding model (~90MB) is fetched once from HuggingFace's CDN when your first document is indexed, then cached locally forever. That download is the only outbound request the Second Brain
|
|
279
|
+
> **Privacy note:** the embedding model (~90MB) is fetched once from HuggingFace's CDN when your first document is indexed, then cached locally forever. That download is the only outbound request the Second Brain's indexing and search make — your documents and queries are processed locally. Excerpts injected into a prompt are a different matter: they go to your AI tool's model provider with that prompt. Offline at first index? Search degrades gracefully to keyword matching and `monomind doctor` tells you how to warm up later.
|
|
276
280
|
|
|
277
281
|
> **Which model where?** Monomind uses two local embedding models. `Snowflake/snowflake-arctic-embed-xs` (~88MB) serves semantic task routing only. Everything the memory bridge embeds — both the Second Brain document index and the persistent memory store, which share that one bridge — uses `Alibaba-NLP/gte-modernbert-base` (768-dim, ~90MB); there is no separate document model. See [Embeddings](./doc/commands/memory.md#hybrid-search-architecture--options) for the per-subsystem detail.
|
|
278
282
|
|
|
@@ -280,7 +284,7 @@ Retrieval quality is a tested invariant, not a hope: a golden-set eval (paraphra
|
|
|
280
284
|
|
|
281
285
|
## 🧠 Memory That Persists
|
|
282
286
|
|
|
283
|
-
Every session, every agent, every org writes to a persistent memory store that survives across sessions — text plus embedding vectors in local SQLite (better-sqlite3, pure-WASM fallback), embedded by a local model. No cloud vector database
|
|
287
|
+
Every session, every agent, every org writes to a persistent memory store that survives across sessions — text plus embedding vectors in local SQLite (better-sqlite3, pure-WASM fallback), embedded by a local model. No cloud vector database and no API keys; the store itself uploads nothing. Entries recalled into a prompt go to your AI tool's model provider with that prompt. The next time you run anything, the store holds what earlier sessions recorded about what was built, what failed, and which patterns worked.
|
|
284
288
|
|
|
285
289
|
```mermaid
|
|
286
290
|
graph TD
|
|
@@ -324,14 +328,14 @@ Before touching any file, Monomind queries **Monograph** — a SQLite-backed kno
|
|
|
324
328
|
|
|
325
329
|
## 🎣 Hooks & Workers
|
|
326
330
|
|
|
327
|
-
Monomind wires 28 hook subcommands into Claude Code across edit, task, command, and session lifecycle events — logging
|
|
331
|
+
Monomind wires 28 hook subcommands into Claude Code across edit, task, command, and session lifecycle events — logging edits and outcomes to local pattern files and picking agents.
|
|
328
332
|
|
|
329
333
|
```mermaid
|
|
330
334
|
flowchart LR
|
|
331
335
|
CE["Claude Code\nEvent"] --> H["Hook Router"]
|
|
332
336
|
H --> P["pre-edit\npre-task\npre-command"]
|
|
333
337
|
H --> SS["session-start\nsession-end\nnotify"]
|
|
334
|
-
H --> I["route\
|
|
338
|
+
H --> I["route\nlog outcomes"]
|
|
335
339
|
H --> T["teammate-idle\ntask-completed"]
|
|
336
340
|
|
|
337
341
|
I --> DB[("patterns.json\nmemory store")]
|
|
@@ -360,7 +364,7 @@ In Claude Code, the live pre-bash/pre-write gate is wired up via its own lazy-lo
|
|
|
360
364
|
|
|
361
365
|
---
|
|
362
366
|
|
|
363
|
-
## 📋 <!-- doc-count:mastermind-commands -->
|
|
367
|
+
## 📋 <!-- doc-count:mastermind-commands -->40<!-- /doc-count:mastermind-commands --> Mastermind Commands
|
|
364
368
|
|
|
365
369
|
Everything runs from inside Claude Code via slash commands. Here's the highlight reel:
|
|
366
370
|
|
|
@@ -392,7 +396,7 @@ Everything runs from inside Claude Code via slash commands. Here's the highlight
|
|
|
392
396
|
| `/mastermind:finance` | Budgets, invoicing, modeling |
|
|
393
397
|
| `/mastermind:ops` | Operations and workflow automation |
|
|
394
398
|
|
|
395
|
-
**[→ Full reference (<!-- doc-count:mastermind-commands -->
|
|
399
|
+
**[→ Full reference (<!-- doc-count:mastermind-commands -->40<!-- /doc-count:mastermind-commands --> commands)](https://monoes.github.io/monomind/#slash)**
|
|
396
400
|
|
|
397
401
|
---
|
|
398
402
|
|
|
@@ -442,7 +446,7 @@ graph TD
|
|
|
442
446
|
style ORG fill:#F59E0B22,stroke:#F59E0B
|
|
443
447
|
```
|
|
444
448
|
|
|
445
|
-
**Claude Code's Task tool drives in-session multi-agent work; `monomind org run` drives persistent background orgs.**
|
|
449
|
+
**Claude Code's Task tool drives in-session multi-agent work; `monomind org run` drives persistent background orgs.** Monomind keeps its own state on your machine; the AI tools it drives send prompts and code to their model providers — see [Trust & Security](#trust--security).
|
|
446
450
|
|
|
447
451
|
---
|
|
448
452
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "monomind",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.22.0",
|
|
4
4
|
"description": "Open-source CLI extension for Claude Code, OpenCode, Antigravity, Kimi Code, and Codex. Adds an MCP server with a codebase knowledge graph, persistent memory, multi-agent coordination, and reusable slash commands. Apache 2.0 licensed. See https://github.com/monoes/monomind/blob/main/doc/privacy.md for what leaves your machine and when.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
"LICENSE"
|
|
22
22
|
],
|
|
23
23
|
"dependencies": {
|
|
24
|
-
"@monoes/monomindcli": "2.
|
|
24
|
+
"@monoes/monomindcli": "2.22.0"
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"@biomejs/biome": "^2.5.8",
|