> ## 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. # Agent to ModusBrain > Route agent queries through ModusBrain for grounded answers. # How a downstream agent should talk to modusbrain This guide is for authors of downstream agents (hermes, openclaw, future forks) that need to call modusbrain operations from their own runtime. Reading this first will save you a debugging cycle: modusbrain has **two distinct surfaces**, and which one you pick depends on the operation. ## The two surfaces ``` ┌─────────────────────────────────────────────┐ │ modusbrain process │ │ │ Agent (hermes, │ ┌──────────────────┐ ┌────────────────┐ │ openclaw, fork) ────┼──▶ MCP ops surface │ │ localOnly │ │ │ │ (HTTP + OAuth) │ │ admin ops │ │ │ │ │ │ │ │ │ │ search, query, │ │ sync, embed, │ │ │ │ put_page, │ │ dream, doctor,│ │ │ │ get_page, │ │ autopilot, │ │ │ │ find_experts, │ │ init, secrets │ │ │ │ ... │ │ │ │ │ └──────────────────┘ └────────────────┘ │ │ ▲ ▲ │ │ │ │ │ │ │ │ │ │ thin-client OAuth shell-job `inherit:`│ │ (preferred for (only path for │ │ MCP-equivalent ops) localOnly ops) │ └─────────────────────────────────────────────┘ ``` The two surfaces are **not interchangeable**. Pick by op, not by preference. ## Surface 1 — MCP ops over HTTP (thin-client + OAuth) Use for any operation that has an MCP equivalent: `search`, `query`, `put_page`, `get_page`, `find_experts`, `find_orphans`, `find_anomalies`, `get_recent_salience`, `find_trajectory`, and so on. The canonical list is the set of ops in `src/core/operations.ts` whose `localOnly` flag is unset (or `false`). ### Setup The host runs modusbrain as a long-lived HTTP server: ```bash theme={null} MODUSBRAIN_ALLOW_SHELL_JOBS=1 modusbrain serve --http --port 3131 ``` The agent registers as an OAuth client (one-time): ```bash theme={null} modusbrain auth register-client hermes \ --grant-types client_credentials \ --scopes read,write # Prints client_id + client_secret one-time. Store securely. ``` The agent's runtime calls `/mcp` with a bearer token from `client_credentials` grant. Secrets stay in the modusbrain serve process; the agent never sees DATABASE\_URL or API keys. Thin-client mode (`modusbrain init --mcp-only`) gives the agent the same client-credentials wiring, plus the `modusbrain` CLI itself routes MCP-eligible commands through the configured remote MCP. The agent can call `modusbrain search` / `modusbrain query` directly and the CLI does the OAuth dance. ### Why this is preferred for MCP ops * Secrets never leave the server process. * OAuth scopes give you `read`, `write`, `admin` separation — agent only gets what it needs. * Source-scoped tokens (`--source dept-x` on `register-client`) confine the agent to a specific source within a federated brain. * One audit surface (`mcp_request_log`) covers every op call uniformly. ## Surface 2 — localOnly admin ops via shell-job `inherit:` Some operations are flagged `localOnly: true` in `src/core/operations.ts` and are **refused** in thin-client mode at `src/cli.ts:isThinClient`. The full list (as of v0.36.5.0) includes: * `sync` (filesystem walks need local FS access) * `embed` (orchestrates the embed pipeline) * `extract` (walks markdown files) * `dream` (synthesis cycle) * `doctor` (filesystem hygiene checks) * `autopilot` (background daemon orchestration) * `init` (creates `~/.modusbrain/`) * `secrets` (config management) For these, the agent cannot route through HTTP MCP. The only path is to run `modusbrain` as a CLI subprocess. The recommended pattern is to submit the subprocess as a shell job to the modusbrain Minions worker so retry / backoff / DLQ / audit trail all come for free. ### Setup ```bash theme={null} modusbrain jobs submit shell --params '{ "cmd": "modusbrain sync --skip-failed && modusbrain embed --stale", "cwd": "/data/modusbrain", "inherit": ["database_url"] }' ``` The `inherit: ["database_url"]` field tells the worker to look up `database_url` from its `loadConfig()` and inject the value into the child env as `MODUSBRAIN_DATABASE_URL`. The DB row in `minion_jobs.data` carries the names only — `inherit: ["database_url"]` — never the value. See [minions-shell-jobs.md#secrets](./minions-shell-jobs.md#secrets) for the full validation rules and error catalog. ### Why this is preferred over writing secrets into `env:` per-job * Pre-v0.36.5.0 callers passed `env: { MODUSBRAIN_DATABASE_URL: "postgresql://..." }` per job. The URL landed plaintext in `minion_jobs.data` and the shell-audit JSONL. Anyone with brain-DB read access (or a brain dump, or a shared brain via mounts) saw the URL. As of v0.36.5.0, this is rejected at pre-enqueue validation. The error message names `inherit: ["database_url"]` as the replacement. ### Worker setup (one-time, per host) The agent's host needs a worker that processes shell jobs: ```bash theme={null} # One-shot inline execution (PGLite or Postgres): modusbrain jobs submit shell --params '{...}' --follow # Persistent worker (Postgres only — PGLite uses --follow inline): MODUSBRAIN_ALLOW_SHELL_JOBS=1 modusbrain jobs work ``` `MODUSBRAIN_ALLOW_SHELL_JOBS=1` is the worker-side opt-in. Without it, shell jobs sit in `waiting` indefinitely. Set it on the worker process env (or in your deploy unit / launchd plist), not per-submission — submitter env is a weak proxy for worker env. ## Decision table | Operation | Surface | Why | | ------------------------------- | ----------------------------------------------- | --------------------------------------------------- | | `search` / `query` | HTTP MCP via thin-client | Has MCP op; OAuth-scoped. | | `get_page` / `list_pages` | HTTP MCP | Same. | | `put_page` | HTTP MCP | Same; respects subagent allow-list when applicable. | | `find_experts` / `find_orphans` | HTTP MCP | Same. | | `sync` / `embed` / `extract` | Shell job + `inherit:` | `localOnly: true`. | | `dream` | Shell job + `inherit:` | `localOnly: true`. | | `doctor` | Shell job + `inherit:` (or no inherit if no DB) | `localOnly: true`. | | `autopilot` | Run as a daemon directly on the host | Long-lived, not job-shaped. | | `init` / `secrets` | One-time host setup | Operator action, not agent action. | ## Recommended patterns * **Prefer `inherit:` for secrets you don't want in the row.** Names land in `minion_jobs.data`; values resolve at child-spawn from the worker's config. If a brain DB ever traverses a trust boundary, secrets stay out. * **Free-form names.** `inherit:` accepts any snake\_case config-key on your worker — `database_url`, `anthropic_api_key`, `openai_api_key`, `voyage_api_key`, `groq_api_key`, `zeroentropy_api_key`, or any custom field you stuff into `~/.modusbrain/config.json`. The agent picks what it needs. * **`env:` still works** for non-secret values, or for cases where you WANT the value in the row (e.g. an opaque correlation token your audit flow needs to read back later). The validator doesn't second-guess you. * **Never try to route a `localOnly` op through thin-client MCP.** It will fail with `localOnly op refused in thin-client mode`. Use shell-job + `inherit:` (for secrets) or `env:` (for non-secrets). ## Migration: from pre-v0.36.5.0 If your agent submits shell jobs that pass secrets via `env:`: ```jsonc theme={null} // Pre-v0.36.5.0: works but URL persists in minion_jobs.data plaintext. { "cmd": "modusbrain sync --skip-failed", "cwd": "/data/modusbrain", "env": { "MODUSBRAIN_DATABASE_URL": "postgresql://..." } } ``` Switch to (recommended): ```jsonc theme={null} // v0.36.5.0+: name in row, value resolved at child-spawn from worker config. { "cmd": "modusbrain sync --skip-failed", "cwd": "/data/modusbrain", "inherit": ["database_url"] } ``` Make sure the worker host has `database_url` configured (either via `modusbrain config set database_url ` or via `MODUSBRAIN_DATABASE_URL` / `DATABASE_URL` env on the worker process). If the worker can't resolve the key, the validator rejects the job at submit time with a paste-ready hint.