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
/**
* Per-repo git record store with watermark
* (Project History Suite, t_c812752c).
*/
import { afterEach, beforeEach, expect, test } from "bun:test";
import {
chmodSync,
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
rmSync,
symlinkSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
appendGitRecords,
gitStoreDir,
gitStoreRootDir,
listGitCommits,
listGitRepos,
listGitTags,
readGitState,
writeGitState,
} from "../../../../src/core/brain/git/store.ts";
import type { GitCommitRecord, GitTagRecord } from "../../../../src/core/brain/git/store.ts";
import { acquireLockSync, LOCK_WAIT_BUDGET_ENV } from "../../../../src/core/brain/sync-lockfile.ts";
import { withDeviceId, useUnshardedLegacyLog } from "../../../helpers/device-id.ts";
import { CHMOD_CANNOT_DENY } from "../../../helpers/platform.ts";
// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();
let tmp: string;
let vault: string;
const KEY = "fixture-repo-abcd1234";
function commit(sha: string, over: Partial<GitCommitRecord> = {}): GitCommitRecord {
return {
kind: "commit",
sha,
authorName: "Fixture Author",
authorEmail: "[email protected]",
committedAt: "2026-06-01T10:00:00+00:00",
subject: "feat: default subject",
body: "",
files: ["src/a.ts"],
release: null,
...over,
};
}
function tag(name: string, targetSha: string): GitTagRecord {
return { kind: "tag", name, targetSha, createdAt: "2026-06-02T10:00:00+00:00" };
}
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-git-store-"));
vault = join(tmp, "vault");
mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
test("gitStoreDir nests under Brain/projects/git/<repo-key>", () => {
expect(gitStoreDir(vault, KEY)).toBe(join(vault, "Brain", "projects", "git", KEY));
});
test("gitStoreRootDir is Brain/projects/git and the parent of every repo store", () => {
expect(gitStoreRootDir(vault)).toBe(join(vault, "Brain", "projects", "git"));
expect(gitStoreDir(vault, KEY)).toBe(join(gitStoreRootDir(vault), KEY));
});
test("append + list round-trips commits and tags, oldest-first", () => {
const a = commit("a".repeat(40), { subject: "feat: first" });
const b = commit("b".repeat(40), { subject: "fix: second", files: ["src/b.ts", "docs/x.md"] });
const res = appendGitRecords(vault, KEY, [a, tag("v1.0.0", "b".repeat(40)), b]);
expect(res.appended).toBe(3);
expect(res.skipped).toBe(0);
const commits = listGitCommits(vault, KEY);
expect(commits.map((c) => c.subject)).toEqual(["feat: first", "fix: second"]);
expect(commits[1]!.files).toEqual(["src/b.ts", "docs/x.md"]);
const tags = listGitTags(vault, KEY);
expect(tags).toHaveLength(1);
expect(tags[0]!.name).toBe("v1.0.0");
});
test("append dedups commits by sha and tags by name across calls", () => {
appendGitRecords(vault, KEY, [commit("a".repeat(40)), tag("v1.0.0", "a".repeat(40))]);
const res = appendGitRecords(vault, KEY, [
commit("a".repeat(40), { subject: "changed subject must not re-append" }),
tag("v1.0.0", "a".repeat(40)),
commit("c".repeat(40)),
]);
expect(res.appended).toBe(1);
expect(res.skipped).toBe(2);
const commits = listGitCommits(vault, KEY);
expect(commits).toHaveLength(2);
expect(commits[0]!.subject).toBe("feat: default subject");
});
test("listGitCommits filters by file, author, text, time range, and limit keeps newest", () => {
appendGitRecords(vault, KEY, [
commit("a".repeat(40), {
subject: "feat: alpha",
files: ["src/a.ts"],
committedAt: "2026-06-01T10:00:00+00:00",
}),
commit("b".repeat(40), {
subject: "fix: beta touches a",
files: ["src/a.ts", "src/b.ts"],
committedAt: "2026-06-02T10:00:00+00:00",
authorName: "Other Author",
}),
commit("c".repeat(40), {
subject: "docs: gamma",
body: "explains the alpha decision",
files: ["docs/g.md"],
committedAt: "2026-06-03T10:00:00+00:00",
}),
]);
expect(listGitCommits(vault, KEY, { file: "src/a.ts" })).toHaveLength(2);
expect(listGitCommits(vault, KEY, { author: "other" })).toHaveLength(1);
// text matches subject AND body, case-insensitive
expect(listGitCommits(vault, KEY, { text: "ALPHA" }).map((c) => c.subject)).toEqual([
"feat: alpha",
"docs: gamma",
]);
expect(listGitCommits(vault, KEY, { since: "2026-06-02T00:00:00Z" })).toHaveLength(2);
expect(listGitCommits(vault, KEY, { until: "2026-06-01T23:59:59Z" })).toHaveLength(1);
const limited = listGitCommits(vault, KEY, { limit: 2 });
expect(limited.map((c) => c.subject)).toEqual(["fix: beta touches a", "docs: gamma"]);
});
test("a retargeted tag appends a fresh record and wins in listGitTags", () => {
appendGitRecords(vault, KEY, [tag("v1.0.0", "a".repeat(40))]);
// Same (name, target): dedup. New target for the same name: append.
const res = appendGitRecords(vault, KEY, [
tag("v1.0.0", "a".repeat(40)),
tag("v1.0.0", "b".repeat(40)),
]);
expect(res.skipped).toBe(1);
expect(res.appendedTags).toBe(1);
const tags = listGitTags(vault, KEY);
expect(tags).toHaveLength(1);
expect(tags[0]!.targetSha).toBe("b".repeat(40));
});
test("invalid since/until datetimes are rejected, not silently empty", () => {
appendGitRecords(vault, KEY, [commit("a".repeat(40))]);
expect(() => listGitCommits(vault, KEY, { since: "not-a-date" })).toThrow(/invalid 'since'/);
expect(() => listGitCommits(vault, KEY, { until: "garbage" })).toThrow(/invalid 'until'/);
});
test("malformed JSONL lines are skipped, not fatal", () => {
appendGitRecords(vault, KEY, [commit("a".repeat(40))]);
const path = join(gitStoreDir(vault, KEY), "commits.jsonl");
writeFileSync(path, `${readFileSync(path, "utf8")}not json\n{"kind":"junk"}\n`);
appendGitRecords(vault, KEY, [commit("b".repeat(40))]);
expect(listGitCommits(vault, KEY)).toHaveLength(2);
});
test("git state round-trips and validates the watermark sha", () => {
expect(readGitState(vault, KEY)).toEqual({ state: null, error: null });
writeGitState(vault, KEY, {
repoPath: "/work/fixture-repo",
lastSha: "d".repeat(40),
lastIngestedAt: "2026-06-04T08:00:00Z",
});
const probe = readGitState(vault, KEY);
expect(probe.error).toBeNull();
expect(probe.state!.lastSha).toBe("d".repeat(40));
expect(probe.state!.repoPath).toBe("/work/fixture-repo");
expect(() =>
writeGitState(vault, KEY, {
repoPath: "/work/fixture-repo",
lastSha: "HEAD",
lastIngestedAt: "2026-06-04T08:00:00Z",
}),
).toThrow(/full 40-hex/);
});
test("a corrupted state file reads as an error probe, never throws", () => {
mkdirSync(gitStoreDir(vault, KEY), { recursive: true });
writeFileSync(join(gitStoreDir(vault, KEY), "state.json"), "{broken");
const probe = readGitState(vault, KEY);
expect(probe.state).toBeNull();
expect(probe.error).toMatch(/not valid JSON/);
// Tampered watermark sha is rejected on read too.
writeFileSync(
join(gitStoreDir(vault, KEY), "state.json"),
JSON.stringify({ repo_path: "/x", last_sha: "HEAD~1; evil", last_ingested_at: "t" }),
);
expect(readGitState(vault, KEY).error).toMatch(/full 40-hex/);
});
test("listGitRepos enumerates per-repo stores with their states", () => {
expect(listGitRepos(vault)).toEqual([]);
appendGitRecords(vault, KEY, [commit("a".repeat(40))]);
writeGitState(vault, "other-repo-00000000", {
repoPath: "/work/other",
lastSha: "e".repeat(40),
lastIngestedAt: "2026-06-04T08:00:00Z",
});
const repos = listGitRepos(vault);
expect(repos.map((r) => r.key)).toEqual([KEY, "other-repo-00000000"]);
expect(repos[0]!.state).toBeNull();
expect(repos[1]!.state!.repoPath).toBe("/work/other");
expect(existsSync(join(vault, "Brain", "projects", "git", KEY, "commits.jsonl"))).toBe(true);
});
test("listGitRepos skips an entry that vanished, a dangling link", () => {
appendGitRecords(vault, KEY, [commit("a".repeat(40))]);
symlinkSync(join(tmp, "nowhere"), join(gitStoreRootDir(vault), "dangling"));
expect(listGitRepos(vault).map((r) => r.key)).toEqual([KEY]);
});
test.skipIf(CHMOD_CANNOT_DENY)(
"listGitRepos surfaces an entry it cannot stat by its error code",
() => {
appendGitRecords(vault, KEY, [commit("a".repeat(40))]);
const root = gitStoreRootDir(vault);
// Readable but not searchable: the names list, every stat is refused.
chmodSync(root, 0o444);
try {
expect(() => listGitRepos(vault)).toThrow(/EACCES/);
} finally {
chmodSync(root, 0o755);
}
},
);
test("two devices write their own commits shards and reads merge both (t_774dea61)", () => {
const a = commit("c".repeat(40), { subject: "feat: from host a" });
const b = commit("d".repeat(40), { subject: "fix: from host b" });
withDeviceId("a", () => appendGitRecords(vault, KEY, [a]));
withDeviceId("b", () => appendGitRecords(vault, KEY, [b]));
const dir = gitStoreDir(vault, KEY);
expect(existsSync(join(dir, "commits.a.jsonl"))).toBe(true);
expect(existsSync(join(dir, "commits.b.jsonl"))).toBe(true);
expect(existsSync(join(dir, "commits.jsonl"))).toBe(false);
// Cross-device dedup: replaying host a's commit under host b is a no-op
// because the dedup read spans every shard.
const replay = withDeviceId("b", () => appendGitRecords(vault, KEY, [a]));
expect(replay.appended).toBe(0);
expect(
listGitCommits(vault, KEY)
.map((c) => c.subject)
.toSorted(),
).toEqual(["feat: from host a", "fix: from host b"]);
});
test("the append lock is the device's own shard, not the legacy name (t_774dea61)", () => {
const dir = gitStoreDir(vault, KEY);
mkdirSync(dir, { recursive: true });
const previousBudget = process.env[LOCK_WAIT_BUDGET_ENV];
process.env[LOCK_WAIT_BUDGET_ENV] = "0";
// Another writer holds the legacy file and device b's shard.
const legacy = acquireLockSync(join(dir, "commits.jsonl"));
const other = acquireLockSync(join(dir, "commits.b.jsonl"));
try {
const result = withDeviceId("a", () => appendGitRecords(vault, KEY, [commit("e".repeat(40))]));
expect(result.appended).toBe(1);
const own = acquireLockSync(join(dir, "commits.a.jsonl"));
try {
expect(() =>
withDeviceId("a", () => appendGitRecords(vault, KEY, [commit("f".repeat(40))])),
).toThrow(/lock busy: .*commits\.a\.jsonl\.lock/);
} finally {
own.release();
}
} finally {
legacy.release();
other.release();
if (previousBudget === undefined) delete process.env[LOCK_WAIT_BUDGET_ENV];
else process.env[LOCK_WAIT_BUDGET_ENV] = previousBudget;
}
});
test("commits from two devices list oldest-first by commit time (t_774dea61)", () => {
// Device a ingested the newer range, device b the older one; a sorts
// first by shard name, so a name-order merge listed b's old commits last
// and a `limit` kept them as the "newest".
withDeviceId("a", () =>
appendGitRecords(vault, KEY, [
commit("1".repeat(40), { subject: "a-new-1", committedAt: "2026-06-03T10:00:00+00:00" }),
commit("2".repeat(40), { subject: "a-new-2", committedAt: "2026-06-04T10:00:00+00:00" }),
]),
);
withDeviceId("b", () =>
appendGitRecords(vault, KEY, [
commit("3".repeat(40), { subject: "b-old-1", committedAt: "2026-06-01T10:00:00+00:00" }),
commit("4".repeat(40), { subject: "b-old-2", committedAt: "2026-06-02T10:00:00+00:00" }),
]),
);
expect(listGitCommits(vault, KEY).map((c) => c.subject)).toEqual([
"b-old-1",
"b-old-2",
"a-new-1",
"a-new-2",
]);
expect(listGitCommits(vault, KEY, { limit: 1 }).map((c) => c.subject)).toEqual(["a-new-2"]);
});
test("a commit two devices both ingested before their shards synced lists once (t_774dea61)", () => {
// Both devices found the sha absent and wrote it: device b's shard is a
// byte copy of device a's, the state a pre-sync race leaves behind.
withDeviceId("a", () =>
appendGitRecords(vault, KEY, [
commit("5".repeat(40), { subject: "both", committedAt: "2026-06-01T10:00:00+00:00" }),
commit("6".repeat(40), { subject: "only-a", committedAt: "2026-06-02T10:00:00+00:00" }),
]),
);
const dir = gitStoreDir(vault, KEY);
const firstLine = readFileSync(join(dir, "commits.a.jsonl"), "utf8").split("\n")[0]!;
writeFileSync(join(dir, "commits.b.jsonl"), `${firstLine}\n`);
expect(listGitCommits(vault, KEY).map((c) => c.subject)).toEqual(["both", "only-a"]);
expect(listGitCommits(vault, KEY, { limit: 2 }).map((c) => c.subject)).toEqual([
"both",
"only-a",
]);
});