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
export interface CliFlagManifest {
readonly name: string;
readonly type: "boolean" | "string" | "string-array";
readonly inherited?: boolean;
}
export interface CliCommandManifest {
readonly name: string;
readonly summary: string;
readonly flags?: ReadonlyArray<CliFlagManifest>;
readonly commands?: ReadonlyArray<CliCommandManifest>;
}
export interface CliRootManifest {
readonly command: "o2b";
readonly flags: ReadonlyArray<CliFlagManifest>;
readonly commands: ReadonlyArray<CliCommandManifest>;
}
export const INHERITED_JSON_FLAG: CliFlagManifest = Object.freeze({
name: "json",
type: "boolean",
inherited: true,
});
/**
* The root synonym for `o2b version`. It is declared here and not only
* handled in `main.ts` because the completion scripts and `o2b help
* --json` are built from this manifest: a flag the manifest never heard
* of is a flag no shell offers.
*/
export const ROOT_VERSION_FLAG: CliFlagManifest = Object.freeze({
name: "version",
type: "boolean",
});
export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({
command: "o2b",
flags: [INHERITED_JSON_FLAG, ROOT_VERSION_FLAG],
commands: [
command("status", "Show Open Second Brain configuration status", [
flag("config", "string"),
flag("vault", "string"),
]),
command("init", "Initialize a vault profile", [
flag("vault", "string"),
flag("name", "string"),
flag("agent-name", "string"),
flag("timezone", "string"),
flag("force", "boolean"),
flag("interactive", "boolean"),
]),
command("doctor", "Run health checks on vault, config, and plugins", [
flag("vault", "string"),
flag("config", "string"),
flag("repo", "string"),
]),
command("onboarding", "Show the guided first-run setup checklist", [
flag("vault", "string"),
flag("config", "string"),
]),
command("export-config", "Write a redacted config snapshot", [
flag("config", "string"),
flag("output", "string"),
]),
command("index", "Regenerate the vault index from discovered pages", [flag("vault", "string")]),
command(
"mcp",
"Run the optional MCP tool server",
[
flag("vault", "string"),
flag("config", "string"),
flag("repo", "string"),
flag("scope", "string"),
flag("writer-only", "boolean"),
flag("tool-profile", "string"),
flag("host-target", "string"),
flag("harness", "string"),
flag("probe", "boolean"),
flag("allow-tool", "string-array"),
flag("disable-tool", "string-array"),
flag("max-tools", "string"),
],
[
// The management sub-dispatcher: routed before the server starts,
// so it is modelled here for help and completions even though it
// never reaches dispatchCommand as its own case.
command(
"token",
"Mint, rotate, revoke, or list per-agent MCP tokens",
[],
[
command("mint", "Mint one named token; the material is shown exactly once", [
flag("agent", "string"),
flag("name", "string"),
flag("vault", "string"),
flag("config", "string"),
]),
command("rotate", "Re-mint one named token; the new material is shown exactly once", [
flag("name", "string"),
flag("vault", "string"),
flag("config", "string"),
]),
command("revoke", "Revoke one named token; the material stops authenticating", [
flag("name", "string"),
flag("vault", "string"),
flag("config", "string"),
]),
command("list", "List tokens: names, agents, statuses, non-secret prefixes", [
flag("vault", "string"),
flag("config", "string"),
]),
],
),
],
),
command("version", "Print the installed Open Second Brain version"),
command("help", "Print command help or the command manifest"),
command("completions", "Print shell completion script for o2b", [flag("shell", "string")]),
command("install-cli", "Create symlinks for o2b and vault-log"),
// The whole flag set, not only the two the friction mode added:
// `tests/cli/help-surface-parity.test.ts` renders the human help from
// this list, so declaring one flag on a verb that parses twelve would
// advertise a surface narrower than the verb's own argument parser.
command("install", "Multi-runtime install orchestrator", [
flag("target", "string"),
flag("apply", "boolean"),
flag("check", "boolean"),
// The consent flag the apply lane takes (t_b6bcd984): without it a
// --json/non-TTY apply refuses, so help and completions must offer
// the remedy.
flag("yes", "boolean"),
// Declaring `json` here (the refusal above names it) stops
// addInheritedFlagsToCommand appending the inherited stand-in, so
// the verb models the flag its own parser takes.
flag("json", "boolean"),
flag("friction", "boolean"),
flag("base", "string"),
flag("compare", "string"),
flag("dry-run", "boolean"),
flag("force", "boolean"),
flag("out", "string"),
flag("format", "string"),
flag("vault", "string"),
flag("config", "string"),
]),
command("update", "Update Open Second Brain across detected runtimes", [
flag("target", "string"),
flag("dry-run", "boolean"),
flag("force", "boolean"),
]),
// The whole parseFlags schema, for the reason the `o2b install`
// entry above gives: the human help renders from this list, so an
// unmodelled flag is a flag neither help nor completions can offer.
command(
"bootstrap",
"One-command harness provisioning: idempotent MCP registration, a named per-agent MCP token shown exactly once, and a bootstrap receipt; --rotate re-mints",
[
flag("target", "string"),
flag("agent", "string"),
flag("token", "boolean"),
flag("rotate", "boolean"),
flag("check", "boolean"),
flag("force", "boolean"),
flag("vault", "string"),
flag("config", "string"),
],
),
command("uninstall", "Print or apply an uninstall plan", [
flag("config", "string"),
flag("apply-local", "boolean"),
flag("remove-cli", "boolean"),
flag("target", "string"),
]),
command("tool-call", "Invoke an MCP tool handler from the CLI", [
flag("vault", "string"),
flag("tool-arg", "string-array"),
]),
command(
"secrets",
"Inspect $secret:NAME references without printing values",
[],
[
command("list", "List $secret:NAME references found in the config", [
flag("config", "string"),
flag("vault", "string"),
flag("json", "boolean"),
]),
command("status", "Report whether each referenced secret resolves", [
flag("config", "string"),
flag("vault", "string"),
flag("json", "boolean"),
]),
],
),
command(
"aider",
"Session-bracketing memory wrapper for Aider",
[],
[
command("wrap", "Run Aider bracketed with live memory load + write-back", [
flag("session-id", "string"),
flag("aider-bin", "string"),
flag("chat-history", "string"),
flag("vault", "string"),
flag("config", "string"),
]),
],
),
command(
"brain",
"Brain memory verbs",
[],
[
command("init", "Bootstrap Brain skeleton"),
command("feedback", "Record a taste signal", [
flag("vault", "string"),
flag("topic", "string"),
flag("signal", "string"),
flag("principle", "string"),
flag("scope", "string"),
flag("source", "string-array"),
flag("agent", "string"),
flag("raw", "string"),
flag("raw-file", "string"),
flag("force-confirmed", "boolean"),
flag("date", "string"),
flag("slug", "string"),
flag("expires", "string"),
]),
command(
"dream",
"Run deterministic consolidation; staged lifecycle via stage/validate/apply, " +
"retriage re-runs the salience gate over a staged bundle; " +
"--step runs one independently-runnable step, --gate overrides a phase gate for one run",
[flag("step", "string"), flag("gate", "string-array")],
),
command("apply-evidence", "Record preference evidence"),
command("note", "Append a narrative milestone"),
command("digest", "Render recent Brain transitions"),
command("intent-review", "Review signal clusters before dream"),
command("retention", "Review retired preference retention"),
command("monthly", "Render month-level Brain synthesis"),
command("query", "Read preferences, topics, and logs", [
flag("vault", "string"),
flag("preference", "string"),
flag("topic", "string"),
flag("since", "string"),
flag("at", "string"),
flag("show-expired", "boolean"),
]),
command("agent-query", "Read source-agent provenance"),
command("agent-diff", "Compare source-agent coverage"),
command(
"writes",
"Recorded note writes: list (default), destinations, revert, prune-images",
[
flag("vault", "string"),
flag("agent", "string"),
flag("device", "string"),
flag("path", "string"),
flag("since", "string"),
flag("until", "string"),
flag("op", "string"),
flag("apply", "string"),
flag("json", "boolean"),
],
[
command("list", "Recorded note writes, newest first", [
flag("vault", "string"),
flag("agent", "string"),
flag("device", "string"),
flag("path", "string"),
flag("since", "string"),
flag("until", "string"),
flag("op", "string"),
flag("json", "boolean"),
]),
command("destinations", "Fold the write ledger into one row per destination", [
flag("vault", "string"),
flag("agent", "string"),
flag("device", "string"),
flag("path", "string"),
flag("since", "string"),
flag("until", "string"),
flag("limit", "string"),
flag("json", "boolean"),
]),
command("revert", "Plan, and with --apply run, a per-agent undo of note writes", [
flag("vault", "string"),
flag("agent", "string"),
flag("device", "string"),
flag("path", "string"),
flag("since", "string"),
flag("until", "string"),
flag("apply", "string"),
flag("json", "boolean"),
]),
command("prune-images", "Remove before-images past a retention window", [
flag("vault", "string"),
flag("older-than-days", "string"),
flag("dry-run", "boolean"),
flag("json", "boolean"),
]),
],
),
command("reject", "Retire a preference"),
command("merge", "Merge duplicate preferences"),
command("freeze", "Stop every content write on every device", [
flag("vault", "string"),
flag("reason", "string"),
flag("json", "boolean"),
]),
command("unfreeze", "Lift the freeze and reopen the content lane", [
flag("vault", "string"),
flag("json", "boolean"),
]),
command(
"permissions",
"Show the trust policy document and query the decision ledger",
[],
[
command("show", "Render the permissions document and a dry-run decision table", [
flag("vault", "string"),
flag("json", "boolean"),
]),
command("ledger", "List decision ledger rows with filters", [
flag("vault", "string"),
flag("actor", "string"),
flag("action", "string"),
flag("verdict", "string"),
flag("since", "string"),
flag("until", "string"),
flag("limit", "string"),
flag("json", "boolean"),
]),
],
),
command(
"log",
"Inspect Brain/log itself: verify (per-shard hash chain)",
[],
[
command("verify", "Report where each log shard stops linking up", [
flag("vault", "string"),
flag("json", "boolean"),
]),
],
),
command(
"attest",
"Ed25519-signed store attestations: keygen, sign, list, verify",
[flag("vault", "string"), flag("json", "boolean"), flag("passphrase-from-env", "string")],
[
command("keygen", "Generate the operator's Ed25519 attestation keypair", []),
command("sign", "Seal, sign and write one store attestation", []),
command("list", "Every attestation, newest first", []),
command("verify", "Re-measure the store against the newest attestation", []),
],
),
command("pin", "Pin a preference"),
command("unpin", "Unpin a preference"),
command("set-primary", "Set primary Brain agent"),
command(
"settings",
"Read and change the shared brain settings",
[flag("vault", "string"), flag("agent", "string"), flag("json", "boolean")],
[
command("get", "Show one shared brain setting"),
command("set", "Set one shared brain setting"),
command("unset", "Remove one shared brain setting; its default applies"),
command("list", "List the shared brain settings that are set"),
],
),
command("protect", "Emit runtime deny rules for Brain", [
flag("target", "string"),
flag("vault", "string"),
flag("apply", "boolean"),
flag("yes", "boolean"),
flag("json", "boolean"),
]),
command("unprotect", "Remove managed runtime deny rules", [
flag("target", "string"),
flag("vault", "string"),
flag("apply", "boolean"),
flag("yes", "boolean"),
flag("json", "boolean"),
]),
command(
"snapshot",
"Inspect Brain snapshots",
[],
[
command("log", "Newest-first listing of every recovery point with its reason", [
flag("vault", "string"),
flag("reason", "string"),
flag("limit", "string"),
]),
command("diff", "Read-only diff between two snapshots, or snapshot vs live", [
flag("vault", "string"),
]),
],
),
command("rollback", "Restore Brain from a snapshot"),
command("upgrade", "Migrate release-owned Brain files"),
command("export", "Export active preferences or a session-transcript dataset", [
flag("vault", "string"),
flag("format", "string"),
flag("transcripts", "string"),
flag("runtime", "string"),
flag("since", "string"),
flag("until", "string"),
flag("out", "string"),
flag("force", "boolean"),
]),
command("explorer", "Open or export Brain graph explorer"),
command("doctor", "Check Brain invariants"),
command("status", "Unified operator status snapshot with next-command hints", [
flag("vault", "string"),
flag("json", "boolean"),
]),
command("hygiene", "Hygiene pipeline: scan findings, apply remediation plan"),
command("refresh", "Targeted recompile of stale derived pages"),
command("anticipate", "Inspect or refresh the anticipatory context cache"),
command("watchdog", "Probe Brain recovery status"),
command("health", "Render semantic Brain health"),
command("history", "Render preference edit history"),
command("activation", "Activation event store: status and sweep"),
command("truth", "Claim ledger: slots, conflicts, aggregate, collisions"),
command("facts", "Decompose text into atomic assertions"),
command("dead-end", "Record or list failed approaches"),
command("foresight", "Render forward-looking projection"),
command("label", "Assign, remove, show or suggest controlled-vocabulary labels"),
command("attr", "Assign, remove, or show typed-page attribute fields"),
command("tiers", "Check, restore, or accept identity-field drift"),
command(
"secret",
"Capability-gated secret custody: set, list, rm, run, lock, unlock, export, import",
),
command(
"maintenance",
"Quiet-window, lease-guarded heavy maintenance lane",
[],
[
// The whole `run` schema: the lane is the cron entry point, and
// `--cron-template` is the only way to reach its recipe, so a
// flag missing here would be missing from help and completions.
command(
"run",
"Run the lane tasks behind its gates, or print a cron or systemd recipe with --cron-template (writes nothing)",
[
flag("vault", "string"),
flag("force", "boolean"),
flag("retry", "string-array"),
flag("window", "string"),
flag("tz", "string"),
flag("busy-minutes", "string"),
flag("busy-threshold", "string"),
flag("agent", "string"),
flag("progress", "boolean"),
flag("json", "boolean"),
flag("force-cost", "boolean"),
flag("cron-template", "boolean"),
flag("interval", "string"),
flag("format", "string"),
],
),
command("status", "Render the lane lease holder and recent journal", [
flag("vault", "string"),
flag("limit", "string"),
flag("json", "boolean"),
]),
],
),
command(
"receipts",
"Receipt compaction surfaces: scan the continuity and metrics ledgers, fold expired records on compact",
[
flag("vault", "string"),
flag("agent", "string"),
flag("shard", "string-array"),
flag("older-than-days", "string"),
flag("apply", "boolean"),
flag("expect", "string"),
flag("strict", "boolean"),
flag("json", "boolean"),
],
),
command(
"storage",
"Render the vault storage report: usage per surface and the forecast tier against the cap",
[flag("vault", "string"), flag("json", "boolean")],
),
command(
"changes",
"List brain store record ids new since a watermark, grouped by stream, scope and topic",
[
flag("vault", "string"),
flag("since", "string"),
flag("limit", "string"),
flag("json", "boolean"),
],
),
command(
"migrate-store",
"Move the legacy brain into the brain store on this machine (--dry-run plans it and writes nothing; --resume continues an interrupted run)",
[
flag("vault", "string"),
flag("dry-run", "boolean"),
flag("resume", "boolean"),
flag("rollback", "boolean"),
flag("wait", "string"),
flag("remove-legacy", "boolean"),
flag("force-release-gate", "boolean"),
flag("force", "boolean"),
flag("json", "boolean"),
],
),
command("audit", "Render mutation audit trail"),
command(
"generation-reports",
"Record/list/summarize opt-in inbound LLM generation traces",
[],
[
command("record", "Record one gated inbound generation report"),
command("list", "List generation report records"),
command("summary", "Summarize generation usage with memory linkage"),
command("show", "Show one generation report record"),
],
),
command("morning-brief", "Render session-start summary"),
command("codec", "Compress or expand session prose"),
command("sources", "Show signal source dashboard"),
command(
"schema",
"Inspect Brain schema vocabulary",
[flag("vault", "string")],
[
command("report", "Inspect Brain schema vocabulary", [flag("vault", "string")]),
command("stats", "Summarise Brain schema vocabulary", [flag("vault", "string")]),
command("lint", "Lint Brain schema vocabulary", [flag("vault", "string")]),
command("graph", "Render Brain schema graph", [flag("vault", "string")]),
command("explain", "Explain a Brain schema token", [flag("vault", "string")]),
command("orphans", "Review unused Brain schema declarations", [
flag("vault", "string"),
]),
command("apply", "Apply audited Brain schema mutations", [
flag("vault", "string"),
flag("mutation", "string-array"),
flag("actor", "string"),
flag("reason", "string"),
]),
command("sync", "Brain schema sync (not implemented; refuses)", [
flag("vault", "string"),
flag("dry-run", "boolean"),
flag("batch-size", "string"),
]),
],
),
command("graph-export", "Export vault graph"),
command("graph-import", "Import vault graph stubs"),
command("backlinks", "List inbound Brain references"),
command("semantics-backfill", "Preview Brain semantics backfill"),
command("mcp-landscape", "List MCP servers configured across the vault"),
command("scan-inline", "Capture inline @osb markers"),
command("scan-citations", "Promote inline [Source: ...] citations to dated events", [
flag("vault", "string"),
flag("dry-run", "boolean"),
flag("strict", "boolean"),
flag("path", "string-array"),
flag("exclude", "string-array"),
flag("agent", "string"),
flag("json", "boolean"),
]),
// Every flag the parser accepts, following the `o2b install`
// precedent from earlier in this release: advertising a narrower
// surface than the parser takes is the discoverability dead end
// `manifest-completeness.test.ts` exists to prevent, and this
// verb declared none of the thirteen it already parsed.
command("import-session", "Replay registered agent sessions", [
flag("vault", "string"),
flag("format", "string"),
flag("since", "string"),
flag("dry-run", "boolean"),
flag("agent", "string"),
flag("recall", "boolean"),
flag("recall-session-id", "string"),
flag("recall-summary-group-size", "string"),
flag("ingest-scope", "string"),
flag("filter-role", "string-array"),
flag("filter-text", "string"),
flag("preserve-event-time", "boolean"),
flag("discover", "boolean"),
flag("status", "boolean"),
flag("all", "boolean"),
flag("propose-backlog", "boolean"),
flag("progress", "boolean"),
flag("json", "boolean"),
]),
command("handoff", "Write an operator-readable session handoff note"),
command("intention", "Manage scoped current-intention chains"),
command("project", "Link project directories to their owning vault"),
command("source", "Manage read-only recall sources of the active vault"),
command(
"forget-source",
"Find and delete entries derived from an exact source file (dry-run by default)",
[
flag("vault", "string"),
flag("confirm", "boolean"),
flag("include-originals", "boolean"),
flag("json", "boolean"),
],
),
command(
"batch-plan",
"Plan a large-folder ingest into bounded parallel batches (skips unchanged sources)",
[
flag("vault", "string"),
flag("max-bytes", "string"),
flag("max-files", "string"),
flag("reconcile", "boolean"),
flag("json", "boolean"),
],
),
command(
"pre-extract",
"Extract deterministic code structure (classes/functions/imports/inheritance, Terraform blocks/references) from a source file as JSON seeds",
[flag("json", "boolean")],
),
command(
"extract",
"Preview what ingest derives from one source file (HTML title, text and parts; CSV or TSV table note), or why it derives nothing",
[flag("json", "boolean")],
),
command("links", "Normalize wikilink path format across Brain notes"),
command("bridges", "Propose, accept, or dismiss embedding-near bridge links"),
command("clusters", "Detect link-graph communities and materialize cluster notes"),
command(
"co-occurrence",
"Suggest edges between entities co-referenced from the same notes",
),
command(
"hallways",
"Session-mined association pass over the mention ledger: mine, show, promote, dismiss",
),
command("file-context", "Surface prior vault work that mentions a file path"),
command("benchmark", "Score recall quality against a fixed query dataset"),
command("tune", "Grid-evaluate and persist self-tuning recall parameters"),
command("profile", "Materialize the compact Brain/profile.md digest"),
command("sgrep", "Grep-shaped semantic Brain search (path:line: output)"),
command("continuity", "Export continuity records as ATOF/ATIF trajectories"),
command(
"payload",
"Read, list, and collect externalized session payloads",
[],
[
command("get", "Page the exact content of one payload ref", [
flag("vault", "string"),
flag("offset", "string"),
flag("limit", "string"),
flag("json", "boolean"),
]),
command("list", "List stored and missing payloads with reference counts", [
flag("vault", "string"),
flag("json", "boolean"),
]),
command("gc", "Remove unreferenced payloads (dry-run by default)", [
flag("vault", "string"),
flag("apply", "boolean"),
flag("json", "boolean"),
]),
],
),
command("bench", "Memory quality benchmark over a disposable fixture vault"),
command("git", "Git history as project memory: ingest, status, find, mine"),
command("architect", "Deterministic architecture notes for a code project"),
command(
"session",
"Agent write sessions: open, submit, approve, abandon, status, list, sweep",
),
command("panel", "Multi-persona decision panel riding the write-session kernel"),
command(
"trigger",
"Grounded proactive trigger queue (scan/list/ack/dismiss/act/suppress/unsuppress/snooze/unsnooze/history)",
),
command("deep-synthesis", "Topic dossier: agreements, contradictions, stale claims, gaps"),
command("ideas", "Ranked next-direction candidates from open loops"),
command(
"entity",
"Canonical entity registry: set, get, list, relate, archive, prune, lexicon, merge",
),
command("session-hook", "Capture runtime lifecycle hook payloads"),
command("import-claude-memory", "Import Claude memory feedback"),
// no-dead-ends, task 6: the fifty-five brain cases the manifest
// never modelled, so neither shell completions nor `o2b help
// --json` could name them. Listed in dispatcher order; the
// ratchet in `tests/cli/manifest-completeness.test.ts` reads the
// dispatcher, so a fifty-sixth cannot land unlisted.
command(
"lifecycle",
"Tombstone or supersede a memory, resolve chain tips, list curator slices",
),
command("expire", "Set, change or clear a signal's or preference's expiration date", [
flag("vault", "string"),
flag("expires", "string"),
flag("agent", "string"),
]),
command(
"note-lifecycle",
"Note FILES or whole FOLDERS: rename, move, archive or delete a file, move-folder or rename-folder a folder, rewriting inbound wikilinks",
[
flag("vault", "string"),
flag("config", "string"),
flag("apply", "boolean"),
flag("confirm", "boolean"),
flag("delete-linked", "boolean"),
flag("expect", "string"),
flag("strict", "boolean"),
],
),
command(
"scaffold-stub",
"Unresolved wikilink targets: list them from the index, or materialise a stub",
[
flag("vault", "string"),
flag("config", "string"),
flag("path", "string"),
flag("source", "string-array"),
flag("if-exists", "string"),
flag("limit", "string"),
flag("apply", "boolean"),
],
),
command(
"claims",
"Claim-graph query: current truth, truth at an instant, replaced-by, contested-by",
),
command(
"decision",
"Decision records: record, outcome, rate, show, list, compare, similar, history, recall, open, list_open, show_open, resolve, discard",
),
command(
"tension",
"Detect and triage persisted contradictions: detect, list, show, confirm, dismiss, resolve, verify",
),
command("state", "Overwrite-only exact-state lane keyed by aspect: set, get, list, clear"),
command(
"health-baseline",
"Acknowledge-before watermark for health advisories: set, get, clear",
),
command(
"vitals",
"Governance scorecard: domain diversity, connectivity, orphans, gap pressure",
),
command(
"bank-export",
"Serialise a whole-vault bank bundle: preferences, graph, pages, sources",
),
command("bank-import", "Reconstruct the page graph and preferences from a bank bundle"),
command(
"authored-at-backfill",
"Backfill authored_at on session-imported signals (dry-run by default)",
),
command(
"privacy-marker-restamp",
"Restamp informal privacy markers as visibility: private (dry-run by default)",
[flag("vault", "string"), flag("apply", "boolean")],
),
command(
"distill",
"Condense a source into agent-supplied atomic claims with block provenance and checked quotes",
[
flag("vault", "string"),
flag("agent", "string"),
flag("claims", "string"),
flag("claims-file", "string"),
flag("strict-quotes", "boolean"),
flag("excerpt-file", "string"),
],
),
command("session-summary", "Session-scoped structured digest: write, get, list"),
command(
"idea-lineage",
"Trace how a derived artifact was reached: observation, synthesis, conclusion",
),
command("note-history", "Decompose a note's git history into episodic phases"),
command(
"diarize",
"Subject profile: document set, stated-versus-evidenced gap, needs-LLM skeleton",
),
command(
"design-note",
"One-shot design note grounded in tension, decision, and truth records",
[
flag("vault", "string"),
flag("agent", "string"),
flag("payload", "string"),
flag("payload-file", "string"),
],
),
command(
"extract-signals",
"Mine taste signals from an imported session's user turns (two-phase, needs-LLM)",
[
flag("vault", "string"),
flag("agent", "string"),
flag("payload", "string"),
flag("payload-file", "string"),
],
),
command(
"dead-letters",
"Dead extraction writes: list with each row's recovery exit, show, recover (dry-run; --apply --yes to write)",
[],
[
command("list", "Every dead letter with its classification and recovery command", [
flag("vault", "string"),
flag("json", "boolean"),
]),
command("show", "One dead letter in full detail", [
flag("vault", "string"),
flag("json", "boolean"),
]),
command("recover", "Re-run a letter's frozen payload at current vault state", [
flag("vault", "string"),
flag("agent", "string"),
flag("dry-run", "boolean"),
flag("apply", "boolean"),
flag("yes", "boolean"),
flag("json", "boolean"),
]),
],
),
command("okf-export", "Write a portable Open Knowledge Format bundle"),
command(
"okf-import",
"Import an Open Knowledge Format bundle (staged for review by default)",
),
command(
"knowledge-pack",
"Export, preview, install, uninstall and list portable knowledge packs",
),
command("page-dedup", "Detect, and optionally merge, near-duplicate vault pages"),
command("token-footprint", "Report per-category vault token size against a warn threshold"),
command("context-pack", "Return a tier-then-recency vault slice under a token budget"),
command("context-receipts", "List, show, or re-hash-verify prompt context receipt records"),
command(
"event-trace",
"Join logged events to the continuity records sharing their correlation ids",
),
command("context-presets", "Show, suggest, or diff read-only context budget presets"),
command(
"pre-compact-extract",
"Extract typed continuity records from bounded session text",
),
command(
"post-compact-audit",
"Audit pinned-anchor survival after a compaction and re-assert drifted anchors",
),
command("recall-telemetry", "List, summarize, or cost opt-in recall telemetry records"),
command("knowledge-gaps", "Rank recurring queries the vault answers poorly"),
command(
"skill-proposals",
"Learn, list, review, and recover skill proposals, including drafts from mature pages and benchmark-gated rewrites",
[flag("vault", "string"), flag("payload", "string"), flag("payload-file", "string")],
[
command("rewrite-plan", "Print a rewrite round's frozen receipt and dev envelopes", [
flag("vault", "string"),
flag("candidate-file", "string"),
flag("skills-root", "string"),
flag("json", "boolean"),
]),
command("rewrite-score", "Score submitted rewrite rounds and gate the verdict", [
flag("vault", "string"),
flag("rounds-dir", "string"),
flag("candidate-file", "string"),
flag("skills-root", "string"),
flag("json", "boolean"),
]),
],
),
command("procedural-memory", "Reconcile or list the procedural memory index and its usage"),
command("procedural-graph", "Rebuild or show the procedural graph and hint projections"),
command("recurrence", "Inspect and update recurrence and support diagnostics"),
command("attention-flows", "Declarative attention recipes over open loops and learnings"),
command("obligation", "Recurring obligations with cadence-driven next-due dates"),
command("agenda", "Synthesize agenda conflicts and focus blocks from provided events"),
command("today", "Today dashboard: due obligations, open loops, recent activity, totals"),
command("apply-markers", "Apply @osb set frontmatter write-backs (report by default)"),
command(
"pending",
"Review the write-approval queue: list, apply, reject",
[],
[
command("list", "List the staged entries awaiting approval, all lanes", [
flag("vault", "string"),
flag("lane", "string"),
flag("json", "boolean"),
]),
command("apply", "Move one staged entry into its publish target unchanged", [
flag("vault", "string"),
flag("dry-run", "boolean"),
flag("json", "boolean"),
]),
command("reject", "Retire one staged entry with a recorded reason", [
flag("vault", "string"),
flag("reason", "string"),
flag("dry-run", "boolean"),
flag("json", "boolean"),
]),
],
),
command("signal", "Fact signal lifecycle: retire a signal with a reason"),
command("capture", "Stage one capture from the terminal: body, source, sender, guidance", [
flag("vault", "string"),
flag("source", "string"),
flag("sender", "string"),
flag("guidance", "string"),
flag("agent", "string"),
flag("at", "string"),
]),
command("telegram-capture", "Inbound Telegram capture bot: long-poll run or catchup"),
command("inbox-drain", "Classify and route staged captures (dry-run by default)"),
command(
"repair-lane",
"Propose memory-graph edges (dry-run by default); --apply is holdout-gated",
[
flag("vault", "string"),
flag("apply", "boolean"),
flag("confirm", "string"),
flag("include-inferred", "boolean"),
],
),
command(
"orphan-repair",
"Detach dangling session references from observations (dry-run by default)",
[flag("vault", "string"), flag("apply", "boolean"), flag("confirm", "string")],
),
command(
"session-grep",
"Search imported session recall turns and summaries; --operation coverage selects whole-thread coverage",
[
flag("operation", "string"),
flag("char-budget", "string"),
flag("entity-key", "string"),
],
),
command("session-describe", "Describe an imported session recall DAG", [
flag("topics", "boolean"),
]),
command("session-expand", "Expand a session recall node to its source turns"),
command("lint", "Self-healing structural checks; --consolidate --apply writes the fixes", [
flag("vault", "string"),
flag("consolidate", "boolean"),
flag("apply", "boolean"),
flag("yes", "boolean"),
]),
command(
"validate",
"Standalone validation gate over --paths or git-dirty notes; errors exit 1, --strict warnings exit 2",
[
flag("paths", "string-array"),
flag("dirty", "boolean"),
flag("strict", "boolean"),
flag("vault", "string"),
flag("json", "boolean"),
],
),
command(
"actions",
"Ranked maintenance action list over dedup, lint, and footprint findings",
),
command("summary", "Operator dashboard: trust verdict, doctor and dream counts, actions"),
command(
"unlinked",
"Raw-text mentions of an artifact's title or aliases outside wikilinks",
),
command(
"synthesise",
"Concept cluster: a target plus its depth-1 linkers, optionally mentions",
),
command("moc-audit", "Per-MOC coverage audit: well-covered, fragile, candidate-missing"),
command(
"timeline",
"Chronological event list filtered by preference, topic, kind, or date",
),
command(
"evolution",
"Per-preference or per-topic story: status transitions, evidence, retire",
),
command("stale", "Stale preferences, signals, and log files against configured thresholds"),
command("daily", "Daily brief: events by kind, status transitions, vault delta"),
command("weekly", "Seven-day synthesis: transitions, retired, contradictions, vault delta"),
// t_1e952e43: operator-approved lesson promotion into agent rules
// files. Operator-only; no MCP tool exposes these subcommands.
command(
"lessons",
"Operator-approved lesson promotion: candidates | approve <pref-id> | deny <pref-id> | refresh-blocks",
[flag("vault", "string"), flag("target", "string-array")],
[
command("candidates", "List promotable lessons and blocked ones with reasons", [
flag("vault", "string"),
]),
command("approve", "Approve a lesson and write it into the named agent rules files", [
flag("target", "string-array"),
flag("apply", "boolean"),
flag("yes", "boolean"),
flag("force", "boolean"),
flag("vault", "string"),
]),
command("deny", "Record a denial; the lesson is suppressed from promotion", [
flag("apply", "boolean"),
flag("yes", "boolean"),
flag("vault", "string"),
]),
command(
"refresh-blocks",
"Re-render managed lessons blocks (dry run by default; never creates a block)",
[
flag("apply", "boolean"),
flag("yes", "boolean"),
flag("force", "boolean"),
flag("vault", "string"),
],
),
],
),
],
),
command(
"decision-model",
"Inspect the optional decision-model feature (off unless enabled with a key)",
[],
[
command(
"check",
"Show the decision-model config, the key variable's name and whether it is set; --ping sends one synthetic request",
[flag("vault", "string"), flag("config", "string"), flag("ping", "boolean")],
),
command(
"report",
"Summarise decision_model_call records per use: outcomes, latency, tokens, cost, rerank shadow agreement",
[
flag("vault", "string"),
flag("config", "string"),
flag("since", "string"),
flag("use", "string"),
],
),
command(
"eval",
"Run or list the preregistered per-use evals (real spend; a promote writes the machine-side tuning mark)",
[],
[
command(
"run",
"Grade the preregistered take for --use over the configured adapter; a promote verdict marks the profile-use pair tuned",
[flag("use", "string"), flag("vault", "string"), flag("config", "string")],
),
command(
"list",
"List cached decision_model_eval_grade records, oldest first; malformed records are skipped with a named note",
[
flag("use", "string"),
flag("since", "string"),
flag("vault", "string"),
flag("config", "string"),
],
),
],
),
command(
"thresholds",
"The local per-model thresholds store next to config.yaml (issue #264)",
[],
[
command(
"fit",
"Derive a use's threshold from its labelled report data against a false-action target and write it for the answering model",
[
flag("use", "string"),
flag("target", "string"),
flag("since", "string"),
flag("vault", "string"),
flag("config", "string"),
],
),
command(
"list",
"List the stored thresholds by model and use, with per-vault overrides and kept history",
[flag("vault", "string"), flag("config", "string")],
),
command(
"set",
"Write one threshold by hand for a model and use; existing entries keep their history",
[
flag("model", "string"),
flag("use", "string"),
flag("value", "string"),
flag("name", "string"),
flag("vault", "string"),
flag("config", "string"),
],
),
],
),
],
),
command(
"search",
"Search the vault index",
[],
[
// Declared in the order `cmdSearchQuery` parses them. There is no
// per-verb `--help` for the search verbs, so `o2b help` is the only
// place these are discoverable; a partial list here reads as
// complete, so the whole `parseFlags` schema is modelled and
// `tests/cli/search-query-flag-manifest.test.ts` holds it to that.
command("query", "Search the vault index", [
flag("vault", "string"),
flag("config", "string"),
flag("db", "string"),
flag("limit", "string"),
flag("semantic", "boolean"),
flag("keyword-only", "boolean"),
flag("match-mode", "string"),
flag("kind", "string"),
flag("source", "string"),
flag("path", "string"),
flag("keyword-weight", "string"),
flag("semantic-weight", "string"),
flag("auto-refresh", "boolean"),
flag("property", "string-array"),
flag("degree", "string-array"),
flag("visibility", "string-array"),
flag("agent-scope", "string"),
flag("query-doc", "string"),
flag("expand", "boolean"),
flag("disclosure", "string"),
flag("profile", "string"),
flag("evidence-pack", "boolean"),
flag("include-superseded", "boolean"),
flag("since", "string"),
flag("until", "string"),
flag("global", "boolean"),
flag("no-record-access", "boolean"),
flag("verbose", "boolean"),
flag("explain", "boolean"),
]),
// Both builders declare their whole `parseFlags` schema for the
// same reason `query` does, and `tests/cli/search-query-flag-manifest.test.ts`
// holds all three to it: `--cron-template` and `--interval` were
// parsed by `reindex` and advertised nowhere, so neither help nor
// completions could offer the recipe this CLI knows how to print.
command("index", "Incrementally update the search index", [
flag("vault", "string"),
flag("config", "string"),
flag("db", "string"),
flag("embeddings", "boolean"),
flag("force", "boolean"),
flag("force-cost", "boolean"),
flag("concurrency", "string"),
flag("verbose", "boolean"),
flag("progress", "boolean"),
flag("freshen", "string"),
flag("freshen-state", "string"),
]),
command("reindex", "Rebuild the search index", [
flag("vault", "string"),
flag("config", "string"),
flag("db", "string"),
flag("embeddings", "boolean"),
flag("force-cost", "boolean"),
flag("concurrency", "string"),
flag("verbose", "boolean"),
flag("progress", "boolean"),
flag("cron-template", "boolean"),
flag("interval", "string"),
flag("format", "string"),
flag("self-heal", "string"),
]),
command("watch", "Watch the vault and incrementally sync the index on .md edits"),
command("status", "Print search index status"),
command(
"check",
"Run search pre-flight diagnostics; --integrity adds a full structural scan of the index file, --no-probe skips the live embedding-provider call",
// The whole schema, for the reason the three verbs above give:
// the vault-addressing triple was parsed here and advertised
// nowhere, so `o2b help --json` - the only discovery surface
// these verbs have - said this verb took nothing but --json.
[
flag("vault", "string"),
flag("config", "string"),
flag("db", "string"),
flag("integrity", "boolean"),
flag("no-probe", "boolean"),
],
),
command("provider", "Manage embedding provider profiles"),
command("expand", "Drill a search card into the fuller note and its raw chunk transcript"),
command("focus", "Set, show, or clear the session recall focus bias"),
command("feedback", "Record a relevance verdict for one recall result"),
command("weights", "Show or reset the learned hybrid ranking weights"),
command("rerank-provider", "Manage reranker provider profiles"),
command("rerank-fit", "Diagnose whether the configured reranker fits this vault's queries"),
command(
"rerank-eval",
"Benchmark rerank off against a reranker kind over a labelled dataset (hit@k and MRR deltas)",
[
flag("vault", "string"),
flag("config", "string"),
flag("db", "string"),
flag("dataset", "string"),
flag("kind", "string"),
flag("k", "string"),
flag("compare-local", "boolean"),
],
),
command("plan", "Preview the should-read shortlist for a query without reading the notes"),
// The whole schema, for the reason the neighbours give: this
// family has no per-verb `--help`, so an unmodelled flag is
// unreachable from help and from completions alike.
command(
"restamp",
"Record this build's sqlite-vec version as the one the stored vectors are accepted under (dry-run unless --apply; refuses a model or dimension disagreement)",
[
flag("vault", "string"),
flag("config", "string"),
flag("db", "string"),
flag("apply", "boolean"),
],
),
// Both `schema` subcommands parse `--json` (export also `--stdout`),
// so the inherited stand-in covers the one and `stdout` is declared
// here; `tests/cli/search-query-flag-manifest.test.ts` holds this
// row to both parse schemas like every sibling above.
command(
"schema",
"Export or check the versioned search-query JSON Schema artifact (check exits 2 on drift from the descriptor)",
[flag("stdout", "boolean")],
),
// The whole `parseFlags` schema, for the reason the two builders
// above give: there is no per-verb `--help` on this family, so a
// flag the manifest does not model is a flag neither help nor
// completions can offer. `--progress` arrived here last and would
// have been the third such flag.
command(
"vector-backfill",
"Compute vectors for indexed chunks that have none (dry-run unless --apply)",
[
flag("vault", "string"),
flag("config", "string"),
flag("db", "string"),
flag("apply", "boolean"),
flag("force-cost", "boolean"),
flag("path", "string-array"),
flag("progress", "boolean"),
],
),
command(
"event-anchor-backfill",
"Resolve event anchors for indexed documents that have none (dry-run unless --apply)",
),
],
),
command(
"vault",
"Vault scope and profile verbs",
[],
[
command("status", "Show vault policy walk summary"),
command("inspect", "Inspect one vault-relative path"),
command("profile", "Manage named vault profiles"),
command("map", "Print vault-map role tokens"),
],
),
command(
"state",
"In-vault state surface verbs",
[],
[
command(
"status",
"Report every state surface in the vault with its path, reachability, and the override that placed it",
[flag("vault", "string"), flag("config", "string"), flag("json", "boolean")],
),
command(
"migrate",
"Plan (or, with --apply --yes, perform) a digest-bound move of the vault's state to another directory",
[
flag("to", "string"),
flag("vault", "string"),
flag("config", "string"),
flag("dry-run", "boolean"),
flag("apply", "boolean"),
flag("yes", "boolean"),
flag("json", "boolean"),
],
),
command(
"rollback",
"Restore a migration's manifest-bound files whose digests still match, refusing anything changed since",
[
flag("from", "string"),
// `--to` rescues a vault that moved after the migration, which
// is the one case the rollback plan refuses by name. Leaving it
// undeclared hid the remedy from `o2b help --json` and from
// shell completions - the two places an operator looks when the
// refusal tells them a flag exists.
flag("to", "string"),
flag("dry-run", "boolean"),
flag("apply", "boolean"),
flag("yes", "boolean"),
flag("json", "boolean"),
],
),
],
),
command(
"store",
"Brain store verbs",
[],
[
command(
"init",
"Create the brain store (both partitions, or --partitions shared), or complete a half-created one",
[flag("partitions", "string"), flag("config", "string"), flag("json", "boolean")],
),
command(
"path",
"Print the store root, partitions, device-local state directory and view target, with origin and existence",
[flag("config", "string"), flag("json", "boolean")],
),
command(
"device",
"List the devices the store knows, or retire one that is gone",
[flag("config", "string"), flag("json", "boolean")],
[
command("list", "List each device with its last record and state"),
command("retire", "Retire a device that is gone (not this machine)", [
flag("reason", "string"),
]),
],
),
command(
"partition",
"Take a partition off this machine on purpose",
[flag("config", "string"), flag("json", "boolean")],
[
command("leave", "Stop holding a partition whose folder is gone (never shared)", [
flag("force", "boolean"),
]),
],
),
command(
"shard",
"Skip one bad line of a held shard on this machine, list the skipped lines, or release one",
[flag("config", "string"), flag("json", "boolean")],
[
command("quarantine", "Skip one bad line of a held shard on this machine", [
flag("offset", "string"),
]),
command("list", "List the quarantined lines with their state"),
command("release", "Read a quarantined line again", [flag("offset", "string")]),
],
),
],
),
command(
"view",
"Human view verbs",
[],
[
command(
"writer",
"Show the view writer, or make this machine the view writer (--here, --force without a release)",
[
flag("here", "boolean"),
flag("force", "boolean"),
flag("config", "string"),
flag("json", "boolean"),
],
),
command("render", "Render the human view (only the view writer writes pages)", [
flag("config", "string"),
flag("json", "boolean"),
]),
command("recover", "List the replaced versions of a view page, or print one", [
flag("print", "string"),
flag("config", "string"),
flag("json", "boolean"),
]),
],
),
command(
"topic",
"Topics: list, show and change them by recording topic events",
[],
[
command("list", "List topics, newest first", [
flag("scope", "string"),
flag("config", "string"),
flag("json", "boolean"),
]),
command("show", "Show one topic: its head, items and page", [
flag("config", "string"),
flag("json", "boolean"),
]),
command("review", "Proposed merges and quiet topics", [
flag("config", "string"),
flag("json", "boolean"),
]),
command("create", "Create a topic", [
flag("scope", "string"),
flag("goal", "string"),
flag("description", "string"),
flag("private", "boolean"),
flag("shared", "boolean"),
flag("config", "string"),
flag("json", "boolean"),
]),
command("rename", "Rename a topic or change its description", [
flag("title", "string"),
flag("description", "string"),
flag("config", "string"),
flag("json", "boolean"),
]),
command("status", "Change a topic's status", [
flag("resolved", "string"),
flag("config", "string"),
flag("json", "boolean"),
]),
command("goal", "Set or clear a topic's goal", [
flag("clear", "boolean"),
flag("config", "string"),
flag("json", "boolean"),
]),
command("assign", "Assign a record to a topic", [
flag("config", "string"),
flag("json", "boolean"),
]),
command("unassign", "Take a record out of a topic", [
flag("config", "string"),
flag("json", "boolean"),
]),
command("merge", "Merge a topic into another", [
flag("into", "string"),
flag("config", "string"),
flag("json", "boolean"),
]),
command("split", "Move items or records of a topic to another", [
flag("into", "string"),
flag("items", "string"),
flag("records", "string"),
flag("owner", "string"),
flag("config", "string"),
flag("json", "boolean"),
]),
command("link", "Link two topics, or remove the link", [
flag("to", "string"),
flag("remove", "boolean"),
flag("config", "string"),
flag("json", "boolean"),
]),
command("archive", "Close a topic", [flag("config", "string"), flag("json", "boolean")]),
command("undo", "Undo one topic record", [
flag("config", "string"),
flag("json", "boolean"),
]),
command(
"record",
"Record a decision, question, log entry, milestone, resolution or completion",
[
flag("text", "string"),
flag("class", "string"),
flag("reason", "string"),
flag("item", "string"),
flag("question", "string"),
flag("answer", "string"),
flag("milestone", "string"),
flag("evidence", "string"),
flag("owner", "string"),
flag("as-human", "boolean"),
flag("config", "string"),
flag("json", "boolean"),
],
),
],
),
command(
"discipline",
"Daily logging discipline verbs",
[],
[
command("report", "Render discipline report"),
command("install", "Install discipline cron"),
command("uninstall", "Remove discipline cron"),
],
),
command(
"partner",
"Read-only reports on external code-project partners",
[],
[
command(
"codegraph",
"Codegraph partner reports",
[],
[
command("report", "Report codegraph index status and workspace members", [
flag("vault", "string"),
flag("fail-on-health", "boolean"),
]),
command(
"resync",
"Print a cron or systemd recipe that re-indexes the code project when its commit moves (requires --cron-template; writes nothing)",
[
flag("cron-template", "boolean"),
flag("interval", "string"),
flag("format", "string"),
flag("project", "string"),
flag("vault", "string"),
],
),
],
),
],
),
],
});
export function manifestForJson(): CliRootManifest {
return addInheritedFlags(CLI_COMMAND_MANIFEST);
}
export function commandNames(manifest: CliRootManifest = CLI_COMMAND_MANIFEST): string[] {
return manifest.commands.map((item) => item.name);
}
export function nestedCommandNames(parent: string): string[] {
const node = CLI_COMMAND_MANIFEST.commands.find((item) => item.name === parent);
return node?.commands?.map((item) => item.name) ?? [];
}
/**
* Every root command that models nested subcommands, paired with them.
*
* The completion renderer used to hand-list the three roots it knew about,
* so a fourth that grew subcommands was offered by no shell and nothing
* anywhere said so. Deriving the groups from the manifest is what makes
* the completion surface follow the manifest rather than trail it.
*/
export function nestedCommandGroups(
manifest: CliRootManifest = CLI_COMMAND_MANIFEST,
): Array<{ parent: string; children: string[] }> {
// Every depth, not only the first. Shell completion keys off the word
// immediately before the cursor, so a verb two levels down is reachable
// by its own parent's name and needs no path context - which is what
// makes a flat, recursively-collected map the right shape here.
const byParent = new Map<string, string[]>();
const visit = (items: ReadonlyArray<CliCommandManifest>): void => {
for (const item of items) {
const children = item.commands ?? [];
if (children.length === 0) continue;
const merged = byParent.get(item.name) ?? [];
for (const child of children) {
if (!merged.includes(child.name)) merged.push(child.name);
}
byParent.set(item.name, merged);
visit(children);
}
};
visit(manifest.commands);
return [...byParent].map(([parent, children]) => ({ parent, children }));
}
/** One modelled subcommand, e.g. `nestedCommand("search", "query")`. */
export function nestedCommand(parent: string, child: string): CliCommandManifest | undefined {
const node = CLI_COMMAND_MANIFEST.commands.find((item) => item.name === parent);
return node?.commands?.find((item) => item.name === child);
}
export function allFlagNames(manifest: CliRootManifest = manifestForJson()): string[] {
const names = new Set<string>();
for (const flagSpec of manifest.flags) names.add(flagSpec.name);
const visit = (items: ReadonlyArray<CliCommandManifest>): void => {
for (const item of items) {
for (const flagSpec of item.flags ?? []) names.add(flagSpec.name);
if (item.commands) visit(item.commands);
}
};
visit(manifest.commands);
return [...names].toSorted();
}
function command(
name: string,
summary: string,
flags: ReadonlyArray<CliFlagManifest> = [],
commands: ReadonlyArray<CliCommandManifest> = [],
): CliCommandManifest {
return Object.freeze({
name,
summary,
...(flags.length > 0 ? { flags } : {}),
...(commands.length > 0 ? { commands } : {}),
});
}
function flag(name: string, type: CliFlagManifest["type"]): CliFlagManifest {
return Object.freeze({ name, type });
}
function addInheritedFlags(root: CliRootManifest): CliRootManifest {
return {
...root,
commands: root.commands.map((item) => addInheritedFlagsToCommand(item)),
};
}
function addInheritedFlagsToCommand(commandSpec: CliCommandManifest): CliCommandManifest {
const ownFlags = commandSpec.flags ?? [];
const hasJson = ownFlags.some((item) => item.name === INHERITED_JSON_FLAG.name);
return {
...commandSpec,
flags: hasJson ? ownFlags : [...ownFlags, INHERITED_JSON_FLAG],
...(commandSpec.commands
? {
commands: commandSpec.commands.map((item) => addInheritedFlagsToCommand(item)),
}
: {}),
};
}