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
docs: concise README, ZCode client page, CLI reference and safety notes moved to child pages (#219)
Serg Erosheeb3c4c85c1d6
diff --git a/README.md b/README.mdindex dd7e14a8..6cdaa0ee 100644--- a/README.md+++ b/README.md@@ -2,211 +2,135 @@-> An [Obsidian](https://obsidian.md)-native memory layer for your AI agent. Plain Markdown you own, in the same vault you already use.+Open Second Brain is a memory layer for AI agents that lives in an [Obsidian](https://obsidian.md) vault. Agents read and write it through MCP servers, lifecycle hooks and the `o2b` CLI. Everything the agent learns is a Markdown file under `Brain/`, so you can open, edit, grep and version it like any other note. A deterministic `dream` pass turns repeated signals into rules and retires the ones nothing uses; no model runs inside that algorithm.-Open Second Brain plugs into [Hermes Agent](https://github.com/NousResearch/hermes-agent) and turns your Obsidian vault into a memory layer the agent reads and writes through deterministic CLI / MCP tools. Preferences, signals, evidence, and audit trails are real `.md` files under `Brain/` in the vault you already open in Obsidian every day. You can grep them, version them with git, search them in Obsidian, edit them by hand. No daemon, no vector black box, no hidden state outside the vault.--## What is new--Open Second Brain 1.57.0 runs natively on Windows 10 and 11. It keeps its files under `%LOCALAPPDATA%\open-second-brain`, ships `.cmd` launchers beside the bash ones, and `o2b install-cli` and the MCP host configs work there - see [`install/windows.md`](install/windows.md). Getting there fixed habits that POSIX forgives and Windows does not: SQLite handles that outlive `close()`, renames onto files another process holds open, tar walks in `readdir` order, and paths split on `/`. Several of those were never Windows bugs, just nondeterminism every platform had. The suite passes with 0 failures on Linux and on native Windows, and a `windows-latest` CI job keeps it that way.--Previous release, 1.56.0, taught this install to answer questions about itself: `o2b version`, `second_brain_wiring` views for linked projects and host health, and an instruction block rendered from the capability window the host actually granted. The [CHANGELOG](CHANGELOG.md) has the detail.--Previous releases, 1.55.0 and 1.54.0, made every note write an attributable and revertible event - a write record, a before-image store, a planned revert sealed by a digest, a fleet freeze refused at the one guard every content writer passes, and a per-shard hash chain under every append-only ledger - and turned `visibility:` from a label into a boundary enforced at the three roots every read surface reaches page content through. The [CHANGELOG](CHANGELOG.md) has the detail on both.--Previous releases, 1.53.1 and 1.53.0, closed a dedup pass that proposed the same merge forever and could write a merge cycle, and taught Hermes recall to carry the turn's query without leaving the curated lane that makes injection safe. The [CHANGELOG](CHANGELOG.md) has the detail on both.--Previous release, 1.52.0, was the honesty wave: nothing writes silently, nothing degrades silently. Nine tracker cards were read against the live source before anything was designed, and the reading did most of the work - one card described a feature that had already shipped end to end, one asked for privacy by riding a predicate that is inert in every default install, and four more had premises the source contradicted. What survived is one rule applied eight ways.--A note update now refuses to destroy what it could not read - an unreadable note raises `target_unreadable` instead of parsing as empty, and a blank body over a non-empty note needs an explicit `allow_empty`. `o2b search check` measures instead of inferring: a real pending-vector count replaces a recommendation that told fully embedded vaults to compute their first vectors, an embedder record audit reports when the recorded dimension contradicts the stored data, and `o2b search restamp` repairs the one drift that needs no provider. Every structured Brain record carries a server-derived `origin_channel` no caller can supply; Brain status derives `log_events_since_dream` from the shards it already reads and names an unreadable shard a lower bound; imports read back what they claim and report every missing key by name, and the sessions lane resumes an interrupted transcript at the turn boundary; the three note-producing envelope lanes hand the generating agent a bounded, ownership-filtered wikilink candidate manifest; a failed multi-artifact write leaves a durable dead letter; and a standing census documented - truthfully, at the time - that `visibility: private` was a view filter rather than a privacy boundary, with `o2b search check` saying so on vaults that use the field. That census is the coverage map 1.54.0 built the enforcement against.--The units speak one vocabulary on purpose: attempted, found, and missing with every missing key named, one pure module consumed by the import census, the write accounting, and the embedder audit, pinned by the same census that guards the project's other closed vocabularies. An independent reviewer given the finished branch returned two blocking findings and eleven non-blocking ones, all applied; the [CHANGELOG](CHANGELOG.md) names each.--Previous release, 1.51.0, was about which memories earn their keep: a deterministic salience gate in front of the dream pass's expensive fold, session mining that can only reach the speculative inbox, a provenance-following note delete under one snapshot and an exact count guard, expiration settable and changeable through one normalizer, vault pages staged as Agent Skill drafts that leave the vault only on explicit accept, an architect overview that names its grounding, and the shared needs-llm-step envelope type under all of it. Before it, 1.49.0 through 1.50.3 made a label into a real boundary, taught the installer to see what the machine already has, and fixed a Hermes bridge that discarded the one line of stderr naming why it could not start - the [CHANGELOG](CHANGELOG.md) has the detail.--Previous release, 1.48.0, was about work you can watch, bound and stop: the long passes emit progress and observe interrupts where an interrupt can physically be observed, a successful install states what it measured rather than what it hoped, the project scanner stopped entering what the repository ignores (24148 files visited became 2729), and five independent reviewers returned forty-four reproduced findings against the finished branch, all resolved by measurement rather than argument.--Previous release, 1.47.0, wired what already existed: nine capabilities that were exported, tested and used elsewhere, each with a site that needed them and did not call them - a destructive-operation gate with two call sites against roughly twenty-five destructive operations, and a ranker that read a document's authoring instant nine lines after ranking on the file's modification time.--Previous release, 1.46.0, was about claims the code could not back up. Nine units, four of them reported on the public tracker, and what they have in common is not a subsystem: in every one, the information needed to tell two cases apart either existed already and was thrown away, or cost one filesystem call nobody made. A search that returned nothing could not tell you whether the corpus was empty or the embedder was down, though fifteen degradation signals were being computed and then flattened into prose or dropped. Entity intake decided whether to trust a source from the shape of a string, never asking whether a file was behind it - and the caller supplying that string is the same agent that read the material being classified. Two concurrent writers racing for the same filename lost one of the records outright, measured at twelve dropped events out of twenty-four. The Hermes plugin and the core resolved different vaults while a docstring claimed they were identical, which is why a setup that worked showed as unconfigured for five weeks with nobody able to say why.--You can now say what you want indexed instead of listing everything you do not, with `vault.include_paths`; absent, it changes nothing, and that is measured against the previous release rather than asserted. A write tells you what is wrong with the page it just wrote, instead of deferring to a sweep that may never run. Recall telemetry carries which channel delivered, so a hook that was never installed and a hook that ran and stayed quiet stop looking identical. Every advertised tool parameter is documented and CI keeps it that way, and an unknown argument is named back to you with a suggestion rather than silently ignored.--Some of what was asked for is not here, and the absence is a decision. There was no registry of embedding-provider shutdown dates, because the only way to build one is a hand-maintained table over an open set of endpoints that would rot in place and be believed - a decision 1.48.0 reverses above, having answered that objection rather than set it aside. The schema-completeness guard covers input schemas only, because the output vocabulary declares union-typed fields with no type on purpose and the rule would demand a lie there. And the fix the intake issue asked for - let the host supply the trust verdict instead of the caller - is unbuildable, because no unforgeable caller identity exists in this surface, a conclusion this project had already reached elsewhere and not applied here. What shipped instead removes the free bypass and makes the claim auditable; it does not make the claim true, and the code says so. Four reviewers were then given the finished branch with no knowledge of how it was built, and told that a comment is a claim rather than evidence. They found twelve defects, two of them regressions this work introduced and invisible to its own tests. All are fixed, and the [CHANGELOG](CHANGELOG.md) names them.--Previous release, 1.45.1, fixed a Hermes flush that had been discarded at the boundary since 0.32.0 and a starter vault that went stale ninety days after it was authored. Before it, 1.45.0 was about silence not being an answer, and 1.44.0 about what the index already knew: thirteen units on the retrieval path, most of them values the system computed and discarded before anything could see them. Details for all three live in the [CHANGELOG](CHANGELOG.md).--Previous release, 1.43.0, was about provenance at the boundary: what enters your vault, under whose authority, validated against what, and backed by what proof. Entities an agent extracts from an untrusted source - a scraped page, a fetched article - now land in a quarantine lane instead of becoming first-class Brain entities, and trust is derived from the shape of the source identity rather than from any word list. You can declare in `_brain.yaml` which path prefixes a caller-named write may touch, and a write outside them is refused with the command that resolves it; its authority is the config file, not the caller, because a caller can name itself anything. Note creation gains an idempotent skip whose result tells you which happened, validation before the write lands, and a template mode with a deliberately small grammar. A back-dated note - an imported log, a meeting record - now ranks by the date its body declares rather than by when the file was touched, with the source of that date recorded beside it. Schema mutations can be previewed before they touch the vault, which matters more than it sounds: `--dry-run` was previously parsed and ignored. And an outcome an agent posts about its own work now carries the kernel's own on-disk evidence beside the claim, with a mismatch recorded rather than resolved.--Two things 1.43.0 deliberately did not build are worth knowing about, because their absence was a decision rather than an omission. There is no independent verifier, because agent identity here is an unauthenticated string and two records asserting two names chosen by one process are not two actors. And there is no pack fetched by URL, because a schema pack has no portable representation and no registry to install into. Five independent reviewers were given the finished branch and found thirty defects, nine of them introduced by this work and three of them mechanisms nothing could make fire; one of those three was removed rather than repaired. The [CHANGELOG](CHANGELOG.md) has the detail, including what was found and deliberately left open.--Previous release, 1.42.0, was a structural wave with no new capability: the six modules that cost the most to change, both import cycles removed, and nine places where absence and inability-to-examine had been collapsed into one answer. Details live in the [CHANGELOG](CHANGELOG.md).--Previous release, 1.41.0, was a signals-that-survive wave: eight units that carry a signal the system already computes the last few metres, to the decision it should have changed. Ingest now honours the repository's own `.gitignore`, nested ignore files, `.git/info/exclude` and submodule boundaries, through the same discovery module the hygiene scan uses - so a repo path stops pulling in the build artifacts it already declares as noise. A recall graded weak no longer evaporates when the call returns: repeated weak recall on the same question becomes a tracked, self-closing gap task. A query that names a period is ranked for that period instead of against it, detected from ISO and `since:`/`until:` tokens only so it behaves the same in every language. A scope-less capture says which routing signal it was missing and which scopes the vault actually has. Model-authored payloads are checked against a declared shape before they become knowledge, unconditionally - a validator that can be switched off is one the write path cannot rely on. Plain text can now seed a fact or a skill, not only a taste signal. And resumed work is recognised by a declared identity rather than by a fifteen-minute clock, so a branch or worktree switch stops breaking the chain. A ninth unit was built, reviewed, and reverted rather than shipped, because proving it inert was easier than pretending it was not - the [CHANGELOG](CHANGELOG.md) says why.--## Why--- **Lives in your Obsidian vault.** Open `Brain/preferences/pref-no-internal-abbrev.md` in Obsidian and you literally see what your agent learned about you - title, status, evidence count, confidence band, body text. Wikilinks, backlinks, graph view all work.-- **You own the data.** Plain Markdown on your filesystem. No service to cancel, no cloud account, no schema migration when a vendor pivots. Syncthing to your other machines if you want.-- **Memory that learns deterministically.** A `dream` pass turns repeat signals into rules and retires the ones nothing applies any more. Counters and atomic file moves - no LLM inside the algorithm, no surprise hallucinations in your memory.-- **One vault, every agent.** Hermes Agent is the primary integration. Claude Code, OpenAI Codex, Cursor, Aider, OpenClaw, opencode, Grok Build, kiro, Copilot CLI, Gemini CLI, and Pi all plug into the same Brain through MCP.--## One vault, many runtimes+## How it fits```mermaidflowchart LR- Vault[("Your vault<br/>Brain/ - plain Markdown")]- Hermes["**Hermes Agent**<br/>(primary)"]- CC[Claude Code]- Codex[OpenAI Codex]- Others["Cursor · Aider · OpenClaw<br/>opencode · Grok Build · kiro · Copilot CLI<br/>Gemini CLI · Pi · any MCP host"]-- Hermes <==> Vault- CC <--> Vault- Codex <--> Vault- Others <--> Vault-- style Hermes fill:#1e3a5f,stroke:#90caf9,color:#fff- style Vault fill:#5d3a9b,stroke:#ce93d8,color:#fff+ subgraph Clients["Agent clients"]+ Plug["Plugins: Claude Code, Codex,<br/>Hermes, opencode, Grok Build"]+ Mcp["MCP config: Cursor, kiro, Copilot CLI,<br/>Gemini CLI, ZCode, any MCP host"]+ Claw["OpenClaw<br/>in-process plugin"]+ Cliu["Aider, Pi<br/>CLI and context file"]+ end+ subgraph Product["Open Second Brain"]+ Srv["MCP servers<br/>open-second-brain, open-second-brain-writer"]+ Hooks["Lifecycle hooks<br/>o2b-hook"]+ Cli["CLI<br/>o2b"]+ Core["Core"]+ end+ subgraph Vault["Your vault"]+ Brain["Brain/<br/>Markdown the agent writes"]+ Notes["Your notes"]+ Index[(".open-second-brain/brain.sqlite<br/>rebuildable search index")]+ end+ Plug --> Srv+ Plug --> Hooks+ Mcp --> Srv+ Claw --> Core+ Cliu --> Cli+ Srv --> Core+ Hooks --> Core+ Cli --> Core+ Core --> Brain+ Core --> Index+ Core -. reads, writes a named note on request .-> Notes```-Hermes Agent owns the schedule (dream cron, daily digests, Telegram delivery). Other runtimes participate as readers and writers of the same Brain through MCP - no per-runtime fork of the memory.--## Quick start with Hermes Agent--**The simplest path - let your agent set it up.** Paste this into Hermes (or whichever AI agent already has shell access on the target machine):--> Install Open Second Brain for me by following the steps at <https://github.com/itechmeat/open-second-brain/blob/main/install/hermes.md>. My vault is at `/path/to/your-vault`.--The agent reads the install doc, runs every command, and verifies the result. That's it.--If you prefer running the steps yourself:+Each client reaches the same core through a plugin, an MCP registration or the CLI. The core keeps its own records under `Brain/` and a generated search index under `.open-second-brain/` that it can rebuild from the files. Your notes are read; the note tools write one only at a path the caller names.-```bash-# 1. Install the plugin-hermes plugins install itechmeat/open-second-brain --enable-hermes gateway restart--# 2. Put `o2b` on PATH-~/.hermes/plugins/open-second-brain/scripts/o2b install-cli--# 3. Bootstrap the vault-o2b init --vault /path/to/your-vault --name "My Second Brain"-o2b brain init --vault /path/to/your-vault --primary-agent <agent-name>--# 4. Verify-o2b doctor --vault /path/to/your-vault+```mermaid+flowchart LR+ Agent["Agent"] -->|brain_feedback| Inbox["Brain/inbox/<br/>signal"]+ Inbox -->|dream pass| Pref["Brain/preferences/<br/>rule"]+ Pref -->|rendered into| Active["Brain/active.md"]+ Active -->|read at session start| Agent+ Agent -->|brain_apply_evidence| Log["Brain/log/"]+ Log -->|next dream pass| Pref```-Enable Open Second Brain as the memory provider in `~/.hermes/config.yaml` (`memory.provider: open-second-brain`) and restart the gateway one more time - the agent now injects `Brain/active.md` into its system prompt, recalls context before each turn, and writes signals through `brain_feedback`, all through the one native provider. Full step-by-step: [`install/hermes.md`](install/hermes.md).+The learning loop: signals become rules, rules reach the next session through `Brain/active.md`, and applied or violated evidence confirms, quarantines or retires them. Details: [`docs/how-it-works.md`](docs/how-it-works.md#a-preferences-lifecycle).-## Other runtimes+## Install-| Runtime | Install |-| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |-| Claude Code | Marketplace plugin (bundled MCP servers + hooks) - [`install/claudecode.md`](install/claudecode.md) |-| OpenAI Codex | `codex plugin marketplace add ...` then `o2b install --target codex --apply` (MCP servers via `codex mcp add`, or a `config.toml` merge without the binary) - [`install/codex.md`](install/codex.md) |-| OpenClaw | Native JS plugin, no MCP needed - [`install/openclaw.md`](install/openclaw.md) |-| opencode | `o2b install --target opencode --apply` (MCP servers + native plugin) - [`install/opencode.md`](install/opencode.md) |-| Grok Build | `o2b install --target grok --apply` (MCP in `config.toml` + native hooks) - [`install/grok.md`](install/grok.md) |-| Cursor · Aider · kiro · Copilot CLI · Gemini CLI · Pi | `o2b install --target <name> --apply` - see [`install/`](install/) |-| Any other MCP host | `o2b install --target generic --apply` - [`install/generic.md`](install/generic.md) |+1. Install [Bun](https://bun.sh/) 1.1 or later: [`install/prerequisites.md`](install/prerequisites.md).+2. Install the plugin for your client (guides below), or get the `o2b` CLI: [`install/prerequisites.md`](install/prerequisites.md#get-the-o2b-cli).+3. Create the vault files:-**Native Windows** (10/11, x64) is supported alongside Linux and macOS: Bun from `install.ps1`, `.cmd` launchers instead of symlinks, config under `%LOCALAPPDATA%` - [`install/windows.md`](install/windows.md).+ ```bash+ o2b init --vault /path/to/vault --name "My Second Brain"+ o2b brain init --vault /path/to/vault+ ```-Each non-Hermes target writes a sidecar manifest under `<vault>/.open-second-brain/install.lock.json` so `o2b uninstall --target <name> --apply` removes exactly what it added.+4. Connect the client (table below), then check the result:-## What you get+ ```bash+ o2b doctor --vault /path/to/vault+ o2b install --check+ ```-- **Your memory as Markdown.** Every rule the agent learns about you is a file under `Brain/` you can open, edit, grep, and version. Obsidian wikilinks, backlinks, and the graph view just work - there is no separate UI to learn.-- **Memory that learns, and forgets, on its own.** A nightly `dream` pass turns repeated corrections into rules and retires the ones nothing uses any more. Deterministic by design: counters and atomic file moves, no LLM guessing inside your memory.-- **One brain, every agent.** Teach a rule in one agent and the next one already knows it - Hermes, Claude Code, Codex, Cursor, and the rest read and write the same vault.-- **You stay in control.** Pin, merge, retire, or roll back any rule from the `o2b` CLI. Every Brain mutation takes a verified snapshot first, so a bad change is one `o2b brain rollback` away.-- **Who wrote what, and how to take it back.** Every note write is a log event with a write id, the agent, the device, and the content hash before and after, and the bytes it replaced are kept. `o2b brain writes` reads the record; `o2b brain writes revert --agent <name>` plans a restore of exactly that agent's writes, refuses by name where another writer sits on top, and applies only the plan you read. `o2b brain freeze` stops every content writer on every device that syncs the vault until you say otherwise, and the log carries a per-shard hash chain so a line that was edited or removed after the fact has a file and a line number.-- **Search that explains itself.** Keyword plus an optional semantic layer over your vault, with results that show why they surfaced and what was missing - not a black box. Opt into a structured per-result score breakdown (`explain`), inline trust metadata (age, superseded, conflict), a relevance threshold that returns nothing rather than weak noise, and reinforcement that lifts memories you have marked useful. Track retrieval quality over time with `brain_eval` and the recall benchmark (hit@k, MRR, answer-containment@k).-- **Conversations survive compaction.** When the host compresses context and rotates the session id, capture and recall stitch the segments back into one conversation - any segment id returns the whole lineage.-- **Memory that cleans itself, on your terms.** `o2b brain hygiene scan` surfaces contested facts, near-duplicate rules, stale derived pages, and never-recalled memories; `apply` executes only the findings you select, and stale pages recompile from their recorded sources with a dry-run preview.-- **A vault that stays fresh, consistent, and scoped.** `o2b search watch` keeps the index live as you edit, debounced and incremental; note identity is Unicode-normalized so the same file is one entry across macOS and Linux devices instead of a phantom cross-device duplicate; and recall accepts an opt-in `agent_scope` so a page marked with an `owner:` is reachable only to its owner while shared pages stay open to all.-- **Knowledge that knows where it came from.** Drop a source document and the agent's extraction becomes cross-referenced entity and concept pages plus a summary page that backlinks the source and lists its connections; N sources become one dated report whose every finding cites the source that flagged it; a derived fact carries a `deduced`/`inferred` provenance level and links back to its premises, and recall trusts an operator-stated rule above a machine-derived one. A fact can declare an `owner:` so multi-agent brains keep separate truth spaces, and a standing-query attention flow surfaces the open loops you declare. The plugin never runs a model itself - the agent owns generation, the vault owns the durable, provenanced record - and every behaviour is opt-in.-- **An index that survives interruption.** Stopping `o2b search watch` mid-sync finishes the in-flight pass at a file boundary before exiting (within `search_shutdown_grace_seconds`) instead of killing it mid-write; an incremental run is already resumable through the unchanged-file fastpath, and `search_resume_reindex` extends that to a full rebuild - an interrupted reindex resumes its staging build instead of starting over, guarded by a signature so a drifted build is discarded rather than trusted. Both default off, so behaviour is unchanged unless you ask for it.-- **A brain you can carry, hand off, and write to in process.** `o2b brain bank-export` serialises a whole vault - preferences, the page graph, a per-page interchange contract (path, kind, advisory confidence/provenance, citations, aliases, freshness), and the sources dashboard - into one deterministic, schema-versioned bundle for backup, migration, or downstream-tool ingest; `bank-import` reconstructs the page graph and the preferences - the latter through the audited preference transaction, so the trial window, confidence band, revision counter and audit trail are maintained and a bundle that is behind the vault is refused instead of rewinding it - and reports the rest as carried-not-restored rather than faking a full restore. A `brain_create_note` MCP tool writes an actual vault note (path + frontmatter + content) atomically, refusing traversal, the Brain root, and clobbering. And `createBrain(vault)` is a thin in-process SDK over the same core functions - bank/graph export-import, preference export, source ingest plus list/get/delete, and note creation - so scripts and agents manage brain content without the CLI or MCP layer.-- **Knowledge you can share without sharing the vault.** `o2b brain knowledge-pack export --select topic:…|tag:…|<id>` packs a chosen subset - rules and the pages that hold runbooks and conventions - into an OKF-based bundle sealed with sha256, blocking pages marked `visibility:` or carrying an `owner:` and redacting secrets on the way out. The receiving vault can `preview` it (manifest, samples, integrity, conflicts, prompt-injection warnings), `install` it as untrusted candidates - rules arrive unconfirmed on a fresh trial window, pages stage in `OKF Review/`, each stamped `knowledge_pack: <name>@<sha>` - and `uninstall` it as a unit behind a snapshot. See [docs/cli-reference.md](docs/cli-reference.md#knowledge-packs).-- **Recall you can tune, and a working set that prunes itself.** `o2b search --profile fast|balanced|thorough` (and the `brain_search` `profile` field) pick a recall preset over the same bounded knobs the self-tuner uses - an explicit profile wins over a learned grid point, and no profile leaves ranking bit-for-bit unchanged. `o2b brain file-context <path>` surfaces prior vault work that mentions a file before you read it; `o2b brain co-occurrence` proposes relationship edges between entities repeatedly co-referenced from the same notes, scored structurally over the wikilink graph with no natural-language word list in any language; and `o2b brain continuity rank` weights working-memory records by a usage-driven decay derived only from real recall telemetry, so stale decisions fade while actively-recalled ones stay prominent. All deterministic, all read-only or suggestion-only.-- **Session knowledge you can query, trace, and walk.** `o2b brain session-summary` (and `brain_session_summary`) stores a session-scoped digest over four categories - request, decisions, learnings, next_steps - that the agent extracts and the kernel only stores, so you can ask what a session decided as one unit. `o2b brain idea-lineage <id>` traces how a derived artifact was reached as an observation to synthesis to conclusion graph over the edges already recorded (continuity `sourceRefs`, or a preference's belief-evolution), cycle-guarded and depth-bounded. `o2b brain note-history <path>` splits a note's git history into episodic phases on a deterministic commit-time gap - language-agnostic, no commit-message parsing. The kernel never calls a model; absent inputs report honestly rather than fabricating.-- **Operational readability for code partners and large vaults.** Open Second Brain now exposes a read-only CodeGraph report (`o2b partner codegraph report`, `brain_codegraph_report`) that resolves the in-scope code project, reports the codegraph index state with node and edge counts, and structurally parses Cargo.toml for Rust workspace members. The report is honest about missing CLIs, missing indexes, and non-Rust projects. For large vaults, community materialization can run in fixed-size batches (`o2b brain clusters run --batch-size N`, `brain_clusters` `batch_size`) with per-batch success or isolated failure reporting, while the default run stays byte-identical.-- **Consistent feedback categorization.** A vault-local `feedback.default_scope` in `Brain/_brain.yaml` gives agent-recorded signals a consistent category (for example `coding`) when no explicit scope is provided, with the same precedence across the inbox signal, its shared-namespace mirror, and any force-confirmed preference. The effective scope is computed once at the signal write boundary and byte-identical output is preserved when the setting is absent or no explicit scope is given.-- **Path-safe vault writes.** The write-session commit chokepoint now re-resolves every target through `ensureInsideVault` before any directory creation, read, or write, catching symlinked ancestors that point outside the vault root. The backstop fails closed: a target resolving outside the configured vault is rejected and nothing is written. All other caller-derived vault paths already funnel through guarded constructors; regression tests pin both invariants.-- **Recall that pays for depth only on demand.** General vault search now offers the same progressive 3-layer disclosure session-recall already had. `o2b search "<q>" --disclosure cards` (and the `brain_search` `disclosure: "cards"` field) returns compact layer-1 cards - path, title, score, reasons, a bounded snippet, and a `path:Lstart-Lend` pointer - instead of full content per hit, so recall stays token-cheap. Drill a hit with `o2b search expand --chunk <id>` (or `brain_search_expand`) to get layer 2 (the fuller note) and layer 3 (the raw chunk transcript, paginated by cursor). It reuses the existing index read - no new index, no model - and the default `full` mode is byte-identical to before. Cards compose with cross-vault recall too: `--global --disclosure cards` returns the token-cheap layer-1 cards merged across every origin (each labelled by its origin), not an empty result set.+The full router with readiness criteria is [`install.md`](install.md); native Windows is covered in [`install/windows.md`](install/windows.md).-- **A today surface for the operator, and prose that writes back.** `o2b brain today` (and `brain_brief view=today`) renders a read-only, live-derived dashboard - due and overdue obligations, open loops, a chronologically merged typed activity timeline with relative ages, and totals - where every section is re-derived on demand from the vault, never stored, and a failing section reports its error while the rest still render. Jot `@osb loop <text>` in any note to keep an intention visible until you close it with `@osb loop close id=<id>` (ids are printed on the dashboard; loop markers survive scans and are never consumed). Jot `@osb set note=<target> field=<field> value=<value>` and `o2b brain apply-markers --apply` turns it into a schema-validated frontmatter mutation - fail-closed target resolution (ambiguous titles list candidates instead of guessing), one `attribute-write` audit event per applied change with the prior value, idempotent consumption of applied markers, and the whole write path gated behind the opt-in `guardrails.marker_writeback` flag. Report mode needs no flag and writes nothing.+## Supported clients-- **It knows what it is, and what it is wired into.** `o2b version` answers on the command line the question the MCP handshake has always answered - one constant behind both, so the two surfaces cannot disagree. `second_brain_wiring` puts two CLI-only answers on the MCP surface: `view=projects` lists every project directory registered against this vault with the state of its pointer file, and `view=hosts` runs the same per-adapter verification `o2b install --check` runs, so an agent can ask whether the runtimes this install wired up can still be reached. Paths in those answers are opaque references unless you asked for raw ones. And the instructions block every agent reads at connect time is now rendered from what this runtime actually left callable: guidance for a tool the host disabled is removed rather than contradicted, and each removal is named with its reason.+| Client | Integration | Guide |+| --- | --- | --- |+| Claude Code | Marketplace plugin: MCP servers and hooks | [`install/claudecode.md`](install/claudecode.md) |+| OpenAI Codex | Marketplace plugin, then `o2b install --target codex --apply` | [`install/codex.md`](install/codex.md) |+| Hermes Agent | Plugin and memory provider | [`install/hermes.md`](install/hermes.md) |+| OpenClaw | Native plugin, no MCP | [`install/openclaw.md`](install/openclaw.md) |+| opencode | `o2b install --target opencode --apply`: MCP servers and a native plugin | [`install/opencode.md`](install/opencode.md) |+| Grok Build | `o2b install --target grok --apply`: MCP servers and hooks | [`install/grok.md`](install/grok.md) |+| Cursor | `o2b install --target cursor --apply` | [`install/cursor.md`](install/cursor.md) |+| kiro | `o2b install --target kiro --apply` | [`install/kiro.md`](install/kiro.md) |+| GitHub Copilot CLI | `o2b install --target copilot-cli --apply` | [`install/copilot-cli.md`](install/copilot-cli.md) |+| Gemini CLI | `o2b install --target gemini-cli --apply` | [`install/gemini-cli.md`](install/gemini-cli.md) |+| ZCode | MCP servers added to its config by hand | [`install/zcode.md`](install/zcode.md) |+| Aider | `o2b install --target aider --apply`: context file, no MCP | [`install/aider.md`](install/aider.md) |+| Pi | `o2b install --target pi --apply`: skill over the CLI | [`install/pi.md`](install/pi.md) |+| Any other MCP host | `o2b install --target generic --apply --out -` prints the server entries | [`install/generic.md`](install/generic.md) |-- **It knows the machine it is installed on.** `o2b install --friction` lays every supported runtime side by side - how it is installed, whether it caps the tool surface, whether a `--check` on it is a file comparison or a live question put to the host, and whether this build can read the transcripts that runtime writes. Two hosts can now be ASKED (`codex mcp list`, `copilot mcp list`) instead of inferred from a config file, so "installed" and "actually loaded" stop being the same answer. `o2b state status` does the same for the vault: forty declared state locations, each with where it resolved, whether it is reachable, and which setting put it there - and `o2b state migrate` moves the lot to another directory behind a digest manifest, refusing before it commits and reversible after. `o2b brain import-session --discover` finds the session logs already on your disk and says which have never been imported, so cross-agent recall no longer depends on your knowing where each runtime keeps its transcripts.+`o2b uninstall --target <name> --apply` removes what `o2b install` wrote; the vault is never touched ([`install.md`](install.md#uninstall)).-That is the day-to-day picture. The full capability surface, every CLI verb, and the mental model live in the [documentation](#documentation) below.+## Capabilities-## Safety+- **Preferences that learn and expire.** Signals, a deterministic dream pass, confidence and retirement: [how it works](docs/how-it-works.md#a-preferences-lifecycle).+- **Reversible changes.** Brain mutations take a snapshot first; `o2b brain rollback` restores it: [snapshots](docs/how-it-works.md#snapshots-and-rollback).+- **Attributed writes.** `o2b brain writes` lists every note write by agent and device, `writes revert` plans a restore, `o2b brain freeze` stops all writers, and `o2b brain log verify` checks the hash-chained log: [Brain CLI](docs/cli-reference.md#brain-observing-memory).+- **Search.** Keyword search with an optional semantic lane, result explanations, recall profiles and compact cards: [search CLI](docs/cli-reference.md#search), [ranking](docs/how-it-works.md#full-text-search).+- **Session recall.** Import agent transcripts already on disk and search them: [session logs](docs/cli-reference.md#session-logs-this-machine-already-has-since-v1500).+- **Hygiene.** `o2b brain hygiene scan` finds contested, duplicate, stale and unused memories; `apply` runs only the findings you pick: [maintenance](docs/cli-reference.md#maintenance-and-operator-surfaces).+- **Sharing and backup.** Knowledge packs export a chosen subset; `o2b brain bank-export` writes a one-file backup bundle: [knowledge packs](docs/cli-reference.md#knowledge-packs).+- **Today view and note markers.** `o2b brain today`, `@osb loop` and `@osb set` markers: [Brain CLI](docs/cli-reference.md#brain-observing-memory).+- **Self-inspection.** `o2b version`, `o2b install --friction` and `o2b state status` report what is installed and where state lives: [CLI reference](docs/cli-reference.md#core).+- **MCP surface.** Tools, tool profiles for hosts with tool limits, and the always-loaded writer server: [`docs/mcp.md`](docs/mcp.md).-- Plain Markdown on your filesystem. No daemon, no background writes. The MCP server is a stdio subprocess that exits with the parent runtime. An optional HTTP transport (`o2b mcp --transport http`) is off by default and safe by design: it binds loopback (`127.0.0.1`), enforces a Host/Origin DNS-rebinding guard on every request, and exposes an unauthenticated `GET /health` liveness probe. A bearer token (`--api-key`) is optional on loopback and mandatory when binding a non-loopback host - the server refuses to expose an unauthenticated endpoint on the network. On `SIGTERM`/`SIGINT` either transport stops accepting new work, finishes what is already running under a bounded deadline (`O2B_MCP_DRAIN_MS`, ten seconds by default), and only then exits - so a shutdown never truncates a tool call, and `/health` reports `draining` while it happens.-- Your vault is the only source of truth - no hidden state, no cloud copy.-- Brain mutations (`dream`, `merge`, `upgrade`) take a pre-run snapshot with a SHA-256 sidecar; `o2b brain rollback` aborts on drift unless `--force-rollback`. Destructive cleanups (`forget-source --confirm`, `entity prune --confirm`) run behind the same snapshot gate and report their recovery point; dry runs take no snapshot.-- Store hardening: `o2b brain doctor --remediate` can tighten existing `Brain/` files to owner-only permissions (dry-run first, idempotent), the doctor flags vault-internal symlinks that resolve outside the vault, and MCP responses carry an opaque `vault://` store reference instead of the absolute host path unless `expose_host_paths: true` is set.-- Secrets are not supposed to live in the vault. Daily logs and config exports run through a best-effort redactor, `$secret:NAME` references resolve from the local environment and are never stored, and Brain redaction strips `<private>...</private>` regions before storage.-- Automatically surfaced Brain context passes through a deterministic prompt-injection guard; filtered output returns a placeholder with a reason code and the source Markdown is never rewritten. Opt into `untrusted_source_delimiting` for language-agnostic structural containment instead: an untrusted span is wrapped in a provenance-carrying `<untrusted_source path sha256>` delimiter and neutralized by structure (invisible/control characters, delimiter breakouts) rather than a per-language word list, losslessly and identically for every language.-- Context receipts and recall telemetry are opt-in and store redacted metadata, hashes, and counters rather than raw prompt text.-- Optional decision models (a typed judgment model such as Jev, used to choose among candidates the code already produced) are off by default, per use. They run only when the machine config enables them and the named key variable is set (a self-hosted server on loopback needs no key); while active, shadow and enforce both send masked, clipped, redacted candidate text to the configured endpoint, private pages and `<private>` regions never leave, and no decision writes to the vault. See [`docs/decision-models.md`](docs/decision-models.md).+## Optional features-## Optional decision models+- **Semantic search:** an embedding provider plus `sqlite-vec`; the `embeddings-setup` skill walks through it: [`skills/embeddings-setup/SKILL.md`](skills/embeddings-setup/SKILL.md).+- **Decision models:** a typed judgment model that can rerank search and filter candidates, off by default per use: [`docs/decision-models.md`](docs/decision-models.md).-An optional decision model (a typed judgment model such as Jev) can rerank the head of the search results, pick the skills `skills_attach` offers, pre-filter the turns of the extract-signals envelope and the notes the recall hook injects, and add advisory verdicts to dedup, tension, label and answerable proposals. Each use is off by default: until you enable it, nothing changes and nothing is sent. The `decision-model-setup` skill walks an agent through the setup. To turn on the reranker by hand:--1. Export a key from a supported provider as an environment variable, for example `TYPESAFE_API_KEY`.-2. In the machine config set `decision_model_enabled: "true"`, `decision_model_provider: typesafe`, `decision_model_env_key: TYPESAFE_API_KEY` (the variable's name, never the key), `decision_model_uses: "rerank:shadow"`, `search_rerank_enabled: "true"`, `search_rerank_kind: decision-model` and `search_rerank_top_k: "30"`.-3. Run `o2b decision-model check --ping`.--It pays off only with a semantic lane (`embedding_provider` configured, `local` is enough). The other uses, the routes (TypeSafe, OpenRouter, Vercel, OpenCode Zen, self-hosted), moving from shadow to enforce, measuring, what is sent, the cost gate and the per-vault opt-out: [`docs/decision-models.md`](docs/decision-models.md).--## Updating--```bash-o2b update # detect runtimes, skip unchanged, apply, verify-o2b doctor # confirm the new manifest validates-```+## What is new-Updates need no manual symlink surgery: hooks resolve the active plugin version-on their own and the `~/.local/bin` CLI symlinks self-heal on the next session-start. Per-runtime upgrade paths and the canonical version source live in-[`install.md`](install.md); the update-safety contract (and the invariants any-change to hooks/launcher/install must keep) lives in-[`docs/updating.md`](docs/updating.md).+1.61.0 moves MCP server start-up off the Brain upgrade path, makes ingest locks fair, puts the Claude Code MCP manifest inside `plugin.json`, and adds an inbox archive. Every release is described in the [CHANGELOG](CHANGELOG.md).## Documentation-| Topic | Doc |-| -------------------------------------------------- | ---------------------------------------------------------------- |-| Mental model, vault layout, dream mechanics | [`docs/how-it-works.md`](docs/how-it-works.md) |-| MCP protocol, tools, lifecycle, writer split | [`docs/mcp.md`](docs/mcp.md) |-| Full CLI reference (every verb, every flag) | [`docs/cli-reference.md`](docs/cli-reference.md) |-| Update safety contract + hook/launcher invariants | [`docs/updating.md`](docs/updating.md) |-| Hermes cron jobs (daily digest, discipline report) | [`docs/hermes-cron.md`](docs/hermes-cron.md) |-| Cross-project pointer (multi-host vaults) | [`docs/cross-project-pointer.md`](docs/cross-project-pointer.md) |-| Observability contract (events, gates, payloads) | [`docs/observability.md`](docs/observability.md) |-| Optional decision models (off by default) | [`docs/decision-models.md`](docs/decision-models.md) |-| Metrics layer (the dashboard data contract) | [`docs/metrics.md`](docs/metrics.md) |-| Frozen-surface and stability policy | [`docs/stability.md`](docs/stability.md) |-| Architecture | [`docs/architecture.md`](docs/architecture.md) |-| Origin idea | [`docs/idea.md`](docs/idea.md) |--## Uninstalling--```bash-o2b uninstall # print plan (read-only)-o2b uninstall --apply-local --remove-cli # remove local state and symlinks-```--Your vault is never touched by the uninstall flow. Delete it yourself with normal filesystem tools if you want to.--## License--MIT. Source: <https://github.com/itechmeat/open-second-brain>.+| Topic | Page |+| --- | --- |+| Mental model, vault layout, dream pass, safety properties | [`docs/how-it-works.md`](docs/how-it-works.md) |+| Every CLI verb and flag | [`docs/cli-reference.md`](docs/cli-reference.md) |+| MCP protocol, tools, writer split | [`docs/mcp.md`](docs/mcp.md) |+| Architecture and configuration model | [`docs/architecture.md`](docs/architecture.md) |+| Updating (`o2b update`) and upgrade notes | [`docs/updating.md`](docs/updating.md) |+| Observability events | [`docs/observability.md`](docs/observability.md) |+| Metrics data contract | [`docs/metrics.md`](docs/metrics.md) |+| Cross-project pointer | [`docs/cross-project-pointer.md`](docs/cross-project-pointer.md) |+| Scheduled Brain digest (Hermes cron) | [`docs/hermes-cron.md`](docs/hermes-cron.md) |+| Stability policy | [`docs/stability.md`](docs/stability.md) |+| Origin of the idea | [`docs/idea.md`](docs/idea.md) |++## Project++[CHANGELOG](CHANGELOG.md) · [Security policy](SECURITY.md) · [Source on GitHub](https://github.com/itechmeat/open-second-brain) · [MIT License](LICENSE)diff --git a/docs/cli-reference.md b/docs/cli-reference.mdindex 87914202..0024bb8b 100644--- a/docs/cli-reference.md+++ b/docs/cli-reference.md@@ -397,6 +397,8 @@ o2b brain backlinks List inbound references to a Brain artifact ido2b brain semantics-backfill Dry-run typed preference-edge backfill preview (since v0.24.0): --json returns missing inverse superseded_by proposals; no writeso2b brain mcp-landscape List MCP servers configured across the vault (since v0.19.0): name, source file, packages, required env-var names (values never read)o2b brain scan-inline Capture `@osb` markers from folders listed under `notes.read_paths` in _brain.yaml+o2b brain today Read-only today dashboard: due and overdue obligations, open loops (`@osb loop <text>` markers, closed by `@osb loop close id=<id>`), merged recent activity, totals; --lookback-days (default 7), --limit (default 20), --json. Each section derives live; a failing section is reported and the rest still render+o2b brain apply-markers Turn `@osb set note=<target> field=<field> value=<value>` markers into schema-validated frontmatter writes. Report mode by default (writes nothing); --apply needs `guardrails.marker_writeback` in _brain.yaml, consumes applied markers so a re-run is idempotent, and leaves unresolvable or refused targets unconsumed; --path <subdir> (repeatable) or notes.read_pathso2b brain import-session Replay signals from a registered agent session .jsonl (or directory); --recall also stores turns in the session recall DAG. Since v1.50.0 the path argument has a machine-wide sibling: --status reports per-runtime coverage, --discover lists what has never been imported, --discover --all imports it (see "Session logs this machine already has" below)o2b brain session-hook Internal hook bridge: read one lifecycle payload from stdin, capture prompt markers / brain_feedback, append lifecycle audit/log rowso2b brain context-receipts List/show opt-in prompt context receipt continuity records (since v0.29.0)@@ -1503,6 +1505,9 @@ o2b search "<query>" Hybrid full-text + semantic search across the vaulempty; the human transcript names the cause on the no-results linetotal is the pre-truncation ranked pool, not the number of rows returnedCJK text is expanded for FTS recall without polluting returned content+ --profile fast|balanced|thorough picks a recall preset; no profile leaves ranking unchanged+ --disclosure cards returns compact cards (path, title, score, snippet, line range) instead of full content; default full+o2b search expand Drill one card: --chunk <id> (printed on the card) returns the fuller note and the raw chunk transcript, paged by --cursor; read-onlyo2b search feedback Record explicit recall feedback for one result(--query Q --result <path> --verdict up|down; one JSON event fileunder Brain/search/feedback/, learned weights refresh deterministically)diff --git a/docs/how-it-works.md b/docs/how-it-works.mdindex 309cc0fa..2b341284 100644--- a/docs/how-it-works.md+++ b/docs/how-it-works.md@@ -1393,6 +1393,18 @@ These are invariants of the system, not configuration to enable.`o2b brain rollback <run-id>` let you undo any single dream pass.- **Path-safe.** Every writer routes through a vault-boundary check;`Brain/` operations cannot escape the configured vault root.+- **Local MCP transport.** `o2b mcp` is a stdio subprocess of the+ client by default. The optional `--transport http` binds `127.0.0.1`,+ checks `Host` and `Origin` on every request against DNS rebinding,+ and refuses a non-loopback `--host` without `--api-key` (or+ `OPEN_SECOND_BRAIN_MCP_API_KEY`). Shutdown drains in-flight calls,+ see [mcp.md](mcp.md#shutdown-and-draining-since-v1500).+- **Guarded injected context.** Automatically surfaced Brain context+ passes a prompt-injection guard. With `guardrails.untrusted_source_delimiting`+ enabled in `_brain.yaml`, the context pack (`brain_context_pack`) wraps+ untrusted spans in a provenance-carrying delimiter instead of filtering+ them by a word list. The pre-compress pack (`brain_pre_compress_pack`)+ does not apply the delimiter yet and uses the guard only.- **No LLM inside the algorithm.** Semantic merging of similar butdifferently-slugged topics is left to external agents who can callthe CLI / MCP surface directly — the dream pass itself only doesdiff --git a/install.md b/install.mdindex 58309d29..4fe8139e 100644--- a/install.md+++ b/install.md@@ -20,8 +20,7 @@ pattern that every install path ends with. On native Windows, read## Quick install-For MCP-aware runtimes the v0.10.11 orchestrator handles install-in one command:+For these runtimes one `o2b install` command writes the integration:| Runtime | Command | Notes ||----------------------|----------------------------------------------------|-----------------------------------------------------------------------|@@ -35,6 +34,9 @@ in one command:| Pi (pi.dev) | `o2b install --target pi --apply` | `install/pi.md` — skill symlink, not MCP || Generic / other | `o2b install --target generic --apply --out -` | `install/generic.md` — prints payload; never edits external config |+ZCode has no install target yet: add the printed servers to its config+by hand, see `install/zcode.md`.+For runtimes that ship their own plugin/MCP install pipeline, OSBhooks into that pipeline instead of `o2b install --target`:@@ -107,7 +109,7 @@ Universal:stamps `@<chosen-agent-name>` in `Daily/`, not `@agent`.MCP-driven runtimes only (Cursor, opencode, Grok Build, kiro,-Copilot CLI, Gemini CLI, Claude Code, Codex, Hermes — not `aider`,+Copilot CLI, Gemini CLI, Claude Code, Codex, Hermes, ZCode; not `aider`,`pi`, or `generic`):- [ ] all OSB tools advertised by the runtime's MCP listing.diff --git a/install/prerequisites.md b/install/prerequisites.mdindex f98e6871..48564ed6 100644--- a/install/prerequisites.md+++ b/install/prerequisites.md@@ -13,6 +13,27 @@ If you cannot install Bun (locked-down environment, unsupportedarchitecture), the plugin will not function on that host. No Pythonfallback exists.+## Get the `o2b` CLI++Plugin hosts (Claude Code, Codex, Hermes, OpenClaw) ship the launcher+with the plugin; their install page shows how to publish it. For every+other client, clone the repository and publish the launcher from the+clone:++```bash+git clone https://github.com/itechmeat/open-second-brain ~/open-second-brain+~/open-second-brain/scripts/o2b install-cli+export PATH="$HOME/.local/bin:$PATH"+o2b version+```++`install-cli` links `o2b`, `vault-log` and `o2b-hook` into `~/.local/bin`.+Add that directory to `PATH` in your shell profile. A client that starts+MCP servers with a bare `o2b` command needs it on the `PATH` it runs with;+if it does not have it, use the absolute path `~/.local/bin/o2b` (expanded)+as the command.+On native Windows, follow [`windows.md`](windows.md) instead.+## Supported platformsLinux, macOS and the other POSIX hosts Bun runs on, plus native@@ -73,7 +94,7 @@ o2b doctor --vault /path/to/vault --repo .o2b install --check```-`o2b install --check` is the v0.10.11 runtime-install health check+`o2b install --check` is the runtime-install health check(per-target managed-block / MCP-ping verification). `o2b doctor`covers vault invariants — they are complementary, not substitutes.diff --git a/install/zcode.md b/install/zcode.mdnew file mode 100644index 00000000..a34e1da3--- /dev/null+++ b/install/zcode.md@@ -0,0 +1,74 @@+# ZCode++[ZCode](https://github.com/zai-org/ZCode) reads MCP servers from its own+config file. There is no `o2b install --target zcode` yet, so the two+Open Second Brain servers are added by hand. Verified with the ZCode CLI+0.16.9 on Linux.++## 1. Prerequisites++- `o2b` on `PATH` and a vault initialized with `o2b init` - see+ [`prerequisites.md`](prerequisites.md#get-the-o2b-cli).++## 2. Add the MCP servers++Print the server entries for your vault:++```bash+o2b install --target generic --apply --out - --vault /path/to/vault+```++The printout is keyed `mcpServers`. ZCode expects the same entries under+`mcp.servers` in one of these files:++| Scope | File |+|---|---|+| User | `~/.zcode/cli/config.json` |+| One project | `<project>/.zcode/config.json` |++Merge the entries into the existing file; keep its other keys:++```json+{+ "mcp": {+ "servers": {+ "open-second-brain": {+ "command": "o2b",+ "args": ["mcp", "--vault", "/path/to/vault"]+ },+ "open-second-brain-writer": {+ "command": "o2b",+ "args": ["mcp", "--writer-only", "--vault", "/path/to/vault"]+ }+ }+ }+}+```++The `env` block from the printout (`VAULT_AGENT_NAME`, `VAULT_TIMEZONE`)+can be kept as is. If ZCode cannot find `o2b`, set `command` to the+absolute launcher path (for example `/home/<user>/.local/bin/o2b`). Start a+new ZCode session to load the servers.++## 3. Verify++In the ZCode TUI, `/mcp list` shows both servers. The CLI can also run+one prompt headless (`-p`) that calls a tool:++```bash+zcode -p "Call second_brain_status on the open-second-brain MCP server and report the vault path" --mode plan+```++The answer names the vault from step 2. ZCode exposes the tools as+`mcp__open-second-brain__<tool>` and `mcp__open-second-brain-writer__<tool>`.++## Plugin marketplace++ZCode can also install this repository as a plugin from its marketplace.+With ZCode 0.16.9 on Linux the bundled MCP servers do not start: the+plugin cache copy of `scripts/o2b` loses its executable bit and the spawn+fails with `EACCES`. On Linux, use the config above instead.++## Uninstall++Remove the two entries from `mcp.servers`. The vault is not touched.diff --git a/plugins/codex/README.md b/plugins/codex/README.mdindex bb61f4df..3e6ed8d3 100644--- a/plugins/codex/README.md+++ b/plugins/codex/README.md@@ -2,211 +2,135 @@-> An [Obsidian](https://obsidian.md)-native memory layer for your AI agent. Plain Markdown you own, in the same vault you already use.+Open Second Brain is a memory layer for AI agents that lives in an [Obsidian](https://obsidian.md) vault. Agents read and write it through MCP servers, lifecycle hooks and the `o2b` CLI. Everything the agent learns is a Markdown file under `Brain/`, so you can open, edit, grep and version it like any other note. A deterministic `dream` pass turns repeated signals into rules and retires the ones nothing uses; no model runs inside that algorithm.-Open Second Brain plugs into [Hermes Agent](https://github.com/NousResearch/hermes-agent) and turns your Obsidian vault into a memory layer the agent reads and writes through deterministic CLI / MCP tools. Preferences, signals, evidence, and audit trails are real `.md` files under `Brain/` in the vault you already open in Obsidian every day. You can grep them, version them with git, search them in Obsidian, edit them by hand. No daemon, no vector black box, no hidden state outside the vault.--## What is new--Open Second Brain 1.57.0 runs natively on Windows 10 and 11. It keeps its files under `%LOCALAPPDATA%\open-second-brain`, ships `.cmd` launchers beside the bash ones, and `o2b install-cli` and the MCP host configs work there - see [`install/windows.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/windows.md). Getting there fixed habits that POSIX forgives and Windows does not: SQLite handles that outlive `close()`, renames onto files another process holds open, tar walks in `readdir` order, and paths split on `/`. Several of those were never Windows bugs, just nondeterminism every platform had. The suite passes with 0 failures on Linux and on native Windows, and a `windows-latest` CI job keeps it that way.--Previous release, 1.56.0, taught this install to answer questions about itself: `o2b version`, `second_brain_wiring` views for linked projects and host health, and an instruction block rendered from the capability window the host actually granted. The [CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md) has the detail.--Previous releases, 1.55.0 and 1.54.0, made every note write an attributable and revertible event - a write record, a before-image store, a planned revert sealed by a digest, a fleet freeze refused at the one guard every content writer passes, and a per-shard hash chain under every append-only ledger - and turned `visibility:` from a label into a boundary enforced at the three roots every read surface reaches page content through. The [CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md) has the detail on both.--Previous releases, 1.53.1 and 1.53.0, closed a dedup pass that proposed the same merge forever and could write a merge cycle, and taught Hermes recall to carry the turn's query without leaving the curated lane that makes injection safe. The [CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md) has the detail on both.--Previous release, 1.52.0, was the honesty wave: nothing writes silently, nothing degrades silently. Nine tracker cards were read against the live source before anything was designed, and the reading did most of the work - one card described a feature that had already shipped end to end, one asked for privacy by riding a predicate that is inert in every default install, and four more had premises the source contradicted. What survived is one rule applied eight ways.--A note update now refuses to destroy what it could not read - an unreadable note raises `target_unreadable` instead of parsing as empty, and a blank body over a non-empty note needs an explicit `allow_empty`. `o2b search check` measures instead of inferring: a real pending-vector count replaces a recommendation that told fully embedded vaults to compute their first vectors, an embedder record audit reports when the recorded dimension contradicts the stored data, and `o2b search restamp` repairs the one drift that needs no provider. Every structured Brain record carries a server-derived `origin_channel` no caller can supply; Brain status derives `log_events_since_dream` from the shards it already reads and names an unreadable shard a lower bound; imports read back what they claim and report every missing key by name, and the sessions lane resumes an interrupted transcript at the turn boundary; the three note-producing envelope lanes hand the generating agent a bounded, ownership-filtered wikilink candidate manifest; a failed multi-artifact write leaves a durable dead letter; and a standing census documented - truthfully, at the time - that `visibility: private` was a view filter rather than a privacy boundary, with `o2b search check` saying so on vaults that use the field. That census is the coverage map 1.54.0 built the enforcement against.--The units speak one vocabulary on purpose: attempted, found, and missing with every missing key named, one pure module consumed by the import census, the write accounting, and the embedder audit, pinned by the same census that guards the project's other closed vocabularies. An independent reviewer given the finished branch returned two blocking findings and eleven non-blocking ones, all applied; the [CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md) names each.--Previous release, 1.51.0, was about which memories earn their keep: a deterministic salience gate in front of the dream pass's expensive fold, session mining that can only reach the speculative inbox, a provenance-following note delete under one snapshot and an exact count guard, expiration settable and changeable through one normalizer, vault pages staged as Agent Skill drafts that leave the vault only on explicit accept, an architect overview that names its grounding, and the shared needs-llm-step envelope type under all of it. Before it, 1.49.0 through 1.50.3 made a label into a real boundary, taught the installer to see what the machine already has, and fixed a Hermes bridge that discarded the one line of stderr naming why it could not start - the [CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md) has the detail.--Previous release, 1.48.0, was about work you can watch, bound and stop: the long passes emit progress and observe interrupts where an interrupt can physically be observed, a successful install states what it measured rather than what it hoped, the project scanner stopped entering what the repository ignores (24148 files visited became 2729), and five independent reviewers returned forty-four reproduced findings against the finished branch, all resolved by measurement rather than argument.--Previous release, 1.47.0, wired what already existed: nine capabilities that were exported, tested and used elsewhere, each with a site that needed them and did not call them - a destructive-operation gate with two call sites against roughly twenty-five destructive operations, and a ranker that read a document's authoring instant nine lines after ranking on the file's modification time.--Previous release, 1.46.0, was about claims the code could not back up. Nine units, four of them reported on the public tracker, and what they have in common is not a subsystem: in every one, the information needed to tell two cases apart either existed already and was thrown away, or cost one filesystem call nobody made. A search that returned nothing could not tell you whether the corpus was empty or the embedder was down, though fifteen degradation signals were being computed and then flattened into prose or dropped. Entity intake decided whether to trust a source from the shape of a string, never asking whether a file was behind it - and the caller supplying that string is the same agent that read the material being classified. Two concurrent writers racing for the same filename lost one of the records outright, measured at twelve dropped events out of twenty-four. The Hermes plugin and the core resolved different vaults while a docstring claimed they were identical, which is why a setup that worked showed as unconfigured for five weeks with nobody able to say why.--You can now say what you want indexed instead of listing everything you do not, with `vault.include_paths`; absent, it changes nothing, and that is measured against the previous release rather than asserted. A write tells you what is wrong with the page it just wrote, instead of deferring to a sweep that may never run. Recall telemetry carries which channel delivered, so a hook that was never installed and a hook that ran and stayed quiet stop looking identical. Every advertised tool parameter is documented and CI keeps it that way, and an unknown argument is named back to you with a suggestion rather than silently ignored.--Some of what was asked for is not here, and the absence is a decision. There was no registry of embedding-provider shutdown dates, because the only way to build one is a hand-maintained table over an open set of endpoints that would rot in place and be believed - a decision 1.48.0 reverses above, having answered that objection rather than set it aside. The schema-completeness guard covers input schemas only, because the output vocabulary declares union-typed fields with no type on purpose and the rule would demand a lie there. And the fix the intake issue asked for - let the host supply the trust verdict instead of the caller - is unbuildable, because no unforgeable caller identity exists in this surface, a conclusion this project had already reached elsewhere and not applied here. What shipped instead removes the free bypass and makes the claim auditable; it does not make the claim true, and the code says so. Four reviewers were then given the finished branch with no knowledge of how it was built, and told that a comment is a claim rather than evidence. They found twelve defects, two of them regressions this work introduced and invisible to its own tests. All are fixed, and the [CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md) names them.--Previous release, 1.45.1, fixed a Hermes flush that had been discarded at the boundary since 0.32.0 and a starter vault that went stale ninety days after it was authored. Before it, 1.45.0 was about silence not being an answer, and 1.44.0 about what the index already knew: thirteen units on the retrieval path, most of them values the system computed and discarded before anything could see them. Details for all three live in the [CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md).--Previous release, 1.43.0, was about provenance at the boundary: what enters your vault, under whose authority, validated against what, and backed by what proof. Entities an agent extracts from an untrusted source - a scraped page, a fetched article - now land in a quarantine lane instead of becoming first-class Brain entities, and trust is derived from the shape of the source identity rather than from any word list. You can declare in `_brain.yaml` which path prefixes a caller-named write may touch, and a write outside them is refused with the command that resolves it; its authority is the config file, not the caller, because a caller can name itself anything. Note creation gains an idempotent skip whose result tells you which happened, validation before the write lands, and a template mode with a deliberately small grammar. A back-dated note - an imported log, a meeting record - now ranks by the date its body declares rather than by when the file was touched, with the source of that date recorded beside it. Schema mutations can be previewed before they touch the vault, which matters more than it sounds: `--dry-run` was previously parsed and ignored. And an outcome an agent posts about its own work now carries the kernel's own on-disk evidence beside the claim, with a mismatch recorded rather than resolved.--Two things 1.43.0 deliberately did not build are worth knowing about, because their absence was a decision rather than an omission. There is no independent verifier, because agent identity here is an unauthenticated string and two records asserting two names chosen by one process are not two actors. And there is no pack fetched by URL, because a schema pack has no portable representation and no registry to install into. Five independent reviewers were given the finished branch and found thirty defects, nine of them introduced by this work and three of them mechanisms nothing could make fire; one of those three was removed rather than repaired. The [CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md) has the detail, including what was found and deliberately left open.--Previous release, 1.42.0, was a structural wave with no new capability: the six modules that cost the most to change, both import cycles removed, and nine places where absence and inability-to-examine had been collapsed into one answer. Details live in the [CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md).--Previous release, 1.41.0, was a signals-that-survive wave: eight units that carry a signal the system already computes the last few metres, to the decision it should have changed. Ingest now honours the repository's own `.gitignore`, nested ignore files, `.git/info/exclude` and submodule boundaries, through the same discovery module the hygiene scan uses - so a repo path stops pulling in the build artifacts it already declares as noise. A recall graded weak no longer evaporates when the call returns: repeated weak recall on the same question becomes a tracked, self-closing gap task. A query that names a period is ranked for that period instead of against it, detected from ISO and `since:`/`until:` tokens only so it behaves the same in every language. A scope-less capture says which routing signal it was missing and which scopes the vault actually has. Model-authored payloads are checked against a declared shape before they become knowledge, unconditionally - a validator that can be switched off is one the write path cannot rely on. Plain text can now seed a fact or a skill, not only a taste signal. And resumed work is recognised by a declared identity rather than by a fifteen-minute clock, so a branch or worktree switch stops breaking the chain. A ninth unit was built, reviewed, and reverted rather than shipped, because proving it inert was easier than pretending it was not - the [CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md) says why.--## Why--- **Lives in your Obsidian vault.** Open `Brain/preferences/pref-no-internal-abbrev.md` in Obsidian and you literally see what your agent learned about you - title, status, evidence count, confidence band, body text. Wikilinks, backlinks, graph view all work.-- **You own the data.** Plain Markdown on your filesystem. No service to cancel, no cloud account, no schema migration when a vendor pivots. Syncthing to your other machines if you want.-- **Memory that learns deterministically.** A `dream` pass turns repeat signals into rules and retires the ones nothing applies any more. Counters and atomic file moves - no LLM inside the algorithm, no surprise hallucinations in your memory.-- **One vault, every agent.** Hermes Agent is the primary integration. Claude Code, OpenAI Codex, Cursor, Aider, OpenClaw, opencode, Grok Build, kiro, Copilot CLI, Gemini CLI, and Pi all plug into the same Brain through MCP.--## One vault, many runtimes+## How it fits```mermaidflowchart LR- Vault[("Your vault<br/>Brain/ - plain Markdown")]- Hermes["**Hermes Agent**<br/>(primary)"]- CC[Claude Code]- Codex[OpenAI Codex]- Others["Cursor · Aider · OpenClaw<br/>opencode · Grok Build · kiro · Copilot CLI<br/>Gemini CLI · Pi · any MCP host"]-- Hermes <==> Vault- CC <--> Vault- Codex <--> Vault- Others <--> Vault-- style Hermes fill:#1e3a5f,stroke:#90caf9,color:#fff- style Vault fill:#5d3a9b,stroke:#ce93d8,color:#fff+ subgraph Clients["Agent clients"]+ Plug["Plugins: Claude Code, Codex,<br/>Hermes, opencode, Grok Build"]+ Mcp["MCP config: Cursor, kiro, Copilot CLI,<br/>Gemini CLI, ZCode, any MCP host"]+ Claw["OpenClaw<br/>in-process plugin"]+ Cliu["Aider, Pi<br/>CLI and context file"]+ end+ subgraph Product["Open Second Brain"]+ Srv["MCP servers<br/>open-second-brain, open-second-brain-writer"]+ Hooks["Lifecycle hooks<br/>o2b-hook"]+ Cli["CLI<br/>o2b"]+ Core["Core"]+ end+ subgraph Vault["Your vault"]+ Brain["Brain/<br/>Markdown the agent writes"]+ Notes["Your notes"]+ Index[(".open-second-brain/brain.sqlite<br/>rebuildable search index")]+ end+ Plug --> Srv+ Plug --> Hooks+ Mcp --> Srv+ Claw --> Core+ Cliu --> Cli+ Srv --> Core+ Hooks --> Core+ Cli --> Core+ Core --> Brain+ Core --> Index+ Core -. reads, writes a named note on request .-> Notes```-Hermes Agent owns the schedule (dream cron, daily digests, Telegram delivery). Other runtimes participate as readers and writers of the same Brain through MCP - no per-runtime fork of the memory.--## Quick start with Hermes Agent--**The simplest path - let your agent set it up.** Paste this into Hermes (or whichever AI agent already has shell access on the target machine):--> Install Open Second Brain for me by following the steps at <https://github.com/itechmeat/open-second-brain/blob/main/install/hermes.md>. My vault is at `/path/to/your-vault`.--The agent reads the install doc, runs every command, and verifies the result. That's it.--If you prefer running the steps yourself:+Each client reaches the same core through a plugin, an MCP registration or the CLI. The core keeps its own records under `Brain/` and a generated search index under `.open-second-brain/` that it can rebuild from the files. Your notes are read; the note tools write one only at a path the caller names.-```bash-# 1. Install the plugin-hermes plugins install itechmeat/open-second-brain --enable-hermes gateway restart--# 2. Put `o2b` on PATH-~/.hermes/plugins/open-second-brain/scripts/o2b install-cli--# 3. Bootstrap the vault-o2b init --vault /path/to/your-vault --name "My Second Brain"-o2b brain init --vault /path/to/your-vault --primary-agent <agent-name>--# 4. Verify-o2b doctor --vault /path/to/your-vault+```mermaid+flowchart LR+ Agent["Agent"] -->|brain_feedback| Inbox["Brain/inbox/<br/>signal"]+ Inbox -->|dream pass| Pref["Brain/preferences/<br/>rule"]+ Pref -->|rendered into| Active["Brain/active.md"]+ Active -->|read at session start| Agent+ Agent -->|brain_apply_evidence| Log["Brain/log/"]+ Log -->|next dream pass| Pref```-Enable Open Second Brain as the memory provider in `~/.hermes/config.yaml` (`memory.provider: open-second-brain`) and restart the gateway one more time - the agent now injects `Brain/active.md` into its system prompt, recalls context before each turn, and writes signals through `brain_feedback`, all through the one native provider. Full step-by-step: [`install/hermes.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/hermes.md).+The learning loop: signals become rules, rules reach the next session through `Brain/active.md`, and applied or violated evidence confirms, quarantines or retires them. Details: [`docs/how-it-works.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/how-it-works.md#a-preferences-lifecycle).-## Other runtimes+## Install-| Runtime | Install |-| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |-| Claude Code | Marketplace plugin (bundled MCP servers + hooks) - [`install/claudecode.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/claudecode.md) |-| OpenAI Codex | `codex plugin marketplace add ...` then `o2b install --target codex --apply` (MCP servers via `codex mcp add`, or a `config.toml` merge without the binary) - [`install/codex.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/codex.md) |-| OpenClaw | Native JS plugin, no MCP needed - [`install/openclaw.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/openclaw.md) |-| opencode | `o2b install --target opencode --apply` (MCP servers + native plugin) - [`install/opencode.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/opencode.md) |-| Grok Build | `o2b install --target grok --apply` (MCP in `config.toml` + native hooks) - [`install/grok.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/grok.md) |-| Cursor · Aider · kiro · Copilot CLI · Gemini CLI · Pi | `o2b install --target <name> --apply` - see [`install/`](https://github.com/itechmeat/open-second-brain/blob/main/install/) |-| Any other MCP host | `o2b install --target generic --apply` - [`install/generic.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/generic.md) |+1. Install [Bun](https://bun.sh/) 1.1 or later: [`install/prerequisites.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/prerequisites.md).+2. Install the plugin for your client (guides below), or get the `o2b` CLI: [`install/prerequisites.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/prerequisites.md#get-the-o2b-cli).+3. Create the vault files:-**Native Windows** (10/11, x64) is supported alongside Linux and macOS: Bun from `install.ps1`, `.cmd` launchers instead of symlinks, config under `%LOCALAPPDATA%` - [`install/windows.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/windows.md).+ ```bash+ o2b init --vault /path/to/vault --name "My Second Brain"+ o2b brain init --vault /path/to/vault+ ```-Each non-Hermes target writes a sidecar manifest under `<vault>/.open-second-brain/install.lock.json` so `o2b uninstall --target <name> --apply` removes exactly what it added.+4. Connect the client (table below), then check the result:-## What you get+ ```bash+ o2b doctor --vault /path/to/vault+ o2b install --check+ ```-- **Your memory as Markdown.** Every rule the agent learns about you is a file under `Brain/` you can open, edit, grep, and version. Obsidian wikilinks, backlinks, and the graph view just work - there is no separate UI to learn.-- **Memory that learns, and forgets, on its own.** A nightly `dream` pass turns repeated corrections into rules and retires the ones nothing uses any more. Deterministic by design: counters and atomic file moves, no LLM guessing inside your memory.-- **One brain, every agent.** Teach a rule in one agent and the next one already knows it - Hermes, Claude Code, Codex, Cursor, and the rest read and write the same vault.-- **You stay in control.** Pin, merge, retire, or roll back any rule from the `o2b` CLI. Every Brain mutation takes a verified snapshot first, so a bad change is one `o2b brain rollback` away.-- **Who wrote what, and how to take it back.** Every note write is a log event with a write id, the agent, the device, and the content hash before and after, and the bytes it replaced are kept. `o2b brain writes` reads the record; `o2b brain writes revert --agent <name>` plans a restore of exactly that agent's writes, refuses by name where another writer sits on top, and applies only the plan you read. `o2b brain freeze` stops every content writer on every device that syncs the vault until you say otherwise, and the log carries a per-shard hash chain so a line that was edited or removed after the fact has a file and a line number.-- **Search that explains itself.** Keyword plus an optional semantic layer over your vault, with results that show why they surfaced and what was missing - not a black box. Opt into a structured per-result score breakdown (`explain`), inline trust metadata (age, superseded, conflict), a relevance threshold that returns nothing rather than weak noise, and reinforcement that lifts memories you have marked useful. Track retrieval quality over time with `brain_eval` and the recall benchmark (hit@k, MRR, answer-containment@k).-- **Conversations survive compaction.** When the host compresses context and rotates the session id, capture and recall stitch the segments back into one conversation - any segment id returns the whole lineage.-- **Memory that cleans itself, on your terms.** `o2b brain hygiene scan` surfaces contested facts, near-duplicate rules, stale derived pages, and never-recalled memories; `apply` executes only the findings you select, and stale pages recompile from their recorded sources with a dry-run preview.-- **A vault that stays fresh, consistent, and scoped.** `o2b search watch` keeps the index live as you edit, debounced and incremental; note identity is Unicode-normalized so the same file is one entry across macOS and Linux devices instead of a phantom cross-device duplicate; and recall accepts an opt-in `agent_scope` so a page marked with an `owner:` is reachable only to its owner while shared pages stay open to all.-- **Knowledge that knows where it came from.** Drop a source document and the agent's extraction becomes cross-referenced entity and concept pages plus a summary page that backlinks the source and lists its connections; N sources become one dated report whose every finding cites the source that flagged it; a derived fact carries a `deduced`/`inferred` provenance level and links back to its premises, and recall trusts an operator-stated rule above a machine-derived one. A fact can declare an `owner:` so multi-agent brains keep separate truth spaces, and a standing-query attention flow surfaces the open loops you declare. The plugin never runs a model itself - the agent owns generation, the vault owns the durable, provenanced record - and every behaviour is opt-in.-- **An index that survives interruption.** Stopping `o2b search watch` mid-sync finishes the in-flight pass at a file boundary before exiting (within `search_shutdown_grace_seconds`) instead of killing it mid-write; an incremental run is already resumable through the unchanged-file fastpath, and `search_resume_reindex` extends that to a full rebuild - an interrupted reindex resumes its staging build instead of starting over, guarded by a signature so a drifted build is discarded rather than trusted. Both default off, so behaviour is unchanged unless you ask for it.-- **A brain you can carry, hand off, and write to in process.** `o2b brain bank-export` serialises a whole vault - preferences, the page graph, a per-page interchange contract (path, kind, advisory confidence/provenance, citations, aliases, freshness), and the sources dashboard - into one deterministic, schema-versioned bundle for backup, migration, or downstream-tool ingest; `bank-import` reconstructs the page graph and the preferences - the latter through the audited preference transaction, so the trial window, confidence band, revision counter and audit trail are maintained and a bundle that is behind the vault is refused instead of rewinding it - and reports the rest as carried-not-restored rather than faking a full restore. A `brain_create_note` MCP tool writes an actual vault note (path + frontmatter + content) atomically, refusing traversal, the Brain root, and clobbering. And `createBrain(vault)` is a thin in-process SDK over the same core functions - bank/graph export-import, preference export, source ingest plus list/get/delete, and note creation - so scripts and agents manage brain content without the CLI or MCP layer.-- **Knowledge you can share without sharing the vault.** `o2b brain knowledge-pack export --select topic:…|tag:…|<id>` packs a chosen subset - rules and the pages that hold runbooks and conventions - into an OKF-based bundle sealed with sha256, blocking pages marked `visibility:` or carrying an `owner:` and redacting secrets on the way out. The receiving vault can `preview` it (manifest, samples, integrity, conflicts, prompt-injection warnings), `install` it as untrusted candidates - rules arrive unconfirmed on a fresh trial window, pages stage in `OKF Review/`, each stamped `knowledge_pack: <name>@<sha>` - and `uninstall` it as a unit behind a snapshot. See [docs/cli-reference.md](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#knowledge-packs).-- **Recall you can tune, and a working set that prunes itself.** `o2b search --profile fast|balanced|thorough` (and the `brain_search` `profile` field) pick a recall preset over the same bounded knobs the self-tuner uses - an explicit profile wins over a learned grid point, and no profile leaves ranking bit-for-bit unchanged. `o2b brain file-context <path>` surfaces prior vault work that mentions a file before you read it; `o2b brain co-occurrence` proposes relationship edges between entities repeatedly co-referenced from the same notes, scored structurally over the wikilink graph with no natural-language word list in any language; and `o2b brain continuity rank` weights working-memory records by a usage-driven decay derived only from real recall telemetry, so stale decisions fade while actively-recalled ones stay prominent. All deterministic, all read-only or suggestion-only.-- **Session knowledge you can query, trace, and walk.** `o2b brain session-summary` (and `brain_session_summary`) stores a session-scoped digest over four categories - request, decisions, learnings, next_steps - that the agent extracts and the kernel only stores, so you can ask what a session decided as one unit. `o2b brain idea-lineage <id>` traces how a derived artifact was reached as an observation to synthesis to conclusion graph over the edges already recorded (continuity `sourceRefs`, or a preference's belief-evolution), cycle-guarded and depth-bounded. `o2b brain note-history <path>` splits a note's git history into episodic phases on a deterministic commit-time gap - language-agnostic, no commit-message parsing. The kernel never calls a model; absent inputs report honestly rather than fabricating.-- **Operational readability for code partners and large vaults.** Open Second Brain now exposes a read-only CodeGraph report (`o2b partner codegraph report`, `brain_codegraph_report`) that resolves the in-scope code project, reports the codegraph index state with node and edge counts, and structurally parses Cargo.toml for Rust workspace members. The report is honest about missing CLIs, missing indexes, and non-Rust projects. For large vaults, community materialization can run in fixed-size batches (`o2b brain clusters run --batch-size N`, `brain_clusters` `batch_size`) with per-batch success or isolated failure reporting, while the default run stays byte-identical.-- **Consistent feedback categorization.** A vault-local `feedback.default_scope` in `Brain/_brain.yaml` gives agent-recorded signals a consistent category (for example `coding`) when no explicit scope is provided, with the same precedence across the inbox signal, its shared-namespace mirror, and any force-confirmed preference. The effective scope is computed once at the signal write boundary and byte-identical output is preserved when the setting is absent or no explicit scope is given.-- **Path-safe vault writes.** The write-session commit chokepoint now re-resolves every target through `ensureInsideVault` before any directory creation, read, or write, catching symlinked ancestors that point outside the vault root. The backstop fails closed: a target resolving outside the configured vault is rejected and nothing is written. All other caller-derived vault paths already funnel through guarded constructors; regression tests pin both invariants.-- **Recall that pays for depth only on demand.** General vault search now offers the same progressive 3-layer disclosure session-recall already had. `o2b search "<q>" --disclosure cards` (and the `brain_search` `disclosure: "cards"` field) returns compact layer-1 cards - path, title, score, reasons, a bounded snippet, and a `path:Lstart-Lend` pointer - instead of full content per hit, so recall stays token-cheap. Drill a hit with `o2b search expand --chunk <id>` (or `brain_search_expand`) to get layer 2 (the fuller note) and layer 3 (the raw chunk transcript, paginated by cursor). It reuses the existing index read - no new index, no model - and the default `full` mode is byte-identical to before. Cards compose with cross-vault recall too: `--global --disclosure cards` returns the token-cheap layer-1 cards merged across every origin (each labelled by its origin), not an empty result set.+The full router with readiness criteria is [`install.md`](https://github.com/itechmeat/open-second-brain/blob/main/install.md); native Windows is covered in [`install/windows.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/windows.md).-- **A today surface for the operator, and prose that writes back.** `o2b brain today` (and `brain_brief view=today`) renders a read-only, live-derived dashboard - due and overdue obligations, open loops, a chronologically merged typed activity timeline with relative ages, and totals - where every section is re-derived on demand from the vault, never stored, and a failing section reports its error while the rest still render. Jot `@osb loop <text>` in any note to keep an intention visible until you close it with `@osb loop close id=<id>` (ids are printed on the dashboard; loop markers survive scans and are never consumed). Jot `@osb set note=<target> field=<field> value=<value>` and `o2b brain apply-markers --apply` turns it into a schema-validated frontmatter mutation - fail-closed target resolution (ambiguous titles list candidates instead of guessing), one `attribute-write` audit event per applied change with the prior value, idempotent consumption of applied markers, and the whole write path gated behind the opt-in `guardrails.marker_writeback` flag. Report mode needs no flag and writes nothing.+## Supported clients-- **It knows what it is, and what it is wired into.** `o2b version` answers on the command line the question the MCP handshake has always answered - one constant behind both, so the two surfaces cannot disagree. `second_brain_wiring` puts two CLI-only answers on the MCP surface: `view=projects` lists every project directory registered against this vault with the state of its pointer file, and `view=hosts` runs the same per-adapter verification `o2b install --check` runs, so an agent can ask whether the runtimes this install wired up can still be reached. Paths in those answers are opaque references unless you asked for raw ones. And the instructions block every agent reads at connect time is now rendered from what this runtime actually left callable: guidance for a tool the host disabled is removed rather than contradicted, and each removal is named with its reason.+| Client | Integration | Guide |+| --- | --- | --- |+| Claude Code | Marketplace plugin: MCP servers and hooks | [`install/claudecode.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/claudecode.md) |+| OpenAI Codex | Marketplace plugin, then `o2b install --target codex --apply` | [`install/codex.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/codex.md) |+| Hermes Agent | Plugin and memory provider | [`install/hermes.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/hermes.md) |+| OpenClaw | Native plugin, no MCP | [`install/openclaw.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/openclaw.md) |+| opencode | `o2b install --target opencode --apply`: MCP servers and a native plugin | [`install/opencode.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/opencode.md) |+| Grok Build | `o2b install --target grok --apply`: MCP servers and hooks | [`install/grok.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/grok.md) |+| Cursor | `o2b install --target cursor --apply` | [`install/cursor.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/cursor.md) |+| kiro | `o2b install --target kiro --apply` | [`install/kiro.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/kiro.md) |+| GitHub Copilot CLI | `o2b install --target copilot-cli --apply` | [`install/copilot-cli.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/copilot-cli.md) |+| Gemini CLI | `o2b install --target gemini-cli --apply` | [`install/gemini-cli.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/gemini-cli.md) |+| ZCode | MCP servers added to its config by hand | [`install/zcode.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/zcode.md) |+| Aider | `o2b install --target aider --apply`: context file, no MCP | [`install/aider.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/aider.md) |+| Pi | `o2b install --target pi --apply`: skill over the CLI | [`install/pi.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/pi.md) |+| Any other MCP host | `o2b install --target generic --apply --out -` prints the server entries | [`install/generic.md`](https://github.com/itechmeat/open-second-brain/blob/main/install/generic.md) |-- **It knows the machine it is installed on.** `o2b install --friction` lays every supported runtime side by side - how it is installed, whether it caps the tool surface, whether a `--check` on it is a file comparison or a live question put to the host, and whether this build can read the transcripts that runtime writes. Two hosts can now be ASKED (`codex mcp list`, `copilot mcp list`) instead of inferred from a config file, so "installed" and "actually loaded" stop being the same answer. `o2b state status` does the same for the vault: forty declared state locations, each with where it resolved, whether it is reachable, and which setting put it there - and `o2b state migrate` moves the lot to another directory behind a digest manifest, refusing before it commits and reversible after. `o2b brain import-session --discover` finds the session logs already on your disk and says which have never been imported, so cross-agent recall no longer depends on your knowing where each runtime keeps its transcripts.+`o2b uninstall --target <name> --apply` removes what `o2b install` wrote; the vault is never touched ([`install.md`](https://github.com/itechmeat/open-second-brain/blob/main/install.md#uninstall)).-That is the day-to-day picture. The full capability surface, every CLI verb, and the mental model live in the [documentation](#documentation) below.+## Capabilities-## Safety+- **Preferences that learn and expire.** Signals, a deterministic dream pass, confidence and retirement: [how it works](https://github.com/itechmeat/open-second-brain/blob/main/docs/how-it-works.md#a-preferences-lifecycle).+- **Reversible changes.** Brain mutations take a snapshot first; `o2b brain rollback` restores it: [snapshots](https://github.com/itechmeat/open-second-brain/blob/main/docs/how-it-works.md#snapshots-and-rollback).+- **Attributed writes.** `o2b brain writes` lists every note write by agent and device, `writes revert` plans a restore, `o2b brain freeze` stops all writers, and `o2b brain log verify` checks the hash-chained log: [Brain CLI](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#brain-observing-memory).+- **Search.** Keyword search with an optional semantic lane, result explanations, recall profiles and compact cards: [search CLI](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#search), [ranking](https://github.com/itechmeat/open-second-brain/blob/main/docs/how-it-works.md#full-text-search).+- **Session recall.** Import agent transcripts already on disk and search them: [session logs](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#session-logs-this-machine-already-has-since-v1500).+- **Hygiene.** `o2b brain hygiene scan` finds contested, duplicate, stale and unused memories; `apply` runs only the findings you pick: [maintenance](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#maintenance-and-operator-surfaces).+- **Sharing and backup.** Knowledge packs export a chosen subset; `o2b brain bank-export` writes a one-file backup bundle: [knowledge packs](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#knowledge-packs).+- **Today view and note markers.** `o2b brain today`, `@osb loop` and `@osb set` markers: [Brain CLI](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#brain-observing-memory).+- **Self-inspection.** `o2b version`, `o2b install --friction` and `o2b state status` report what is installed and where state lives: [CLI reference](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#core).+- **MCP surface.** Tools, tool profiles for hosts with tool limits, and the always-loaded writer server: [`docs/mcp.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/mcp.md).-- Plain Markdown on your filesystem. No daemon, no background writes. The MCP server is a stdio subprocess that exits with the parent runtime. An optional HTTP transport (`o2b mcp --transport http`) is off by default and safe by design: it binds loopback (`127.0.0.1`), enforces a Host/Origin DNS-rebinding guard on every request, and exposes an unauthenticated `GET /health` liveness probe. A bearer token (`--api-key`) is optional on loopback and mandatory when binding a non-loopback host - the server refuses to expose an unauthenticated endpoint on the network. On `SIGTERM`/`SIGINT` either transport stops accepting new work, finishes what is already running under a bounded deadline (`O2B_MCP_DRAIN_MS`, ten seconds by default), and only then exits - so a shutdown never truncates a tool call, and `/health` reports `draining` while it happens.-- Your vault is the only source of truth - no hidden state, no cloud copy.-- Brain mutations (`dream`, `merge`, `upgrade`) take a pre-run snapshot with a SHA-256 sidecar; `o2b brain rollback` aborts on drift unless `--force-rollback`. Destructive cleanups (`forget-source --confirm`, `entity prune --confirm`) run behind the same snapshot gate and report their recovery point; dry runs take no snapshot.-- Store hardening: `o2b brain doctor --remediate` can tighten existing `Brain/` files to owner-only permissions (dry-run first, idempotent), the doctor flags vault-internal symlinks that resolve outside the vault, and MCP responses carry an opaque `vault://` store reference instead of the absolute host path unless `expose_host_paths: true` is set.-- Secrets are not supposed to live in the vault. Daily logs and config exports run through a best-effort redactor, `$secret:NAME` references resolve from the local environment and are never stored, and Brain redaction strips `<private>...</private>` regions before storage.-- Automatically surfaced Brain context passes through a deterministic prompt-injection guard; filtered output returns a placeholder with a reason code and the source Markdown is never rewritten. Opt into `untrusted_source_delimiting` for language-agnostic structural containment instead: an untrusted span is wrapped in a provenance-carrying `<untrusted_source path sha256>` delimiter and neutralized by structure (invisible/control characters, delimiter breakouts) rather than a per-language word list, losslessly and identically for every language.-- Context receipts and recall telemetry are opt-in and store redacted metadata, hashes, and counters rather than raw prompt text.-- Optional decision models (a typed judgment model such as Jev, used to choose among candidates the code already produced) are off by default, per use. They run only when the machine config enables them and the named key variable is set (a self-hosted server on loopback needs no key); while active, shadow and enforce both send masked, clipped, redacted candidate text to the configured endpoint, private pages and `<private>` regions never leave, and no decision writes to the vault. See [`docs/decision-models.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/decision-models.md).+## Optional features-## Optional decision models+- **Semantic search:** an embedding provider plus `sqlite-vec`; the `embeddings-setup` skill walks through it: [`skills/embeddings-setup/SKILL.md`](https://github.com/itechmeat/open-second-brain/blob/main/skills/embeddings-setup/SKILL.md).+- **Decision models:** a typed judgment model that can rerank search and filter candidates, off by default per use: [`docs/decision-models.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/decision-models.md).-An optional decision model (a typed judgment model such as Jev) can rerank the head of the search results, pick the skills `skills_attach` offers, pre-filter the turns of the extract-signals envelope and the notes the recall hook injects, and add advisory verdicts to dedup, tension, label and answerable proposals. Each use is off by default: until you enable it, nothing changes and nothing is sent. The `decision-model-setup` skill walks an agent through the setup. To turn on the reranker by hand:--1. Export a key from a supported provider as an environment variable, for example `TYPESAFE_API_KEY`.-2. In the machine config set `decision_model_enabled: "true"`, `decision_model_provider: typesafe`, `decision_model_env_key: TYPESAFE_API_KEY` (the variable's name, never the key), `decision_model_uses: "rerank:shadow"`, `search_rerank_enabled: "true"`, `search_rerank_kind: decision-model` and `search_rerank_top_k: "30"`.-3. Run `o2b decision-model check --ping`.--It pays off only with a semantic lane (`embedding_provider` configured, `local` is enough). The other uses, the routes (TypeSafe, OpenRouter, Vercel, OpenCode Zen, self-hosted), moving from shadow to enforce, measuring, what is sent, the cost gate and the per-vault opt-out: [`docs/decision-models.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/decision-models.md).--## Updating--```bash-o2b update # detect runtimes, skip unchanged, apply, verify-o2b doctor # confirm the new manifest validates-```+## What is new-Updates need no manual symlink surgery: hooks resolve the active plugin version-on their own and the `~/.local/bin` CLI symlinks self-heal on the next session-start. Per-runtime upgrade paths and the canonical version source live in-[`install.md`](https://github.com/itechmeat/open-second-brain/blob/main/install.md); the update-safety contract (and the invariants any-change to hooks/launcher/install must keep) lives in-[`docs/updating.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/updating.md).+1.61.0 moves MCP server start-up off the Brain upgrade path, makes ingest locks fair, puts the Claude Code MCP manifest inside `plugin.json`, and adds an inbox archive. Every release is described in the [CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md).## Documentation-| Topic | Doc |-| -------------------------------------------------- | ---------------------------------------------------------------- |-| Mental model, vault layout, dream mechanics | [`docs/how-it-works.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/how-it-works.md) |-| MCP protocol, tools, lifecycle, writer split | [`docs/mcp.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/mcp.md) |-| Full CLI reference (every verb, every flag) | [`docs/cli-reference.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md) |-| Update safety contract + hook/launcher invariants | [`docs/updating.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/updating.md) |-| Hermes cron jobs (daily digest, discipline report) | [`docs/hermes-cron.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/hermes-cron.md) |-| Cross-project pointer (multi-host vaults) | [`docs/cross-project-pointer.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/cross-project-pointer.md) |-| Observability contract (events, gates, payloads) | [`docs/observability.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/observability.md) |-| Optional decision models (off by default) | [`docs/decision-models.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/decision-models.md) |-| Metrics layer (the dashboard data contract) | [`docs/metrics.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/metrics.md) |-| Frozen-surface and stability policy | [`docs/stability.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/stability.md) |-| Architecture | [`docs/architecture.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/architecture.md) |-| Origin idea | [`docs/idea.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/idea.md) |--## Uninstalling--```bash-o2b uninstall # print plan (read-only)-o2b uninstall --apply-local --remove-cli # remove local state and symlinks-```--Your vault is never touched by the uninstall flow. Delete it yourself with normal filesystem tools if you want to.--## License--MIT. Source: <https://github.com/itechmeat/open-second-brain>.+| Topic | Page |+| --- | --- |+| Mental model, vault layout, dream pass, safety properties | [`docs/how-it-works.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/how-it-works.md) |+| Every CLI verb and flag | [`docs/cli-reference.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md) |+| MCP protocol, tools, writer split | [`docs/mcp.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/mcp.md) |+| Architecture and configuration model | [`docs/architecture.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/architecture.md) |+| Updating (`o2b update`) and upgrade notes | [`docs/updating.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/updating.md) |+| Observability events | [`docs/observability.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/observability.md) |+| Metrics data contract | [`docs/metrics.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/metrics.md) |+| Cross-project pointer | [`docs/cross-project-pointer.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/cross-project-pointer.md) |+| Scheduled Brain digest (Hermes cron) | [`docs/hermes-cron.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/hermes-cron.md) |+| Stability policy | [`docs/stability.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/stability.md) |+| Origin of the idea | [`docs/idea.md`](https://github.com/itechmeat/open-second-brain/blob/main/docs/idea.md) |++## Project++[CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md) · [Security policy](https://github.com/itechmeat/open-second-brain/blob/main/SECURITY.md) · [Source on GitHub](https://github.com/itechmeat/open-second-brain) · [MIT License](https://github.com/itechmeat/open-second-brain/blob/main/LICENSE)diff --git a/tests/docs/install-verify-conformance.test.ts b/tests/docs/install-verify-conformance.test.tsindex b2540495..4e2a3a1b 100644--- a/tests/docs/install-verify-conformance.test.ts+++ b/tests/docs/install-verify-conformance.test.ts@@ -72,6 +72,7 @@ const PIPELINE_HOSTED_DOCS: Readonly<Record<string, string>> = Object.freeze({"openclaw.md": "plugin-hosted; verified with `openclaw plugins inspect`, not an OSB adapter","prerequisites.md": "shared setup, not a runtime document","windows.md": "shared setup for native Windows, not a runtime document",+ "zcode.md": "manual MCP config in ZCode's own file; no install adapter yet",});interface Harness {