Skip to main content

​
Getting Started

No. ModusBrain ships with a zero-configuration embedded PGLite database that runs entirely in-process on your local machine. No server setup, no Docker container, and no cloud account is required to get started.For teams with larger knowledge bases (1,000+ documents) or organizations that need multi-machine access, ModusBrain also supports a full PostgreSQL + pgvector backend via Supabase or any hosted Postgres provider. You can start locally and migrate later with a single command:
ModusBrain requires at least one embedding provider API key to enable semantic search and skill compilation. Supported providers include:
  • ZeroEntropy — recommended for highest quality retrieval (ZEROENTROPY_API_KEY)
  • OpenAI — broadly available, good general-purpose embeddings (OPENAI_API_KEY)
  • Voyage AI — alternative high-quality embedding provider (VOYAGE_API_KEY)
  • Anthropic — used for LLM-powered compilation and reasoning (ANTHROPIC_API_KEY)
Set keys via the CLI:
PGLite is ModusBrain’s default embedded database. It runs in-process, requires zero setup, and is ideal for individual developers or small teams using a single machine.Postgres + pgvector (typically via Supabase) is the recommended backend when you need:
  • A knowledge base with more than 1,000 documents
  • Multi-machine access (e.g., a team sharing one brain over HTTP)
  • Production-grade durability and backup strategies
The modusbrain init command automatically detects your repo size and suggests Supabase when it’s warranted.
Yes. ModusBrain can be installed via npm and run with Node.js (version 18.0.0 or higher):
Bun is the recommended runtime because it provides faster startup times and is the platform the CLI is primarily developed and tested against, but the npm installation works across standard Node.js environments.
Run the built-in system diagnostics command after installation:
If any check returns a warning or failure, modusbrain doctor will print the exact fix command needed to resolve the issue.

​
Operational Skills

An operational skill is a versioned, structured artifact that ModusBrain compiles from your raw company documentation. It contains:
  • Prose judgment — semantic, context-aware guidelines for reasoning about edge cases
  • Structured policy rules — explicit executable logic (e.g. if amount < 500 => auto_approve)
  • Provenance record — a full audit trail linking the skill back to every source document, compiler identity, and timestamp
Skills are the unit of work that AI agents execute against. Instead of an agent reading raw markdown and reasoning about it independently, it receives a structured, pre-approved, versioned skill runbook with a confidence score.
When you compile a skill, it is initially created in draft status. Draft skills are safety-gated — no autonomous agent can execute them.Once a designated owner reviews the compiled skill and explicitly approves it, its status changes to active. Only active skills are available for agent execution.This two-stage model ensures that a human always reviews and signs off on company policy before any agent acts on it:
When an agent’s request falls below the configured confidence threshold for a skill’s risk tier, ModusBrain blocks the execution and returns a structured error response indicating the confidence score and the minimum threshold required.The agent receives this as a clear signal rather than a silent failure. Operators have three options to respond:
  1. Issue an approval token — a time-limited override that allows one specific agent to bypass the gate for exactly one execution
  2. Lower the risk tier — recompile the skill with a lower-tier setting if the current threshold is misconfigured
  3. Submit a correction — provide feedback that improves future confidence scores for this skill
Yes. ModusBrain keeps a full version history of every compiled skill. You can view the version history and promote any previous version back to active status:
There is no limit. You can compile as many skills as you need from your documentation. Each skill is a separate versioned artifact with its own approval chain, risk tier, and audit log.Common patterns include compiling one skill per major business process (e.g., refund-handling, expense-reimbursement, onboarding-checklist) and having multiple agents share the same active skill version.

​
Safety & Compliance

When an agent requests a skill execution, ModusBrain evaluates the full task context — the task description, the provided parameters, and the active skill policy — and computes a confidence score between 0 and 1.This score is then compared against the skill’s risk tier threshold:The gating happens entirely server-side before any action is taken.
An approval token is a time-limited (1-hour), single-use credential that allows an agent to bypass the confidence gate for exactly one execution of a specific skill.Use approval tokens when:
  • A legitimate business case requires executing a high-stakes action that falls below the automatic confidence threshold
  • An emergency situation requires bypassing the normal approval flow
  • You want a human to review an edge case without recompiling the skill
Approval token issuances and the executions they authorize are both recorded in the audit ledger.
All audit records are stored in your configured database (PGLite or Postgres). Each record captures:
  • The executing agent’s identity
  • The skill slug and exact version evaluated
  • The full parameter set passed to the execution
  • The calculated confidence score
  • The final outcome (allowed, blocked, or overridden)
  • A timestamp and operator identity for any approval actions
Query logs at any time:
ModusBrain is designed with data locality in mind. With the default PGLite backend, all data — including your company’s knowledge, skill runbooks, and audit logs — stays entirely on your local machine. Nothing is sent to external servers except the specific API calls made to your configured embedding and LLM providers.For the HTTP MCP server deployment, all data stays within your own infrastructure. ModusBrain does not operate a SaaS brain service — you own and control your own data at all times.

​
MCP & Integrations

ModusBrain works with any tool that supports the Model Context Protocol (MCP). Verified integrations include:
  • Claude Code — via claude mcp add modusbrain -- modusbrain serve
  • Claude Desktop — via stdio MCP configuration
  • ChatGPT — via OpenAI MCP client support
  • Codex — via codex mcp add modusbrain -- modusbrain serve
  • Cursor — via stdio MCP
  • Perplexity — via OAuth-scoped HTTP MCP
See the MCP & Integrations section for per-client setup guides.
Yes. ModusBrain ships with a full HTTP MCP server mode that includes OAuth 2.1 authorization, per-user scoped credentials, and an admin dashboard.
Each team member gets their own token with read, write, or admin access. The server includes an admin SPA at /admin for managing users and viewing activity.See the For Teams & Companies guide for the full setup walkthrough.
Yes. ModusBrain supports a thin-client mode that configures a remote MCP connection without setting up a local database or embedding engine.
In thin-client mode, most local commands route transparently through the remote server. This is ideal for team members who want to query and use the company brain without running their own instance.

​
Troubleshooting

modusbrain doctor is a self-healing diagnostic tool. When it reports a warning or failure, it also prints the exact fix command in the output message. Most common issues and their solutions:For persistent issues, run modusbrain doctor --fix to attempt automatic remediation.
Low confidence scores usually indicate one of three things:
  1. The source documentation is thin or contradictory — Enrich the relevant docs in your knowledge base, then recompile the skill.
  2. Conflicting policy documents — Run modusbrain opskill flag-conflict <slug> to identify and resolve document-level contradictions before recompiling.
  3. The risk tier is too high for the skill’s domain — Review whether the assigned risk tier matches the actual business risk of the operation.
After making corrections, recompile to generate a new draft skill version:
Use the built-in upgrade command, which handles binary updates, schema migrations, and post-upgrade configuration prompts in one step:
The upgrade command is TTY-only by design — it will prompt you to confirm schema changes before applying them. If you are running in a non-interactive CI environment, prompts are skipped with informational stderr messages.
A schema_version: 0 in your modusbrain doctor output means the database schema has not been initialized or the migrations have not been applied. This typically happens after a fresh install or a failed upgrade.Fix it by running the migration command manually:
After this completes, run modusbrain doctor again to confirm all schema checks are green.
Yes. ModusBrain is fully open source and available at github.com/thebuildceo/modusbrain. You can self-host the complete platform — including the CLI, the HTTP MCP server, and the admin dashboard — on your own infrastructure with no licensing fees or usage restrictions.The source-from-clone install path is: