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 session-summary` (Session Knowledge Synthesis, t_325a7e4a):
* write or read a session-scoped structured digest over the four
* canonical categories (request / decisions / learnings / next_steps).
*
* write --session <id> [--request <s>] [--decision <s>]...
* [--learning <s>]... [--next-step <s>]... [--turn <id>]... [--host <h>]
* get --session <id>
* list [--session <id>]
*
* The kernel stores agent-supplied categories verbatim; it never parses
* prose into categories. An all-empty digest is rejected (exit 2).
*/
import {
appendSessionSummary,
getSessionSummaryReport,
listSessionSummaries,
SessionSummaryError,
type SessionSummaryDigest,
type SessionSummaryRecordRef,
type SessionSummaryReport,
} from "../../../core/brain/session-summary.ts";
import { brainVerbContext, fail, parse, usageError } from "../helpers.ts";
const USAGE =
"usage: o2b brain session-summary write --session <id> [--request <s>] " +
"[--decision <s>]... [--learning <s>]... [--next-step <s>]... [--turn <id>]... [--host <h>] [--json]\n" +
" o2b brain session-summary get --session <id> [--json]\n" +
" o2b brain session-summary list [--session <id>] [--json]";
/**
* The text-mode stand-in for a digest whose record names no session
* (t_22d58fa7). A dash, not an id and not the empty string the old
* `String(... ?? "")` coercion manufactured - a no-session record is
* rendered as having none, never as belonging to some session.
*/
const NO_SESSION_RENDER = "-";
export async function cmdBrainSessionSummary(argv: string[]): Promise<number> {
const subcommand = argv[0];
if (subcommand === "write") return writeSummary(argv.slice(1));
if (subcommand === "get") return getSummary(argv.slice(1));
if (subcommand === "list") return listSummaries(argv.slice(1));
return fail(USAGE);
}
function asStringArray(value: string | boolean | string[] | undefined): ReadonlyArray<string> {
return Array.isArray(value) ? value : [];
}
function writeSummary(argv: string[]): number {
const { flags } = parse(argv, {
vault: { type: "string" },
session: { type: "string" },
request: { type: "string" },
decision: { type: "string-array" },
learning: { type: "string-array" },
"next-step": { type: "string-array" },
turn: { type: "string-array" },
host: { type: "string" },
json: { type: "boolean" },
});
const session = typeof flags["session"] === "string" ? flags["session"].trim() : "";
if (session.length === 0) return usageError("brain session-summary write: --session is required");
const vault = brainVerbContext(flags).vault;
try {
const digest = appendSessionSummary(vault, {
sessionId: session,
...(typeof flags["request"] === "string" ? { request: flags["request"] } : {}),
decisions: asStringArray(flags["decision"]),
learnings: asStringArray(flags["learning"]),
nextSteps: asStringArray(flags["next-step"]),
sourceTurnIds: asStringArray(flags["turn"]),
...(typeof flags["host"] === "string" ? { host: flags["host"] } : {}),
});
return emit(
flags,
{ written: true, digest: serialize(digest) },
() => `wrote session summary ${digest.id}`,
);
} catch (error) {
if (error instanceof SessionSummaryError)
return usageError(`brain session-summary write: ${error.message}`);
throw error;
}
}
/**
* The one note line text mode appends when the session holds more than one
* content-differing digest (t_59d4c919). Token-shaped so an operator can
* grep it; the count is the honest total, the shown digest stays the
* sorted-latest. Divergence is reported here, never merged away.
*/
function divergenceNoteLine(count: number): string {
return `note: digest_count=${count} divergent=true (showing the sorted-latest digest)`;
}
/** Wire shape of one divergence record: identity and hash, never a payload echo. */
function serializeRecordRef(record: SessionSummaryRecordRef): Record<string, unknown> {
return { id: record.id, created_at: record.createdAt, content_hash: record.contentHash };
}
function getSummary(argv: string[]): number {
const { flags } = parse(argv, {
vault: { type: "string" },
session: { type: "string" },
json: { type: "boolean" },
});
const session = typeof flags["session"] === "string" ? flags["session"].trim() : "";
if (session.length === 0) return usageError("brain session-summary get: --session is required");
const vault = brainVerbContext(flags).vault;
const report = getSessionSummaryReport(vault, session);
if (flags["json"] === true) {
process.stdout.write(`${JSON.stringify(serializeReport(report), null, 2)}\n`);
return 0;
}
if (report === null) {
process.stdout.write(`no session summary for ${session}\n`);
return 0;
}
process.stdout.write(renderDigest(report.digest));
if (report.divergent === true) {
process.stdout.write(`${divergenceNoteLine(report.digestCount)}\n`);
}
return 0;
}
/** The get envelope: additive divergence fields only when the session diverges. */
function serializeReport(report: SessionSummaryReport | null): Record<string, unknown> {
if (report === null) return { found: false };
return {
found: true,
digest: serialize(report.digest),
digest_count: report.digestCount,
...(report.divergent === true
? {
divergent: true,
records: (report.records ?? []).map(serializeRecordRef),
}
: {}),
};
}
function listSummaries(argv: string[]): number {
const { flags } = parse(argv, {
vault: { type: "string" },
session: { type: "string" },
json: { type: "boolean" },
});
const session = typeof flags["session"] === "string" ? flags["session"].trim() : undefined;
const vault = brainVerbContext(flags).vault;
const digests = listSessionSummaries(
vault,
session !== undefined && session.length > 0 ? { sessionId: session } : {},
);
if (flags["json"] === true) {
process.stdout.write(
`${JSON.stringify({ count: digests.length, digests: digests.map(serialize) }, null, 2)}\n`,
);
return 0;
}
if (digests.length === 0) {
process.stdout.write("no session summaries\n");
return 0;
}
process.stdout.write(`${digests.length} session summary record(s)\n`);
for (const digest of digests) {
const session = digest.sessionId ?? NO_SESSION_RENDER;
process.stdout.write(
` ${digest.createdAt} ${session} d=${digest.decisions.length} l=${digest.learnings.length} n=${digest.nextSteps.length}\n`,
);
}
return 0;
}
function serialize(digest: SessionSummaryDigest): Record<string, unknown> {
return {
id: digest.id,
// Presence-gated with the digest shape (t_22d58fa7): a record naming
// no session carries no session_id key, never a fabricated "".
...(digest.sessionId !== undefined ? { session_id: digest.sessionId } : {}),
request: digest.request,
decisions: digest.decisions,
learnings: digest.learnings,
next_steps: digest.nextSteps,
created_at: digest.createdAt,
...(digest.host !== undefined ? { host: digest.host } : {}),
// Same field the MCP serializer carries; dropping it here was the
// verified CLI/MCP drift (t_59d4c919).
...(digest.project !== undefined ? { project: digest.project } : {}),
};
}
function renderDigest(digest: SessionSummaryDigest): string {
const lines = [`session ${digest.sessionId ?? NO_SESSION_RENDER} (${digest.createdAt})`];
if (digest.request !== null) lines.push(` request: ${digest.request}`);
appendCategory(lines, "decisions", digest.decisions);
appendCategory(lines, "learnings", digest.learnings);
appendCategory(lines, "next_steps", digest.nextSteps);
return `${lines.join("\n")}\n`;
}
function appendCategory(lines: string[], label: string, items: ReadonlyArray<string>): void {
if (items.length === 0) return;
lines.push(` ${label}:`);
for (const item of items) lines.push(` - ${item}`);
}
function emit(
flags: Record<string, string | boolean | string[] | undefined>,
json: Record<string, unknown>,
text: () => string,
): number {
if (flags["json"] === true) {
process.stdout.write(`${JSON.stringify(json, null, 2)}\n`);
return 0;
}
process.stdout.write(`${text()}\n`);
return 0;
}