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
/**
* The attestation manifest kernel (delivery trust, Lane D task D1).
*
* The manifest is the thing a signature is computed over, so the tests
* here hold it to three properties: every head it records is the chain
* head the appender would have linked to, the collection is reproducible
* while the store stands still, and the digest is exactly
* `sha256Hex(canonicalJson(manifest))` - the one encoding
* `src/core/integrity/digest.ts` persists. A head collected lock-free
* would be a head the appender may already have superseded, so the lock
* discipline is asserted by name too.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { Database } from "bun:sqlite";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import {
ATTESTATION_MANIFEST_SCHEMA_VERSION,
attestationStoreDigest,
collectAttestationManifest,
} from "../../../../src/core/brain/attestation/digest.ts";
import {
acquireLogLock,
collectLogShardHeads,
appendLogEvent,
} from "../../../../src/core/brain/log.ts";
import { brainDirs } from "../../../../src/core/brain/paths.ts";
import { writeVaultIdentity } from "../../../../src/core/brain/vault-identity.ts";
import { noopSafeguard } from "../../../../src/core/brain/safeguard.ts";
import { canonicalJson, sha256Hex } from "../../../../src/core/integrity/digest.ts";
import {
EMBEDDING_DIMENSION_STATE_KEY,
EMBEDDING_MODEL_STATE_KEY,
EMBEDDING_VEC_VERSION_STATE_KEY,
setState,
} from "../../../../src/core/search/store/state.ts";
const DATE = "2026-06-03";
let tmp: string;
let vault: string;
let configHome: string;
const savedEnv: Record<string, string | undefined> = {};
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-attest-digest-"));
vault = join(tmp, "vault");
mkdirSync(join(vault, "Brain", "log"), { recursive: true });
writeFileSync(join(vault, "Brain", "_brain.yaml"), "schema_version: 1\n", "utf8");
configHome = mkdtempSync(join(tmpdir(), "o2b-attest-digest-cfg-"));
const configPath = join(configHome, "config.yaml");
writeFileSync(configPath, `vault: ${vault}\nagent_name: tester\n`, "utf8");
for (const k of ["VAULT_AGENT_NAME", "VAULT_TIMEZONE", "VAULT_DIR", "OPEN_SECOND_BRAIN_CONFIG"]) {
savedEnv[k] = process.env[k];
delete process.env[k];
}
process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
for (const [k, v] of Object.entries(savedEnv)) {
if (v === undefined) delete process.env[k];
else process.env[k] = v;
}
});
function append(count: number, deviceId = ""): void {
for (let i = 0; i < count; i++) {
appendLogEvent(
vault,
{
timestamp: `${DATE}T10:00:0${i}Z`,
eventType: "note",
body: { text: `event ${deviceId} ${i}`, agent: "@tester" },
},
{ deviceId },
);
}
}
/** The `h` of the last chained line of a shard, read the way an operator would. */
function chainHeadOf(relName: string): string {
const lines = readFileSync(join(brainDirs(vault).log, relName), "utf8")
.trim()
.split("\n")
.filter((line) => line.trim() !== "");
for (let i = lines.length - 1; i >= 0; i--) {
const row = JSON.parse(lines[i]!) as Record<string, unknown>;
if (typeof row["h"] === "string" && row["h"] !== "") return row["h"];
}
throw new Error(`no chained line in ${relName}`);
}
/** A minimal index file carrying the three embedding-ABI state keys. */
function seedIndex(model: string): void {
const dbPath = join(vault, ".open-second-brain", "brain.sqlite");
mkdirSync(dirname(dbPath), { recursive: true });
const db = new Database(dbPath);
try {
db.run(
"CREATE TABLE IF NOT EXISTS index_state (key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at TEXT NOT NULL)",
);
setState(db, EMBEDDING_MODEL_STATE_KEY, model);
setState(db, EMBEDDING_DIMENSION_STATE_KEY, "64");
setState(db, EMBEDDING_VEC_VERSION_STATE_KEY, "v0.8.0");
} finally {
db.close();
}
}
describe("collectLogShardHeads", () => {
test("records one head per JSONL shard, each the chain head the appender linked", () => {
append(2);
append(1, "device-b");
const heads = collectLogShardHeads(vault);
expect(Object.keys(heads).toSorted()).toEqual([`${DATE}.device-b.jsonl`, `${DATE}.jsonl`]);
expect(heads[`${DATE}.jsonl`]).toBe(chainHeadOf(`${DATE}.jsonl`));
expect(heads[`${DATE}.device-b.jsonl`]).toBe(chainHeadOf(`${DATE}.device-b.jsonl`));
});
test("shares the appender's lock: a held log lock is a refusal, never a lock-free read", () => {
append(1);
const logDir = brainDirs(vault).log;
// The production lock helper, not a hand-rolled lockSync call: its
// bounded retry still ends in the ELOCKED throw when the lock is
// held, which is the refusal under test.
const release = acquireLogLock(logDir);
try {
let caught: NodeJS.ErrnoException | null = null;
try {
collectLogShardHeads(vault);
} catch (err) {
caught = err as NodeJS.ErrnoException;
}
expect(caught?.code).toBe("ELOCKED");
} finally {
release();
}
});
test("never claims a head the appender already superseded", () => {
append(1);
const firstHead = chainHeadOf(`${DATE}.jsonl`);
append(1);
const heads = collectLogShardHeads(vault);
expect(heads[`${DATE}.jsonl`]).not.toBe(firstHead);
expect(heads[`${DATE}.jsonl`]).toBe(chainHeadOf(`${DATE}.jsonl`));
});
test("a vault with no log yields an empty map and writes nothing to stderr", () => {
rmSync(join(vault, "Brain", "log"), { recursive: true, force: true });
const writes: string[] = [];
const original = process.stderr.write.bind(process.stderr);
process.stderr.write = ((chunk: unknown) => {
writes.push(String(chunk));
return true;
}) as typeof process.stderr.write;
try {
expect(collectLogShardHeads(vault)).toEqual({});
} finally {
process.stderr.write = original;
}
expect(writes).toEqual([]);
});
});
describe("collectAttestationManifest", () => {
test("carries the manifest schema version and the vault identity id", () => {
const identity = writeVaultIdentity(vault);
const manifest = collectAttestationManifest(vault);
expect(manifest.schemaVersion).toBe(ATTESTATION_MANIFEST_SCHEMA_VERSION);
expect(ATTESTATION_MANIFEST_SCHEMA_VERSION).toBe("o2b.attestation.manifest.v1");
expect(manifest.vaultIdentityId).toBe(identity.vault_id);
});
test("binds the log head map and reports no index stamp when no store exists", () => {
append(1, "device-b");
const manifest = collectAttestationManifest(vault);
expect(manifest.logHeads).toEqual(collectLogShardHeads(vault));
expect(manifest.indexStamp).toBeNull();
});
test("the index stamp is the store's current stamp token, and moves when the store restamps", () => {
seedIndex("model-a");
const before = collectAttestationManifest(vault);
expect(before.indexStamp).toMatch(/^[0-9a-f]{64}$/);
expect(collectAttestationManifest(vault).indexStamp).toBe(before.indexStamp);
seedIndex("model-b");
expect(collectAttestationManifest(vault).indexStamp).not.toBe(before.indexStamp);
});
test("ledger inventories list exactly the doctor-swept ledger directories' files", () => {
append(1);
mkdirSync(join(vault, "Brain", ".state"), { recursive: true });
writeFileSync(join(vault, "Brain", ".state", "session-lineage.jsonl"), "{}\n", "utf8");
mkdirSync(join(vault, "Brain", "metrics"), { recursive: true });
writeFileSync(join(vault, "Brain", "metrics", "surface-a.tester.jsonl"), "{}\n", "utf8");
// Not a swept ledger directory: its files must not appear anywhere.
mkdirSync(join(vault, "Brain", "entities", "topic"), { recursive: true });
writeFileSync(join(vault, "Brain", "entities", "topic", "idea.md"), "x\n", "utf8");
const inventories = collectAttestationManifest(vault).ledgerInventories;
const keys = Object.keys(inventories).toSorted();
expect(keys).toContain("Brain/log");
expect(keys).toContain("Brain/.state");
expect(keys).toContain("Brain/metrics");
expect(inventories["Brain/log"]).toContain(`${DATE}.jsonl`);
expect(inventories["Brain/.state"]).toEqual(["session-lineage.jsonl"]);
expect(inventories["Brain/metrics"]).toEqual(["surface-a.tester.jsonl"]);
for (const key of keys) expect(key).not.toContain("entities");
});
test("a file at the git store root itself stays out of the inventories, its per-repository shards stay in", () => {
// The doctor's own ruling: the git store root holds no ledger, so
// the manifest descends one level exactly as the doctor does - a
// stray file at the root must not flip the store digest with
// nothing naming why.
const gitRoot = join(vault, "Brain", "projects", "git");
// The commits shards sit next to the repo's state.json, one level
// below the root - the layout the doctor's sweep descends into.
mkdirSync(join(gitRoot, "repo-one"), { recursive: true });
writeFileSync(join(gitRoot, "repo-one", "commits-2026-06-03.jsonl"), "{}\n", "utf8");
writeFileSync(join(gitRoot, "stray.jsonl"), "{}\n", "utf8");
const inventories = collectAttestationManifest(vault).ledgerInventories;
expect(Object.keys(inventories)).not.toContain("Brain/projects/git");
expect(inventories["Brain/projects/git/repo-one"]).toEqual(["commits-2026-06-03.jsonl"]);
expect(JSON.stringify(inventories)).not.toContain("stray.jsonl");
});
test("an index that exists but cannot be read refuses the manifest instead of reading as absent", () => {
mkdirSync(join(vault, ".open-second-brain", "brain.sqlite"), { recursive: true });
expect(() => collectAttestationManifest(vault)).toThrow(/could not be read/);
});
test("the store digest is stable while the store stands still and moves with a shard head", () => {
append(1);
const first = collectAttestationManifest(vault);
expect(attestationStoreDigest(first)).toBe(
attestationStoreDigest(collectAttestationManifest(vault)),
);
append(1);
expect(attestationStoreDigest(collectAttestationManifest(vault))).not.toBe(
attestationStoreDigest(first),
);
});
test("the digest is sha256Hex(canonicalJson(manifest)) byte-for-byte", () => {
append(1);
seedIndex("model-a");
const manifest = collectAttestationManifest(vault);
expect(attestationStoreDigest(manifest)).toBe(sha256Hex(canonicalJson(manifest)));
});
test("a Safeguard is accepted and consulted on the walk", () => {
append(1);
let checkpoints = 0;
const base = noopSafeguard("attestation-test");
const guarded = Object.freeze({
operation: base.operation,
timeoutMs: base.timeoutMs,
checkpoint: () => {
checkpoints++;
base.checkpoint();
},
});
collectAttestationManifest(vault, { safeguard: guarded });
expect(checkpoints).toBeGreaterThanOrEqual(1);
});
});