An open-source MCP server that extends Claude Code with a codebase knowledge graph, persistent memory, and multi-agent coordination.
Apache 2.0 licensed · Your code and memory stay local β see [Trust & Security](#trust--security) for the network calls Monomind does make
π’ Orgs Β· π Quickstart Β· β‘ Mastermind Β· π Commands Β· ποΈ Architecture
--- ## What is Monomind? Monomind is an **open-source CLI and MCP server** that plugs into Claude Code, [OpenCode](https://opencode.ai), Antigravity, Kimi Code, and Codex via the standard [Model Context Protocol](https://modelcontextprotocol.io/). It adds capabilities these assistants don't ship with out of the box: - **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. - **Persistent memory** β a JSON pattern store with episodic recall that survives across sessions. Agents and orgs share context without re-prompting. - **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. - **Reusable slash commands** β 30+ development workflows (build, review, debug, TDD, architecture) available as `/mastermind:*` commands inside Claude Code. ```bash npm install -g monomind # Apache 2.0 licensed, runs entirely on your machine cd your-project && monomind init claude mcp add monomind -- npx -y monomind@latest mcp start ```| rules | rollback``` `org` has 31 subcommands total (run, stop, pause, resume, reload, status, serve, supervisor, test-loop, logs, report, memory, costs, flow, questions, answer, approve, deny, gates, gate-approve, gate-reject, replay, resume-from, branch, decisions, create, validate, migrate, list, delete, mark-complete) β `org memory` is the newest addition. > **Note:** `/mastermind:runorg` now delegates directly to the Org Runtime v2 daemon (the same path as `monomind org run`) β there is no boss agent, no monotask board, and no manual curl calls in this path. The old prompt-orchestrated flow (Task-tool boss agent, monotask board, manual dashboard event posting) is retired to `/mastermind:runorgv1`, reachable only by that explicit legacy name, kept only for orgs not yet migrated off the v1 config shape. New orgs should use `monomind org run` (or `/mastermind:runorg`) against a hand-authored `.monomind/orgs/ .json`. --- ## β‘ The Autonomous Build Loop For code, `/mastermind:autodev` is the equivalent of Orgs β a loop that researches, builds, and reviews your codebase without stopping. ```mermaid flowchart LR R["Research\nParallel scan:\ngit log, files\nTODOs, graph\nmemory"] --> S S["Select\nFeasibility x\nblast-radius x\nfocus"] --> B B["Build\nArchitect\nCoder\nTester\nReviewer"] --> V V["Review Loop\nCode + Security\n+ Reality\nmax 5 iterations"] --> L L["Log + Loop\nStore to memory\n--tillend:\nschedule next"] L -->|"more to do"| R style R fill:#00D2AA22,stroke:#00D2AA style B fill:#8B5CF622,stroke:#8B5CF6 style V fill:#F59E0B22,stroke:#F59E0B style L fill:#10B98122,stroke:#10B981 ``` ```bash /mastermind:autodev --tillend # loop until nothing left /mastermind:autodev --tillend --focus security # bias toward security fixes /mastermind:autodev 3 # exactly 3 improvements ``` ### Universal loop flags | Flag | Purpose | |---|---| | `--tillend` | Repeat until empty round (zero findings, zero actions) | | `--repeat ` | Repeat exactly N times | | `--focus ` | Bias toward: `security` Β· `dx` Β· `performance` | | `--auto` | No confirmation prompts | | `--maxruns ` | Safety cap (default 50) | --- ## π Quickstart ```bash # 1. Install npm install -g monomind # 2. Initialize in your project cd your-project monomind init # 3. Wire into Claude Code as an MCP server claude mcp add monomind -- npx -y monomind@latest mcp start # 4. Health check monomind doctor --fix ``` > **Semantic routing (opt-in download):** embedding-based task routing needs a local model (~88 MB, `Snowflake/snowflake-arctic-embed-xs` via transformers.js). `monomind init` asks interactively whether to download it β the default is No, and non-interactive/CI installs never download it silently. Declining is fine: routing falls back to keyword mode. Fetch it any time with `monomind download-embeddings` (or `node scripts/download-embedding-model.mjs` on a source checkout). Open Claude Code. You now have 49 `/mastermind:*` workflows available: ```bash /mastermind:autodev --tillend # start autonomous code loop monomind org run sample-team # run your first AI org (init writes a runnable sample-team.json β edit it, or run it as-is) /mastermind:help # show all commands ``` --- ## π Second Brain β Your Documents, Retrieved by Meaning 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. Everything runs on your machine: a local embedding model (MiniLM via transformers.js) and a local SQLite vector store. **Your notes never leave your computer.** 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". ```bash monomind doc ingest ./notes # index documents (init + session-start do this automatically) monomind doc search -q "pricing psychology in checkout" # semantic search, by meaning not keywords monomind doc list # what's indexed monomind doc export # portable OKF bundle β move your brain between machines ``` **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 β still no cloud, ever. 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. > **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 ever makes β your documents and queries never leave your machine. Offline at first index? Search degrades gracefully to keyword matching and `monomind doctor` tells you how to warm up later. > **Which model where?** Monomind uses three local embedding models, each scoped to one subsystem: `Snowflake/snowflake-arctic-embed-xs` (~88MB) for semantic task routing, MiniLM (~90MB) for Second Brain document retrieval, and `Alibaba-NLP/gte-modernbert-base` (768-dim) for the persistent memory store. See [Embeddings](./doc/commands/memory.md#hybrid-search-architecture--options) for which model each subsystem uses. --- ## π§ Memory That Persists 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, no API keys, no data transmission. The next time you run anything, Monomind already knows what was built, what failed, and which patterns work. ```mermaid graph TD L0["L0 - In-flight\nCurrent session drawers\nephemeral"] L1["L1 - Working\nCross-session memory\nBM25 K1=1.5, B=0.75"] L2["L2 - Long-term\nEpisodic store\nSemantic recall"] L3["L3 - Shared\nCross-agent namespace\nFederated swarm reads"] L0 -->|promoted| L1 --> L2 --> L3 style L0 fill:#00D2AA11,stroke:#00D2AA style L1 fill:#F59E0B11,stroke:#F59E0B style L2 fill:#8B5CF611,stroke:#8B5CF6 style L3 fill:#EF444411,stroke:#EF4444 ``` ```bash monomind memory store --key "key insight" --value "β¦" --namespace my-project monomind memory search "auth implementation" # semantic (local embeddings) with keyword fallback ``` --- ## πΊοΈ Monograph β Your Codebase, as a Graph Before touching any file, Monomind queries **Monograph** β a SQLite-backed knowledge graph of your entire codebase. Nodes are files, classes, and functions. Edges are imports, calls, and dependencies. ```bash /mastermind:understand # build the graph /mastermind:graph-status # nodes Β· edges Β· freshness # Inside Claude Code, Monograph runs automatically: # β "what files does auth.ts import?" # β "what breaks if I change UserService?" # β "find all callers of validateToken()" ``` 19 default MCP tools (+27 advanced via `MONOGRAPH_MCP_ADVANCED=1`). Impact analysis. Community detection. Zero grep. --- ## π£ Hooks & Workers Monomind wires 28 hook subcommands into Claude Code across edit, task, command, and session lifecycle events β logging patterns, routing agents, and feeding the intelligence system. ```mermaid flowchart LR CE["Claude Code\nEvent"] --> H["Hook Router"] H --> P["pre-edit\npre-task\npre-command"] H --> SS["session-start\nsession-end\nnotify"] H --> I["route\nlearn"] H --> T["teammate-idle\ntask-completed"] I --> DB[("patterns.json\nmemory store")] DB -->|next session| CE ``` **9 on-demand workers** run at session start (staleness-gated, refreshed when older than 6 hours): `health` Β· `ddd` Β· `security` Β· `cache` Β· `progress` Β· `map` Β· `audit` Β· `consolidate` Β· `reflexion`. --- ## π‘οΈ MonoFence AI β Security Layer Every agent boundary is defended by **monofence-ai** β real-time detection of prompt injection, jailbreaks, homoglyphs, base64 evasion, multi-turn escalation, and PII leakage. ```typescript import { isSafe, createMonoDefence } from 'monofence-ai'; isSafe('Ignore all previous instructions'); // β false (~0.04ms) const fence = createMonoDefence({ enableContextTracking: true }); const result = await fence.detect(userInput); // result.safe Β· result.threats Β· result.overallRisk ``` In Claude Code, the live pre-bash/pre-write gate is wired up via its own lazy-loaded integration in `.claude/helpers/handlers/gates-handler.cjs` (`MONOMIND_MONOFENCE_GATE=off` to disable) β not via monofence-ai's `registerSecurityHooks()` API, which is a separate integration point consumed only by `@monoes/hooks`' in-process `HookExecutor`. --- ## π 49 Mastermind Commands Everything runs from inside Claude Code via slash commands. Here's the highlight reel: ### Development | Command | What it does | |---|---| | `/mastermind:autodev` | Autonomous research β build β review loop | | `/mastermind:build` | Build a feature from a brief | | `/mastermind:review` | Iterative review until zero findings | | `/mastermind:debug` | Systematic root-cause debugging | | `/mastermind:tdd` | Red β Green β Refactor | | `/mastermind:architect` | Architecture review + file structure | | `/mastermind:plan` | Comprehensive implementation plan | | `/mastermind:worktree` | Feature work in isolated git worktree | ### Organizations | Command | What it does | |---|---| | `monomind org run ` | Start an org as a real SDK-backed daemon | | `monomind org status` / `list` | Runtime state for one or all orgs | | `monomind org stop ` | Request a graceful stop | | `/mastermind:approvev1` | Action pending approval requests | ### Business Domains | Command | What it does | |---|---| | `/mastermind:marketing` | Campaigns, copy, SEO, social | | `/mastermind:content` | Blog posts, threads, newsletters | | `/mastermind:sales` | Outreach, proposals, pipeline | | `/mastermind:finance` | Budgets, invoicing, modeling | | `/mastermind:ops` | Operations and workflow automation | **[β Full reference (49 commands)](https://monoes.github.io/monomind/#slash)** --- ## π¦ Packages | Package | npm | Purpose | |---|---|---| | `monomind` | [](https://www.npmjs.com/package/monomind) | Umbrella shim β **install this one** | | `@monoes/monomindcli` | [](https://www.npmjs.com/package/@monoes/monomindcli) | CLI engine (32 commands, MCP server) | | `@monoes/monograph` | [](https://www.npmjs.com/package/@monoes/monograph) | Code knowledge graph (tree-sitter + SQLite) | | `@monoes/memory` | [](https://www.npmjs.com/package/@monoes/memory) | Persistent memory backends (SQLite + vectors) | | `@monoes/hooks` | [](https://www.npmjs.com/package/@monoes/hooks) | Hook registry + 9 on-demand workers | | `@monoes/mcp` | [](https://www.npmjs.com/package/@monoes/mcp) | MCP server framework (stdio/HTTP/WebSocket) | | `@monoes/routing` | [](https://www.npmjs.com/package/@monoes/routing) | Semantic task-to-agent routing | | `@monoes/monobrowse` | [](https://www.npmjs.com/package/@monoes/monobrowse) | Browser automation via CDP | | `@monoes/monodesign` | [](https://www.npmjs.com/package/@monoes/monodesign) | Frontend design intelligence | | `monofence-ai` | [](https://www.npmjs.com/package/monofence-ai) | AI manipulation defence | See [CLI Reference](./doc/commands/cli-reference.md) for the full 32-command index. --- ## ποΈ How It's Built ```mermaid graph TD CC["Claude Code"] MCP["MCP Server\nmonomind mcp start"] D["Background Workers\n(@monoes/hooks, in-process)"] ORG["OrgDaemon\nmonomind org run\nreal SDK sessions"] CC <-->|"MCP tools: monograph, memory"| MCP MCP <--> D D --> ADB[("Memory store\npatterns + episodes")] D --> MG[("Monograph\ncode graph")] D --> HK["Hooks\n29 subcommands"] CC -->|"Task tool - spawns agents"| AG["In-session agents\narchitect, coder\ntester, reviewer\nsecurity, perf"] AG <-->|reads and writes| ADB ORG -->|"spawns, policy-gated"| RA["Role agents"] ORG <-->|reads and writes| ADB style CC fill:#00D2AA22,stroke:#00D2AA style AG fill:#8B5CF622,stroke:#8B5CF6 style ADB fill:#F59E0B22,stroke:#F59E0B style ORG fill:#F59E0B22,stroke:#F59E0B ``` **Claude Code's Task tool drives in-session multi-agent work; `monomind org run` drives persistent background orgs.** Your code and memory stay local β see [Trust & Security](#trust--security) for the network calls Monomind does make. --- ## Resources - π [Full Documentation](https://monoes.github.io/monomind/) - π₯οΈ [CLI Command Reference](https://github.com/monoes/monomind/blob/main/doc/commands/cli-reference.md) - π’ [Org Runtime v2 Architecture](https://github.com/monoes/monomind/blob/main/doc/concepts/org-runtime.md) - π’ [Autonomous Orgs](https://monoes.github.io/monomind/#orgs) - β‘ [Mastermind Reference](https://monoes.github.io/monomind/#mastermind) - π [All Slash Commands](https://monoes.github.io/monomind/#slash) - π [Issues](https://github.com/monoes/monomind/issues) - π¬ [Discussions](https://github.com/monoes/monomind/discussions) ---
Built with β₯ by monoes Β· Apache 2.0 License
