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 distill` CLI (t_2e2e959f): condense a source into atomic claims
* with block-level provenance, supplied as JSON.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
existsSync,
mkdirSync,
mkdtempSync,
readdirSync,
readFileSync,
rmSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { nestedCommand } from "../../src/cli/command-manifest.ts";
import { readExcerptSection } from "../../src/core/brain/provenance/capture-scope.ts";
import { BRAIN_DISTILLATIONS_REL } from "../../src/core/brain/path-constants.ts";
import { PAYLOAD_UNPARSEABLE_MESSAGE } from "../../src/core/brain/payload-json.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);
let tmp: string;
let vault: string;
let env: Record<string, string>;
beforeEach(async () => {
tmp = mkdtempSync(join(tmpdir(), "o2b-cli-distill-"));
vault = join(tmp, "vault");
const config = join(tmp, "config.yaml");
env = { OPEN_SECOND_BRAIN_CONFIG: config };
await runCli(["init", "--vault", vault, "--name", "Test"], { env });
await runCli(["brain", "init", "--vault", vault], { env });
mkdirSync(join(vault, "Articles"), { recursive: true });
writeFileSync(join(vault, "Articles", "src.md"), "# Src\n\nBody.\n", "utf8");
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
test("distills a source into a citeable claims page", async () => {
const claims = JSON.stringify([
{ text: "First atomic claim.", block: "abc" },
{ text: "Second atomic claim." },
]);
const res = await runCli(
["brain", "distill", "Articles/src.md", "--claims", claims, "--vault", vault, "--json"],
{ env },
);
expect(res.returncode).toBe(0);
const out = JSON.parse(res.stdout) as { distillation_path: string; claim_count: number };
expect(out.claim_count).toBe(2);
const md = readFileSync(join(vault, out.distillation_path), "utf8");
expect(md).toContain("## Claims");
expect(md).toContain("([[Articles/src.md#^abc]])");
expect(existsSync(join(vault, out.distillation_path))).toBe(true);
});
test("an empty claim list is rejected (validation error, exit 1)", async () => {
const res = await runCli(
["brain", "distill", "Articles/src.md", "--claims", "[]", "--vault", vault],
{ env },
);
expect(res.returncode).toBe(1);
});
const CLAIMS_SHAPE_HINT = "claims must be a JSON array of { text, block? } objects";
/** One `--claims` run; `runCli` swaps process env, so runs stay sequential. */
async function distillWithClaims(claims: string) {
return runCli(["brain", "distill", "Articles/src.md", "--claims", claims, "--vault", vault], {
env,
});
}
test("a claims payload that is not a list names the shape the CLI accepts", async () => {
// The operator's mistake is the WRAPPER, not an item, so the error has to
// name the accepted payload rather than report a path inside one.
const wrapperHoldsNoList = await distillWithClaims('{"claims": 3}');
expect(wrapperHoldsNoList.returncode).toBe(1);
expect(wrapperHoldsNoList.stderr).toContain(CLAIMS_SHAPE_HINT);
const wrapperNamesAnotherKey = await distillWithClaims('{"notes": []}');
expect(wrapperNamesAnotherKey.returncode).toBe(1);
expect(wrapperNamesAnotherKey.stderr).toContain(CLAIMS_SHAPE_HINT);
const notAWrapperAtAll = await distillWithClaims('"a claim"');
expect(notAWrapperAtAll.returncode).toBe(1);
expect(notAWrapperAtAll.stderr).toContain(CLAIMS_SHAPE_HINT);
});
test("a malformed claim item still reports its path", async () => {
const res = await runCli(
["brain", "distill", "Articles/src.md", "--claims", '[{"text": 3}]', "--vault", vault],
{ env },
);
expect(res.returncode).toBe(1);
expect(res.stderr).toContain("$[0].text");
});
/**
* The CLI is the SECOND entry point into `distillSource` (wiring-what-exists,
* A1). A trust guard placed in the MCP handler alone would leave this verb
* writing under the top authority tier for a source nothing in the vault owns,
* which is why the classification lives in the core and both surfaces report it.
*/
test("the lane reaches the operator on both surfaces", async () => {
const claims = JSON.stringify([{ text: "An atomic claim." }]);
const trusted = await runCli(
["brain", "distill", "Articles/src.md", "--claims", claims, "--vault", vault, "--json"],
{ env },
);
expect(trusted.returncode).toBe(0);
const trustedOut = JSON.parse(trusted.stdout) as { trust: string; source_hash?: string };
expect(trustedOut.trust).toBe("trusted");
expect(typeof trustedOut.source_hash).toBe("string");
const untrusted = await runCli(
["brain", "distill", "Articles/absent.md", "--claims", claims, "--vault", vault, "--json"],
{ env },
);
expect(untrusted.returncode).toBe(0);
const untrustedOut = JSON.parse(untrusted.stdout) as { trust: string; source_hash?: string };
expect(untrustedOut.trust).toBe("untrusted");
expect(untrustedOut.source_hash).toBeUndefined();
// The human line says so too: an operator who never passes --json would
// otherwise read the same success sentence for both lanes.
const human = await runCli(
["brain", "distill", "Articles/absent.md", "--claims", claims, "--vault", vault],
{ env },
);
expect(human.returncode).toBe(0);
expect(human.stdout).toContain("untrusted_source");
});
test("missing <source> or --claims is a usage error (exit 2)", async () => {
const noSource = await runCli(["brain", "distill", "--claims", "[]", "--vault", vault], { env });
expect(noSource.returncode).toBe(2);
const noClaims = await runCli(["brain", "distill", "Articles/src.md", "--vault", vault], { env });
expect(noClaims.returncode).toBe(2);
});
const QUOTED_SOURCE = "Articles/quoted.md";
/** A source whose one paragraph carries the block id `^p1`. */
function seedQuotedSource(): void {
writeFileSync(
join(vault, QUOTED_SOURCE),
"# Quoted\n\nThe protocol settles every batch within one minute. ^p1\n",
"utf8",
);
}
/** Distillation pages on disk; the directory may not exist yet. */
function distillationPages(): string[] {
const dir = join(vault, BRAIN_DISTILLATIONS_REL);
return existsSync(dir) ? readdirSync(dir).filter((name) => name.endsWith(".md")) : [];
}
/**
* The quote check and the capture scope reach the operator (distilled
* provenance, D2): two flags in, two suffixes and two `--json` members out.
*/
describe("o2b brain distill - quote check and capture scope", () => {
const VERBATIM = {
text: 'The author writes "settles every batch within one minute".',
block: "p1",
};
const PARAPHRASE = { text: 'The author writes "settles all batches quickly".', block: "p1" };
test("--strict-quotes refuses a paraphrase in quotation marks and writes nothing", async () => {
seedQuotedSource();
const res = await runCli(
[
"brain",
"distill",
QUOTED_SOURCE,
"--claims",
JSON.stringify([PARAPHRASE]),
"--strict-quotes",
"--vault",
vault,
],
{ env },
);
expect(res.returncode).toBe(1);
expect(res.stderr).toContain(
"distill: quoted spans failed verification: claim 0: not-in-block",
);
expect(distillationPages()).toEqual([]);
});
test("--excerpt-file stores a bounded-local page for a url source", async () => {
const excerptPath = join(tmp, "excerpt.txt");
writeFileSync(excerptPath, "The protocol settles every batch within one minute.\n", "utf8");
const res = await runCli(
[
"brain",
"distill",
"https://example.test/post",
"--claims",
JSON.stringify([{ text: "A claim." }]),
"--excerpt-file",
excerptPath,
"--vault",
vault,
],
{ env },
);
expect(res.returncode).toBe(0);
expect(res.stdout.trimEnd()).toEndWith(" [untrusted_source] [bounded-local]");
const [page] = distillationPages();
const md = readFileSync(join(vault, BRAIN_DISTILLATIONS_REL, page!), "utf8");
expect(md).toContain("capture_scope: bounded-local");
expect(readExcerptSection(md)).toBe(readFileSync(excerptPath, "utf8"));
});
test("an --excerpt-file that is not valid UTF-8 is refused before any write", async () => {
// Decoding leniently would store U+FFFD in place of the file's bytes,
// and the stored excerpt would no longer be the captured text.
const excerptPath = join(tmp, "latin1.txt");
writeFileSync(excerptPath, Buffer.from([0x63, 0x61, 0x66, 0xe9, 0x0a]));
const res = await runCli(
[
"brain",
"distill",
"https://example.test/post",
"--claims",
JSON.stringify([{ text: "A claim." }]),
"--excerpt-file",
excerptPath,
"--vault",
vault,
],
{ env },
);
expect(res.returncode).toBe(2);
expect(res.stderr).toContain("distill: excerpt file is not valid UTF-8");
expect(distillationPages()).toEqual([]);
});
test("a checked quote adds the quotes suffix to the human line", async () => {
seedQuotedSource();
const res = await runCli(
["brain", "distill", QUOTED_SOURCE, "--claims", JSON.stringify([VERBATIM]), "--vault", vault],
{ env },
);
expect(res.returncode).toBe(0);
expect(res.stdout.trimEnd()).toEndWith(" [quotes verified:1 unquoted:0]");
});
test("--json carries capture_scope and quotes", async () => {
seedQuotedSource();
const res = await runCli(
[
"brain",
"distill",
QUOTED_SOURCE,
"--claims",
JSON.stringify([VERBATIM, PARAPHRASE]),
"--vault",
vault,
"--json",
],
{ env },
);
expect(res.returncode).toBe(0);
const out = JSON.parse(res.stdout) as {
capture_scope: string;
quotes: { verified_in_block: number; unquoted: number; findings: unknown[] };
};
expect(out.capture_scope).toBe("full-local");
expect(out.quotes.verified_in_block).toBe(1);
expect(out.quotes.unquoted).toBe(1);
expect(out.quotes.findings).toHaveLength(1);
});
test("a clean trusted run keeps its human line exactly", async () => {
const res = await runCli(
[
"brain",
"distill",
"Articles/src.md",
"--claims",
JSON.stringify([{ text: "A claim." }]),
"--vault",
vault,
],
{ env },
);
expect(res.returncode).toBe(0);
expect(res.stdout.trimEnd()).toMatch(/^distilled 1 claim\(s\) -> \S+\.md$/);
});
test("the manifest entry lists the two new flags", () => {
const names = (nestedCommand("brain", "distill")?.flags ?? []).map((f) => f.name);
expect(names).toContain("strict-quotes");
expect(names).toContain("excerpt-file");
});
});
describe("o2b brain distill - think-block strip (t_dac8bf7e)", () => {
test("a <think>-prefixed claims payload succeeds, names the strip, and distills the same claims", async () => {
const claims = `<think>weighing the spans</think>${JSON.stringify([
{ text: "First atomic claim.", block: "abc" },
])}`;
const res = await runCli(
["brain", "distill", "Articles/src.md", "--claims", claims, "--vault", vault, "--json"],
{ env },
);
expect(res.returncode).toBe(0);
const out = JSON.parse(res.stdout) as {
claim_count: number;
distillation_path: string;
note?: string;
};
expect(out.claim_count).toBe(1);
expect(out.note).toContain("<think>");
expect(existsSync(join(vault, out.distillation_path))).toBe(true);
});
test("the human line names the strip too - never a silent strip", async () => {
const claims = `<think>weighing the spans</think>${JSON.stringify([{ text: "A claim." }])}`;
const res = await runCli(
["brain", "distill", "Articles/src.md", "--claims", claims, "--vault", vault],
{ env },
);
expect(res.returncode).toBe(0);
expect(res.stdout).toContain("<think>");
});
test("garbage claims still exit 1 with the plain refusal", async () => {
const res = await distillWithClaims("not json");
expect(res.returncode).toBe(1);
expect(res.stderr).toBe(`distill: ${PAYLOAD_UNPARSEABLE_MESSAGE}\n`);
});
test("claims that still do not parse after the strip name the attempt and exit 1", async () => {
const res = await distillWithClaims("<think>r</think>not json");
expect(res.returncode).toBe(1);
expect(res.stderr).toContain("<think>");
});
test("clean claims output carries no note key", async () => {
const res = await runCli(
[
"brain",
"distill",
"Articles/src.md",
"--claims",
JSON.stringify([{ text: "A claim." }]),
"--vault",
vault,
"--json",
],
{ env },
);
expect(res.returncode).toBe(0);
const out = JSON.parse(res.stdout) as Record<string, unknown>;
expect("note" in out).toBe(false);
});
});