ModusBrain

The operational execution layer for autonomous AI agents.

ModusBrain compiles scattered company knowledge — policies, wikis, support runbooks, and tickets — into versioned operational skills protected by confidence-gated safety boundaries, cryptographic audit logs, and manual human approval overrides.

With ModusBrain, your autonomous agents act consistently based on verified company guidelines, entirely eliminating the risk of creative hallucinations during critical actions.

The Operational lifecycle (5 Phases)

ModusBrain bridges the gap between static retrieval and safe agent execution by establishing a secure five-phase operational lifecycle:

| Phase | Description | | :--- | :--- | | 1. Compile | Automatically reads unstructured documentation and compiles it into versioned draft skills (combining semantic guidance and structured policy rules). | | 2. Gate | Evaluates agent execution requests in real time, calculating confidence scores and gating actions based on risk tiers. | | 3. Approve | Holds newly compiled skills in a draft status, requiring an explicit owner sign-off or time-limited approval tokens before execution. | | 4. Audit | Logs every execution attempt, context parameter, calculated confidence, and outcome to a secure, tamper-resistant ledger. | | 5. Feedback | Allows operators to submit corrections, which write evidence files back to the graph to trigger automatic skill recompilation. |

Quick Start (5 Minutes)

1. Install the CLI

Install the global CLI using your preferred package manager (Node.js >= 18.0.0 or Bun >= 1.3.10 is required):

# Via npm
npm install -g @genthropic/modusbrain

# Via Bun
bun install -g @genthropic/modusbrain

2. Initialize your Brain

Set up the zero-configuration embedded local database and apply the initial database migrations:

modusbrain init
modusbrain apply-migrations --yes
modusbrain config set schema_pack gbrain-base-v2

3. Compile, Approve, and Execute your First Skill

Draft an operational skill, promote it to active status, and run it with the runtime evaluation engine:

# Compile the skill runbook
modusbrain opskill compile "refund handling" --risk-tier high_stakes

# Approve the compiled draft for agent execution
modusbrain opskill approve refund-handling --by [email protected]

# Execute the skill with runtime context parameters
modusbrain opskill execute refund-handling \
  --task "Process $300 refund for order #1204" \
  --context '{"amount":300}'

4. Check the Secure Audit Trail

Inspect the queryable execution log containing parameters, versions, and final outcomes:

modusbrain opskill audit --slug refund-handling --json

CLI Command Reference

ModusBrain provides a rich CLI interface for managing your operational knowledge graph:

modusbrain opskill compile "<topic>"   # Draft a versioned skill from source documentation
modusbrain opskill approve <slug>      # Promote a draft skill to active status
modusbrain opskill execute <slug>      # Execute an active skill with confidence gating
modusbrain opskill audit               # Query the secure action audit ledger
modusbrain opskill correct <slug>      # Submit operator corrections and feedback
modusbrain search "<query>"            # Run a hybrid RAG search query
modusbrain think "<query>"             # Perform synthesis with full document citations
modusbrain doctor                      # Execute system-wide health and sanity checks

Run modusbrain --help for the complete command list and optional parameters.

Configuration & Migration Fallbacks

ModusBrain has been rebranded from gbrain to modusbrain. The migration is fully backward-compatible, utilizing fallback resolution pathways for existing installations:

| Setting | Standard Value | Legacy Fallback / Migration Alias | | :--- | :--- | :--- | | Config Directory | ~/.modusbrain | ~/.gbrain (automatically detected if existing configuration is present) | | Environment Variables | MODUSBRAIN_* | GBRAIN_* (fallback resolution order checks legacy prefix if unset) | | Source Dotfile | .modusbrain-source | .gbrain-source (automatically imported if legacy file exists) | | CLI Command | modusbrain | gbrain (globally symlinked alias preserved for backward compatibility) |

Developer Guides & Documentation

• AGENTS.md — Downstream setup and agent operating protocol
• MODUSBRAIN_LAUNCH.md — Launch playbook, website guidelines, and Mintlify configuration
• company-brain-rfs-analysis.md — In-depth architectural design and deployment models
• llms.txt — Comprehensive text-ingestion map for LLM integrations

Development

To set up a local development environment, clone the repository and run the test suites:

# Clone the repository
git clone https://github.com/thebuildceo/modusbrain.git
cd modusbrain

# Install development dependencies
bun install --ignore-scripts

# Run local unit tests
bun test test/operational-skills.test.ts test/branding.test.ts

# Compile the binary
bun run build  # Compiles into bin/modusbrain

Verification Suite

Before submitting Pull Requests or publishing updates, run the verification checks:

bun run verify

License & Attribution

ModusBrain is licensed under the MIT License. It extends the open-source ModusBrain engine. See the LICENSE and NOTICE files for full licensing statements.