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
/**
* `o2b brain storage` (storage-lifecycle, Lane 1 task 1.7).
*
* Claims pinned here:
*
* 1. The report carries the per-surface census, the forecast and the
* usage sample this invocation records; an uncapped vault answers
* tier `unbounded` plainly - bytes are reported, no days-to-cap is
* invented, nothing refuses.
* 2. Each invocation appends exactly one `storage_usage` sample.
* 3. A cap positions the tier, and the stored trend travels into
* `slope_bytes_per_day` and `days_to_cap` beside the fresh census.
* 4. An unreadable surface is refused by name (`unmeasured` with its
* reason), never reported as zero bytes, and the forecast answers
* `unmeasurable` rather than projecting from a partial census.
* 5. A vault with no brain config fails by name (exit 1), it does not
* answer as an empty vault.
*/
import {
afterEach,
beforeEach,
describe,
expect,
setDefaultTimeout,
setSystemTime,
test,
} from "bun:test";
import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { cmdBrainStorage } from "../../../../src/cli/brain/verbs/storage.ts";
import { bootstrapBrain } from "../../../../src/core/brain/init.ts";
import { resetVaultIdentityPins } from "../../../../src/core/brain/vault-identity.ts";
import { brainConfigPath } from "../../../../src/core/brain/paths.ts";
import {
metricsDir,
listMetrics,
appendMetric,
type MetricRecord,
} from "../../../../src/core/brain/metrics.ts";
import {
STORAGE_USAGE_METRIC_SURFACE,
STORAGE_FORECAST_TIER,
} from "../../../../src/core/brain/storage/forecast.ts";
import { measureStorageUsage } from "../../../../src/core/brain/storage/usage.ts";
import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";
import { runCli } from "../../../helpers/run-cli.ts";
import { CHMOD_CANNOT_DENY } from "../../../helpers/platform.ts";
import { CLI_SPAWN_BUDGET_MS } from "../../../helpers/cli-timeout.ts";
// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
let vault: string;
let configHome: string;
let savedConfigEnv: string | undefined;
beforeEach(() => {
resetVaultIdentityPins();
vault = mkdtempSync(join(tmpdir(), "o2b-cli-storage-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-cli-storage-cfg-"));
atomicWriteFileSync(join(configHome, "config.yaml"), `vault: ${vault}\n`);
bootstrapBrain(vault, { configPath: join(configHome, "config.yaml") });
savedConfigEnv = process.env["OPEN_SECOND_BRAIN_CONFIG"];
process.env["OPEN_SECOND_BRAIN_CONFIG"] = join(configHome, "config.yaml");
});
afterEach(() => {
if (savedConfigEnv === undefined) delete process.env["OPEN_SECOND_BRAIN_CONFIG"];
else process.env["OPEN_SECOND_BRAIN_CONFIG"] = savedConfigEnv;
resetVaultIdentityPins();
rmSync(vault, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
rmSync(configHome, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
});
/** The report shape an invocation prints, as the tests read it. */
interface StorageReportJson {
measured: boolean;
usage: {
measuredAt: string;
complete: boolean;
surfaces: ReadonlyArray<{ surface: string; tier: string; bytes: number }>;
bytesByTier: Record<string, number>;
totalBytes: number;
unmeasured: ReadonlyArray<{ surface: string; reason: string }>;
};
forecast: {
tier: string;
measuredBytes: number | null;
capBytes: number | null;
percentUsed: number | null;
slopeBytesPerDay: number | null;
daysToCap: number | null;
unmeasured: ReadonlyArray<{ surface: string; reason: string }>;
samplesUnreadable: boolean;
};
sample: { runId: string; appended: boolean; appendError?: string };
}
function writePage(name: string, totalBytes: number): void {
mkdirSync(join(vault, "Brain", "sources"), { recursive: true });
writeFileSync(join(vault, "Brain", "sources", name), "x".repeat(totalBytes), "utf8");
}
function configureCap(capBytes: number): void {
writeFileSync(
brainConfigPath(vault),
`schema_version: 1\n\nstorage:\n cap_bytes: ${capBytes}\n`,
"utf8",
);
}
/** Seed one `storage_usage` sample at a fixed time and total. */
function seedSample(runAt: string, totalBytes: number, runId: string): void {
mkdirSync(metricsDir(vault), { recursive: true });
appendMetric(vault, {
surface: STORAGE_USAGE_METRIC_SURFACE,
runAt,
payload: { run_id: runId, total_bytes: totalBytes, measured: true, unmeasured: [] },
});
}
/** The usage samples recorded for this vault so far. */
function usageSamples(): MetricRecord[] {
return listMetrics(vault, { surface: STORAGE_USAGE_METRIC_SURFACE });
}
// ---- captured-output driving ----------------------------------------------
/** Everything the verb wrote to stdout and stderr during `drive`. */
interface Captured {
readonly stdout: string;
readonly stderr: string;
}
/**
* Run the verb in-process with both output streams captured. The stream
* methods are restored before this returns, even when the verb throws.
*/
async function drive(argv: ReadonlyArray<string>): Promise<{ captured: Captured; code: number }> {
let out = "";
let err = "";
const originalOut = process.stdout.write;
const originalErr = process.stderr.write;
const append =
(sink: (chunk: string) => void) =>
(chunk: Uint8Array | string): boolean => {
sink(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
return true;
};
process.stdout.write = append((c) => (out += c)) as typeof process.stdout.write;
process.stderr.write = append((c) => (err += c)) as typeof process.stderr.write;
try {
// The captured strings are read only after the verb has run, so the
// object is built after the await - building it inline would snapshot
// the buffers while they are still empty.
const code = await cmdBrainStorage([...argv]);
return { captured: { stdout: out, stderr: err }, code };
} finally {
process.stdout.write = originalOut;
process.stderr.write = originalErr;
}
}
const DAY_MS = 86_400_000;
async function runJsonReport(): Promise<{ code: number; report: StorageReportJson }> {
const { captured, code } = await drive(["--json"]);
return { code, report: JSON.parse(captured.stdout) as StorageReportJson };
}
describe("o2b brain storage", () => {
test("an uncapped vault reports the census and the unbounded tier plainly", async () => {
writePage("AA-page.md", 50_000);
// No writes happen between this measure and the verb's own census,
// so the totals must agree exactly.
const expected = measureStorageUsage(vault);
const { code, report } = await runJsonReport();
expect(code).toBe(0);
expect(report.measured).toBe(true);
expect(report.usage.totalBytes).toBe(expected.totalBytes);
expect(report.usage.surfaces.map((s) => s.surface)).toEqual(
expected.surfaces.map((s) => s.surface),
);
expect(report.forecast.tier).toBe(STORAGE_FORECAST_TIER.unbounded);
expect(report.forecast.capBytes).toBeNull();
expect(report.forecast.percentUsed).toBeNull();
expect(report.forecast.daysToCap).toBeNull();
expect(report.sample.appended).toBe(true);
});
test("each invocation appends exactly one usage sample", async () => {
expect(usageSamples()).toHaveLength(0);
await cmdBrainStorage(["--json"]);
const afterFirst = usageSamples();
expect(afterFirst).toHaveLength(1);
await cmdBrainStorage(["--json"]);
const afterSecond = usageSamples();
expect(afterSecond).toHaveLength(2);
expect(afterSecond[0]!.payload["run_id"]).not.toBe(afterSecond[1]!.payload["run_id"]);
});
test("a cap positions the tier and the stored trend travels", async () => {
writePage("AA-page.md", 50_000);
// Measure only after every fixture write: the cap rewrite replaces
// the bootstrap config template, which would otherwise shift the
// census between the measure and the verb's own.
configureCap(1_000_000);
const total = measureStorageUsage(vault).totalBytes;
// Cap at twice the stable total: the fresh reading sits around half
// the cap (never near the 80/95 percent bands), so the tier comes
// from the horizon. A day-based trend needs three distinct days and
// the verb's own fresh census supersedes the newest seeded day inside
// the fit, which flattens the seeded rise to a fraction of the daily
// step; twice the cap keeps the resulting horizon a few days inside
// warn's 30 - and past critical's 7 - on every machine.
const cap = Math.floor(total * 2.0);
configureCap(cap);
// Seed the two days before today and today itself (UTC midnights), so
// the verb's fresh census always lands on the newest seeded day; fixed
// dates turned into a fourth distinct day once the calendar moved past
// them and flattened the trend out of the warn band. The clock is
// frozen at today's UTC noon so the census cannot cross midnight.
const today = Math.floor(Date.now() / DAY_MS) * DAY_MS;
const seedDay = (daysAgo: number): string => new Date(today - daysAgo * DAY_MS).toISOString();
seedSample(seedDay(2), total - total / 10, "seed-older");
seedSample(seedDay(1), total, "seed-newer");
seedSample(seedDay(0), total + total / 20, "seed-newest");
setSystemTime(new Date(today + DAY_MS / 2));
let run: Awaited<ReturnType<typeof runJsonReport>>;
try {
run = await runJsonReport();
} finally {
setSystemTime();
}
const { code, report } = run;
expect(code).toBe(0);
const forecast = report.forecast;
expect(forecast.tier).toBe(STORAGE_FORECAST_TIER.warn);
expect(forecast.capBytes).toBe(cap);
expect(forecast.measuredBytes).not.toBeNull();
// The percent and the days answer from the fresh census; the seeded
// samples and the report's own sample are the only bytes that moved,
// so the numeric identities are asserted relationally.
expect(Math.abs((forecast.percentUsed! * cap) / 100 - forecast.measuredBytes!)).toBeLessThan(1);
expect(
Math.abs(forecast.measuredBytes! + forecast.daysToCap! * forecast.slopeBytesPerDay! - cap),
).toBeLessThan(1);
// The slope is the seeded trend, not sample noise.
expect(forecast.slopeBytesPerDay!).toBeGreaterThan(total / 30);
expect(forecast.slopeBytesPerDay!).toBeLessThan(total / 10);
});
test.skipIf(CHMOD_CANNOT_DENY)(
"an unreadable surface is refused by name, never reported as zero",
async () => {
writePage("AA-page.md", 9_000);
configureCap(10_000);
mkdirSync(join(vault, "Brain", ".artifacts"), { recursive: true });
writeFileSync(join(vault, "Brain", ".artifacts", "tool-result.json"), "{}", "utf8");
chmodSync(join(vault, "Brain", ".artifacts"), 0o000);
try {
const { code, report } = await runJsonReport();
expect(code).toBe(0);
expect(report.usage.complete).toBe(false);
expect(report.usage.unmeasured).toEqual([
{ surface: "artifacts", reason: "surface_unreadable" },
]);
expect(report.usage.surfaces.map((s) => s.surface)).not.toContain("artifacts");
expect(report.forecast.tier).toBe(STORAGE_FORECAST_TIER.unmeasurable);
expect(report.forecast.unmeasured.map((u) => u.surface)).toEqual(["artifacts"]);
} finally {
chmodSync(join(vault, "Brain", ".artifacts"), 0o755);
}
},
);
// A vault with a legacy `Brain/` tree and no `_brain.yaml`. A vault with
// no `Brain/` at all is store-only and reads its settings from the store
// (design D14 item 3), so it has no missing config to name.
test("a vault with no brain config fails by name", async () => {
const bare = mkdtempSync(join(tmpdir(), "o2b-cli-storage-bare-"));
mkdirSync(join(bare, "Brain"));
try {
const { captured, code } = await drive(["--json", "--vault", bare]);
expect(code).toBe(1);
expect(captured.stderr).toContain("config file does not exist");
} finally {
rmSync(bare, { recursive: true, force: true });
}
});
test("the text report names the unbounded tier and the sample", async () => {
const { captured, code } = await drive([]);
expect(code).toBe(0);
expect(captured.stdout).toContain("unbounded");
expect(captured.stdout).toContain("sample: appended as");
});
test("the dispatcher routes `brain storage` to the verb", async () => {
const r = await runCli(["brain", "storage", "--json"], {
env: { OPEN_SECOND_BRAIN_CONFIG: join(configHome, "config.yaml") },
});
expect(r.returncode).toBe(0);
const report = JSON.parse(r.stdout) as StorageReportJson;
expect(report.measured).toBe(true);
expect(report.forecast.tier).toBe(STORAGE_FORECAST_TIER.unbounded);
});
});