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
/**
* Intake trust requires bytes behind the source (GitHub #160).
*
* `classifySourceTrust` decided trusted-versus-quarantined from the SHAPE of a
* caller-supplied string and never asked whether the file was there. The
* caller is the same agent that extracted the entities from the material being
* classified, so a prompt injection in that material only had to tell the
* agent what to report: a vault-shaped path that names nothing lands the
* extraction trusted and active, beside the operator's own records.
*
* The rule pinned here is that a source identity buys trust only when it
* resolves to a readable file inside the vault. `brain_intake_entities`
* asserts that these entities were extracted from this material, and a path
* with no bytes behind it cannot have produced an extraction.
*
* What this does NOT buy is stated in the classifier's own docblock and is not
* pinned here, because it is not a behaviour: an attacker forced to name a
* real file names `README.md`. The check removes the free bypass and makes the
* claim auditable; it does not stop the lie.
*
* The third answer is kept apart from both lanes. An unreadable file is not a
* trust verdict - it is a question the filesystem refused - so it propagates
* instead of being folded into `untrusted`, where a permissions mistake would
* quarantine the operator's own note and quarantine is one-way.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { chmodSync, mkdirSync, 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 { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";
import { parseFrontmatter } from "../../../../src/core/vault.ts";
import { getEntity, listEntities } from "../../../../src/core/brain/entities/registry.ts";
import { BRAIN_ENTITY_STATUS } from "../../../../src/core/brain/entities/types.ts";
import { hashFile } from "../../../../src/core/brain/ingest/content-manifest.ts";
import {
intakeExtraction,
IntakeValidationError,
} from "../../../../src/core/brain/intake/extract-intake.ts";
import {
classifySourceOrigin,
classifySourceTrust,
SOURCE_HASH_MAX_BYTES,
SourceTrustError,
} from "../../../../src/core/brain/intake/source-trust.ts";
import {
INTAKE_TRUST,
SOURCE_CONTENT_HASH_FRONTMATTER_KEY,
} from "../../../../src/core/brain/trust/untrusted-provenance.ts";
import { CHMOD_CANNOT_DENY } from "../../../helpers/platform.ts";
let vault: string;
let configHome: string;
const NOW = new Date("2026-06-13T12:00:00Z");
const EXTRACTION = { entities: [{ category: "concept", name: "Restaking" }] };
const SOURCE = "Articles/primer.md";
const SOURCE_BYTES = "the source bytes the extraction claims to come from\n";
/** A directory this vault denies itself, so `stat` answers with an errno. */
const LOCKED_DIR = "Locked";
function seed(rel: string, contents = SOURCE_BYTES): string {
const abs = join(vault, rel);
mkdirSync(join(abs, ".."), { recursive: true });
writeFileSync(abs, contents, "utf8");
return abs;
}
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-trust-bytes-vault-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-trust-bytes-cfg-"));
const configPath = join(configHome, "config.yaml");
atomicWriteFileSync(configPath, `vault: ${vault}\n`);
bootstrapBrain(vault, { configPath });
});
afterEach(() => {
// Restore the locked directory first: a 0-mode directory cannot be walked,
// so the cleanup below would fail on the vault that contains it.
const locked = join(vault, LOCKED_DIR);
try {
chmodSync(locked, 0o755);
} catch {
// The test that locks it is the only one that creates it.
}
rmSync(vault, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
});
describe("classifySourceOrigin - a shape without bytes is not a source", () => {
test("a vault-shaped path that names no file is untrusted and hashes nothing", () => {
const origin = classifySourceOrigin(vault, SOURCE);
expect(origin.trust).toBe(INTAKE_TRUST.untrusted);
expect(origin.contentHash).toBeUndefined();
});
test("the same path with a real file behind it is trusted and records its hash", () => {
const abs = seed(SOURCE);
const origin = classifySourceOrigin(vault, SOURCE);
expect(origin.trust).toBe(INTAKE_TRUST.trusted);
expect(origin.contentHash).toBe(hashFile(abs));
});
test("an address outside the vault stays untrusted however the shape gate is fed", () => {
seed(SOURCE);
for (const source of ["https://example.com/a", "evil.com/article", "../outside/x.md"]) {
expect(classifySourceOrigin(vault, source).trust).toBe(INTAKE_TRUST.untrusted);
}
});
test("a directory is not a file: naming one buys no trust", () => {
seed(SOURCE);
expect(classifySourceOrigin(vault, "Articles").trust).toBe(INTAKE_TRUST.untrusted);
});
// chmod cannot deny access on Windows (read-only attribute only) or to root.
test.skipIf(CHMOD_CANNOT_DENY)(
"a source that exists but cannot be read is an error, not a verdict",
() => {
seed(`${LOCKED_DIR}/note.md`);
chmodSync(join(vault, LOCKED_DIR), 0o000);
expect(() => classifySourceOrigin(vault, `${LOCKED_DIR}/note.md`)).toThrow();
},
);
});
/**
* The refusal above travels: `brain_intake_entities` wraps this classifier,
* and a rethrown Node errno renders as
* `EACCES: permission denied, stat '/home/<user>/<vault>/Locked/note.md'` -
* the operator's home path in an MCP error, on a string the CALLER supplied.
* That is a per-path existence-and-permission oracle over the operator's
* filesystem. The refusal stays; only the message is ours to compose.
*/
describe("classifySourceOrigin - a refusal names the identity and the errno, nothing else", () => {
// chmod cannot deny access on Windows (read-only attribute only) or to root.
test.skipIf(CHMOD_CANNOT_DENY)(
"an unreadable source refuses without a path or a sentence",
() => {
seed(`${LOCKED_DIR}/note.md`);
chmodSync(join(vault, LOCKED_DIR), 0o000);
let thrown: unknown;
try {
classifySourceOrigin(vault, `${LOCKED_DIR}/note.md`);
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(SourceTrustError);
const message = (thrown as Error).message;
expect(message).toContain(`${LOCKED_DIR}/note.md`);
expect(message).toContain("EACCES");
expect(message).not.toContain(vault);
expect(message).not.toContain("permission denied");
},
);
test("a source past the read ceiling is refused rather than read for a lane", () => {
seed(SOURCE, "x".repeat(SOURCE_HASH_MAX_BYTES + 1));
let thrown: unknown;
try {
classifySourceOrigin(vault, SOURCE);
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(SourceTrustError);
expect((thrown as Error).message).toContain(SOURCE);
expect((thrown as Error).message).toContain(String(SOURCE_HASH_MAX_BYTES));
expect((thrown as Error).message).not.toContain(vault);
});
test("a source under the ceiling is hashed as before", () => {
const abs = seed(SOURCE, "x".repeat(1024));
expect(classifySourceOrigin(vault, SOURCE).contentHash).toBe(hashFile(abs));
});
});
/**
* The lane alone, for the caller that cites several sources and will discard
* every digest anyway. Same shape gate, same existence question, no read.
*/
describe("classifySourceTrust - the lane without the bytes", () => {
test("agrees with the full classifier on both verdicts", () => {
seed(SOURCE);
expect(classifySourceTrust(vault, SOURCE)).toBe(INTAKE_TRUST.trusted);
expect(classifySourceTrust(vault, "evil.com/article")).toBe(INTAKE_TRUST.untrusted);
});
test("a source too large to hash still has a lane, because no lane needs its bytes", () => {
seed(SOURCE, "x".repeat(SOURCE_HASH_MAX_BYTES + 1));
expect(classifySourceTrust(vault, SOURCE)).toBe(INTAKE_TRUST.trusted);
});
});
describe("intakeExtraction - the verdict follows the bytes", () => {
function intake(source: string): void {
intakeExtraction(vault, EXTRACTION, {
agent: "ingest-agent",
now: NOW,
provenance: { level: "stated", sources: [`[[${source}]]`], premises: [] },
});
}
test("a source that names no file quarantines what it claims to have extracted", () => {
intake(SOURCE);
expect(getEntity(vault, { category: "concept", query: "Restaking" })).toBeNull();
expect(listEntities(vault, { status: BRAIN_ENTITY_STATUS.quarantine })).toHaveLength(1);
});
test("a source with a real file behind it lands active and stamps the audit hash", () => {
const abs = seed(SOURCE);
intake(SOURCE);
const entity = getEntity(vault, { category: "concept", query: "Restaking" });
expect(entity).not.toBeNull();
const [meta] = parseFrontmatter(entity!.path);
expect(meta[SOURCE_CONTENT_HASH_FRONTMATTER_KEY]).toBe(hashFile(abs));
});
test("the verdict is returned to the caller rather than recomputed by it", () => {
seed(SOURCE);
const res = intakeExtraction(vault, EXTRACTION, {
agent: "ingest-agent",
now: NOW,
provenance: { level: "stated", sources: [`[[${SOURCE}]]`], premises: [] },
});
expect(res.trust).toBe(INTAKE_TRUST.trusted);
});
test("a source whose hash would be discarded is never read for it", () => {
// Two trusted sources: there is no single set of bytes this extraction
// came from, so no hash is recorded - and a classifier that hashed every
// source before deciding that would read the large one in full for a
// digest it then threw away. Past the read ceiling, that read is a
// refusal, which is what makes the waste observable here.
seed(SOURCE);
seed("Articles/huge.md", "x".repeat(SOURCE_HASH_MAX_BYTES + 1));
intakeExtraction(vault, EXTRACTION, {
agent: "ingest-agent",
now: NOW,
provenance: {
level: "stated",
sources: [`[[${SOURCE}]]`, "[[Articles/huge.md]]"],
premises: [],
},
});
const entity = getEntity(vault, { category: "concept", query: "Restaking" });
expect(entity).not.toBeNull();
const [meta] = parseFrontmatter(entity!.path);
expect(meta[SOURCE_CONTENT_HASH_FRONTMATTER_KEY]).toBeUndefined();
});
test("an intake citing no source at all is refused, and writes nothing", () => {
expect(() =>
intakeExtraction(vault, EXTRACTION, {
agent: "ingest-agent",
now: NOW,
provenance: { level: "stated", sources: [], premises: [] },
}),
).toThrow(IntakeValidationError);
expect(listEntities(vault)).toHaveLength(0);
});
});