Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* Help text for `o2b brain` and each of its verbs.
*
* Pure data plus imported constants. The release the sidecar manifest
* shipped in used to be a literal here, a second literal in the rollback
* warning and a third in the operating manual, so it is imported from the
* module that owns the format rather than re-typed. The recall-telemetry
* filter vocabularies are here for the same reason and a sharper one: the
* mode list was spelled out in prose in four places, and when `query` was
* added to the vocabulary all four kept advertising three modes - one of
* them a JSON schema enum, which rejected a mode the system was already
* recording. A hand-typed list of a closed set is a word list that goes
* stale silently, so every surface renders the set instead.
* Split out of `./helpers.ts` so the verb-handler bundle does not
* have to load this ~200-line string table when it only needs
* `parse` / `resolveBrainVault`.
*/
import { BRAIN_MANIFEST_SIDECAR_SINCE_VERSION } from "../../core/brain/manifest.ts";
import { HYGIENE_DETECTOR_IDS } from "../../core/brain/hygiene/types.ts";
import {
RECALL_CHANNELS,
RECALL_TELEMETRY_MODES,
RECALL_TELEMETRY_STATUSES,
} from "../../core/brain/recall-telemetry.ts";
/** `search|context_pack|pre_compress|query`, rendered from the closed set. */
const RECALL_MODE_CHOICES = RECALL_TELEMETRY_MODES.join("|");
const RECALL_STATUS_CHOICES = RECALL_TELEMETRY_STATUSES.join("|");
const RECALL_CHANNEL_CHOICES = RECALL_CHANNELS.join("|");
/**
* `o2b brain maintenance` usage line, defined once: the verb prints it on
* a usage error and its `--help` text below opens with it.
*/
export const MAINTENANCE_USAGE =
"usage: o2b brain maintenance run [--force] [--retry <task|custom:name>] [--window H-H] [--tz ZONE] " +
"[--busy-minutes N] [--busy-threshold N] [--force-cost] [--relink-apply] [--progress] " +
"| run --cron-template [--interval N] [--format cron|systemd] [--window H-H --tz ZONE] " +
"| status [--limit N] [--vault <path>] [--json]";
export const BRAIN_HELP = `usage: o2b brain <verb> [args...]
Brain verbs (observing memory):
init Bootstrap <vault>/Brain/ (idempotent; --force overwrites)
feedback Record a taste signal (--topic, --signal, --principle)
dream Deterministic dreaming pass; stage/validate/apply/retriage bundles
apply-evidence Log a real-work application of a preference
note Append a one-line narrative milestone to today's brain log
lifecycle Tombstone/supersede a memory, correct one record, resolve chain tips, curator slices
expire Set, change or clear a signal's or preference's expiration date
note-lifecycle Note FILES or FOLDERS: rename/move/archive/delete a file, move/rename a folder, rewriting inbound links
scaffold-stub Unresolved wikilink targets: list them, or materialise a stub
claims Claim-graph query: current truth, truth-at-T, replaced-by, contested-by
decision Decisions: record/outcome/show/list/similar + open questions: open/list_open/show_open/resolve/discard
tension Detect + triage persisted contradictions: detect/list/show/confirm/dismiss/resolve
digest Render the recent-changes digest (markdown or --json)
intent-review Read-only pre-dream review of active signal clusters
retention Recommendation-only keep/improve/park/prune review
monthly Monthly synthesis over Brain timeline activity
query Read by --preference, --topic, or --since
agent-query Read Brain provenance by source agent (--agent; --json)
agent-diff Compare source-agent coverage (browse/search/diff/map)
writes Recorded note writes: list (default), destinations, revert, prune-images
reject Move a preference to retired (user-rejected); --yes if pinned
freeze Stop every content write on every device (--reason <text>)
unfreeze Lift the freeze and reopen the content lane
log Inspect Brain/log itself: verify (per-shard hash chain)
attest Ed25519-signed store attestations: keygen, sign, list, verify
pin Mark a preference exempt from automatic retire (idempotent)
unpin Clear the pinned flag (idempotent)
state Overwrite-only exact-state lane (set/get/list/clear --aspect)
set-primary Declare or clear primary_agent in the brain settings (--clear)
settings Shared brain settings: get, set, unset, list (<block>.<field>)
migrate-store Move the legacy brain into the brain store
(--dry-run | --resume | --rollback | --remove-legacy [--force]
| --force-release-gate)
protect Emit / apply native deny rules for Brain/ (--target {claudecode|codex} [--apply --yes])
unprotect Remove OSB-managed deny rules (preview; --apply writes, --yes consents) (--target {claudecode|codex})
permissions Show the trust policy document and query the decision ledger (show | ledger)
merge Merge two near-duplicate preferences (<keep> <drop>; --dry-run, --force)
upgrade Migrate release-owned files forward (--dry-run by default; --apply --yes)
export Dump preferences or a transcript dataset
(--format json|llms-txt|transcripts-jsonl [--out <path>])
okf-export Write a portable Open Knowledge Format bundle (--out <dir> [--force])
okf-import Import an OKF bundle (<dir>; staged as review candidates, --trusted writes direct)
knowledge-pack Portable knowledge subsets: export (--select), preview, install, uninstall, list
explorer Launch the loopback HTML explorer; --export <path> writes a single offline file
snapshot Inspect recovery points: log (newest-first, --reason filter),
diff (two snapshots, or a snapshot vs live)
rollback Restore Brain/ from a snapshot (--list or <run_id>; --yes;
--dry-run previews via the same diff renderer)
doctor Validate Brain invariants (--strict; --remediate/--repair [--apply --yes])
status Unified operator status snapshot with next-command hints
hygiene Hygiene pipeline: scan findings; apply by ids (--dry-run)
refresh Targeted recompile of stale derived pages (--stale [--dry-run])
anticipate Inspect or refresh the anticipatory context cache (--session)
watchdog Probe Brain health and plan safe recovery (--remediate, --restore, --force-restore)
health Semantic-health report: contradictions, concept gaps, stale claims
health-baseline Acknowledge-before watermark for advisories (set <date>|now / get / clear)
history Render a preference's edit-history timeline
activation Activation event store: status and sweep
truth Claim ledger: ingest, slots, conflicts, aggregate, collisions, events, state, sweep
facts Decompose text into atomic assertions (--ingest to ledger)
dead-end Negative-knowledge registry: record and list failed approaches
foresight Forward projection: routines coming due, open commitments and questions
label Controlled-vocabulary classification: assign, remove, show note labels
bridges Embedding-near link proposals: discover, list, accept, dismiss
clusters Link-graph communities: detect and materialize cluster notes
vitals Aggregate governance scorecard: diversity, connectivity, gap pressure
co-occurrence Suggest edges between entities co-referenced from the same notes
hallways Session-mined associations: mine, show, promote, dismiss
file-context Surface prior vault work that mentions a file path
benchmark Recall quality benchmark: hit@k and MRR over a fixed dataset
tune Self-tuning recall: grid-evaluate, persist, inspect, reset
attr Typed-page attribute fields: assign, remove, show (schema-pack declared)
tiers Frontmatter tier guard: check identity-field drift, restore or accept
secret Capability-gated secret custody: set, list, rm, run, lock, unlock, export, import (use w/o exposure)
maintenance Quiet-window, lease-guarded lane (dream, reindex, bridges, clusters, custom tasks)
audit Render a preference's full mutation audit trail
morning-brief Session-start summary: top prefs, open questions, recent notes
codec Compress/expand session prose with the deterministic codec (stdin/--in)
sources Read-only dashboard of signals by (agent, source_type)
schema Inspect resolved schema vocabulary and artifact token usage
graph-export Serialise the vault knowledge graph to graph.json
graph-import Reconstruct vault pages from graph.json (--mode skip|overwrite|merge)
bank-export Serialise a whole-vault bank bundle (prefs + graph + pages + sources)
bank-import Reconstruct the page graph + preferences from a bank bundle (--mode skip|overwrite|merge)
backlinks List inbound references to a Brain artifact id
semantics-backfill Preview deterministic typed preference-edge backfill proposals
authored-at-backfill Backfill authored_at on session signals (dry-run default; --apply to write)
privacy-marker-restamp Formalize informal privacy markers (dry-run default; --apply to write)
mcp-landscape List MCP servers configured across the vault (packages, env names)
scan-inline Capture @osb markers from folders listed under the notes.read_paths brain setting
scan-citations Promote inline [Source: <name>, YYYY-MM-DD] markers to dated provenance events
import-session Replay signals from a registered agent session .jsonl (or directory)
entity Canonical entity registry: set, get, list, relate, archive, prune, lexicon, merge
session-hook Capture one runtime hook payload from stdin (internal hook bridge)
import-claude-memory Import metadata.type:feedback MEMORY entries as confirmed preferences
page-dedup Detect (and optionally merge) near-duplicate vault pages
token-footprint Report per-category vault token size with a warn threshold
context-pack Return a tier-then-recency vault slice under a token budget
context-receipts List/show/verify prompt context receipt records
event-trace Show context traces attached to logged events by correlation id
context-presets Show/suggest/diff read-only context budget presets
pre-compact-extract Extract typed continuity records from bounded text
post-compact-audit Audit pinned-anchor survival after a compaction; re-assert drifted anchors
recall-telemetry List/summarize opt-in recall telemetry records
knowledge-gaps Rank recurring queries the vault answers poorly (unmet demand)
generation-reports Record/list/summarize opt-in LLM generation traces
skill-proposals Learn/list/review skill proposals, from telemetry and from mature vault pages
procedural-memory Reconcile/list procedural memory index and usage
procedural-graph Rebuild/show procedural graph and hint projections
recurrence Inspect and update recurrence/support diagnostics
attention-flows Declarative attention recipes for open loops and learnings
obligation Recurring obligations with cadence-driven next-due dates
agenda Synthesize agenda conflicts/focus blocks from provided events
today Today dashboard: due obligations, open loops, recent activity, totals
apply-markers Apply @osb set frontmatter write-backs (report by default; --apply writes)
pending Review the write-approval queues (signals/notes/ingest): list | apply <id> | reject <id>
lessons Operator-approved lesson promotion: candidates | approve <id> | deny <id> | refresh-blocks
signal Fact signal lifecycle: retire <id> --reason <text>
capture Stage one capture from the terminal: body, source, sender, guidance
telegram-capture Inbound Telegram capture bot: run (long-poll) | catchup
inbox-drain Classify and route staged captures (dry-run; --apply to route)
repair-lane Propose memory-graph edges (dry-run; --apply --confirm to write, holdout-gated)
orphan-repair Detach dangling session references from observations (dry-run; --apply --confirm)
session-grep Search session recall turns/summaries; --operation coverage
selects whole-thread coverage under --char-budget
session-describe Describe an imported session recall DAG (--topics renders
the adaptive topic-budget report)
session-expand Expand a session recall node to source turns
lint Self-healing structural checks (--consolidate); --apply to write
validate Validation gate over --paths or --dirty notes; errors exit 1, --strict warnings exit 2
actions Ranked maintenance action list (dedup + lint + footprint)
summary Operator dashboard: trust verdict, doctor/dream counts, actions
unlinked Raw-text mentions of an artifact's title/aliases outside [[...]]
synthesise Concept cluster: target + linkers (depth-1), optionally + mentions
moc-audit Per-MOC coverage audit (well-covered/fragile/candidate-missing)
timeline Chronological event list filtered by pref-id/topic/kind/since/until
evolution Per-pref or per-topic story: status transitions + evidence + retire
stale Stale preferences/signals/log files (configurable thresholds)
daily Daily brief: events by kind, status transitions, vault delta
weekly 7-day synthesis: transitions, retired, contradictions, vault delta
project Link project directories to their owning vault (link/list/remove/status)
source Read-only recall sources of the active vault (add/list/remove)
forget-source Find/delete entries derived from an exact source file (dry-run by default)
links Normalize wikilink path format (preserve/full/short); dry-run by default
profile Materialize Brain/profile.md digest + .o2bfs root marker (age-gated)
sgrep Grep-shaped semantic search: o2b brain sgrep <query> [path]
trigger Proactive trigger queue with anti-nag lifecycle (scan/list/ack/dismiss/act/suppress/unsuppress/snooze/unsnooze/history)
deep-synthesis Topic dossier: notes, agreements, contradictions, stale claims, gaps
diarize Subject profile: document set, stated-vs-evidenced gap, needs-llm-step skeleton
extract-signals Mine taste signals from an imported session's user turns (two-phase, needs-llm-step)
dead-letters Dead extraction writes: list (default) | show <id> | recover <id> (dry-run; --apply --yes to write)
design-note One-shot design note grounded in tensions, decisions and truth records
ideas Ranked next-direction candidates from open loops (--triggers to enqueue)
continuity Export ATOF/ATIF trajectories, rank records by usage decay, promote host memory writes (export and rank are read-only; promote is dry-run by default)
payload Externalized session payloads: get (paged), list, gc (dry-run by default)
bench Memory quality benchmark over a disposable fixture vault
git Git history as project memory: ingest, status, find, mine
architect Deterministic architecture notes for a code project
session Agent write sessions: open, submit, approve, abandon, status, list, sweep
panel Multi-persona decision panel riding the write-session kernel
Common flags:
--vault <path> Override the configured vault
--json Structured output where applicable
--help Per-verb help (run \`o2b brain <verb> --help\`)
`;
/**
* `brain secret` per-op flag tables and the usage line assembled from
* them. One source, two surfaces: the USAGE the verb prints on a usage
* error and the line `o2b brain secret --help` shows are both built here,
* so they cannot drift apart - and an op that never documents a flag
* refuses it by name (via {@link secretOpAccepts}) instead of silently
* swallowing it while the flag's effect never happens.
*/
const SECRET_OP_FLAGS: Record<string, ReadonlyArray<string>> = {
set: ["env-var", "allow", "from-env", "passphrase-from-env", "agent"],
list: [],
rm: ["passphrase-from-env"],
run: ["passphrase-from-env", "agent"],
lock: [],
unlock: ["passphrase-from-env"],
unwrap: ["passphrase-from-env"],
export: ["out", "passphrase-from-env"],
import: ["replace", "passphrase-from-env"],
};
/** The usage spelling of every flag, keyed by its parsed name. */
const SECRET_FLAG_USAGE: Record<string, string> = {
"env-var": "[--env-var V]",
allow: "[--allow PATTERN]...",
"from-env": "[--from-env SRC]",
agent: "[--agent N]",
"passphrase-from-env": "[--passphrase-from-env SRC]",
out: "--out FILE",
replace: "[--replace]",
vault: "[--vault <path>]",
json: "[--json]",
};
/** Every op answers `--vault` and `--json`; the rest are per-op. */
const SECRET_COMMON_FLAGS: ReadonlyArray<string> = ["vault", "json"];
/** Whether `op` documents `flag` - the parse-time acceptance contract. */
export function secretOpAccepts(op: string, flag: string): boolean {
return SECRET_COMMON_FLAGS.includes(flag) || (SECRET_OP_FLAGS[op] ?? []).includes(flag);
}
function secretOpUsage(op: string, lead: string, tail = ""): string {
const flags = [...(SECRET_OP_FLAGS[op] ?? []), ...SECRET_COMMON_FLAGS]
.map((flag) => SECRET_FLAG_USAGE[flag])
.join(" ");
return `${lead} ${flags}${tail}`;
}
export const SECRET_VERB_USAGE =
"usage: o2b brain secret " +
[
secretOpUsage("set", "set <name>"),
secretOpUsage("list", "list"),
secretOpUsage("rm", "rm <name>"),
secretOpUsage("lock", "lock"),
secretOpUsage("unlock", "unlock"),
secretOpUsage("unwrap", "unwrap"),
secretOpUsage("export", "export"),
secretOpUsage("import", "import FILE"),
secretOpUsage("run", "run <name>", " -- <command...>"),
].join(" | ");
export const VERB_HELP: Record<string, string> = {
"forget-source":
"usage: o2b brain forget-source <source> [--confirm] [--include-originals] [--vault <path>] [--json]\n" +
"Find and delete every Brain entry derived from an EXACT source file. Dry-run by\n" +
"default: reports the blast radius and deletes nothing. --confirm deletes the\n" +
"single-purpose derived entries + ingest index artifacts (summary page + manifest\n" +
"entry); shared/aggregate pages are reported, never deleted. --include-originals\n" +
"also removes the original source file outside Brain/. Confirmed runs write an\n" +
"auditable source_invalidation continuity record.\n",
init:
"usage: o2b brain init [--vault <path>] [--force] [--primary-agent <name>] [--json]\n" +
"Bootstrap <vault>/Brain/. Requires `o2b init` to have run first.\n" +
"--primary-agent <name> writes the value into _brain.yaml on first init;\n" +
"on re-run against an existing _brain.yaml use `o2b brain set-primary` instead.\n",
feedback:
"usage: o2b brain feedback --topic <slug> --signal positive|negative --principle <text>\n" +
" [--scope <slug>] [--source <wikilink>...] [--agent <name>] [--raw <text>|--raw-file <path>]\n" +
" [--force-confirmed] [--vault <path>] [--json]\n" +
"Creates a `sig-*.md` in Brain/inbox/. With --force-confirmed also creates a `pref-*.md`.\n",
dream:
"usage: o2b brain dream [run] [--dry-run] | stage | validate <run-id> | apply <run-id> |\n" +
" retriage <run-id> | discard <run-id> | list [--now <ISO-8601>] [--agent <name>]\n" +
" [--vault <path>] [--json]\n" +
"Runs the deterministic dreaming algorithm (idempotent), or manages the staged\n" +
"lifecycle: stage persists a reviewable proposal bundle under Brain/dream/staged/,\n" +
"validate proves the vault has not drifted, apply re-validates then runs the same\n" +
"engine live, discard drops the bundle. retriage re-runs the salience gate\n" +
"(dream.salience_threshold) against the bundle and names the facts that would move\n" +
"into or out of the rollup fold set; it changes nothing, so re-stage to adopt it.\n",
"apply-evidence":
"usage: o2b brain apply-evidence --pref <id> --artifact <wikilink> --result applied|violated|outdated\n" +
" [--agent <name>] [--note <text>] [--vault <path>] [--json]\n" +
"Appends a single event to today's log. Missing preference exits 2.\n",
note:
"usage: o2b brain note <text> [--agent <name>] [--vault <path>] [--config <path>] [--json]\n" +
"Append one narrative-milestone line to today's brain log under the `note`\n" +
"event kind: a log record in the brain store once this machine is switched,\n" +
"Brain/log/<today>.md before. Works with no vault on a store-only machine.\n" +
"CLI mirror of the MCP `brain_note` tool, same contract.\n" +
"Use from cron jobs and shell scripts. Multi-line text collapses to one line.\n",
lifecycle:
"usage: o2b brain lifecycle <tombstone|supersede|temporal-replace|tip|curator|correct> [...] [--vault <path>] [--json]\n" +
"Cross-type tombstone + supersede + correct lifecycle. tombstone <path> --reason <r>\n" +
"[--superseded-by <id>] marks a memory _status: tombstoned in place (no delete);\n" +
"supersede <predecessor> <successor> tombstones the predecessor and records the\n" +
"replacement pointer; temporal-replace <predecessor> <successor> --at <T> closes the\n" +
"predecessor (valid_until = T) and opens the successor (valid_from = T) at one shared\n" +
"instant; tip <id> walks a supersede chain to its live tip; curator\n" +
"[--high-use-min <n>] lists injected-never-used, contradicted, and high-used\n" +
"memories from observed-use verdicts; correct <target> [--value <v>]\n" +
"[--successor <id>] [--flatly-wrong] [--window-end <T>] [--reason <r>] sweeps one\n" +
"record's correction - blast-radius report by default, --apply retires the target\n" +
"(validity close, or tombstone when --flatly-wrong), retargets mentions, appends\n" +
"ledger correction events and bundle-correlated receipts. Tombstoned entries stay\n" +
"on disk for audit but are excluded from recall, inject, and active.md.\n",
expire:
"usage: o2b brain expire <id> --expires <YYYY-MM-DD|ISO-8601|none>\n" +
" [--agent <name>] [--vault <path>] [--json]\n" +
"Set, change or clear the expiration_date of one signal or preference,\n" +
"addressed by id (sig-<date>-<slug>, pref-<slug> or ret-<slug>). An expired\n" +
"memory is FILTERED on read, never deleted or moved - `o2b brain query\n" +
"--show-expired` still shows it. --expires none clears the date; it is a word\n" +
"rather than an empty string so a broken shell expansion cannot un-expire a\n" +
"memory. An unparseable date, or an id naming no artifact, exits 2 by name.\n" +
"Create-time expirations come from `o2b brain feedback --expires` instead.\n",
"note-lifecycle":
"usage: o2b brain note-lifecycle <rename|move|archive|delete|move-folder|rename-folder> <path> [<to>]\n" +
" [--apply] [--confirm] [--delete-linked] [--expect <n>] [--strict] [--vault <path>]\n" +
" [--config <path>] [--json]\n" +
"Note FILES, not memories: rename changes the filename in place, move changes the\n" +
"directory, archive displaces the note under Archive/ mirroring its path, delete\n" +
"removes it. Dry run by default - it walks, counts and writes nothing. --apply\n" +
"performs it; delete additionally requires --confirm, because no archive covers a\n" +
"note outside Brain/. --expect <n> asserts the count before any write and --strict\n" +
"refuses a mutation carrying no such guard.\n" +
"--delete-linked (delete only) widens the removal to the Brain files that DECLARE\n" +
"the note as their provenance and trace SOLELY to it - a per-item summary, signal,\n" +
"preference or entity page whose frontmatter names it and whose whole content\n" +
"restates it. A page that merely mentions the note in prose is reported and kept,\n" +
"as is a page citing a second source, as is every user note; the receipt prints\n" +
"the deletion set and the reported set separately, names the scope it scanned,\n" +
"and --expect then counts the deletion set.\n" +
"The folder actions move a WHOLE folder: move-folder relocates it under a\n" +
"destination parent, rename-folder renames it within its parent - the same\n" +
"rename/move split as the file actions, so a caller that meant one and spells\n" +
"the other is refused wrong_action rather than moved by accident. Every\n" +
"destination is checked free before the first rename, so an occupied destination\n" +
"refuses with nothing moved and the source untouched; the move set's inbound\n" +
"path-spelled links are rewritten in one pass over the successfully moved set,\n" +
"and a mid-set failure is named per file (the move_failures response keys, with\n" +
"left_behind naming what stayed in the source) with no rollback.\n" +
"Inbound [[wikilinks]] are rewritten across the vault, minus what vault scope\n" +
"excludes, minus code fences, and minus Brain/log, which is append-only. The\n" +
"receipt names how stale the search index now is and the command that fixes it.\n" +
"Distinct from `o2b brain lifecycle`, which annotates a memory and moves no bytes.\n",
"privacy-marker-restamp":
"usage: o2b brain privacy-marker-restamp [--apply] [--vault <path>] [--json]\n" +
"Make an informal privacy marker formal. A page that declares its audience only\n" +
"through an informal marker (access / confidentiality / sensitivity) is a\n" +
"candidate; dry-run is the default and writes nothing. --apply unions the\n" +
"reserved visibility token (`private`) into each candidate's `visibility:`.\n" +
"A page whose frontmatter cannot be rewritten losslessly is refused by name\n" +
"(reported in `skipped` with the reason) and left untouched. Additive and\n" +
"idempotent: no key is removed, no declared token is dropped, and a re-run\n" +
"writes nothing; it never removes a token.\n",
"scaffold-stub":
"usage: o2b brain scaffold-stub list [--limit <n>] [--vault <path>] [--json]\n" +
" or: o2b brain scaffold-stub write <target> [--path <rel>] [--source <rel>]...\n" +
" [--if-exists <refuse|skip>] [--apply] [--vault <path>] [--config <path>] [--json]\n" +
"list reads the vault's unresolved wikilink targets from the search index, and\n" +
"refuses with a state and a next command when that index is missing or only\n" +
"partly resolved rather than reporting zero. write materialises a stub for one\n" +
"target, its body linking back to the --source documents that referenced it.\n" +
"Dry run by default; --apply writes.\n",
claims:
"usage: o2b brain claims [--at <instant>] [--history] [--replaced <id>] [--contests <id>] [--rebuild] [--vault <path>] [--json]\n" +
"Query the claim-graph projection over existing superseded_by / contradicts /\n" +
"valid_from / valid_until relations. Default is current truth; --at <ISO|YYYY-MM-DD>\n" +
"gives truth at that instant; --history lists every claim (tombstoned included);\n" +
"--replaced <id> follows the supersede chain to the live tip; --contests <id>\n" +
"lists contesting claims; --rebuild rebuilds and persists Brain/claim-graph.json.\n" +
"The write-time lint reports a count or amount written with no date as the\n" +
"advisory `undated-quantity` finding; it is silenced by valid_from in\n" +
"frontmatter, any ISO date in the body, or a [Source: <name>, YYYY-MM-DD]\n" +
"marker, and --at / --history are how such a claim is placed in time.\n",
decision:
"usage: o2b brain decision <record|outcome|rate|show|list|compare|similar|history|recall|open|list_open|show_open|resolve|discard> [...] [--vault <path>] [--json]\n" +
"Decision-record note family under Brain/decisions/. record --title <t> --chosen <c>\n" +
"--assumption <a> --review-date <YYYY-MM-DD> [--premortem <p>] [--notes <n>]\n" +
"[--rating <1-5>] [--rationale <r>] captures a type: decision note and opens one review\n" +
"obligation idempotently; outcome <slug> --outcome <text> backfills the hindsight\n" +
"outcome; rate <slug> --rating <1-5> [--rationale <r>] sets a rating (logged); show\n" +
"<slug> and list [--rated] read stored decisions (--rated sorts by rating); compare\n" +
"<slug...> reads decisions side by side; similar --title <t> [--chosen <c>] surfaces\n" +
"historically similar decisions with their recorded outcomes; history [--subject <id>]\n" +
"[--cursor <c>] [--limit <n>] pages decision-change receipts (before/after, confidence\n" +
"delta, reason code) appended alongside the truth ledger; recall --prompt <text>\n" +
"[--turn <n>] [--count <n>] [--last-turn <n>] [--surfaced-ids <id> ...]\n" +
"deterministically resurfaces a rated decision matching the prompt when\n" +
"decision_recall.max_per_session is configured (byte-identical when unset); the\n" +
"count/last-turn/surfaced-ids flags thread the per-session cap and spacing state.\n" +
"Open decisions (parked questions with enumerated options) live beside them as\n" +
"open-<slug>.md: open --title <t> --question <q> --option <o> [--option <o>...]\n" +
"[--context <c>] parks one (a duplicate question refuses, naming the existing id);\n" +
"a title with no ASCII letters or digits hashes to an unnamed-<hash> id (the slug\n" +
"grammar is ASCII); list_open [--status open|resolved|discarded] lists them\n" +
"(unreadable records named); show_open <id> reads one; resolve <id> --choice <c>\n" +
"[--rationale <r>] mints the real type: decision page and stamps the pointer;\n" +
"discard <id> --reason <r> closes the question without deciding. Terminal records\n" +
"stay in place.\n",
tension:
"usage: o2b brain tension <detect|list|show|confirm|dismiss|resolve|verify> [...] [--vault <path>] [--json]\n" +
"Triage persisted contradictions under Brain/tensions/. detect [--jaccard <n>] scans\n" +
"the configured note corpus (notes.read_paths) and persists a\n" +
"tension note (open state) with a dedup key (subject pair + stance signature) so\n" +
"re-detection updates the existing note instead of duplicating. list [--unresolved]\n" +
"and show <slug> read; confirm <slug> moves open -> confirmed; dismiss <slug>\n" +
"[--reason <r>] and resolve <slug> [--reason <r>] close it (open|confirmed ->\n" +
"dismissed|resolved). Invalid transitions are rejected. A context pack that injects\n" +
"a subject note of an unresolved (open|confirmed) tension emits a warning; dismissed\n" +
"and resolved tensions warn about nothing. verify [<slug>] (read-only) adds an\n" +
"advisory decision-model verdict per tension when the optional tension use is set.\n",
digest:
"usage: o2b brain digest [--vault <path>] [--since <ISO>] [--until <ISO>] [--json] [--silent-if-empty]\n" +
"Renders the 24-hour change digest. Empty + --silent-if-empty exits 2.\n",
"intent-review":
"usage: o2b brain intent-review [--vault <path>] [--now <ISO-8601>] [--json]\n" +
"Read-only pre-dream review of active signal clusters. Surfaces whether\n" +
"each topic is ready for main dream review, needs more evidence, or is\n" +
"blocked by conflicting signals.\n",
retention:
"usage: o2b brain retention [--vault <path>] [--now <ISO-8601>] [--json]\n" +
"Recommendation-only lifecycle review over retired preferences and\n" +
"processed signals. Reports keep/improve/park/prune candidates and never\n" +
"deletes or moves artifacts.\n",
monthly:
"usage: o2b brain monthly [--vault <path>] [--month YYYY-MM] [--json]\n" +
"Read-only monthly synthesis over the Brain timeline: event count, status\n" +
"transitions, retirements, contradictions, and neglected areas when\n" +
"expected areas are supplied by future callers.\n",
query:
"usage: o2b brain query --preference <id> | --topic <slug> | --since <ISO>\n" +
" [--at <ISO|YYYY-MM-DD>] [--show-expired] [--vault <path>] [--json]\n" +
"Read-only lookup. One of --preference / --topic / --since is required.\n" +
"--at evaluates expiration_date as of that instant (default now) and\n" +
"--show-expired keeps lapsed memories; both apply to --topic only.\n",
"agent-query":
"usage: o2b brain agent-query [--agent <id>...] [--topic <slug>] [--query <text>]\n" +
" [--kind signal|preference|log|note] [--limit <n>]\n" +
" [--vault <path>] [--json]\n" +
"Read-only source-agent retrieval over Brain provenance. Omit --agent to query all known agents.\n",
writes:
"usage: o2b brain writes [list] [--agent <id>] [--device <id>] [--path <note>]\n" +
" [--since <date>] [--until <date>] [--op create|update|append|revert]\n" +
" [--vault <path>] [--json]\n" +
" o2b brain writes destinations [--agent <id>] [--device <id>] [--path <note>]\n" +
" [--since <date>] [--until <date>] [--limit <n>] [--vault <path>] [--json]\n" +
" o2b brain writes revert (--agent <id> | --device <id> | --path <note>)\n" +
" [--since <date>] [--until <date>] [--apply <digest>]\n" +
" [--vault <path>] [--json]\n" +
" o2b brain writes prune-images [--older-than-days <n>] [--dry-run]\n" +
" [--vault <path>] [--json]\n" +
"Read-only listing of every recorded note write, newest first: timestamp, operation,\n" +
"agent, device, target, and the content digest on each side of the write. The device\n" +
"comes off the log shard, so a legacy un-sharded log prints '-' rather than a guess.\n" +
"revert plans what undoing the selected writes would do: each target resolves to\n" +
"restore, delete or a named refusal (drift, interleaved, image-missing, unrecorded,\n" +
"already-reverted), and the plan is sealed by a digest printed with the exact --apply\n" +
"line that runs it. A selector naming no agent, device or path is refused - a time\n" +
"window alone is a vault rollback, which is o2b brain rollback. --apply re-plans,\n" +
"refuses a digest that no longer describes the vault before any byte moves, takes a\n" +
"note-revert snapshot, and records each restored or deleted target as a note write of\n" +
"operation revert, so a revert is itself attributable and revertible.\n" +
"destinations folds the same ledger by target path: one row per destination the recorded\n" +
"write events name, across the note-write and write-session kinds (only committed - done\n" +
"- sessions count; a failed session landed nothing), with per-kind counts,\n" +
"the contributing agents and devices, and a kinds coverage field that names which kinds\n" +
"spoke. The default window is the last 7 days ending now. --until sets the end and, when\n" +
"--since is absent, the 7-day lower bound is measured back from --until, so a query\n" +
"about a past period stays a 7-day one; --since replaces the lower bound outright.\n" +
"Derived write sites (signal slugs, daily logs) emit neither kind, so the rows carry a\n" +
"coverage note instead of implying completeness.\n" +
"prune-images bounds the before-image store by file age; the default window is 30 days.\n",
"agent-diff":
"usage: o2b brain agent-diff [--mode browse|search|diff|map] [--agent <id>...]\n" +
" [--topic <slug>] [--query <text>]\n" +
" [--kind signal|preference|log|note] [--limit <n>]\n" +
" [--vault <path>] [--json]\n" +
"Compare source-agent coverage using the same provenance foundation as agent-query.\n",
reject:
"usage: o2b brain reject --id <pref-id> --reason <text> [--yes] [--vault <path>] [--json]\n" +
"Move a preference to retired/ with reason 'user-rejected'. --yes required when pinned.\n" +
"With near_duplicate_retire_siblings_enabled on, also lists the active preferences that resemble\n" +
"the rejected one (score, method) with the command that rejects each; --json adds retire_siblings.\n" +
"Nothing else is retired.\n",
freeze:
"usage: o2b brain freeze [--reason <text>] [--vault <path>] [--json]\n" +
"Write Brain/.state/frozen.json. While it exists every content write in this vault is refused - on this device and, once Syncthing has carried the marker, on every device that shares it. The Brain log keeps recording, so the freeze and the writes it refuses stay auditable. Idempotent: a second freeze keeps the first one's reason.\n",
log:
"usage: o2b brain log verify [--vault <path>] [--json]\n" +
"Walk every JSONL shard of the Brain log and report where each one stops linking up. Each appended row carries prev and h, a sha256 over the previous line's hash plus the row's own ts, kind and payload, so an edited or deleted line is detectable. Output names the shard path, the line number, and whether the line was edited (hash-mismatch), removed or reordered (prev-mismatch), or stripped of its chain fields (malformed). Rows written before the chain shipped carry no h; they are counted as legacy and are clean while they precede the chain. Reports only: nothing here rewrites a log to make it verify, and the read path never consults the chain. Exits 1 when any shard does not link up.\n",
attest:
"usage: o2b brain attest keygen [--passphrase-from-env NAME] [--vault <path>] [--json]\n" +
" o2b brain attest sign [--passphrase-from-env NAME] [--vault <path>] [--json]\n" +
" o2b brain attest list [--vault <path>] [--json]\n" +
" o2b brain attest verify [--vault <path>] [--json]\n" +
"Ed25519-signed store attestations. keygen creates the operator keypair under\n" +
".open-second-brain/keys/attestation/ (private half 0600, never synced); the\n" +
"optional passphrase arrives as an env var NAME or on stdin, never argv, and a\n" +
"lost key leaves every past attestation unverifiable. sign measures the store,\n" +
"seals and signs one attestation record, and writes it as one JSON file - it\n" +
"never creates a key. list prints every attestation newest first; verify\n" +
"re-measures the store against the newest one: per-shard intact / appended /\n" +
"diverged / missing, the signature, and the store digest. Exit 0 with the store\n" +
"intact or legitimately appended, 1 on diverged or missing shards or an invalid\n" +
"signature, 2 on usage errors. Reports only: nothing here repairs a store.\n",
unfreeze:
"usage: o2b brain unfreeze [--vault <path>] [--json]\n" +
"Remove the freeze marker and reopen the content lane. The unfreeze log event records who lifted it and what the marker said, which is the only place that survives the file. Idempotent.\n",
permissions:
"usage: o2b brain permissions show [--vault <path>] [--json]\n" +
" o2b brain permissions ledger [--actor <name>] [--action <write|ingest|owner_write>] [--verdict <allow|ask|deny>] [--since <iso>] [--until <iso>] [--limit <n>] [--vault <path>] [--json]\n" +
"Show the vault's permissions document (Brain/_permissions.yaml) with a dry-run decision table resolving every agent it declares against every action, or query the decision ledger rows the gates append. With no document every write is ungated. A document that cannot be read fails closed: show names the field and the file, and `o2b brain doctor` reports the same fault as permissions-unreadable.\n",
pin:
"usage: o2b brain pin --id <pref-id> [--vault <path>] [--json]\n" +
"Set pinned: true. Idempotent. Exempts the preference from automatic retire.\n",
unpin:
"usage: o2b brain unpin --id <pref-id> [--vault <path>] [--json]\n" +
"Clear pinned: true. Idempotent.\n",
state:
"usage: o2b brain state <set|get|list|clear> [--aspect <slug>] [--value <text>] [--vault <path>] [--json]\n" +
"Overwrite-only exact-state lane keyed by aspect (Brain/state/). Each set replaces the aspect's canonical value with no history. The lane is excluded from the search index so a stale value never resurfaces through recall.\n",
rollback:
"usage: o2b brain rollback <run_id> [--vault <path>] [--yes]\n" +
" [--force-rollback] [--json]\n" +
" o2b brain rollback <run_id> --dry-run [--vault <path>] [--json]\n" +
" o2b brain rollback --list [--vault <path>] [--json]\n" +
"Restore Brain/ from a snapshot. Interactive prompt unless --yes.\n" +
"--dry-run prints the would-be restore plan as live → snapshot\n" +
"diff and exits 0 without writing.\n" +
`From ${BRAIN_MANIFEST_SIDECAR_SINCE_VERSION} each snapshot carries a sidecar sha256 manifest of\n` +
"the Brain/ tree captured at snapshot time. rollback compares it\n" +
"against the current Brain/ and aborts with exit 2 if they\n" +
"differ — typically because another device (Syncthing) edited the\n" +
"vault between snapshot and rollback. Pass --force-rollback to\n" +
"overwrite anyway; the log entry records `drift_overridden: true`.\n" +
`Snapshots produced before ${BRAIN_MANIFEST_SIDECAR_SINCE_VERSION} have no sidecar; rollback emits\n` +
"a stderr warning and falls through to the legacy direct-restore\n" +
"path.\n" +
"The derived SQLite store is covered only when\n" +
"snapshots.include_derived_store is on (off by default). Every\n" +
"rollback reports what it did about it: replaced, not restored with\n" +
"the manifest's named reason, or unknown for a snapshot taken before\n" +
"coverage existed. --list carries the same answer per snapshot.\n" +
"--list, the confirmation prompt and the --json result all name the\n" +
"reason the snapshot was taken; 'unknown' means the snapshot carries\n" +
"no sidecar reason and is never inferred from its run id. Filter the\n" +
"history by reason with `o2b brain snapshot log --reason <reason>`.\n",
snapshot:
"usage: o2b brain snapshot log [--reason <reason>] [--limit <n>]\n" +
" [--vault <path>] [--json]\n" +
" o2b brain snapshot diff <run_id_a> [<run_id_b>]\n" +
" [--vault <path>] [--json]\n" +
"log lists every recovery point newest first: run id, created_at, the\n" +
"reason it was taken, archive size, whether a drift manifest is present,\n" +
"and what it did about the derived store. --reason filters by why it\n" +
"happened and rejects an unregistered value with exit 2. A snapshot with\n" +
"no sidecar reads as reason 'unknown' - never as its run-id prefix.\n" +
"diff is a read-only diff between two snapshots, or between a snapshot\n" +
"and the live Brain/ tree (when <run_id_b> is omitted).\n" +
"Together with rollback, the family is log / diff / revert.\n",
hygiene:
"usage: o2b brain hygiene <scan|apply> [--vault <path>] [--json]\n" +
` [--detectors ${HYGIENE_DETECTOR_IDS.join(",")}]\n` +
" [--ids <finding-id,...>] [--dry-run]\n" +
"Scan is read-only: contested truth slots, near-duplicate preferences,\n" +
"stale/orphaned derived pages, low-usefulness candidates. Apply executes\n" +
"only explicitly selected finding ids; review findings never execute.\n" +
"The conflict resolver command comes from _brain.yaml (hygiene.resolver_cmd).\n",
refresh:
"usage: o2b brain refresh --stale [--vault <path>] [--dry-run] [--json]\n" +
"Targeted recompile: re-derive stale pages from their recorded sources\n" +
"(handoff notes re-derive in place), archive orphans into Brain/.snapshots,\n" +
"report unknown pipelines as manual. --dry-run previews with zero writes.\n",
anticipate:
"usage: o2b brain anticipate --session <id> [--refresh] [--signal <text>]\n" +
" [--vault <path>] [--json]\n" +
"Read the anticipatory context cache for the session's lineage root\n" +
"(warm | stale | miss), or force a refresh first (TTL debounce applies).\n",
doctor:
"usage: o2b brain doctor [--vault <path>] [--json] [--strict]\n" +
" [--remediate [--dry-run]] [--repair [--apply]] [--yes]\n" +
"Validate invariants. Warnings exit 0 (or 2 with --strict). Errors always exit 1.\n" +
"--remediate builds a dependency-ordered repair plan and applies the\n" +
"auto-safe steps (content-hash re-stamp); --dry-run previews without writing.\n" +
"--repair previews safe fixes for detected classes (WAL gaps, orphaned\n" +
"references); --repair --apply performs them and logs one event per fix.\n" +
"--apply requires --yes in non-interactive mode (--json or non-TTY stdin);\n" +
"the refusal exits 1 with nothing written, the protected verb's code.\n" +
"Plain doctor and --strict stay read-only.\n",
watchdog:
"usage: o2b brain watchdog [--vault <path>] [--json] [--remediate [--dry-run]]\n" +
" [--restore <run_id> [--force-restore]] [--attempt <n>]\n" +
"Probe Brain config/dirs/search index, emit recovery recommendations, and apply only explicit safe repairs.\n" +
"Snapshot restore is refused unless --restore and --force-restore are both explicit; use rollback for execution.\n",
health:
"usage: o2b brain health [--vault <path>] [--json]\n" +
"Semantic-health report: contradictory confirmed preferences, recurring\n" +
"concepts with no dedicated preference, and confirmed preferences on stale\n" +
"evidence, plus a clean/watch/investigate verdict. Read-only.\n",
"health-baseline":
"usage: o2b brain health-baseline <set <date>|set now|get|clear> [--vault <path>] [--json]\n" +
"Acknowledge-before watermark (health.silence_before in _brain.yaml). set\n" +
"records that state up to a date is seen and accepted, so concept-gap and\n" +
"batch-inflation advisories entirely older than it stop pinning the verdict\n" +
"at watch; get prints the current value; clear removes it. Detection and\n" +
"stored memory are untouched - only what the report surfaces changes.\n",
status:
"usage: o2b brain status [--vault <path>] [--json]\n" +
"Unified operator status snapshot. Composes doctor, semantic health,\n" +
"hygiene, stale scan, review candidates, active profile, and state-file\n" +
"health into one readable view. Every problem line carries the exact next\n" +
"command to run; a healthy vault prints a compact all-clear. Read-only.\n",
history:
"usage: o2b brain history <slug> [--vault <path>] [--json]\n" +
"Render a preference's edit-history timeline (one entry per content\n" +
"mutation: principle/scope/status before -> after). Read-only.\n",
activation:
"usage: o2b brain activation <status|sweep> [--top N] [--retention-days N] [--max-events N] [--vault <path>] [--json]\n" +
"Operator surface over the recall activation event store (Brain/search/activation/).\n" +
"status reports the folded per-path activation and co-access pairs; sweep drops\n" +
"events outside the retention window or beyond the newest-N cap and refolds\n" +
"(--max-events 0 clears every retained event).\n",
truth:
"usage: o2b brain truth <ingest|slots|conflicts|aggregate|collisions|events|state|sweep> [--vault <path>] [--json]\n" +
"Operator surface over the entity claim ledger (Brain/truth/). ingest appends one\n" +
"claim (--entity --aspect --value --source, optional --quantity-value/--quantity-unit/\n" +
"--quantity-action, optional --valid-from/--valid-until validity window); slots\n" +
"renders current values with superseded history; conflicts lists contested slots\n" +
"(two values within the window from independent sources, resolution always ask_user);\n" +
"aggregate sums exact (entity, action, unit) quantity matches; collisions reports\n" +
"cross-agent convergence; events recalls a windowed slice of the ledger (--entity,\n" +
"--since, --until, --limit); state grounds one agent-stated claim with an anchoring\n" +
"verdict (--subject --relation --object --text --source); sweep keeps the newest N\n" +
"events.\n",
facts:
"usage: o2b brain facts decompose (--file <path> | --text <text>) [--ingest --entity E] [--vault <path>] [--json]\n" +
"Deterministically decompose text into atomic assertions via markdown structure\n" +
"(headings, list items, sentence boundaries with an abbreviation guard), anchored\n" +
"to canonical entities. --ingest appends structured-family assertions (quantity,\n" +
"possession, identity, location, email, url) to the claim ledger for --entity.\n",
"dead-end":
"usage: o2b brain dead-end <record|list> [--approach T --reason T [--context T]] [--max-active N] [--vault <path>] [--json]\n" +
"Negative-knowledge registry under Brain/dead-ends/. record persists one\n" +
"tried-and-failed approach as a markdown note (FTS-indexed, so recall can\n" +
"surface avoid-X alongside prefer-Y); the active set is bounded and overflow\n" +
"archives the oldest entries. list renders active entries newest first.\n",
foresight:
"usage: o2b brain foresight [--horizon-days N] [--write] [--vault <path>] [--json]\n" +
"Forward-looking projection over the continuity log and recurrence ladder:\n" +
"recurring routines coming due within the horizon (cadence arithmetic, soonest\n" +
"first), recent open commitments, and open questions - every item carries\n" +
"deterministic sources. --write persists Brain/foresight/<date>.md.\n",
label:
"usage: o2b brain label <path> <dimension>=<value> | --remove <dimension> | --show | --suggest [--dimensions a,b] [--agent N] [--vault <path>] [--json]\n" +
"Controlled-vocabulary classification against the schema pack's labels\n" +
"field. Assignments are fail-closed - unknown dimensions and values are\n" +
"rejected with the declared vocabulary - single-choice per dimension, and\n" +
"persist as a sorted labels frontmatter array plus a canonical label\n" +
"entity. Filter recall with: o2b search <q> --property labels=<dim>/<value>.\n" +
"--suggest is read-only and never assigns: advisory suggestions from the\n" +
"optional labels decision-model use (available: false while it is off).\n",
bridges:
"usage: o2b brain bridges discover [--max N] [--min-similarity X] | list | accept <source> <target> | dismiss <source> <target> [--vault <path>] [--json]\n" +
"Bridge discovery over the vec index: propose links between embedding-near\n" +
"notes that share no existing edge, orphan-first. discover regenerates the\n" +
"reviewable Brain/proposals/bridges.md artifact and records one\n" +
"bridge_discovery metric; accept writes a single related: wikilink into the\n" +
"source note (schema-pack link constraints honored); dismiss silences a\n" +
"pair across future runs. Fail-soft without an index or embeddings.\n",
clusters:
"usage: o2b brain clusters run [--min-size N] | list [--vault <path>] [--json]\n" +
"Graph-wide community detection: deterministic label propagation over the\n" +
"index's resolved link graph. run materializes one derived note per\n" +
"community of size >= min-size (default 4) under Brain/clusters/ - members\n" +
"by internal degree, shared entities, density, no LLM prose - removes\n" +
"stale generated notes, and records one communities metric. list reads\n" +
"the generated notes back. Fail-soft without an index.\n",
vitals:
"usage: o2b brain vitals [--orphan-threshold N] [--vault <path>] [--json]\n" +
"Aggregate governance scorecard over confirmed Brain/preferences/, four\n" +
"numbers the per-item hygiene lints don't surface: domain_diversity\n" +
"(normalised Shannon entropy of the scope distribution), connectivity_index\n" +
"(mean evidenced_by count per preference), orphan_preferences (confirmed\n" +
"preferences below --orphan-threshold evidence items, default 2), and\n" +
"gap_pressure (open concept-gap findings, reused from `doctor`, divided by\n" +
"preference count). Records one vault_vitals metric. Read-only.\n",
"co-occurrence":
"usage: o2b brain co-occurrence [--min-co N] [--min-score X] [--limit N] [--write] [--vault <path>] [--json]\n" +
"Suggest relationship edges between entities repeatedly co-referenced from\n" +
"the same notes, scored by a structural PMI / document-frequency metric over\n" +
"the wikilink graph (no natural-language word list, any script). Read-only\n" +
"by default; --write persists the Brain/link-graph/co-occurrence.json\n" +
"artifact. Already directly-linked pairs are never re-suggested; notes are\n" +
"never mutated.\n",
hallways:
"usage: o2b brain hallways mine [--min-co N] [--min-score X] [--limit N] [--min-sessions N] [--progress] | show | promote <family> <key> [--min-sessions N] | dismiss <family> <key> [--vault <path>] [--json]\n" +
"The session hallways: entities that keep turning up in the same imported\n" +
"transcripts are associated even when no vault page links them. mine folds\n" +
"the mined-mention ledger (from session import) into incidence and pairwise\n" +
"PMI, persists Brain/link-graph/hallways.json and the reviewable\n" +
"Brain/proposals/hallways.md; show reads the proposals back; promote is the\n" +
"only bridge into the entity registry, offered solely for keys seen in >= N\n" +
"distinct sessions (default 3) and refused by the registry's own admission\n" +
"gate when the label fails it - mining itself never writes an entity;\n" +
"dismiss silences a key across future runs.\n",
"file-context":
"usage: o2b brain file-context <file-path> [--limit N] [--min-bytes N] [--vault <path>] [--json]\n" +
"Surface prior vault work that mentions a file (decisions, bug notes, refactor\n" +
"history) by querying the existing index with terms derived structurally from\n" +
"the path (basename + stem, no natural-language processing). A size gate skips\n" +
"trivial files (default 1500 bytes) with an explicit reason. Read-only; no LLM.\n",
benchmark:
"usage: o2b brain benchmark run --dataset <path> [--k N] [--expand] [--vault <path>] [--json]\n" +
"Score the vault's live hybrid recall against a fixed query/expected-result\n" +
"dataset (hit@k + MRR, per query and aggregate) and record one\n" +
"recall_benchmark metric in Brain/metrics/ so recall quality is chartable\n" +
"over time. Dataset shape: {queries: [{id, query, expected: [paths]}]}.\n",
tune:
"usage: o2b brain tune run --dataset <path> [--k N] | status | reset [--vault <path>] [--json]\n" +
"Opt-in self-tuning recall: run grid-evaluates bounded parameters (pool\n" +
"multiplier, traversal depth, learned weights, expansion) with the recall\n" +
"benchmark as the objective and persists the winner to\n" +
"Brain/search/tuning.json. Search honors it only when\n" +
"search_self_tuning_enabled is on; reset deletes the state.\n",
attr:
"usage: o2b brain attr <path> <field>=<value> | --remove <field> | --show [--vault <path>] [--json]\n" +
"Per-type attribute fields declared in the schema pack's attributes map.\n" +
"The note's own frontmatter type selects the descriptor set; assigning an\n" +
"undeclared field is rejected with the declared fields and their\n" +
"natural-language descriptions. One value per field, persisted as a sorted\n" +
"attributes frontmatter array (filterable via --property attributes=<f>=<v>).\n",
tiers:
"usage: o2b brain tiers check | restore <path> [--field F] [--apply] | accept <path> [--field F] [--vault <path>] [--json]\n" +
"Frontmatter tier guard over framework-kind files. The index post-pass\n" +
"snapshots identity/system fields and stages a finding when an identity\n" +
"join key (kind, id, entity_id, category) changes by hand - the snapshot\n" +
"keeps the expected value, so reindexes never absorb the edit. check\n" +
"lists open findings; restore writes the expected value back (--apply);\n" +
"accept adopts the hand-edit as the new baseline. Nothing auto-resolves.\n",
secret:
// Assembled from the per-op flag tables above - the same string the
// verb prints on a usage error, so the two surfaces cannot disagree.
SECRET_VERB_USAGE +
"\n" +
"Capability-gated secret custody under the vault-local state dir:\n" +
"per-value AES-256-GCM ciphertext, 0600 keyfile, no surface ever prints\n" +
"the value. set reads the value from stdin or --from-env (never argv);\n" +
"run injects it as the declared env var into a subprocess whose command\n" +
"matches the allowlist declared at set time, and the captured output is\n" +
"redacted before it reaches the caller. Every operation lands a\n" +
"no-values record in Brain/log/secret-custody/. Protects against\n" +
"context leakage and vault sync exposure - not against root.\n" +
"unlock wraps the keyfile under a passphrase (read from stdin or\n" +
"--passphrase-from-env, never argv) and holds the key for this process\n" +
"only; lock clears it. A wrapped store reaches every key-bearing verb:\n" +
"each accepts --passphrase-from-env (or stdin, where its own work does\n" +
"not occupy stdin) and unlocks before it runs, and a non-interactive\n" +
"host sets OPEN_SECOND_BRAIN_SECRETS_PASSPHRASE, which the first key\n" +
"operation consumes and deletes. unwrap writes the raw keyfile back,\n" +
"ending the passphrase protection. export writes every entry as one\n" +
"passphrase-encrypted bundle to the --out file (values re-encrypted and\n" +
"authenticated against their entry metadata; names and env-var mappings\n" +
"travel in the clear past the shared egress redactor); import restores a\n" +
"bundle, refusing names the store already holds unless --replace is\n" +
"given.\n" +
"WARNING: a lost passphrase is unrecoverable - every stored value and\n" +
"every exported bundle stays unreadable forever, and nothing recovers\n" +
"them.\n",
maintenance:
MAINTENANCE_USAGE +
"\n" +
"Quiet-window, lease-guarded lane for heavy passes. run gates on the\n" +
"local-time window (unset = always open), recent interactive query-rate\n" +
"from recall telemetry, and an expiring SQLite lease no second worker\n" +
"can grab, then executes dream, reindex, bridges, clusters and the\n" +
"declared custom:<name> tasks stale-first. A task that has failed\n" +
"maintenance.failure_streak_limit times in a row is REFUSED by name\n" +
"(exit 7) while the others still run; --retry <task> attempts that one\n" +
"task with every gate still in force, and --force bypasses the soft\n" +
"gates and every refusal, never the lease. The relink task previews\n" +
"the anchor additions it would make; --relink-apply rewrites the\n" +
"stored signal pages. Every attempt - including\n" +
"gate refusals - lands in a bounded journal; status renders lease +\n" +
"journal. Custom tasks are shell commands declared in the machine\n" +
"config (maintenance_custom_<name>), run only with\n" +
"maintenance_custom_tasks: true, from the home directory unless a\n" +
"_cwd is declared, with credential-named variables dropped from their\n" +
"environment. --cron-template prints the cron or systemd recipe that\n" +
"schedules the lane (default interval 1h) and installs nothing.\n",
audit:
"usage: o2b brain audit <pref-id> [--vault <path>] [--json]\n" +
"Render a preference's full mutation audit trail (create / promote /\n" +
"update / retire / merge) with agent, reason, and revision + content-hash\n" +
"before/after. A ret- or bare-slug argument resolves to the same trail.\n" +
"Read-only.\n",
"semantics-backfill":
"usage: o2b brain semantics-backfill [--vault <path>] [--json]\n" +
"Dry-run only. Previews deterministic typed preference-edge backfill\n" +
"proposals, currently the inverse superseded_by edge when an active\n" +
"preference supersedes a retired preference that lacks the pointer.\n",
"authored-at-backfill":
"usage: o2b brain authored-at-backfill [--apply] [--vault <path>] [--json]\n" +
"Dry-run by default. Stamps the additive authored_at frontmatter field\n" +
"onto session-imported signals that preserved a transcript turn instant\n" +
"(valid_from/recorded_at) but predate the field. Idempotent, and never\n" +
"re-embeds - it only edits frontmatter. Pass --apply to write.\n",
codec:
"usage: o2b brain codec --compress | --expand [--in <file>]\n" +
"Run the deterministic, lossless session codec over stdin (or --in <file>)\n" +
"and print the result to stdout. Read-only; structured content preserved.\n",
sources:
"usage: o2b brain sources [--vault <path>] [--json]\n" +
"Read-only dashboard of the brain's signals grouped by (agent, source_type)\n" +
"with active/processed and distinct-topic counts.\n",
schema:
"usage: o2b brain schema [report|stats|lint|graph|explain|orphans|apply|sync] [--vault <path>] [--json]\n" +
"Inspect and mutate the active runtime schema vocabulary through locked, audited writes.\n" +
"report names the pack's integrity: ok, modified, or unverified with the reason.\n" +
"apply --adopt-unattested (store-only machines, the operator only; alone or with\n" +
"--mutation): adopt the records deciding the pack that no audited apply wrote.\n" +
"sync is not implemented and refuses; it never reported real work.\n",
"session-hook":
"usage: o2b brain session-hook [--vault <path>] [--agent <name>] [--dry-run] [--json]\n" +
"Read one runtime hook JSON payload from stdin, capture inline @osb markers / brain_feedback tool calls,\n" +
"and append a non-blocking session-lifecycle audit/log observation. Intended for hooks/session-capture.ts.\n",
"graph-export":
"usage: o2b brain graph-export [--vault <path>] [--out <file>]\n" +
"Serialise the vault knowledge graph (pages, wikilinks, typed relations) to a\n" +
"stable graph.json. Prints to stdout, or writes to --out. Read-only.\n",
"graph-import":
"usage: o2b brain graph-import <file> [--mode skip|overwrite|merge] [--vault <path>] [--json]\n" +
"Reconstruct vault page stubs from a graph.json. skip (default) never\n" +
"overwrites; merge unions wikilinks/relations; writes are vault-guarded.\n",
"bank-export":
"usage: o2b brain bank-export [--vault <path>] [--out <file>]\n" +
"Serialise a whole-vault bank bundle (preferences + page graph + page\n" +
"contracts + sources dashboard) to a schema-versioned JSON. Read-only.\n",
"bank-import":
"usage: o2b brain bank-import <file> [--mode skip|overwrite|merge] [--agent <name>]\n" +
" [--vault <path>] [--json]\n" +
"Reconstruct the page graph and the preferences from a bank bundle.\n" +
"--mode governs the page graph; preferences restore through the audited\n" +
"preference transaction and are governed by their revision, so a bundle\n" +
"behind the vault is refused per-row and named. Exits non-zero when any\n" +
"carried preference could not be restored. Page contracts and the sources\n" +
"dashboard are reported as carried-not-restored; an unsupported bundle\n" +
"schema fails loudly.\n",
"okf-export":
"usage: o2b brain okf-export --out <dir> [--vault <path>] [--force]\n" +
"Write a portable Open Knowledge Format bundle: concepts/, queries/,\n" +
"references/ markdown pages, a date-grouped log.md, and an okf.json\n" +
"manifest. Page class is derived from frontmatter kind:. Read-only on\n" +
"the vault; refuses a non-empty --out dir without --force.\n",
"okf-import":
"usage: o2b brain okf-import <bundle-dir> [--trusted] [--vault <path>]\n" +
"Import an OKF bundle. By default pages are staged under 'OKF Review/'\n" +
"with okf_review: pending (review candidates); --trusted writes each\n" +
"page directly to its recorded path. Foreign-producer bundles get\n" +
"producer + raw type provenance stamped and x-* frontmatter preserved.\n" +
"The manifest's producer is never trusted: without --trusted, machinery\n" +
"frontmatter (_status, _confidence, owner, origin_channel, ...) is\n" +
"stripped even from a bundle that claims to be open-second-brain. Pass\n" +
"--trusted only for a bundle you exported yourself: it keeps that\n" +
"frontmatter for an open-second-brain bundle and admits the\n" +
"Brain/sources/ and Brain/reports/ lanes (other Brain/ paths are always\n" +
"refused).\n",
"knowledge-pack":
"usage: o2b brain knowledge-pack export --name <name> --select <sel>[,<sel>...] --out <dir>\n" +
" [--version <v>] [--force] [--json]\n" +
" o2b brain knowledge-pack preview <pack-dir> [--json]\n" +
" o2b brain knowledge-pack install <pack-dir> [--agent <name>] [--json]\n" +
" o2b brain knowledge-pack uninstall <name> [--confirm] [--json]\n" +
" o2b brain knowledge-pack list [--json]\n" +
"A knowledge pack is an OKF bundle of selected pages plus selected preference\n" +
"rows, sealed with a sha256 per file. Selectors: pref-<slug>, a page id or\n" +
"path, topic:<topic>, tag:<tag>. Export blocks pages with visibility:, entries\n" +
"with owner:, and unreviewed OKF Review/ candidates, and redacts the rest.\n" +
"Preview shows the manifest, samples, integrity, conflicts and privacy\n" +
"warnings (exit 1 on an integrity failure). Install refuses a pack that fails\n" +
"its integrity check; preferences land unconfirmed on a fresh trial window,\n" +
"pages stage under 'OKF Review/', each stamped knowledge_pack: <name>@<sha>.\n" +
"Uninstall is a dry run without --confirm and removes behind a snapshot;\n" +
"entries that gained local evidence or were promoted are kept and named.\n",
"morning-brief":
"usage: o2b brain morning-brief [--vault <path>] [--json] [--top-k <n>]\n" +
" [--lookback-days <n>] [--max-chars-per-memory <n>] [--max-total-chars <n>]\n" +
"Render a read-only session-start summary: top confirmed preferences\n" +
"(confidence then recency), recent reconcile open questions, and recent\n" +
"notes, bounded by the shared recall char budget. Read-only.\n",
backlinks:
"usage: o2b brain backlinks <id> [--vault <path>] [--json]\n" +
"List inbound references to the given Brain artifact id (preference, retired, signal).\n",
"mcp-landscape":
"usage: o2b brain mcp-landscape [--vault <path>] [--json]\n" +
"List the Model Context Protocol servers configured across the vault: each\n" +
"server's name, the config file that declares it, the packages it pulls, and\n" +
"the env-var NAMES it requires. Environment values are never read. Read-only.\n",
settings:
"usage: o2b brain settings get <name> [--vault <path>] [--json]\n" +
" o2b brain settings set <name> <value> [--vault <path>] [--agent <name>] [--json]\n" +
" o2b brain settings unset <name> [--vault <path>] [--agent <name>] [--json]\n" +
" o2b brain settings list [--vault <path>] [--json]\n" +
"Read and change the brain settings every machine shares, named <block>.<field>\n" +
"(for example notes.read_paths, decision_model.enabled, dream.candidate_threshold)\n" +
"or by a scalar key (primary_agent). <value> is JSON when it parses (5, true,\n" +
'["Projects/"]), else a plain string. The value is validated before it is written.\n' +
"A setting of one machine (snapshots, storage, embeddings, decision-model endpoints)\n" +
"is refused with the machine-config key to set instead. Once this machine is\n" +
"switched to the brain store a change is a shared settings record with human\n" +
"authority, which an agent cannot override; before that it edits the settings file.\n" +
"view.language (en, ru) sets the language of the human view's generated text; it is\n" +
"a store setting on every machine, so it needs the brain store.\n",
"migrate-store":
"usage: o2b brain migrate-store [--wait <seconds>] [--vault <path>] [--json]\n" +
" o2b brain migrate-store --dry-run [--vault <path>] [--json]\n" +
" o2b brain migrate-store --resume [--wait <seconds>] [--vault <path>] [--json]\n" +
" o2b brain migrate-store --rollback [--vault <path>] [--json]\n" +
" o2b brain migrate-store --remove-legacy [--force] [--vault <path>] [--json]\n" +
" o2b brain migrate-store --force-release-gate [--json]\n" +
"Move this vault's legacy brain (Brain/ and the machine state beside it) into the\n" +
"brain store and switch this machine to it. --dry-run prints the plan and writes\n" +
"nothing. --resume continues an interrupted migration. On a later machine, --wait\n" +
"waits up to that many seconds for the first machine's store files to arrive by\n" +
"sync before refusing. --rollback takes this\n" +
"machine back to the legacy layout. --remove-legacy moves the legacy tree out of the\n" +
"vault once every device of the store has migrated or been retired; --force removes\n" +
"it anyway. --force-release-gate releases the migration gate a run that is gone left\n" +
"on this machine, unless its holder is still running. The forms exclude each other.\n" +
"Exit codes: 0 done (or a plan that maps every entry), 1 refused, failed, a plan with\n" +
"unmapped entries or a legacy tree kept in place, 2 usage error.\n",
"set-primary":
"usage: o2b brain set-primary <name> [--vault <path>] [--agent <name>] [--json]\n" +
" o2b brain set-primary --clear [--vault <path>] [--agent <name>] [--json]\n" +
"Declare which agent owns the dream consolidation pass for this vault.\n" +
"Stored as the shared brain setting `primary_agent`. Dream runs from a\n" +
"different agent emit a warning but still proceed (observability, not\n" +
"access control). Use --clear to remove the declaration. Once this machine is\n" +
"switched to the brain store, --agent names who made the change in its record.\n",
"scan-inline":
"usage: o2b brain scan-inline [--vault <path>] [--path <subdir>...] [--exclude <subdir>...]\n" +
" [--dry-run] [--strict] [--json] [--agent <name>]\n" +
"Walk the vault for @osb markers (inline form and fenced 'osb' blocks),\n" +
"create brain signals (store records once switched, Brain/inbox/ before),\n" +
"and annotate the source files with\n" +
"@osb✓ [[sig-...]]. Brain/, .git, node_modules, and similar directories\n" +
"are always skipped. Idempotent on re-run.\n",
"scan-citations":
"usage: o2b brain scan-citations [--vault <path>] [--path <subdir>...] [--exclude <subdir>...]\n" +
" [--dry-run] [--strict] [--json] [--agent <name>]\n" +
"Walk the vault for inline [Source: <name>, YYYY-MM-DD] provenance markers\n" +
"and promote each well-formed citation into the temporal timeline as a\n" +
"dated source-citation event stamped at the citation date. Dedup is on\n" +
"(normalized name, date), so a re-run over an unchanged vault promotes\n" +
"nothing. Malformed markers are reported and skipped; --strict exits 2\n" +
"when any malformed marker is found. Brain/ and the usual build dirs are\n" +
"always skipped.\n",
"import-claude-memory":
"usage: o2b brain import-claude-memory [--vault <path>] [--memory <path>]\n" +
" [--from <backend>] [--approval-digest <hex>]\n" +
" [--dry-run | --apply] [--yes] [--json]\n" +
" [--allow-arbitrary-memory-path]\n" +
"Read metadata.type:feedback entries from a Claude Code memory directory and\n" +
"write them as confirmed Brain preferences. A sidecar manifest\n" +
"Brain/.imports/claude-memory.json tracks idempotency. UPDATE preserves\n" +
"accumulated evidence fields. CONFLICT (preference exists without a manifest\n" +
"entry) exits 2 — never silent overwrites.\n" +
"Default is --dry-run; --apply requires --yes and --approval-digest in\n" +
"non-interactive mode.\n",
entity:
"usage: o2b brain entity <set|get|list|relate|archive|prune|lexicon|merge> [args]\n" +
" set <category> <name> [--alias <a>]... [--body <md>] [--confidence <c>] [--json]\n" +
" get <name-or-alias> [--category <c>] [--json] exit 2 when not found\n" +
" list [--category <c>] [--status active|archived] [--json]\n" +
" relate <from> <relation> <to> [--from-category <c>] [--to-category <c>] [--json]\n" +
" archive <name-or-alias> [--restore] [--category <c>] [--json]\n" +
" prune [--confirm] [--include-advisory] [--json] dry-run default; snapshot before removal;\n" +
" advisory verdicts need the opt-in\n" +
" lexicon rebuild [--apply] [--json] dry-run default; writes only the\n" +
" derived Brain/entities/lexicon.json\n" +
" merge <keep> <drop> [--dry-run] [--expect-hash <hash>] [--force] [--json]\n" +
" preview echoes the plan hash; apply\n" +
" verifies it before any write; a TTY gets\n" +
" a y/N prompt, agents pass --force\n" +
" (--json needs it); --force also\n" +
" bypasses the text-level merge guard\n" +
"One canonical entity per (category, name); aliases resolve to the canonical record.\n" +
"Labels are decoration-stripped and quality-gated on set; prune removes historical\n" +
"malformed nodes and their edges. merge folds a duplicate page into the survivor: the\n" +
"old name becomes an alias, the old page is archived behind a recovery point, and no\n" +
"claim is rewritten. Denylist: entities.label_denylist config key. The\n" +
"store-learned lexicon artifact feeds the tightened creation verdicts; rebuild it\n" +
"after corpus edits (a stale artifact degrades admission fail-open, never mis-rejects).",
"design-note":
"usage: o2b brain design-note <topic> [--vault <vault>] [--agent <name>]\n" +
" [--payload <json> | --payload-file <path>] [--json]\n" +
"The one-shot sibling of `o2b brain panel`. Without a payload it is\n" +
"read-only: it grounds the topic in the vault's tension records, decision\n" +
"records and truth projections - naming any store the vault holds nothing\n" +
"in, which is not the same as a store that matched nothing - and prints\n" +
"the single needs-llm-step envelope the calling agent answers.\n" +
"With --payload / --payload-file it validates the written note and commits\n" +
"it as Brain/decisions/design-<date>-<topic>.md, beside the panel outputs.\n" +
"The note must weigh named alternatives and mark EXACTLY ONE recommended:\n" +
"zero and two-plus are both refused, and the refusal states the count.\n" +
"A note for the same topic on the same day is refused, never overwritten.\n",
"dead-letters":
"usage: o2b brain dead-letters [list] [--vault <path>] [--json]\n" +
" o2b brain dead-letters show <id> [--vault <path>] [--json]\n" +
" o2b brain dead-letters recover <id> [--dry-run] [--apply] [--yes]\n" +
" [--agent <name>] [--vault <path>] [--json]\n" +
"The exit for a dead letter - the durable record of a multi-artifact\n" +
"extraction write that failed part way. `list` (the default) renders\n" +
"every letter with its classification - recover, pending, re-extract,\n" +
"not_recoverable, resolved - and the exact copy-paste command that\n" +
"resolves it; `show <id>` prints one letter in full, missing keys and\n" +
"frozen payload named; `recover <id>` re-runs a schema-2 letter's\n" +
"frozen payload through the extraction commit at CURRENT vault state,\n" +
"so already-written items dedup away and nothing stale is replayed.\n" +
"Recover is dry-run by default and previews the per-item verdicts;\n" +
"--apply performs the re-run and requires --yes under --json or a\n" +
"non-TTY stdin. A frozen vault refuses. NOTHING here deletes a letter:\n" +
"a recovered letter is retained, and removing it stays an operator's\n" +
"hand action on the named file.\n",
"extract-signals":
"usage: o2b brain extract-signals <session-ref> [--vault <vault>] [--agent <name>]\n" +
" [--payload <json> | --payload-file <path>] [--json]\n" +
"Mine durable taste signals out of an ALREADY-IMPORTED session's user\n" +
"turns. Without a payload the verb is read-only: it prints the turns it\n" +
"would mine and the single needs-llm-step envelope the calling agent\n" +
"answers. With --payload / --payload-file it validates that answer and\n" +
"writes the accepted items into Brain/inbox/ as speculative signals with\n" +
"source_type: auto_extract, subject to the durability denylist and to\n" +
"Brain/pending/ staging when write approval is enabled.\n" +
"Refusals are named: a payload over the per-session cap, or an item below\n" +
"the confidence floor, rejects the whole payload and writes nothing.\n" +
"Import the session with `o2b brain import-session --recall` first; a\n" +
"session with no imported turns is refused, never reported as empty.\n",
"import-session":
"usage: o2b brain import-session <path> [--vault <vault>]\n" +
" [--format auto|<registered-adapter>]\n" +
" [--agent <name>] [--since <ISO>] [--dry-run] [--recall]\n" +
" [--ingest-scope <label>] [--filter-role <role> ...] [--filter-text <substring>]\n" +
" [--preserve-event-time]\n" +
" [--recall-session-id <id>] [--recall-summary-group-size <n>] [--json]\n" +
" o2b brain import-session --status [--vault <vault>] [--progress] [--json]\n" +
" o2b brain import-session --discover [--all] [--vault <vault>] [--progress] [--json]\n" +
"Extract signals from a registered agent session .jsonl file (or\n" +
"directory of .jsonl files). Two extraction paths run in parallel:\n" +
"@osb markers in user/assistant messages, and replay of brain_feedback\n" +
"tool_use calls. Dedup against the inbox by normalised payload hash.\n" +
"With --recall, also stores normalized turns in the continuity-backed\n" +
"session recall DAG.\n" +
"With --preserve-event-time, each signal is stamped with its turn's\n" +
"original timestamp (created_at/recorded_at/valid_from) instead of the\n" +
"import wall-clock, so backfilling an old log stays historically\n" +
"faithful. Turns with an absent/unparseable/future timestamp fall back\n" +
"to now.\n" +
"Autodetect failure exits 2 — pass --format to override.\n" +
"--status sweeps the session roots this build declares and reports, per\n" +
"runtime, how many logs were found, how many are already imported, and\n" +
"the gap between them. --discover lists the gap without importing it;\n" +
"--discover --all imports it. Coverage is keyed by content hash in\n" +
"<vault>/.open-second-brain/session-import-ledger.json, so a log whose\n" +
"bytes have not changed is reported as imported without being re-parsed.\n" +
"A <path> and --discover/--status are mutually exclusive and refuse by\n" +
"name; --all on its own does the same.\n",
merge:
"usage: o2b brain merge <keep-pref-id> <drop-pref-id>\n" +
" [--dry-run] [--force] [--vault <path>] [--json]\n" +
" [--agent <name>]\n" +
"Merge two near-duplicate preferences. <keep> retains identity and\n" +
"principle; <drop> retires with reason 'merged-into' and a\n" +
"superseded_by wikilink to <keep>. <keep> picks up the sorted-dedup\n" +
"union of evidenced_by, the summed applied_count / violated_count,\n" +
"and max(last_evidence_at). Confidence is recomputed by the next\n" +
"dream pass — not by merge itself.\n" +
"--dry-run prints the plan and writes nothing.\n" +
"--force skips the interactive prompt but does NOT bypass invariant\n" +
"guards (topic/scope mismatch, pin parity).\n",
export:
"usage: o2b brain export --format json|llms-txt|transcripts-jsonl\n" +
" [--vault <path>] [--out <path>] [--force]\n" +
" o2b brain export --format transcripts-jsonl --transcripts <file|dir>\n" +
" [--runtime <id>] [--since <iso>] [--until <iso>]\n" +
"Read-only dump of active preferences (confirmed | unconfirmed |\n" +
"quarantine) from Brain/preferences/. Retired and signal entries\n" +
"are not included. JSON is single-line; llms-txt follows the\n" +
"llmstxt.org H1 + summary + H2-section shape.\n" +
"transcripts-jsonl reads no vault: it emits one JSON conversation\n" +
"record per line from the session logs under --transcripts, with\n" +
"ordered role/text messages and the names (never the inputs) of the\n" +
"tools each turn called. --runtime keeps one adapter's transcripts;\n" +
"--since / --until select whole conversations by their START, so a\n" +
"kept conversation is never sliced across the window edge.\n" +
"Every format is scanned by the shared egress guard before a byte is\n" +
"written, and a secret-shaped identifier refuses the export outright.\n" +
"Default sink is stdout; --out writes to <path> (refuses to\n" +
"overwrite without --force).\n",
upgrade:
"usage: o2b brain upgrade [--vault <path>] [--dry-run | --apply | --check]\n" +
" [--yes] [--json]\n" +
"Migrate the release-owned files (`Brain/_brain.yaml`,\n" +
"`Brain/_BRAIN.md`) forward to the shape the installed\n" +
"open-second-brain release ships.\n" +
"User-owned content (preferences/, retired/, inbox/, log/) is\n" +
"never touched.\n" +
"--dry-run (default) prints a per-file plan with a unified diff\n" +
"for every pending update. Exit 0 regardless of pending count.\n" +
"--check is dry-run + exit 2 when anything is pending or in error\n" +
"(CI-friendly).\n" +
"--apply takes a pre-apply snapshot named upgrade-<ts> (rollback\n" +
"via run_id) and rewrites every pending file. Requires --yes in\n" +
"non-interactive mode (--json or non-TTY stdin).\n" +
"_brain.yaml merge is purely additive: missing schema-keys are\n" +
"appended, existing values stay. _BRAIN.md is byte-compared\n" +
"against the rendered template and overwritten when it differs.\n",
explorer:
"usage: o2b brain explorer [--port <n>] [--vault <path>]\n" +
" o2b brain explorer --export <path> [--force] [--vault <path>]\n" +
"Live mode: bind a loopback HTTP server on 127.0.0.1:<port> (default\n" +
"7777) that renders preferences and retired entries as a force-directed\n" +
"graph. Press Ctrl+C to stop.\n" +
"Export mode: write the same view as a single offline HTML file at\n" +
"<path>. Without --force, refuses to overwrite an existing file.\n" +
"Zero backend, no LLM, no network access. The page consumes a\n" +
"prebuilt JSON graph; it does not parse vault Markdown client-side.\n",
"page-dedup":
"usage: o2b brain page-dedup [--apply] [--yes] [--vault <path>] [--json]\n" +
"Detect near-duplicate vault pages by normalised topic+principle key.\n" +
"Dry-run by default: lists each cluster with its canonical (oldest)\n" +
"and secondary ids. --apply writes `merged_into:` on every secondary\n" +
"and rewrites `[[secondary]]` wikilinks across the vault to the\n" +
"canonical. Requires --yes in non-interactive mode (--json or non-TTY).\n",
"token-footprint":
"usage: o2b brain token-footprint [--warn-threshold <n>] [--vault <path>] [--json]\n" +
"Report per-category vault token size (preferences, retired, inbox,\n" +
"processed, log, other) using the language-agnostic\n" +
"`ceil(utf8_bytes / 4)` heuristic. Flags vaults that cross the warn\n" +
"threshold (default 200000; override via --warn-threshold or the\n" +
"BRAIN_TOKEN_WARN_THRESHOLD env var).\n",
"context-pack":
"usage: o2b brain context-pack [--max-tokens <n>] [--model <name>] [--query <q>] [--lanes] [--cache-stable] [--dedup-repeated]\n" +
" [--receipt] [--receipt-host <name>] [--telemetry] [--telemetry-host <name>]\n" +
" [--session-id <id>] [--turn-id <id>] [--vault <path>] [--json]\n" +
"Return the highest-tier, most recent vault slice that fits under\n" +
"<n> tokens. --max-tokens is optional: when omitted, the budget derives\n" +
"from the model context window (the vault's context: block, the\n" +
"environment override, or --model; the matching preset's budget), and\n" +
"--json names the deciding channel in max_tokens_source. With nothing\n" +
"resolvable the verb refuses - it never picks a budget silently. Items\n" +
"ordered core → supporting → peripheral, then\n" +
"newest first. Stops adding pages when the next page would exceed\n" +
"the budget. --query <q> filters by NFKC+casefold substring match\n" +
"on topic + principle. --lanes also returns directives, constraints,\n" +
"and consider lanes alongside the legacy flat items list.\n",
"context-receipts":
"usage: o2b brain context-receipts list [--trigger context_pack|pre_compress] [--host <name>] [--session-id <id>] [--limit <n>] [--vault <path>] [--json]\n" +
" o2b brain context-receipts show <receipt-id> [--vault <path>] [--json]\n" +
" o2b brain context-receipts verify <receipt-id> [--vault <path>] [--json]\n" +
"Read prompt context receipt continuity records emitted by opt-in callers.\n",
"event-trace":
"usage: o2b brain event-trace [--date <YYYY-MM-DD>] [--at <HH:MM:SS>] [--kind <event-kind>] [--session-id <id>] [--limit <n>] [--keep-private] [--vault <path>] [--json]\n" +
"Join logged Brain events to the continuity records (recall telemetry, context\n" +
"receipts, generation reports, …) attached to them by shared correlation ids\n" +
"(session_id, turn_id, artifact refs). Defaults to today's log. Use the per-kind\n" +
"readers (context-receipts show, recall-telemetry, generation-reports show) to\n" +
"open a listed record in full. Read-only; private records are dropped unless\n" +
"--keep-private is set.\n",
"context-presets":
"usage: o2b brain context-presets show [preset-id] [--json]\n" +
" o2b brain context-presets suggest [--model <name>] [--context-window <tokens>] [--json]\n" +
" o2b brain context-presets diff <preset-id> [current-value flags] [--override <path>...] [--json]\n" +
"Dry-run model-aware context budget preset diagnostics. Never writes config.\n" +
"With --model alone (no --context-window), the window resolves from the model id\n" +
"first (declared table, then a trailing 1m suffix); a preset hint answers only\n" +
"when nothing places the id, and the reason names what decided.\n",
"pre-compact-extract":
"usage: o2b brain pre-compact-extract --vault <path> --session-id <id> --turn-start <id> --turn-end <id> --text <text> [--host <name>] [--max-chars <n>] [--dry-run] [--json]\n" +
"Extract Decision/Commitment/Outcome/Rule/Open question lines into idempotent continuity records.\n" +
"--dry-run previews the candidate records without writing to the vault (predicts the real extraction byte-for-byte).\n",
"post-compact-audit":
"usage: o2b brain post-compact-audit [--session-id <id>] [--no-reassert] [--force] [--vault <path>] [--json]\n" +
"Reads a { session_id, messages } JSON document from stdin. Detects a Hermes compaction, audits which pinned anchors survived in the active (non-summary) region, and re-asserts only the drifted ones. Gated by post_compact_survival_audit (default off); --force overrides the gate.\n",
"recall-telemetry":
`usage: o2b brain recall-telemetry list [--mode ${RECALL_MODE_CHOICES}] [--status ${RECALL_STATUS_CHOICES}] [--channel ${RECALL_CHANNEL_CHOICES}] [--host <name>] [--since <iso>] [--until <iso>] [--limit <n>] [--vault <path>] [--json]\n` +
" o2b brain recall-telemetry summary [same filters] [--vault <path>] [--json]\n" +
" o2b brain recall-telemetry cost [--since <iso>] [--until <iso>] [--write-cost <n>] [--read-cost <n>] [--write-heavy-ratio <n>] [--vault <path>] [--json]\n" +
"Read opt-in recall telemetry continuity records and aggregate coverage gaps. cost folds write volume (feedback/apply-evidence/note/host writes) against reads into a write-vs-read ratio, a write-heavy flag, and a rough weighted cost signal per period.\n",
"knowledge-gaps":
"usage: o2b brain knowledge-gaps [--min-occurrences <n>] [--max-satisfaction <0..1>] [--since <iso>] [--until <iso>] [--limit <n>] [--vault <path>] [--json]\n" +
"Aggregate the persisted cross-query demand log (Brain/log/query-demand[.<deviceId>].jsonl, every device's shard merged) into recurring queries the vault answers poorly. Buckets by normalized query terms and ranks by frequency x (1 - satisfaction), where satisfaction is the reused IDF-weighted coverage (or the non-empty-result fraction when coverage was not recorded). Turns repeated recall failures into a prioritized backlog of what to write next. Read-only; the log is written only by opt-in recall telemetry.\n",
"generation-reports":
"usage: o2b brain generation-reports record <write_session|context_pack|dream_stage> --ref <id> --agent <name> --prompt <text> [--enable] [--provider <p>] [--model <m>] [--finish-reason <r>] [--latency-ms <n>] [--input-tokens <n>] [--output-tokens <n>] [--cached-tokens <n>] [--total-tokens <n>] [--scope <s>] [--source <id[=path]>...] [--created-at <iso>] [--vault <path>] [--json]\n" +
" o2b brain generation-reports list [--handoff <kind>] [--agent <name>] [--since <iso>] [--until <iso>] [--limit <n>] [--vault <path>] [--json]\n" +
" o2b brain generation-reports summary [same filters] [--vault <path>] [--json]\n" +
" o2b brain generation-reports show <report-id> [--vault <path>] [--json]\n" +
"Inbound, opt-in LLM generation tracing. record is gated (default off) by --enable or generation_trace_enabled; only prompt_hash + counts are stored, never the prompt.\n",
"skill-proposals":
"usage: o2b brain skill-proposals <learn|list|accept|reject|recover|usage|page-candidates|page-draft|rewrite-plan|rewrite-score> [args]\n" +
"Proposal queue lifecycle, from continuity telemetry, from mature vault pages, and from benchmark-gated rewrite rounds.\n" +
" learn [--min-support <n>] [--vault <path>] [--json]\n" +
" list [--vault <path>] [--json]\n" +
" accept <slug> [--note <text>] [--vault <path>] [--json]\n" +
" reject <slug> --note <text> [--vault <path>] [--json]\n" +
" recover [--discard-unreadable] [--vault <path>] [--json]\n" +
" usage [--vault <path>] [--json]\n" +
" page-candidates [--vault <path>] [--json]\n" +
" page-draft <page> (--payload <json> | --payload-file <path>) [--vault <path>] [--json]\n" +
" rewrite-plan <skill> --candidate-file <path> [--skills-root <path>] [--vault <path>] [--json]\n" +
" rewrite-score <skill> [--rounds-dir <dir>] [--candidate-file <path>] [--skills-root <path>] [--vault <path>] [--json]\n" +
"page-candidates is read-only: it gates the vault's user pages on the page-meta trio (core tier, non-stale lifecycle, high confidence) and an observed-reuse floor, skips any page an installed skill already covers, and returns one needs-llm-step envelope per admitted page plus every skip with its reason. page-draft validates the returned draft and STAGES it as a pending mature_page proposal inside the vault; accept is what materializes the SKILL.md under the configured skills root.\n" +
"recover resolves accept sequences a crash abandoned. It refuses, naming the file, on a held accept lock and on an unreadable journal marker; --discard-unreadable removes those markers.\n" +
"rewrite-plan verifies the skill's benchmark task set against its frozen receipt and prints the receipt plus the dev-round envelopes: a baseline round over the incumbent body and a candidate round over --candidate-file, each with its transcript drop site under Brain/skill-benchmarks/<skill>/rounds/. Held-out members are never printed here. rewrite-score grades the submitted transcripts with structural predicates only, runs the preregistered selection gate (a candidate promotes only by strictly beating the baseline by the pinned margin with the dev n met), hands out the single held-out round on a promote, and stages a scored_rewrite pending proposal ONLY on a final promote after the held-out pass; a hold and a short dev arm write only the grade record. The optional judge (skill_rewrite_judge_cmd) is advisory and never moves the metric. An unknown skill_rewrite.mode refuses by name; MCP reads the same status read-only and never accepts or scores.\n",
"procedural-memory":
"usage: o2b brain procedural-memory <reconcile|list|mark-used> [args]\n" +
"Procedural index reconciliation and usage tracking sidecar.\n" +
" reconcile [--root <path> ...] [--vault <path>] [--json]\n" +
" list [--vault <path>] [--json]\n" +
" mark-used <entry-id> [--vault <path>] [--json]\n",
"procedural-graph":
"usage: o2b brain procedural-graph <rebuild|show|hints> [args]\n" +
"Read/write procedural graph and prospective-hints projections.\n" +
" rebuild [--vault <path>] [--json]\n" +
" show [--vault <path>] [--json]\n" +
" hints [--vault <path>] [--json]\n",
recurrence:
"usage: o2b brain recurrence <list|show|learn|forget|purge-source> [args]\n" +
"Recurrence/support diagnostics and reference-counted updates.\n" +
" list [--vault <path>] [--json]\n" +
" show <content-hash> [--vault <path>] [--json]\n" +
" learn --hash <h> --scope <scope> --source <id> [--vault <path>] [--json]\n" +
" forget --hash <h> --scope <scope> --source <id> [--vault <path>] [--json]\n" +
" purge-source --source <id> [--vault <path>] [--json]\n",
"attention-flows":
"usage: o2b brain attention-flows <list|evaluate|render> [args]\n" +
"Declarative attention-flow recipes and evaluation surfaces.\n" +
" list [--vault <path>] [--json]\n" +
" evaluate <flow-id> [--vault <path>] [--json]\n" +
" render <flow-id> [--vault <path>] [--json]\n",
obligation:
"usage: o2b brain obligation <add|done|list|show|remove> [args]\n" +
"Recurring obligations as Brain pages with a deterministic cadence-driven next-due date.\n" +
"Cadences: daily, weekly, biweekly, monthly, quarterly, yearly, every-<N>-days.\n" +
" add --title <t> --cadence <c> [--anchor YYYY-MM-DD] [--notes <n>] [--vault <path>] [--json]\n" +
" done --slug <s> [--date YYYY-MM-DD] [--vault <path>] [--json]\n" +
" list [--overdue] [--vault <path>] [--json]\n" +
" show --slug <s> [--vault <path>] [--json]\n" +
" remove --slug <s> [--vault <path>] [--json]\n",
today:
"usage: o2b brain today [--vault <path>] [--json] [--lookback-days <n>] [--limit <n>]\n" +
"Read-only today dashboard: due and overdue obligations, open loops, merged\n" +
"recent activity, and a totals rollup. Each section derives live and in\n" +
"isolation, so a section that fails to compute is reported without blanking\n" +
"the rest. --lookback-days bounds the recent-activity window (default 7);\n" +
"--limit caps the recent-activity entries (default 20). Never writes.\n",
"apply-markers":
"usage: o2b brain apply-markers [--vault <path>] [--path <subdir>...] [--apply]\n" +
" [--agent <name>] [--json]\n" +
"Apply @osb set markers as schema-validated frontmatter attribute writes.\n" +
"Report mode by default: lists each pending marker with its resolved target\n" +
"and validation verdict and writes nothing. --apply performs the mutations\n" +
"and requires the guardrails.marker_writeback flag in _brain.yaml; with the\n" +
"flag off, --apply refuses and writes nothing. Applied markers are consumed\n" +
"(annotated) so a re-run is idempotent. Unresolvable or invalid targets are\n" +
"reported with an error code and candidates and left unconsumed; a target a\n" +
"governance wall refuses (standing rules, Brain machinery, a non-note file,\n" +
"the declared write binding) is reported as refused, in report mode too,\n" +
"and the run continues with the next marker. Source files\n" +
"come from --path (repeatable) or notes.read_paths.\n",
pending:
"usage: o2b brain pending list [--lane signals|notes|ingest|all] [--vault <path>] [--json]\n" +
" o2b brain pending apply <id> [--dry-run] [--vault <path>] [--json]\n" +
" o2b brain pending reject <id> --reason <text> [--dry-run] [--vault <path>] [--json]\n" +
"Review the write-approval queues (write_approval.enabled plus the\n" +
"per-lane keys). Signals stage flat into Brain/pending/ (sig- ids), note\n" +
"creates under Brain/pending/notes/ (note- ids carrying the encoded\n" +
"publish target) and ingest summary pages under Brain/pending/ingest/\n" +
"(ing- ids). list shows every lane sorted (--lane filters one; files\n" +
"that cannot be read as queue entries are named with a reason, never\n" +
"silently skipped); apply moves one into its decoded publish target\n" +
"unchanged (--dry-run previews the move and writes nothing); reject\n" +
"renders it into Brain/retired/ with retire-shaped frontmatter (the\n" +
"same --dry-run honesty). Applying or rejecting a missing id exits 2\n" +
"(never a silent no-op).\n",
lessons:
"usage: o2b brain lessons candidates [--vault <path>] [--json]\n" +
" o2b brain lessons approve <pref-id> [--target <file>...] [--apply] [--yes] [--force]\n" +
" o2b brain lessons deny <pref-id> [--apply] [--yes] [--vault <path>] [--json]\n" +
" o2b brain lessons refresh-blocks [--apply] [--yes] [--force] [--vault <path>] [--json]\n" +
"Operator-approved lesson promotion into the managed lessons block of the\n" +
"agent rules files (AGENTS.md, CLAUDE.md, GEMINI.md). candidates is\n" +
"read-only: the promotable set plus every blocked lesson with its single\n" +
"named reason, and the resolved promotion scopes. approve follows the\n" +
"install consent ladder: plan-only by default, --apply executes, headless\n" +
"--apply without --yes refuses with exit 6; the ledger row is recorded\n" +
"only after the rules-file writes landed, and every byte goes through the\n" +
"shared rules-block writer. deny records without writing rules files.\n" +
"refresh-blocks re-renders blocks under management (dry run by default;\n" +
"never creates a block), drops a lesson whose approval went stale by\n" +
"name, and stamps lastPromotedAt on what it wrote. Operator-only: no MCP\n" +
"tool exposes these subcommands.\n",
signal:
"usage: o2b brain signal retire <id> --reason <text> [--superseded-by <id>] [--vault <path>] [--json]\n" +
"Retire an extracted fact signal: move Brain/inbox/sig-*.md into\n" +
"Brain/retired/ with retire-shaped frontmatter (_status, retired_at,\n" +
"retired_reason, optional superseded_by, old-id alias). The directory move\n" +
"excludes it from the dream pass while it stays readable in Brain/retired/.\n" +
"Retiring a missing, already-retired, or non-signal id exits 2 (never a\n" +
"silent no-op).\n",
capture:
"usage: o2b brain capture [<body>] [--source <channel>] [--sender <who>]\n" +
" [--guidance <text>] [--at <ISO>] [--vault <path>] [--json]\n" +
"Stage one capture through the capture-note contract - the same writer the\n" +
"Telegram bot uses, so the id, the frontmatter and the staging path are\n" +
"identical. The body is the argument, or stdin when no argument is given.\n" +
"--source names the channel (default cli) and --sender who is capturing\n" +
"(default the configured agent); --at backdates a replayed capture to its\n" +
"own instant. --guidance records what should be DONE with the capture as a\n" +
"## Guidance body section, kept apart from the captured text and part of\n" +
"the id hash, so two captures differing only in guidance stay distinct.\n" +
"An empty body or a blank --guidance is refused by name and exits 2.\n",
"telegram-capture":
"usage: o2b brain telegram-capture <run|catchup> [--vault <path>]\n" +
"Inbound Telegram capture bot. run long-polls getUpdates via fetch (needs\n" +
"TELEGRAM_BOT_TOKEN or telegram_bot_token, and telegram_chat_allowlist);\n" +
"each allowlisted text message becomes one staged capture, /catchup replies\n" +
"with captures since the last acknowledged one, and every rejected or\n" +
"malformed update is one logged decision. A missing token exits with a typed\n" +
"error. catchup renders the same summary to stdout from disk, no token or\n" +
"network needed. Nothing runs implicitly from hooks.\n",
"inbox-drain":
"usage: o2b brain inbox-drain [--apply] [--vault <path>] [--json]\n" +
"Classify and route staged captures via the capture-note contract.\n" +
"Classification is structural only: a url-shaped body is a source\n" +
"reference (ingested), a leading @obligation marker opens an obligation,\n" +
"and everything else is an atomic idea (create-or-merge note). Dry-run is\n" +
"the default and writes nothing; --apply routes each capture and archives\n" +
"it, so a rerun is a no-op. Unroutable items are reported and left in\n" +
"place. Each item names its action and reason.\n",
"orphan-repair":
'usage: o2b brain orphan-repair [--apply --confirm "apply orphan repair"] [--vault <path>] [--json]\n' +
"Detach dangling session references from observation signals. A signal whose\n" +
"session_ref resolves to no session or continuity record is reported by the\n" +
"doctor under orphan-session-ref with this verb as its fix. Dry-run is the\n" +
"default and writes nothing; --apply removes ONLY the session_ref key from\n" +
"each signal's frontmatter and requires the exact confirmation phrase via\n" +
"--confirm. The observation body, topic and every other field are kept, and\n" +
"the detached value is quoted in the report. A hard per-run cap bounds the\n" +
"writes, and a rerun after apply converges to zero writes. The doctor pass\n" +
"never repairs - it reports and names this verb.\n",
"repair-lane":
'usage: o2b brain repair-lane [--apply --confirm "apply repair"] [--include-inferred] [--vault <path>] [--json]\n' +
"Deterministic memory-graph repair lane. Collects candidate edges from\n" +
"structural signals only (explicit references, session continuity, same-\n" +
"topic evidence), ordered by identity strength. Dry-run is the default and\n" +
"writes nothing; --apply writes edges and requires the exact confirmation\n" +
"phrase via --confirm. A confidence threshold and a hard per-run write cap\n" +
"bound the writes; existing edges are skipped, so a rerun converges to zero\n" +
"writes. Inferred candidates are opt-in behind --include-inferred.\n" +
"An explicit reference is a mention of a page title or alias that exactly\n" +
"one page carries; a term several pages carry binds to none of them and is\n" +
"reported as a skip-ambiguous decision naming each carrier.\n" +
"--apply is gated by the paired graph-efficacy holdout harness: every\n" +
"proposed edge is checked as an (anchor, target) holdout, graph lift is\n" +
"counted apart from direct recall, and the apply is refused without writing\n" +
"anything when any target resolves to no durable-memory note or hydrates\n" +
"into no evidence. Dry-run does not run the gate and is byte-identical; it\n" +
"already names each unresolvable endpoint as a skip-missing-target decision.\n",
agenda:
"usage: o2b brain agenda --events <file|-> [args]\n" +
"Deterministic agenda synthesis over caller-provided calendar events (JSON array or {events:[...]}).\n" +
"Reports overlap conflicts, free focus blocks, and external organizers. No vault writes.\n" +
" --events <file|-> event source; '-' reads stdin\n" +
" --focus-min <N> minimum free-gap minutes for a focus block (default 60)\n" +
" --owner-domain <D[,D2]> operator domain(s); organizers outside these are flagged\n" +
" --workday-start HH:MM --workday-end HH:MM clip focus blocks to a daily window\n" +
" [--json]\n",
"session-grep":
"usage: o2b brain session-grep --query <text> [--operation match] [--session-id <id>] [--limit <n>] [--snippet-chars <n>] [--since <t>] [--before <t>] [--vault <path>] [--json]\n" +
" o2b brain session-grep --operation coverage --char-budget <n> [--entity-key <key>] [--session-id <id>] [--vault <path>] [--json]\n" +
"Search imported session recall raw turns and summary nodes. --since and\n" +
"--before bound results to a time window (ISO date/datetime, today/\n" +
"yesterday/last week/last month, or <n>h/<n>d/<n>w); --before is inclusive.\n" +
"--operation coverage runs the coverage-first thread selection instead:\n" +
"facets detected from the thread, fanned out under the adaptive topic\n" +
"budget (floor 12, cap 16), selected under --char-budget, returned\n" +
"chronologically with selection diagnostics. A budget that cannot hold\n" +
"the floor-weighted selection is refused, never silently truncated.\n",
"session-describe":
"usage: o2b brain session-describe --session-id <id> [--topics] [--vault <path>] [--json]\n" +
"Describe counts and summary depths for an imported session recall DAG.\n" +
"--topics adds the adaptive topic-budget report (floor 12, cap 16).\n",
"session-expand":
"usage: o2b brain session-expand <record-id> [--raw-limit <n>] [--cursor <offset>] [--vault <path>] [--json]\n" +
"Expand a raw or summary session recall node to immediate sources and paginated raw turn content.\n",
lint:
"usage: o2b brain lint --consolidate [--apply] [--yes] [--vault <path>] [--json]\n" +
"Self-healing structural lint. Dry-run by default; --apply writes\n" +
"the smallest possible fix per finding. Two operations:\n" +
" fix-merged-link rewrite wikilinks pointing at a page that\n" +
" carries `merged_into:` to the canonical.\n" +
" demote-stale-stable demote `_lifecycle: stable` preferences\n" +
" older than 180 days with no recent\n" +
" evidence to `_lifecycle: draft`.\n" +
"Requires --yes in non-interactive mode (--json or non-TTY).\n",
validate:
"usage: o2b brain validate --paths <path> [--paths <path>...] [--strict] [--vault <path>] [--json]\n" +
" o2b brain validate --dirty [--strict] [--vault <path>] [--json]\n" +
"The standalone validation gate for hook-less writers. Runs the exact\n" +
"write-receipt page lint over exactly one caller-named page set -\n" +
"--paths (vault-relative, repeatable, one flag per page) or --dirty\n" +
"(every git-dirty Markdown note, modified, added and untracked) - and\n" +
"nothing else, so it is safe inside any gate. The exit code is the\n" +
"product, byte-for-byte the doctor contract: an error finding exits 1,\n" +
"warnings exit 2 under --strict, a named page the lint could not read\n" +
"exits 1, clean exits 0. Report-only: the fixes stay with `brain doctor\n" +
"--repair --apply` and `brain lint --consolidate --apply`, which every\n" +
"finding's next_command names.\n",
actions:
"usage: o2b brain actions [--top-n <n>] [--vault <path>] [--json]\n" +
"Ranked maintenance action list. Aggregates page-dedup, lint\n" +
"(dry-run), and token-footprint signals, scores each candidate\n" +
"action by impact (dedup count × weight, staleness × age,\n" +
"broken-link count, token-footprint excess), and prints the top N\n" +
"(default 10) sorted by impact descending. Read-only.\n",
summary:
"usage: o2b brain summary [--skip-dream] [--top-actions <n>] [--vault <path>] [--json]\n" +
"Operator dashboard. Aggregates trust verdict, doctor warnings/errors,\n" +
"dream uncertain/quarantined counts, verification delta, top maintenance\n" +
"actions, and instruction-file ceiling warnings into one report.\n" +
"Runs a dry-run dream pass by default; --skip-dream omits it. Read-only.\n",
unlinked:
"usage: o2b brain unlinked <id> [--limit <n>] [--vault <path>] [--json]\n" +
"Raw-text mentions of <id>'s title and frontmatter aliases that are NOT\n" +
"already inside a [[...]] wikilink. Match boundary is Unicode-aware\n" +
"(codepoint class), language-agnostic. Walks Brain/preferences/ and\n" +
"Brain/retired/. Read-only.\n",
synthesise:
"usage: o2b brain synthesise <id> [--include-unlinked] [--vault <path>] [--json]\n" +
"Assemble the concept-cluster envelope: target note + every artifact\n" +
"that wikilinks to it (depth-1). With --include-unlinked also include\n" +
"raw-text mentions outside [[...]]. Pure assembler, no LLM call. Output\n" +
"is a deterministic JSON envelope downstream consumers can feed to\n" +
"any synthesis prompt. Read-only.\n",
"moc-audit":
"usage: o2b brain moc-audit <hub-id> [--vault <path>] [--json]\n" +
"Per-MOC coverage audit. Given a hub note id, classifies cluster\n" +
"members into well-covered / fragile / candidate-missing buckets and\n" +
"surfaces a suggested-next candidate. MOC detection is purely\n" +
"structural (outbound link count + link density thresholds from\n" +
"_brain.yaml). Read-only.\n",
timeline:
"usage: o2b brain timeline [--pref-id <id>] [--topic <slug>]\n" +
" [--kind <event-kind>] [--since <iso>] [--until <iso>]\n" +
" [--limit <n>] [--vault <path>] [--json]\n" +
"Chronological list of Brain events filtered by any combination of\n" +
"pref-id / topic / kind / since / until / limit. Reads JSONL log via\n" +
"the canonical TimelineIndex. Read-only.\n",
evolution:
"usage: o2b brain evolution (--pref-id <id> | --topic <slug>)\n" +
" [--vault <path>] [--json]\n" +
"Per-preference or per-topic story: status transitions (creation,\n" +
"promotion, retirement) derived from dream summaries; evidence\n" +
"rollup with running applied / violated / outdated counts; retirement\n" +
"chain walked via supersedes / superseded_by links. Read-only.\n",
stale:
"usage: o2b brain stale [--vault <path>] [--json]\n" +
"Structural staleness report. Lists preferences, signals, and log\n" +
"files inactive longer than the configured `temporal:` thresholds\n" +
"(stale_pref_days / stale_signal_days / stale_log_days). Read-only.\n",
daily:
"usage: o2b brain daily [--date <YYYY-MM-DD>] [--vault <path>] [--json]\n" +
"Per-day deterministic brief: events grouped by kind, status\n" +
"transitions, vault delta, deduplicated artifact wikilinks. Defaults\n" +
"to today UTC. Read-only.\n",
weekly:
"usage: o2b brain weekly [--week-end <YYYY-MM-DD>] [--vault <path>] [--json]\n" +
"7-day deterministic synthesis: events by kind, status transitions,\n" +
"retired-in-window list, contradictions (signal-suppressed plus\n" +
"apply-evidence violated), vault delta, source pointers. Defaults to\n" +
"today UTC for week-end. Read-only.\n",
project:
"usage: o2b brain project <link|list|remove|status> [path] [--vault <path>] [--json]\n" +
"Link a project directory to its owning vault via a .o2b-vault.json pointer.\n" +
"resolveVault honours the nearest pointer above the working directory\n" +
"(VAULT_DIR still wins). status reports resolution mode and registry health.\n",
source:
"usage: o2b brain source <add|list|remove> [path|alias] [--alias <name>] [--vault <path>] [--json]\n" +
"Read-only recall sources of the active vault. add validates self-links,\n" +
"duplicates, and direct circular references; list flags missing targets\n" +
"as BROKEN. Distinct from `o2b brain sources` (signals dashboard).\n",
links:
"usage: o2b brain links normalize [path-prefix] [--mode preserve|full|short] [--write] [--json]\n" +
"Rewrite wikilink targets to the configured path format (wiki_link_format).\n" +
"Dry-run by default; decorations, code fences, and media embeds stay\n" +
"verbatim; ambiguous targets are reported and left as typed.\n",
profile:
"usage: o2b brain profile [--stale-seconds <n>] [--force] [--vault <path>] [--json]\n" +
"Materialize the compact Brain/profile.md digest plus the .o2bfs root\n" +
"marker. Age-gated: a fresh profile is left alone unless --force.\n",
sgrep:
"usage: o2b brain sgrep <query> [path-prefix] [--limit <n>] [--keyword-only] [--vault <path>] [--json]\n" +
"Grep-shaped semantic Brain search: path:line: output lines, path\n" +
"scoping, exit 1 on no matches (also in --json mode).\n",
trigger:
"usage: o2b brain trigger <scan|list|ack|dismiss|act|suppress|unsuppress|snooze|unsnooze|history> [id] [--status <s>] [--vault <path>] [--json]\n" +
"Grounded proactive trigger queue under Brain/triggers/. scan generates\n" +
"deduped triggers from health/retention data (cooldown via\n" +
"trigger_cooldown_days, default 7); ack/dismiss/act transition one\n" +
"trigger; history lists terminal ones. suppress silences a finding\n" +
"indefinitely - no cooldown clock, so it never re-nags - and unsuppress\n" +
"restores the status it interrupted along with its original cooldown.\n" +
"snooze defers a trigger until a bounded window ends or the finding\n" +
"fires again, whichever comes first; unsnooze wakes it by hand. A\n" +
"dismissed finding resurfaces only when it re-fires on changed\n" +
"source artifacts, not when a window elapses. list prints how many\n" +
"triggers are currently suppressed; every silenced recurrence is\n" +
"counted on the record (occurrences, last_seen_at).\n",
"deep-synthesis":
"usage: o2b brain deep-synthesis <topic> [--limit <n>] [--triggers] [--vault <path>] [--json]\n" +
"Deterministic topic dossier: matched notes, agreements, contradictions,\n" +
"stale claims, knowledge gaps. --triggers enqueues contradiction/gap\n" +
"findings into the trigger queue.\n",
ideas:
"usage: o2b brain ideas [--cap <n>] [--triggers] [--vault <path>] [--json]\n" +
"Ranked next-direction candidates from open questions, orphan notes,\n" +
"and aging inbox signals. --triggers enqueues the ranked ideas.\n",
continuity:
"usage: o2b brain continuity export --format atof|atif [--session <id>] [--month YYYY-MM] [--out <dir>] [--json]\n" +
" o2b brain continuity rank [--kind <kind>] [--limit N] [--all] [--json]\n" +
" o2b brain continuity promote [--month YYYY-MM] [--apply] [--approval-digest <hex>] [--json]\n" +
"Read-only trajectory export of the continuity store. atof renders one\n" +
"JSONL event stream; atif renders one trajectory document per session.\n" +
"Records flagged private are dropped; redacted text stays masked.\n" +
"rank lists working-memory continuity records by usage-driven decay\n" +
"weight (freshest and most-recalled first; default kind\n" +
"pre_compact_extract, --kind narrows, --all ranks every kind).\n" +
"promote renders host_memory_write records as unconfirmed preference\n" +
"pages under Brain/preferences/pref-hostmem-<record-id12>.md, dry-run\n" +
"by default: the per-record plan, named skips and a plan digest print,\n" +
"and --apply lands exactly that plan - non-interactively it must carry\n" +
"the dry run's --approval-digest. Every record is re-scanned under the\n" +
"export door's strict redaction grade and the masked text is what\n" +
"lands. The ledger stays write-only audit substrate; export remains\n" +
"the full-fidelity audit path.\n",
payload:
"usage: o2b brain payload get <osb-payload://sha256> [--offset N] [--limit N] [--json]\n" +
" o2b brain payload list [--json]\n" +
" o2b brain payload gc [--apply] [--json]\n" +
"Session import (--recall) moves data URIs, long base64 runs and turn text past\n" +
"sessions.payload_max_text_chars into Brain/.payloads/<sha256>.txt, leaving a\n" +
"[payload: osb-payload://<sha256> chars=N] placeholder. get pages the exact\n" +
"stored (redacted) content (default 4000 chars; raw to stdout without --json).\n" +
"list shows stored payloads, reference counts and missing refs. gc names payloads\n" +
"nothing in the vault references; --apply removes them behind a recovery point.\n",
session:
"usage: o2b brain session <open|submit|approve|abandon|status|list|sweep> [<session-id>] [flags]\n" +
"open --target <Brain/...md> [--schema-type S] [--intent create|overwrite|merge]\n" +
" [--prompt P] [--require-review] [--retry-cap N] open an artifact write session.\n" +
"submit <id> [--file F|-] submit the generated artifact (stdin without --file).\n" +
"approve <id> commit a needs-review session. abandon <id> terminal abandon.\n" +
"status <id> | list | sweep inspect or clean the session store.\n" +
"Envelopes are JSON with --json: status, step, prompt, errors, attempts_left.",
panel:
"usage: o2b brain panel <open <topic...>|submit <id>|status <id>|personas|\n" +
" persona-set <slug>|persona-remove <slug>> [flags]\n" +
"open <topic> [--personas a,b,c] [--target T] [--require-review] convene a\n" +
"decision panel; personas are the operator's custom ones (built-in default\n" +
"set: technical, strategic, risk, user-experience). Each submit answers the\n" +
"current persona step; after synthesis the decision note commits under\n" +
"Brain/decisions/panels/. The calling agent generates every word.\n" +
"personas [--json] list the personas in force. persona-set <slug> [--lens L]\n" +
"[--file F] add or replace a custom persona, its prompt read from F or\n" +
"stdin. persona-remove <slug> remove one. A custom persona is a note under\n" +
"Brain/personas/ before the store switch and a store record after it, so\n" +
"it reaches every machine of the store and needs no vault.",
architect:
"usage: o2b brain architect <project-path> [--vault V] [--progress] [--json]\n" +
"Scan a project tree deterministically (built-in runtime only, no dependency,\n" +
"no LLM) and write architecture notes under Brain/projects/arch/<repo-key>/:\n" +
"an overview, a key-decisions note listing this repo's ADR\n" +
"candidates, and one note per detected module.\n" +
"Dependency manifests (package.json, pyproject.toml, Cargo.toml, go.mod)\n" +
"are read at the root and at each module; pom.xml, build.gradle, Gemfile\n" +
"and composer.json are reported unsupported. Each manifest is read,\n" +
"malformed, unreadable or unsupported; --json lists them under\n" +
"`manifests`. A module whose manifest names exactly one other module's\n" +
"manifest gets a depends_on frontmatter key, which the generator owns.\n" +
"Generated content lives in sentinel regions; operator prose\n" +
"outside regions survives every re-scan byte-for-byte.\n" +
"--progress streams the walk and render stages to stderr.",
git:
"usage: o2b brain git <ingest|status|find|mine> [args] [--vault V] [--json]\n" +
"ingest <repo-path> [--max-count N] walk a worktree read-only, store\n" +
"commit/tag records + digest note under Brain/projects/git/<repo-key>/.\n" +
"status per-repo watermarks and record counts.\n" +
"find [text] [--repo K] [--file F] [--author A] [--since S] [--until U]\n" +
"[--limit N] query ingested history newest-first.\n" +
"mine [--repo K] surface decision-shaped commits as draft ADR\n" +
"candidate notes under Brain/decisions/candidates/ (skip-existing).",
bench:
"usage: o2b brain bench memory --fixture <name|path> [--suite <name>]\n" +
" [--pin <json>] [--recall-floor <n>] [--sample-seed <value>]\n" +
" [--sample-cap <n>] [--resume <run-id>] [--runs-dir <dir>] [--json]\n" +
"Memory quality benchmark over a disposable fixture vault under the\n" +
"runs directory (never the configured vault). Reports quality,\n" +
"latency, and context cost separately; checkpoint/resume by run id;\n" +
"bench_judge_cmd arms the optional external judge. Exit 1 on any\n" +
"failed question.\n" +
"--sample-seed V --sample-cap N with a sampling-capable suite\n" +
"(longmemeval): run a seeded, question-type-proportional subset of\n" +
"the dataset instead of the whole fixture. Both flags are required\n" +
"together and fold into the run identity, so a resumed run whose\n" +
"sampling options changed fails the identity guard.\n",
};