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
/**
* Dead-end registry (t_be62c62d): negative knowledge as first-class
* markdown notes under `Brain/dead-ends/` - what was tried, why it
* failed, in what context - bounded to the most-recent-N with
* archive-on-overflow. Markdown-first means FTS indexes the notes
* with zero search changes, so recall surfaces "avoid X" alongside
* "prefer Y".
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
existsSync,
mkdtempSync,
readdirSync,
readFileSync,
rmSync,
writeFileSync,
mkdirSync,
symlinkSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
DEAD_END_MAX_ACTIVE,
deadEndsDir,
listDeadEnds,
recordDeadEnd,
} from "../../../src/core/brain/dead-ends.ts";
import { indexVault } from "../../../src/core/search/indexer.ts";
import { search } from "../../../src/core/search/search.ts";
import { createTempVault, makeConfig } from "../../helpers/search-fixtures.ts";
let vault: string;
const NOW = new Date("2026-06-04T12:00:00Z");
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-dead-ends-"));
// A legacy Brain/ tree: an unswitched machine's vault. A vault without
// one is a fresh install, whose lane pages are store records.
mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
});
function record(approach: string, over: { reason?: string; context?: string; now?: Date } = {}) {
return recordDeadEnd(vault, {
approach,
reason: over.reason ?? "It corrupted the index on concurrent writes",
...(over.context !== undefined ? { context: over.context } : {}),
agent: "claude-dev-agent",
now: over.now ?? NOW,
});
}
describe("recordDeadEnd", () => {
test("writes a markdown note with brain-dead-end frontmatter and sections", () => {
const { entry } = record("Mutable global cache for the search index", {
context: "v0.41 indexing rework",
});
expect(entry.id).toBe("de-2026-06-04-mutable-global-cache-for-the-search-index");
const text = readFileSync(entry.path, "utf8");
expect(text).toContain("kind: brain-dead-end");
expect(text).toContain("agent: claude-dev-agent");
expect(text).toContain("## Approach");
expect(text).toContain("Mutable global cache for the search index");
expect(text).toContain("## Why it failed");
expect(text).toContain("corrupted the index");
expect(text).toContain("## Context");
expect(text).toContain("v0.41 indexing rework");
});
test("same approach on the same day allocates a collision suffix", () => {
const first = record("Retry loop");
const second = record("Retry loop");
expect(first.entry.id).not.toBe(second.entry.id);
expect(second.entry.id.endsWith("-2")).toBe(true);
});
test("empty approach or reason throws", () => {
expect(() => record(" ")).toThrow();
expect(() => record("Approach", { reason: " " })).toThrow();
});
test("overflow archives the oldest entries", () => {
for (let i = 0; i < 4; i++) {
record(`Approach number ${i}`, { now: new Date(`2026-06-0${i + 1}T10:00:00Z`) });
}
const result = recordDeadEnd(vault, {
approach: "The newest approach",
reason: "Still failed",
agent: "claude-dev-agent",
now: new Date("2026-06-05T10:00:00Z"),
maxActive: 3,
});
expect(result.archived.length).toBe(2);
const active = listDeadEnds(vault);
expect(active.entries).toHaveLength(3);
expect(existsSync(join(deadEndsDir(vault), "archive"))).toBe(true);
const archived = readdirSync(join(deadEndsDir(vault), "archive"));
expect(archived).toHaveLength(2);
});
test("default cap is generous", () => {
expect(DEAD_END_MAX_ACTIVE).toBeGreaterThanOrEqual(100);
});
});
describe("recordDeadEnd - a lost race retries instead of dropping the note", () => {
test("a name taken between the probe and the create lands on `-2`", () => {
// A dangling symlink is read as free by `existsSync` (which follows
// the link) and as taken by `link(2)` (which does not) - the exact
// pair of answers the loser of a concurrent write gets, without the
// timing dependence of racing two processes.
const dir = deadEndsDir(vault);
mkdirSync(dir, { recursive: true });
const taken = join(dir, "de-2026-06-04-mutable-global-cache.md");
symlinkSync(join(dir, "never-created"), taken);
const { entry } = record("Mutable global cache");
expect(entry.id).toBe("de-2026-06-04-mutable-global-cache-2");
expect(existsSync(entry.path)).toBe(true);
});
});
describe("listDeadEnds", () => {
test("returns active entries newest first with parsed fields", () => {
record("Old approach", { now: new Date("2026-06-01T10:00:00Z") });
record("New approach", { now: new Date("2026-06-03T10:00:00Z") });
const { entries } = listDeadEnds(vault);
expect(entries.map((e) => e.approach)).toEqual(["New approach", "Old approach"]);
expect(entries[0]!.reason).toContain("corrupted");
expect(entries[0]!.agent).toBe("claude-dev-agent");
});
test("malformed files are skipped fail-closed, never fatal", () => {
record("Good approach");
mkdirSync(deadEndsDir(vault), { recursive: true });
writeFileSync(join(deadEndsDir(vault), "de-2026-06-04-junk.md"), "no frontmatter at all");
const { entries, warnings } = listDeadEnds(vault);
expect(entries).toHaveLength(1);
expect(warnings).toHaveLength(1);
});
test("an empty vault lists nothing", () => {
expect(listDeadEnds(vault).entries).toEqual([]);
});
});
describe("recall integration", () => {
test("dead-end notes index into FTS and surface on search", async () => {
const tmp = createTempVault("dead-end-recall");
try {
recordDeadEnd(tmp.vault, {
approach: "Sharding the quartz ledger by month",
reason: "Quartz ledger shards desynchronized under Syncthing",
agent: "claude-dev-agent",
now: NOW,
});
const config = makeConfig({ vault: tmp.vault, dbPath: tmp.dbPath });
await indexVault(config);
const outcome = await search(config, { query: "quartz ledger shards" });
expect(outcome.results.some((r) => r.path.startsWith("Brain/dead-ends/"))).toBe(true);
} finally {
tmp.cleanup();
}
});
});