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

# MonoBrain

> Discover, classify, index, search, and synthesize AI memory and instruction sources with explicit freshness and write boundaries.

MonoBrain maps the instruction and memory sources that shape an AI workspace:
`AGENTS.md`, `CLAUDE.md`, CLI `initiate.md`/`SKILL.md`, Claude project memory,
Codex memory, and related project guidance. It builds a dedicated Monomento-
backed brain index, reports drift before reading it, and can draft a
folder-scoped `AGENTS.md` without silently applying the draft.

*Published contract: `monobrain 0.1.0`, OpenCLIs build
`2026-05-24-013543`. The OpenCLIs-managed payload, installed-state row, and
public CDN metadata agree on this release identity.*

The public binary exposes **14 canonical operational commands**, **8 root
aliases**, 6 rule-management actions, and a **12-command typed MCP surface**.
`help`, `version`, `mcp`, and `mcp-schema` are control/meta commands rather than
additional memory operations.

<Note>
  When auditing an installation, prefer the exact path in
  `openclis list --json` over `command -v monobrain`: an older copy earlier on
  `PATH` can shadow the OpenCLIs payload while reporting the same SemVer.
</Note>

## Quick Start

```bash theme={null}
openclis install monobrain

monobrain --version
monobrain scan .
monobrain analyze . --class stable -n 20
monobrain index . --project
monobrain status . --project --strict
```

## Complete Command Reference

| Command                        | What it does                                                                                   | Write and control boundary                                                                  |
| ------------------------------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `scan [path]`                  | Lists memory and instruction sources in scope.                                                 | Read-only discovery.                                                                        |
| `analyze [path]`               | Classifies source items as stable, ephemeral, or reference material.                           | `--class`, `-n`, `--target`; read-only.                                                     |
| `skills <query>`               | Returns thin skill-routing hints with source, scope, matched tokens, and corpus-aware weights. | Does not load the full skill; open its `SKILL.md` before use.                               |
| `rules show`                   | Shows the effective global/project skill-routing rule files.                                   | `--path` or `--global`; read-only.                                                          |
| `rules init`                   | Creates a routing-rules JSON file.                                                             | Explicit project/global file write.                                                         |
| `rules exclude add/remove`     | Adds or removes a skill exclusion.                                                             | CLI-only mutation; not exposed through MCP.                                                 |
| `rules penalty add/remove`     | Adds or removes a conditional score multiplier.                                                | CLI-only mutation; index selects a removal row.                                             |
| `map [path]`                   | Shows source layers and candidate `AGENTS.md` target locations.                                | Read-only.                                                                                  |
| `index [path]`                 | Indexes brain documents into the global or project brain DB.                                   | `--project` selects the scoped DB; explicit persistent write.                               |
| `search <query>`               | Searches indexed brain documents after reporting freshness.                                    | `--project`; read-only over current DB.                                                     |
| `path <query>`                 | Searches indexed brain document paths with optional containment evidence.                      | `--contains`, `--project`; read-only.                                                       |
| `claude-memory <path>`         | Resolves the best Claude project `MEMORY.md` by path trigrams and explicit evidence boosts.    | `--project`; read-only.                                                                     |
| `propose-agents [path]`        | Prints provenance-linked `AGENTS.md` draft sections.                                           | `--missing-only`, `--target`; never writes.                                                 |
| `apply <target>`               | Writes one explicitly selected proposal target.                                                | `--from <path>`; an existing target requires `--force`; CLI-only.                           |
| `status [path]`                | Reports fresh, stale, or not-initialized state and source drift.                               | `--project`; `--strict` exits nonzero for stale/uninitialized.                              |
| `audit [repo]`                 | Audits canonical and legacy component/layout ownership.                                        | Read-only.                                                                                  |
| `doctor [repo]`                | Explains the canonical/legacy layout and readiness.                                            | Read-only.                                                                                  |
| `mcp-schema`                   | Prints the CLI-to-MCP command schema generated from the shared command table.                  | Machine-readable.                                                                           |
| `mcp`                          | Runs the stdio MCP server.                                                                     | MCP re-runs read/index CLI commands with `--json`; `apply` and rule mutations are excluded. |
| `help` / `--help` / `-h`       | Prints the installed guide.                                                                    | Read-only.                                                                                  |
| `version` / `--version` / `-V` | Prints the executing version; combines with `--json`.                                          | Read-only.                                                                                  |

All normal commands accept `--json`. Text output includes a `[NEXT]` hint;
JSON includes `next_hint.reason` and `next_hint.commands`.

### Root aliases

| Canonical command | Accepted alias          |
| ----------------- | ----------------------- |
| `skills`          | `skill-hints`           |
| `rules`           | `routing-rules`         |
| `path`            | `path-search`           |
| `claude-memory`   | `resolve-claude-memory` |
| `propose-agents`  | `propose`               |
| `status`          | `freshness`             |
| `audit`           | `self-audit`            |
| `mcp`             | `serve`                 |

`--mcp-schema` is also accepted as a spelling of `mcp-schema`. The installed
`0.1.0` payload does **not** expose a `docs` command; use `monobrain help` for
the embedded guide. A source checkout can be ahead of that published surface,
so source-only dispatch arms are not release proof.

## Freshness Is Explicit

```text theme={null}
discover current source set + mtimes
                ↓ compare
brain DB state = fresh | stale | not-initialized
                ↓
read only after reporting state
                ↓
explicit `index` to refresh; never implicit
```

The dedicated databases are:

```text theme={null}
~/.monolex/monobrain.db
~/.monolex/monobrain/<target>-<hash>.db   # --project
```

They are separate from general [Monomento](/ai-clis/monomento) indexes. Running
`monomento index --project` does not refresh MonoBrain.

`status --strict` turns `stale` and `not-initialized` into non-zero automation
gates. Search, path lookup, and Claude-memory resolution report freshness but
never reindex implicitly; run `monobrain index . --project` explicitly.

## Typed MCP Boundary

```text theme={null}
scan · analyze · map · skills · index · search
path · claude-memory · propose-agents · status · audit · doctor
```

The schema contains 12 commands. `index` is the one persistent writer in that
surface. `rules`, `apply`, raw server/meta commands, and their aliases are
excluded, so an MCP client cannot rewrite routing rules or an `AGENTS.md`
target through this server.

## Memory and Instruction Boundaries

* User memories remain searchable evidence and are not default write candidates
  for `AGENTS.md`.
* `propose-agents` is always read-only; only `apply` writes.
* Claude project-memory resolution compares cwd, repository root, ancestors,
  encoded Claude keys, and git remote aliases. The index keeps both encoded
  `source_path` and original `logical_path`; it does not guess paths by replacing
  hyphens with slashes.
* `skills` is routing assistance, not skill instruction execution.
* The old MonoTerm PTY companion is `monobrain-bridge`; the legacy MCP
  experiment is separate and intentionally not the `monobrain` binary.

## Release Platforms

The `0.1.0` release metadata publishes five platform artifacts:

| Platform key     | Binary          |
| ---------------- | --------------- |
| `darwin-aarch64` | `monobrain`     |
| `darwin-x86_64`  | `monobrain`     |
| `linux-aarch64`  | `monobrain`     |
| `linux-x86_64`   | `monobrain`     |
| `windows-x86_64` | `monobrain.exe` |

There is no `windows-aarch64` artifact in this release.

## Relationships

| Tool                            | Ownership                                                            |
| ------------------------------- | -------------------------------------------------------------------- |
| [Monomento](/ai-clis/monomento) | Shared document retrieval kernel; MonoBrain keeps its own scoped DBs |
| [NIIA](/ai-clis/niia)           | Work-entry and unified research/session context around memory use    |
| [Work Wiki](/ai-clis/work-wiki) | Work evidence and project history, not instruction synthesis         |