> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modusbrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How ModusBrain Works

> The five-phase architecture that turns company knowledge into versioned, safely executable skills.

# How ModusBrain Works

ModusBrain adds a **safe execution layer** on top of the underlying RAG engine. While the base engine handles pulling knowledge from fragmented sources, structuring it, and keeping it current — ModusBrain compiles that knowledge into **versioned operational skills** that AI agents can execute with confidence gating, audit trails, and a closed feedback loop.

> "ModusBrain solved the hardest 70% — pulling scattered knowledge into a current, cited memory layer. ModusBrain adds the last 30%: compiling that memory into versioned, confidence-gated skills that agents can safely execute against, not just query."

***

## What ModusBrain Adds (vs. Base GBrain Engine)

| Capability                             |  Base Engine  |                 ModusBrain Layer                |
| :------------------------------------- | :-----------: | :---------------------------------------------: |
| Pull knowledge from fragmented sources |       ✅       |                   ✅ Unchanged                   |
| Structure it                           |       ✅       |       ✅ + `skill` / `procedure` page types      |
| Keep it current                        | ✅ Dream Cycle |   ✅ + auto re-compile on correction threshold   |
| Not just search/chatbot                |   ✅ `think`   |              ✅ + `opskill execute`              |
| Living map of how the company works    |   ⚠️ Partial  |     ✅ Operational skills capture procedures     |
| Executable skills for AI agents        |     ❌ Gap     |    ✅ **Versioned skill artifacts (v1→v2→v3)**   |
| Safe, consistent agent actions         |     ❌ Gap     | ✅ **Risk tiers + confidence gating + approval** |
| Multi-user / team memory               |       ✅       |                   ✅ Unchanged                   |

***

## Skill & Procedure Page Types

ModusBrain introduces two structured page types that don't exist in plain GBrain:

* **`skill`** — A versioned, agent-executable procedure compiled from your existing brain pages. Skills have a draft/approved/superseded lifecycle and a confidence threshold.
* **`procedure`** — A structured reference document that describes a company process in a way that the compiler can extract structured policy rules from.

These types are part of the `modusbrain-ops` schema pack. Activate it with:

```bash theme={null}
modusbrain config set schema_pack modusbrain-ops
```

When active, the schema pack registers `skill` and `procedure` as first-class page types with enforced `## Facts`, `## Policy`, and `## Judgment` sections that the compiler reads during `opskill compile`.

***

## Versioned Skill Artifacts (v1 → v2 → v3)

Every compiled skill is stored as an **immutable versioned artifact**. Versions are never overwritten — only superseded. This is what makes audit trails trustworthy for compliance.

Each skill version stores:

| Field                  | Description                                          |
| :--------------------- | :--------------------------------------------------- |
| `prose_judgment`       | Natural-language edge-case guidance for the agent    |
| `structured_policy`    | JSON rules, e.g. `if amount < 500 → auto_approve` |
| `provenance`           | Source page slugs, compiler identity, and timestamps |
| `version`              | Immutable integer: v1, v2, v3, …                     |
| `status`               | One of: `draft` → `approved` → `superseded`          |
| `risk_tier`            | `informational`, `low_stakes`, or `high_stakes`      |
| `confidence_threshold` | Minimum score required to allow execution            |

```bash theme={null}
# See all versions for a skill
modusbrain opskill show refund-handling

# Version history in JSON
modusbrain opskill show refund-handling --json
```

A new version is created whenever:

1. You run `modusbrain opskill compile` again (manual re-compile)
2. A conflict is resolved via `modusbrain opskill resolve` (auto re-compile)
3. Enough human corrections accumulate (see below — the correction threshold)

***

## Auto Re-Compile on Correction Threshold

The feedback loop is the most powerful part of the closed cycle. When a human records a correction, ModusBrain writes an evidence page under `skills/corrections/`. Once enough corrections accumulate for a skill (default: **2 corrections**), the system automatically triggers a re-compilation — producing a new draft version that incorporates the corrected guidance.

```bash theme={null}
# Record a correction from a human operator
modusbrain opskill correct refund-handling \
  --original "auto_approve" \
  --correction "Amounts over $400 require manager approval, not $500" \
  --by bob@company.com
```

**What happens next:**

1. An evidence page is written to `skills/corrections/<slug>-correction-<n>.md`
2. The correction count for the skill increments
3. If count reaches the threshold, `compileSkill()` is automatically called
4. A new draft version is created, incorporating all corrections as context
5. The draft waits for human approval before agents can execute it

This ensures the brain **self-corrects over time** — agents get smarter as operators provide feedback, without any manual intervention beyond recording the correction.

<Note>
  The correction threshold is configurable. The default of 2 is conservative by design — you want human review on high-stakes skills before re-compilation happens silently.
</Note>

***

## Operational Skills as the Living Company Map

Before ModusBrain, the base engine gave you a partial view of "how the company works" — you could search for policies, but there was no structured, machine-executable representation of procedures.

ModusBrain fills this gap. Every compiled skill is:

* **Linked** back to the source documents it was compiled from (provenance)
* **Versioned** so you can see how a procedure changed over time
* **Auditable** — you can see when agents executed it and what they decided
* **Correctable** — human feedback flows back into the next version

The result is a **living operational map** of how your company runs — one that agents can execute against safely, not just read.

***

## Full Architecture Map

| Phase         | Feature                          | Implementation                                           |
| :------------ | :------------------------------- | :------------------------------------------------------- |
| 1 — Compile   | Skill compilation from brain     | `src/core/operational-skills/compile.ts`                 |
| 1 — Compile   | `skill` / `procedure` page types | `modusbrain-ops.yaml` schema pack                        |
| 1 — Compile   | DB schema (migration v123)       | `operational_skills_layer` in `src/core/migrate.ts`      |
| 2 — Gate      | Confidence scoring               | `src/core/operational-skills/confidence.ts`              |
| 2 — Gate      | Approval workflow                | `modusbrain opskill approve`, `approve-token`            |
| 3 — Conflicts | Contradiction queue              | `modusbrain opskill flag-conflict`, `resolve`            |
| 4 — Audit     | Action audit trail               | `operational_skill_actions` table                        |
| 5 — Feedback  | Correction → re-compile loop     | `src/core/operational-skills/feedback.ts`                |
| MCP           | Remote agent API                 | `compile_operational_skill`, `execute_operational_skill` |