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
/**
* `o2b brain query` point-in-time recall (what-the-index-already-knew,
* task J).
*
* The expiry filter has taken an as-of instant since C5 - `filterExpired`
* defaults `now` to the wall clock and `queryByRuleTopic` threads a `now`
* option straight into it - and no surface ever passed one. The CLI
* called `queryByRuleTopic(vault, topic)` with no options object at all, so
* "what did the brain hold as of last month" was unaskable from the one
* surface that enforces expiry, and `--show-expired` (which MCP has had
* since C5) did not exist on the CLI either.
*
* The byte-identity pins below are the EXACT stdout the pre-change binary
* produced for the same fixture, captured before the flags existed. They
* are literals rather than a re-serialised comparison so a change in key
* order, indentation or trailing newline fails here.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { writeSignal, type WriteSignalInput } from "../../src/core/brain/signal.ts";
import { runCli } from "../helpers/run-cli.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
const TOPIC = "deploy";
/** The lapsed signal's expiration; every probe instant is chosen around it. */
const LAPSED_EXPIRY = "2026-07-15";
/** An instant BEFORE the expiry: the lapsed signal was still live then. */
const BEFORE_EXPIRY = "2026-06-01T00:00:00Z";
/** An instant AFTER the expiry, still deterministic against any wall clock. */
const AFTER_EXPIRY = "2026-08-01T00:00:00Z";
const LAPSED_PRINCIPLE = "Principle for lapsed";
const EVERGREEN_PRINCIPLE = "Principle for evergreen";
/**
* Exact stdout for `--topic deploy --json`, no new flags.
*
* `origin_channel` is the server-derived channel of the process that
* WROTE the signal (Unit C of the nothing-writes-silently wave), read
* back by `parseSignal` and surfaced here because this payload is the
* parsed signal. `unset` is the explicit literal for "no entry point
* claimed this process": the fixture writes its signals through
* `writeSignal` directly rather than through `o2b`, and the suite
* preload unclaims the channel before every test so this value cannot
* depend on which test file ran first.
*/
const PINNED_JSON_STDOUT = `{
"signals": [
{
"kind": "brain-signal",
"id": "sig-2026-05-02-evergreen",
"created_at": "2026-05-02T00:00:00Z",
"tags": [
"brain",
"brain/signal",
"brain/topic/deploy"
],
"topic": "deploy",
"signal": "positive",
"agent": "tester",
"principle": "Principle for evergreen",
"origin_channel": "unset"
}
],
"preference": null,
"all_log_events": []
}
`;
/** Exact pre-change stdout for `--topic deploy` on the human surface. */
const PINNED_TEXT_STDOUT =
"topic: deploy\n" +
"preference: (none)\n" +
"signals: 1\n" +
" - sig-2026-05-02-evergreen (positive, 2026-05-02T00:00:00Z)\n" +
"log_events: 0\n";
let tmp: string;
let vault: string;
let config: string;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-brain-query-as-of-"));
vault = join(tmp, "vault");
config = join(tmp, "config.yaml");
writeFileSync(config, `vault: ${vault}\nagent_name: claude\n`);
bootstrapBrain(vault, { configPath: config });
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
function signal(slug: string, overrides: Partial<WriteSignalInput> = {}): WriteSignalInput {
return {
topic: TOPIC,
signal: "positive",
agent: "tester",
principle: `Principle for ${slug}`,
created_at: "2026-05-01T00:00:00Z",
date: "2026-05-01",
slug,
...overrides,
};
}
/** One signal that has lapsed, one that never expires. */
function seed(): void {
writeSignal(vault, signal("lapsed", { expiration_date: LAPSED_EXPIRY }));
writeSignal(
vault,
signal("evergreen", { created_at: "2026-05-02T00:00:00Z", date: "2026-05-02" }),
);
}
async function query(...args: string[]) {
return runCli(["brain", "query", "--vault", vault, "--topic", TOPIC, ...args], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
}
function principles(stdout: string): string[] {
const payload = JSON.parse(stdout) as { signals: ReadonlyArray<{ principle: string }> };
return payload.signals.map((s) => s.principle).toSorted();
}
describe("brain query --at", () => {
test("recalls what the brain held at an instant before the memory lapsed", async () => {
seed();
const r = await query("--json", "--at", BEFORE_EXPIRY);
expect(r.stderr).toBe("");
expect(r.returncode).toBe(0);
expect(principles(r.stdout)).toEqual([EVERGREEN_PRINCIPLE, LAPSED_PRINCIPLE]);
});
test("an instant after the expiry drops the lapsed memory again", async () => {
seed();
const r = await query("--json", "--at", AFTER_EXPIRY);
expect(r.returncode).toBe(0);
expect(principles(r.stdout)).toEqual([EVERGREEN_PRINCIPLE]);
});
test("a date-only instant is accepted and read as UTC midnight", async () => {
seed();
const r = await query("--json", "--at", "2026-06-01");
expect(r.returncode).toBe(0);
expect(principles(r.stdout)).toEqual([EVERGREEN_PRINCIPLE, LAPSED_PRINCIPLE]);
});
test("an unparseable instant is refused by name, never coerced to now", async () => {
seed();
const r = await query("--json", "--at", "last month");
expect(r.returncode).toBe(2);
expect(r.stderr).toContain("--at");
expect(r.stderr).toContain("ISO-8601 instant or YYYY-MM-DD date");
expect(r.stderr).toContain("last month");
// A refused query answers nothing; it must not fall through to today.
expect(r.stdout).toBe("");
});
test("--at outside topic mode is refused rather than silently ignored", async () => {
seed();
const r = await runCli(
["brain", "query", "--vault", vault, "--since", BEFORE_EXPIRY, "--at", BEFORE_EXPIRY],
{ env: { OPEN_SECOND_BRAIN_CONFIG: config } },
);
expect(r.returncode).toBe(2);
expect(r.stderr).toContain("--topic");
});
});
describe("brain query --show-expired", () => {
test("keeps a lapsed memory in the result", async () => {
seed();
const r = await query("--json", "--show-expired");
expect(r.returncode).toBe(0);
expect(principles(r.stdout)).toEqual([EVERGREEN_PRINCIPLE, LAPSED_PRINCIPLE]);
});
test("is refused outside topic mode", async () => {
seed();
const r = await runCli(
["brain", "query", "--vault", vault, "--since", BEFORE_EXPIRY, "--show-expired"],
{ env: { OPEN_SECOND_BRAIN_CONFIG: config } },
);
expect(r.returncode).toBe(2);
expect(r.stderr).toContain("--topic");
});
});
describe("byte identity when both flags are absent", () => {
test("--json stdout is byte-for-byte the pre-change output", async () => {
seed();
const r = await query("--json");
expect(r.returncode).toBe(0);
expect(r.stdout).toBe(PINNED_JSON_STDOUT);
});
test("the human surface is byte-for-byte the pre-change output", async () => {
seed();
const r = await query();
expect(r.returncode).toBe(0);
expect(r.stdout).toBe(PINNED_TEXT_STDOUT);
});
test("the pins are not vacuous: either flag changes those exact bytes", async () => {
seed();
const withAt = await query("--json", "--at", BEFORE_EXPIRY);
const withShowExpired = await query("--json", "--show-expired");
expect(withAt.stdout).not.toBe(PINNED_JSON_STDOUT);
expect(withShowExpired.stdout).not.toBe(PINNED_JSON_STDOUT);
});
});