Oh My Second Brain

A constellation of knowledge, still yours.
A user-owned knowledge and convention layer for Obsidian, Markdown, and AI agents.

Quick start · How it works · Documentation · Releases · 한국어

Your vault already holds ideas, decisions, and things you learned. OMS helps your agents find that knowledge and write within the conventions you defined. No new note format. No prescribed folder system. No handover of your knowledge to a single host.

Obsidian stays the command center. Your notes stay plain Markdown, readable and editable even when OMS is not running. Connect Claude Code, Codex, or Hermes to the same vault through their host integrations.

Why OMS?

Quick start

Requires Node.js 20 or later and an existing Obsidian or Markdown vault. Replace /path/to/vault with your vault's absolute path.

1. Install

npm install -g oh-my-second-brain
oms --help

2. Define your vault's conventions

Run setup in your terminal. The interview covers folders, properties, and templates, then seals the contract. Existing notes are not modified.

oms setup --vault /path/to/vault
oms setup status --vault /path/to/vault

3. Connect your agent

Install the integration for the host you use:

oms setup host install --runtime claude --vault /path/to/vault --yes

Replace claude with codex or hermes; use all to install all three. Host integration is optional if you only need the CLI. See the installation guide for Hermes profiles, model setup, and removal.

4. Put your knowledge to work

# Build the derived search index explicitly.
oms doctor sync-embeddings --mode sync --vault /path/to/vault

# Start with lexical search. No vector model required.
oms search "project decisions" --vault /path/to/vault

Try asking your connected agent:

Find my notes about this project and surface the decisions I have already made.

Check this note against my vault contract and show me what needs attention.

Suggest related notes I could link to, without changing any files.

These are example requests, not captured run results. Available workflows and write enforcement differ by host as described below.

How it works

You define the meaning. Your agent writes the content. OMS checks the structure.

[!IMPORTANT]
Set up the contract before relying on write checks. A vault with no seal on this machine is not contract-judged; general path and input safeguards still apply. A contract violation leaves the file unchanged. An allowed write means structural compliance, not factual accuracy or quality approval.

• Meaning is user-owned. The interview covers folders, the property pool, and templates together. OMS hardcodes no property names, folders, or personas and has no Inbox fallback.
• One control file inside the vault. .oms/settings.json holds version, vaultId, templateFolder, embedding, and agentRepair. Other .oms/ entries are ignored and reported as unexpected control files by oms doctor contract. .obsidian/types.json is a read-only observation, not an override of the seal.
• Templates stay yours. OMS records what each template declares. It never rewrites, copies, or applies the template, and does not parse or execute Templater, JavaScript, or a private token language.
• Drift is visible. oms setup status reports templates as active, drift, or missing. It never silently re-seals a changed template.
• One judge, bounded feedback. Denied writes return {field, kind} violations and one guidance command, not rule values, store paths, or the contract body.
• Mismatched seal evidence blocks writes. When this machine's evidence no longer matches the vault, writes fail with contract-unreadable until the owner runs oms setup again. A machine with no seal is a different case: its vault is not contract-judged.

See architecture, conventions, and ADR-007.

oms setup in a terminal runs the interactive interview and seals the contract. oms interview is the same terminal interview on its own command; it requires a terminal and refuses to run under OMS_NON_INTERACTIVE=1.

The setup skill asks the owner each question via oms setup --questions and submits answers with oms setup --answers <file|->. This path can seal a first or stricter contract; a loosening reseal stays with the owner's terminal. The MCP interview tool only shows the questions and the seal state; it seals nothing.

oms setup extract --template <path> returns a template source and its computed hash. The agent reads each template and submits its interpretation with oms setup --interpretations <file>. The owner confirms that interpretation before it drives the interview.

oms doctor contract diagnoses seal problems, stale locks, orphaned generations, unexpected control files, and hook transport failures. Its --fix only re-indexes a moved or unindexed vault. Other broken seals are recovered through oms setup.

Model lifecycle is separate: oms setup model install|select|waive|status.

MCP tools & integrations

One domain kernel, with host-native integrations.

write · search · interview · doctor

The six skills are distill, doctor, interview, search, setup, and write.

distill and setup are tool-less workflows; sealing has no MCP operation. Detail capabilities use op values under the four tools. Tool annotations are per tool: only search is marked read-only, because write and the doctor repairs mutate and interview is kept conservative.

[!NOTE]
Claude's hook rejects a judged contract violation, but allows the write with a warning if the hook itself cannot run. Native file writes in Codex and Hermes do not pass through the OMS judge. This is not a filesystem-wide sandbox.

For Gajae-Code, install the marketplace plugin with gjc plugin install oms@oms; it discovers the six skills at the package-root skills/ path. See host assets for integration details.

Host installation stores a signed maintenance pointer at ${XDG_CONFIG_HOME:-~/.config}/oms/vault.json and stamps oms serve mcp --vault /path/to/vault into managed host entries. Only oms setup host install|remove|sync|status use that pointer to maintain integrations.

Runtime target resolution does not read it. Precedence is explicit target → local vault controls → bridge → OMS_VAULT → current directory. The current-directory fallback is read-only: sealing, note writes, and derived-state repair cannot use it.

oms setup package update updates the package only. Run oms setup host sync separately to synchronize installed host assets. See verified targets.

Search your way

Lexical by default. Additional retrieval channels by choice. Search includes notes that fail the contract; a missing or damaged contract does not stop retrieval.

Missing, incomplete, or uninstalled model selections fail loudly rather than silently switching to another capability. These are available retrieval options, not a claim of parity or superiority over another engine.

Use oms search --context for structured context and oms search --path <note> to read one note exactly. Indexing is explicit: oms doctor sync-embeddings --mode sync|embed|repair selects one of three distinct modes. See the CLI map for all operations.

CLI reference

oms is the short alias of oh-my-second-brain, with seven CLI families. 0.19 replaced the 0.18 families; see the 0.19 migration guide.

oms search <text>                               Search notes; lexical by default
oms search --path|--context|--link              Read one note, gather context, or suggest links
oms interview                                   Interview the vault owner in a terminal and seal
oms write <path>                                Save a note from stdin when the contract allows it
oms setup                                       Seal the contract (--questions/--answers for agents)
oms setup extract|status                        Show a template source or the contract posture
oms setup host install|remove|sync|status       Manage host assets and MCP registrations
oms setup model install|select|waive|status     Manage local model selection
oms setup package check|update                  Check or update the OMS package
oms setup bridge add|remove|status              Manage repository-to-vault bridges
oms doctor status                               Show read-only vault health
oms doctor contract|audit|link-check            Diagnose the contract, notes, or wikilinks
oms doctor sync-embeddings|cleanup|build-graph  Maintain the derived index and graph
oms serve mcp|http                              Start the MCP or local HTTP server
oms hook pre                                    Judge a Claude write against the contract

Every recognized command accepts --help and -h, exits 0, and has no side effects. An unknown command combined with --help exits 1. A family removed in 0.19 exits 1 and names its replacement.

oms doctor audit reports {path, field, kind} entries without rewriting notes. Notes are written as whole content through oms write <path> < note.md or MCP write {path, content, template?}; both take the same verified-target write path, and template optionally names the sealed template being followed. There is no completion call or reviewer conversation.

oms doctor cleanup removes eligible derived state. oms doctor build-graph rebuilds the note graph.

Note create, append, update, and backfill are retired operations. There is no link apply, note renderer, or compatibility path for those retired operations.

Documentation

Contributing & credits

Contributions are welcome. Start with the contributing guide, or open an issue with a reproducible problem or a focused proposal.

ACKNOWLEDGMENTS records design influences, including Ouroboros and Gajae Code's deep-interview. Those credits describe ideas, not a copied runtime or a research result. The original constellation illustration is inspired by the connected-note landscape at beomsukoh.com. Illustrations explain concepts; they are not product screenshots, host-smoke evidence, or product-gate results.

Your notes stay yours.
Built by Beomsu Koh · Package licensed MIT