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
v0.10.10: address CodeRabbit review
Sol Aitken3e297a5b445c
diff --git a/README.md b/README.mdindex 07c28484..75dfd994 100644--- a/README.md+++ b/README.md@@ -184,10 +184,10 @@ exposes the same deterministic operations as MCP tools:- **Core (3):** `second_brain_status`, `second_brain_query`,`vault_health`.-- **Brain (7):** `brain_feedback`, `brain_dream`,- `brain_apply_evidence`, `brain_digest`, `brain_query`,- `brain_doctor`, `brain_backlinks`. See the [Brain section](#brain-observing-memory)- below.+- **Brain (9):** `brain_feedback`, `brain_dream`,+ `brain_apply_evidence`, `brain_note`, `brain_context`,+ `brain_digest`, `brain_query`, `brain_doctor`, `brain_backlinks`.+ See the [Brain section](#brain-observing-memory) below.- **Pay Memory (8):** `payment_memory_init`,`payment_receipt_append`, `asset_capture`,`payment_report_generate`, `payment_policy_check`,@@ -205,13 +205,16 @@ schemas, and lifecycle details are in [`docs/mcp.md`](docs/mcp.md).The plugin's `.mcp.json` ships **two** MCP-server entries:-- `open-second-brain` β the full surface (17 tools); subject to+- `open-second-brain` β the full surface (21 tools); subject toClaude Code's `MCPSearch` tool-search deferral when MCPdefinitions push the system prompt past 10% of the context window.-- `open-second-brain-writer` β a minimal surface of exactly two- tools, `brain_feedback` and `brain_apply_evidence`, marked- `alwaysLoad: true`. The agent records taste signals and evidence- events without a ToolSearch round-trip on every session boot.+- `open-second-brain-writer` β a minimal always-loaded surface of+ four tools: `brain_feedback`, `brain_apply_evidence`, `brain_note`+ (writers) and `brain_context` (read-only pull-bootstrap of+ `Brain/active.md`, v0.10.10). The agent records taste signals,+ evidence events, and milestone notes β and fetches the active+ rule digest at session start in runtimes without a SessionStart+ hook β without a ToolSearch round-trip on every session boot.Both servers reuse the same backing CLI (`o2b mcp --scope writer`vs the default `--scope full`). Handlers are byte-identical; thediff --git a/docs/how-it-works.md b/docs/how-it-works.mdindex aed4b9a3..3bc95af3 100644--- a/docs/how-it-works.md+++ b/docs/how-it-works.md@@ -305,7 +305,8 @@ expose the number alongside the band for inspection.## Active preferences injectionA confirmed rule is useless if the agent does not see it during work.-v0.9.1 closes that gap with three cooperating surfaces, all derived+Four cooperating surfaces close that gap (the first three since+v0.9.1, the fourth β `brain_context` β since v0.10.10), all derivedfrom the same source of truth (`Brain/preferences/`):```mermaid@@ -337,6 +338,11 @@ flowchart LRpull access (`osb://preferences/active` and friends in the tableabove). The MCP `initialize` reply advertises the `resources`capability so clients know to enumerate them.+- **`brain_context` MCP tool** (v0.10.10) lives in the always-loaded+ writer-scope MCP server. Runtimes that lack a `SessionStart` hook+ *and* do not auto-load MCP resources (Cursor, Aider, raw Claude+ API) can fetch the same `active.md` body plus active-preference+ counts with a single tool call.`active.md` is **not** edited by hand β `o2b brain dream` and pin /unpin re-derive it from `preferences/` and `retired/`. Deleting thediff --git a/docs/plans/2026-05-20-v0.10.10-design.md b/docs/plans/2026-05-20-v0.10.10-design.mdindex 18622ad7..f15bb401 100644--- a/docs/plans/2026-05-20-v0.10.10-design.md+++ b/docs/plans/2026-05-20-v0.10.10-design.md@@ -82,7 +82,7 @@ of which confirmed rules carry weight right now.### 4.1 Module layout-```+```textsrc/core/brain/most-applied.ts (new) pure computation: log β ranked entriessrc/core/brain/note.ts (new) shared appendBrainNote coresrc/core/brain/active.ts (edit) call most-applied, render section, expose count@@ -107,7 +107,7 @@ calls.### 4.2 Data flow-```+```textBrain/log/*.md|.jsonl βββΊ readLogDay (existing) βββΊ most-applied βββΊ renderBrain/preferences/*.md βββΊ parsePreference (existing) βββBrain/retired/*.md βββΊ parseRetired (existing) ββββββΊ render@@ -127,7 +127,7 @@ derived from existing log files at render time.### 5.1 Surface-```+```textname: brain_contextdescription: Pull the current Brain/active.md body plus active-preferencecounts. Use at session start when SessionStart hook is@@ -236,7 +236,7 @@ contract) and moves on. The function never throws.In `renderBody`, between `Confirmed` and `Quarantine`:-```+```text## Most-applied (30d) (<N>)- `pref-foo` (scope: <scope>, applied_30d: <n>) β <principle>@@ -311,7 +311,7 @@ CLI wrapper translates it into a 2-exit with the same message).### 7.2 CLI surface-```+```texto2b brain note <text> [--agent <name>] [--vault <path>] [--config <path>] [--json]```@@ -373,7 +373,7 @@ disabled β simpler, picked.)After the existing `config_keys:` block:-```+```textsemantic: off (run 'o2b search check' for setup steps)```@@ -384,7 +384,7 @@ nothing.The `--json` payload grows three keys, always present:-```+```text{"config_path": "...","config_exists": true,diff --git a/docs/plans/2026-05-20-v0.10.10-impl.md b/docs/plans/2026-05-20-v0.10.10-impl.mdindex 6255bcf7..14aabafe 100644--- a/docs/plans/2026-05-20-v0.10.10-impl.md+++ b/docs/plans/2026-05-20-v0.10.10-impl.md@@ -1312,7 +1312,7 @@ plain verbs (between `cmdBrainMerge` and `cmdBrainPin` is fine):Edit `src/cli/brain/help-text.ts`. Add a `note` line to `BRAIN_HELP`near the related verbs (after `feedback`, `apply-evidence`):-```+```textnote <text> Append a one-line narrative milestone to Brain/log/today```@@ -1727,7 +1727,7 @@ Expected: green.Edit `src/mcp/instructions.ts`. Find the writer-server descriptionblock. Add a line for `brain_context`:-```+```text- brain_context β pull the current Brain/active.md body pluscounts. Use at session start when the hostruntime lacks a SessionStart hook (Cursor,@@ -2274,10 +2274,10 @@ If yes:`; + v0.10.10 Most-applied (30d) section`.2. In the `## Π‘ΠΏΠΎΡΠ½ΡΠ΅ / ΠΎΡΠ»ΠΎΠΆΠ΅Π½Π½ΡΠ΅` section, remove the bulletstarting with **Pull-bootstrap MCP-tool `brain_context`/`brain_principles`**.-3. In the `## Deferred work` section, find the- `**Β§32B CLI verb `o2b brain note`.**` bullet. Replace it with a- shipped reference pointing at the v0.10.10 release (mirroring the- tone of the other already-shipped deferred items).+3. In the `## Deferred work` section, find the bullet that starts+ with **Β§32B CLI verb `o2b brain note`** and replace it with a+ shipped reference pointing at the v0.10.10 release (mirroring+ the tone of the other already-shipped deferred items).- [ ] **Step 10.3: Tell the operator.**diff --git a/hooks/lib/detect.ts b/hooks/lib/detect.tsindex e0eb1250..4d44747c 100644--- a/hooks/lib/detect.ts+++ b/hooks/lib/detect.ts@@ -84,6 +84,18 @@ function splitShellCommandSegments(command: string): string[] {continue;}+ if (ch === "\\") {+ // Outside-quotes backslash escapes the next character. Preserve+ // both so an escaped separator (`echo \; o2b brain note ...`)+ // does not split the segment.+ current += ch;+ const next = command[i + 1];+ if (next !== undefined) {+ current += next;+ i += 1;+ }+ continue;+ }if (ch === "'" || ch === '"') {quote = ch;current += ch;diff --git a/src/cli/main.ts b/src/cli/main.tsindex c515eff8..767eb79d 100644--- a/src/cli/main.ts+++ b/src/cli/main.ts@@ -191,7 +191,16 @@ function writeSearchInitBlock(configPath: string): void {// template when the operator explicitly turned semantic search on// but did not configure the key.const semantic = resolveSemanticConfigState(data, process.env);- if (!semantic.semantic_enabled || semantic.embedding_key_present) return;+ // Skip the embedding-key prompt when search is explicitly disabled+ // (no point onboarding semantic when the whole layer is off), the+ // semantic flag is off, or the key is already present.+ if (+ semantic.search_disabled ||+ !semantic.semantic_enabled ||+ semantic.embedding_key_present+ ) {+ return;+ }process.stdout.write([diff --git a/src/mcp/brain-tools.ts b/src/mcp/brain-tools.tsindex 3075ba1b..f8e9d0c4 100644--- a/src/mcp/brain-tools.ts+++ b/src/mcp/brain-tools.ts@@ -86,7 +86,7 @@ import { appendLogEvent } from "../core/brain/log.ts";import type { BrainLogEntry } from "../core/brain/log.ts";import { appendBrainNote } from "../core/brain/note.ts";-import { INVALID_PARAMS, MCPError } from "./protocol.ts";+import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "./protocol.ts";import type { ServerContext, ToolDefinition } from "./tools.ts";import { coerceStr, coerceBool, coerceIsoDate, coerceFormat } from "./coerce.ts";@@ -353,7 +353,12 @@ async function toolBrainNote(...(ctx.configPath ? { configPath: ctx.configPath } : {}),});} catch (err) {- throw new MCPError(INVALID_PARAMS, (err as Error).message);+ // `appendBrainNote` throws one validation error ("text is required");+ // any other failure is an I/O / filesystem fault from `appendLogEvent`+ // and must not be reported as a client-side INVALID_PARAMS.+ const message = (err as Error).message ?? String(err);+ const code = message.startsWith("brain_note:") ? INVALID_PARAMS : INTERNAL_ERROR;+ throw new MCPError(code, message);}return {logged_at: res.logged_at,diff --git a/tests/e2e/v0.10.10-pull-channels.test.ts b/tests/e2e/v0.10.10-pull-channels.test.tsindex 65ad6f1e..41661250 100644--- a/tests/e2e/v0.10.10-pull-channels.test.ts+++ b/tests/e2e/v0.10.10-pull-channels.test.ts@@ -46,10 +46,6 @@ afterEach(() => {rmSync(tmp, { recursive: true, force: true });});-function today(): string {- return new Date().toISOString().slice(0, 10);-}-describe("v0.10.10 pull-channels e2e", () => {test("init β brain note β status β brain_context MCP call", async () => {// 1. Bootstrap the vault and the Brain layer through the CLI.@@ -74,7 +70,9 @@ describe("v0.10.10 pull-channels e2e", () => {const noteResult = JSON.parse(r.stdout);expect(noteResult.agent).toBe("tester");- const logMdPath = join(vault, "Brain", "log", `${today()}.md`);+ // Derive the log path from the CLI response (UTC midnight roll could+ // otherwise flake the assertion when the test crosses a date boundary).+ const logMdPath = String(noteResult.absolute_log_path);const logJsonlPath = logMdPath.replace(/\.md$/, ".jsonl");const md = readFileSync(logMdPath, "utf8");expect(md).toContain("β note");diff --git a/tests/hooks/detect.test.ts b/tests/hooks/detect.test.tsindex af301df1..932c8a04 100644--- a/tests/hooks/detect.test.ts+++ b/tests/hooks/detect.test.ts@@ -231,6 +231,19 @@ describe("summarizeTurn", () => {expect(s).toEqual({ hadArtifact: true, hadBrainEvent: true });});+ test("escaped separator does NOT split a segment", () => {+ // Outside quotes, `\;` is a literal semicolon β bash treats it as+ // part of the previous token, so the line is one segment. If the+ // splitter were to break on `;` regardless, an echo containing+ // `o2b brain note` after the escaped semicolon could falsely+ // clear the guardrail.+ const s = summarizeTurn(+ [{ name: "Write" }, { name: "Bash" }],+ ['echo \\; o2b brain note "not executed"'],+ );+ expect(s).toEqual({ hadArtifact: true, hadBrainEvent: false });+ });+test("`o2b brain notes` lookalike does NOT clear guardrail", () => {// Trailing-space anchor in the needle list prevents a future// `notes` / `note-...` verb from being silently treated as a