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 durable raw-source archive store (answer trust, Task C2).
*
* Four invariants are pinned here because each one is a way the store could
* silently stop being evidence: the address names the bytes on disk (dedup
* is that address applied twice); a credential in a captured source never
* reaches a second file (redaction runs BEFORE persist, and the digest is
* the redacted bytes'); a past-ceiling input is refused whole, never stored
* half; and a verification distinguishes "gone" from "disagrees".
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
existsSync,
mkdirSync,
mkdtempSync,
readdirSync,
readFileSync,
rmSync,
statSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
ARCHIVE_MAX_BYTES,
ARCHIVE_VERIFICATION,
SOURCE_ARCHIVE_BYTES_KEY,
SOURCE_ARCHIVE_HASH_KEY,
discardSourceArchive,
isArchiveVerification,
putSourceArchive,
readSourceArchiveEntry,
sourceArchiveCitingPages,
sourceArchivePath,
sourceArchiveStats,
sourceArchivesDir,
verifySourceArchive,
} from "../../../../src/core/brain/provenance/source-archive.ts";
import { admitToIndex } from "../../../../src/core/vault-scope/index-admission.ts";
import { REDACTION_PLACEHOLDER, redactRawOutput } from "../../../../src/core/redactor.ts";
import { createHash } from "node:crypto";
let vault: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-source-archive-"));
// An unswitched vault: its Brain/ tree is the legacy layout under test.
mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
});
const sha256 = (text: string): string => createHash("sha256").update(text, "utf8").digest("hex");
describe("putSourceArchive", () => {
test("persists the bytes at their digest under Brain/.archives/<sha256>.txt", () => {
const put = putSourceArchive(vault, "the source bytes\n");
expect(put.hash).toBe(sha256("the source bytes\n"));
expect(put.bytes).toBe(Buffer.byteLength("the source bytes\n", "utf8"));
const entry = join(vault, "Brain", ".archives", `${put.hash}.txt`);
expect(existsSync(entry)).toBe(true);
expect(readFileSync(entry, "utf8")).toBe("the source bytes\n");
});
test("identical bytes persist once - the content address is the dedup", () => {
const first = putSourceArchive(vault, "same bytes");
const second = putSourceArchive(vault, "same bytes");
expect(second.hash).toBe(first.hash);
const store = join(vault, "Brain", ".archives");
expect(readdirSync(store)).toEqual([`${first.hash}.txt`]);
});
test("a re-ingest of an intact entry leaves it untouched - no mtime churn", () => {
const first = putSourceArchive(vault, "stable bytes");
const entry = join(vault, "Brain", ".archives", `${first.hash}.txt`);
const before = statSync(entry).mtimeMs;
putSourceArchive(vault, "stable bytes");
expect(statSync(entry).mtimeMs).toBe(before);
});
test("a re-ingest repairs an entry corrupted on disk", () => {
// The natural repair of the `mismatched` state the hygiene scan
// reports: the same source lands the same address, re-verifies the
// entry it finds there, and rewrites it when the bytes disagree.
const first = putSourceArchive(vault, "original");
const entry = join(vault, "Brain", ".archives", `${first.hash}.txt`);
writeFileSync(entry, "tampered after the stamp", "utf8");
expect(verifySourceArchive(vault, first.hash).state).toBe(ARCHIVE_VERIFICATION.mismatched);
const second = putSourceArchive(vault, "original");
expect(second.hash).toBe(first.hash);
expect(verifySourceArchive(vault, first.hash).state).toBe(ARCHIVE_VERIFICATION.verified);
expect(readFileSync(entry, "utf8")).toBe("original");
});
test("a credential-shaped input never lands on disk unredacted", () => {
// The redaction must run BEFORE persist, and the entry's address must
// be the digest of the REDACTED bytes - an address over the raw input
// would name a file that does not exist and break re-verification.
const input = "deploy notes\napi_key: ZXhwb3J0ZWQta2V5LTEyMzQ1\ntrailing prose\n";
const put = putSourceArchive(vault, input);
const stored = readFileSync(join(vault, "Brain", ".archives", `${put.hash}.txt`), "utf8");
expect(stored).not.toContain("ZXhwb3J0ZWQta2V5LTEyMzQ1");
expect(stored).toContain(REDACTION_PLACEHOLDER);
expect(put.hash).toBe(sha256(redactRawOutput(input)));
});
test("a past-ceiling input raises the named error and never a truncated write", () => {
const oversized = "a".repeat(ARCHIVE_MAX_BYTES + 1);
let thrown: unknown;
try {
putSourceArchive(vault, oversized);
} catch (err) {
thrown = err;
}
expect((thrown as Error)?.name).toBe("SourceArchiveError");
expect((thrown as Error).message).toContain(`${ARCHIVE_MAX_BYTES}-byte ceiling`);
// Refuse-not-truncate: nothing was written at all, neither a truncated
// entry nor a partial one.
expect(existsSync(sourceArchivesDir(vault))).toBe(false);
});
test("an input exactly at the ceiling is archived whole", () => {
const atCeiling = "b".repeat(ARCHIVE_MAX_BYTES);
const put = putSourceArchive(vault, atCeiling);
expect(put.bytes).toBe(ARCHIVE_MAX_BYTES);
expect(verifySourceArchive(vault, put.hash).state).toBe(ARCHIVE_VERIFICATION.verified);
});
});
describe("verifySourceArchive and readSourceArchiveEntry", () => {
test("an intact entry verifies", () => {
const put = putSourceArchive(vault, "intact");
expect(verifySourceArchive(vault, put.hash)).toEqual({
state: ARCHIVE_VERIFICATION.verified,
hash: put.hash,
});
});
test("a tampered entry re-hashes differently - mismatched, not missing", () => {
const put = putSourceArchive(vault, "original");
writeFileSync(join(vault, "Brain", ".archives", `${put.hash}.txt`), "tampered", "utf8");
expect(verifySourceArchive(vault, put.hash).state).toBe(ARCHIVE_VERIFICATION.mismatched);
});
test("an absent entry is missing, and a malformed stamp is missing too", () => {
putSourceArchive(vault, "present");
expect(verifySourceArchive(vault, sha256("absent")).state).toBe(ARCHIVE_VERIFICATION.missing);
// A stamp that is not a hash names no entry the store could hold.
expect(verifySourceArchive(vault, "not-a-hash").state).toBe(ARCHIVE_VERIFICATION.missing);
});
test("reading an entry returns its text and byte count; absent is null", () => {
const put = putSourceArchive(vault, "read me");
expect(readSourceArchiveEntry(vault, put.hash)).toEqual({
state: ARCHIVE_VERIFICATION.verified,
hash: put.hash,
bytes: Buffer.byteLength("read me", "utf8"),
text: "read me",
});
expect(readSourceArchiveEntry(vault, sha256("nope"))).toBeNull();
});
test("a caller-supplied hash cannot traverse out of the store", () => {
for (const hostile of ["../secrets.txt", "../../etc/passwd", "A".repeat(64), "ab".repeat(31)]) {
let thrown: unknown;
try {
sourceArchivePath(vault, hostile);
} catch (err) {
thrown = err;
}
expect((thrown as Error)?.name).toBe("SourceArchiveError");
}
});
});
describe("sourceArchiveStats", () => {
test("a vault that never captured reports an empty store, not an error", () => {
expect(sourceArchiveStats(vault)).toEqual({ entries: 0, totalBytes: 0 });
});
test("counts entries and their combined bytes, and nothing it does not recognize", () => {
const a = putSourceArchive(vault, "alpha");
const b = putSourceArchive(vault, "beta");
// A stray file is not an entry: the store counts what its grammar names.
writeFileSync(join(vault, "Brain", ".archives", "notes.txt"), "stray", "utf8");
const stats = sourceArchiveStats(vault);
expect(stats.entries).toBe(2);
expect(stats.totalBytes).toBe(a.bytes + b.bytes);
});
});
describe("discardSourceArchive", () => {
test("removes the entry and says so; an absent entry was not removed", () => {
const put = putSourceArchive(vault, "ephemeral");
expect(discardSourceArchive(vault, put.hash)).toBe(true);
expect(verifySourceArchive(vault, put.hash).state).toBe(ARCHIVE_VERIFICATION.missing);
expect(discardSourceArchive(vault, put.hash)).toBe(false);
});
});
describe("sourceArchiveCitingPages", () => {
test("lists exactly the summary pages stamping the digest, sorted", () => {
const put = putSourceArchive(vault, "cited bytes");
const sources = join(vault, "Brain", "sources");
mkdirSync(sources, { recursive: true });
const stamped = (name: string, hash: string | null): void => {
const hashLines =
hash === null
? []
: [`${SOURCE_ARCHIVE_HASH_KEY}: ${hash}`, `${SOURCE_ARCHIVE_BYTES_KEY}: 11`];
writeFileSync(
join(sources, name),
["---", "kind: brain-source", ...hashLines, "---", "", "body", ""].join("\n"),
"utf8",
);
};
stamped("b-second.md", put.hash);
stamped("a-first.md", put.hash);
stamped("c-other.md", sha256("another source"));
stamped("d-unstamped.md", null);
expect(sourceArchiveCitingPages(vault, put.hash)).toEqual([
"Brain/sources/a-first.md",
"Brain/sources/b-second.md",
]);
expect(sourceArchiveCitingPages(vault, sha256("nothing cites this"))).toEqual([]);
});
});
describe("the archive store is refused to the search index", () => {
test("an entry path is excluded by name, a sibling lane is not", () => {
expect(admitToIndex(`Brain/.archives/${"a".repeat(64)}.txt`)).toEqual({
admit: false,
reason: "source-archive-store",
});
expect(admitToIndex("Brain/archives-notes.md").admit).toBe(true);
});
});
describe("the verification vocabulary", () => {
test("the guard accepts exactly the three members", () => {
expect(Object.values(ARCHIVE_VERIFICATION).toSorted()).toEqual([
"mismatched",
"missing",
"verified",
]);
for (const member of Object.values(ARCHIVE_VERIFICATION)) {
expect(isArchiveVerification(member)).toBe(true);
}
expect(isArchiveVerification("intact")).toBe(false);
expect(isArchiveVerification(42)).toBe(false);
});
});