Skip to content

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.md
index 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 to
Claude Code's `MCPSearch` tool-search deferral when MCP
definitions 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; the
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index 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 injection
A 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 derived
from the same source of truth (`Brain/preferences/`):
```mermaid
@@ -337,6 +338,11 @@ flowchart LR
pull access (`osb://preferences/active` and friends in the table
above). 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 the
diff --git a/docs/plans/2026-05-20-v0.10.10-design.md b/docs/plans/2026-05-20-v0.10.10-design.md
index 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
-```
+```text
src/core/brain/most-applied.ts (new) pure computation: log β†’ ranked entries
src/core/brain/note.ts (new) shared appendBrainNote core
src/core/brain/active.ts (edit) call most-applied, render section, expose count
@@ -107,7 +107,7 @@ calls.
### 4.2 Data flow
-```
+```text
Brain/log/*.md|.jsonl ──► readLogDay (existing) ──► most-applied ──► render
Brain/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
-```
+```text
name: brain_context
description: Pull the current Brain/active.md body plus active-preference
counts. 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
-```
+```text
o2b brain note <text> [--agent <name>] [--vault <path>] [--config <path>] [--json]
```
@@ -373,7 +373,7 @@ disabled β€” simpler, picked.)
After the existing `config_keys:` block:
-```
+```text
semantic: 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.md
index 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`):
-```
+```text
note <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 description
block. Add a line for `brain_context`:
-```
+```text
- brain_context β€” pull the current Brain/active.md body plus
counts. Use at session start when the host
runtime lacks a SessionStart hook (Cursor,
@@ -2274,10 +2274,10 @@ If yes:
`; + v0.10.10 Most-applied (30d) section`.
2. In the `## Π‘ΠΏΠΎΡ€Π½Ρ‹Π΅ / ΠΎΡ‚Π»ΠΎΠΆΠ΅Π½Π½Ρ‹Π΅` section, remove the bullet
starting 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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