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
/**
* Structured session summary (Session Knowledge Synthesis, t_325a7e4a).
*
* A session-scoped digest over four canonical categories - request,
* decisions, learnings, next_steps - stored as one append-only
* continuity record (`kind: "session_summary_digest"`). This is
* distinct from `session_summary_node` (a hierarchical recall rollup of
* turns) and from `pre_compact_extract` (per-line labelled extracts):
* the digest answers "what was the request, what did we decide, what
* did we learn, what is next" for a whole session as a single unit.
*
* Provider-agnostic by construction: the agent supplies the already-
* extracted categories; this module only validates shape, dedupes by
* content hash, and appends. The kernel never parses prose into
* categories with a natural-language word list - that would break the
* language-agnostic guarantee. Absent agent extraction, no digest is
* written (no fabricated empty summary).
*
* Project scope. A digest may carry the `project` axis of the composite
* scope vocabulary (`src/core/scope-key.ts`), normalized by the SAME slug
* rule as the session axis and folded into the dedupe key through the
* canonical {@link compositeScopeKey}, so the same content under two
* projects is two digests. With the axis absent the key is byte-identical
* to the pre-project world - `compositeScopeKey` contributes the empty
* string - which is what keeps every digest already on disk deduping.
*
* NAMING CAUTION: this `project` is the retrieval/dedup scope axis that
* `brain_search` filters on as `project_scope`. It is NOT the unrelated
* `o2b brain project link|list|remove|status` verb, which links a code
* directory to its owning vault at the CONFIGURATION level. The two share
* a word and nothing else; do not wire one to the other.
*/
import { createHash } from "node:crypto";
import { compositeScopeKey } from "../scope-key.ts";
import { appendContinuityRecord, listContinuityRecords } from "./continuity/store.ts";
import type { ContinuityRecord, ContinuitySourceRef } from "./continuity/types.ts";
import { sessionIdOf } from "./session-recall.ts";
import { resolveSessionScope, SessionScopeError } from "./session-scope.ts";
export class SessionSummaryError extends Error {
constructor(message: string) {
super(message);
this.name = "SessionSummaryError";
}
}
export interface SessionSummaryInput {
readonly sessionId: string;
/** One-line statement of what the session set out to do. */
readonly request?: string;
readonly decisions?: ReadonlyArray<string>;
readonly learnings?: ReadonlyArray<string>;
readonly nextSteps?: ReadonlyArray<string>;
/** Originating runtime (claude, codex, ...); recorded when present. */
readonly host?: string;
/** Turn ids the digest was distilled from; recorded as lineage edges. */
readonly sourceTurnIds?: ReadonlyArray<string>;
/**
* Raw project-scope value; normalized by the shared slug rule. A value
* with no alphanumeric is a caller error, never a silent drop to
* unscoped.
*/
readonly project?: string;
readonly createdAt?: string;
}
export interface SessionSummaryDigest {
readonly id: string;
/**
* The session the digest is scoped to, presence-gated (t_22d58fa7):
* omitted when the record names no session - the key absent, a
* non-string value, or the empty string. Absence stays absence; the
* `String(... ?? "")` coercion this replaces manufactured a `""`
* identity no writer ever stamped.
*/
readonly sessionId?: string;
readonly request: string | null;
readonly decisions: ReadonlyArray<string>;
readonly learnings: ReadonlyArray<string>;
readonly nextSteps: ReadonlyArray<string>;
readonly createdAt: string;
readonly host?: string;
/** Normalized project-scope slug; absent when the digest is unscoped. */
readonly project?: string;
}
const KIND = "session_summary_digest";
/** Name of the project axis, used in both the payload key and error text. */
const PROJECT_FIELD = "project";
/**
* Normalize a raw project value through the shared session-scope slug
* rule. Deliberately STRICT where {@link scopeFromFrontmatter} is
* tolerant: frontmatter is untrusted bulk input where an unusable value
* may contribute no scope, but this is an explicit caller argument, and
* silently normalizing it to "unscoped" would file the digest somewhere
* the caller never asked for.
*/
function normalizeProject(raw: string | undefined): string | undefined {
if (raw === undefined) return undefined;
try {
return resolveSessionScope(raw);
} catch (error) {
if (error instanceof SessionScopeError) {
throw new SessionSummaryError(
`session summary ${PROJECT_FIELD} requires at least one alphanumeric: ${JSON.stringify(raw)}`,
);
}
throw error;
}
}
/**
* Validate the agent-supplied categories, dedupe by content hash, and
* append one digest record. Throws {@link SessionSummaryError} when
* every category is empty - an empty digest is never written.
*/
export function appendSessionSummary(
vault: string,
input: SessionSummaryInput,
): SessionSummaryDigest {
const sessionId = input.sessionId.trim();
if (sessionId.length === 0) {
throw new SessionSummaryError("session summary requires a non-empty session id");
}
const request = normalizeLine(input.request);
const decisions = normalizeList(input.decisions);
const learnings = normalizeList(input.learnings);
const nextSteps = normalizeList(input.nextSteps);
if (
request === null &&
decisions.length === 0 &&
learnings.length === 0 &&
nextSteps.length === 0
) {
throw new SessionSummaryError(
"session summary requires at least one of request, decisions, learnings, or next_steps",
);
}
const host = input.host?.trim();
const project = normalizeProject(input.project);
const contentHash = hash(JSON.stringify([request ?? "", decisions, learnings, nextSteps]));
// Canonical scope contribution: the empty string when the axis is
// absent, so an unscoped digest keys byte-identically to every digest
// written before the axis existed. A changed key would silently stop
// deduplicating the whole existing store.
const scopeKey = compositeScopeKey({ owner: null, session: null, project: project ?? null });
const dedupeKey = [KIND, sessionId, contentHash, ...(scopeKey.length > 0 ? [scopeKey] : [])].join(
":",
);
const existing = findByDedupeKey(vault, dedupeKey);
if (existing !== null) return toDigest(existing);
const createdAt = input.createdAt ?? new Date().toISOString();
const record = appendContinuityRecord(vault, {
kind: KIND,
createdAt,
sourceRefs: buildSourceRefs(sessionId, input.sourceTurnIds),
payload: {
session_id: sessionId,
...(request !== null ? { request } : {}),
decisions,
learnings,
next_steps: nextSteps,
...(host !== undefined && host.length > 0 ? { host } : {}),
...(project !== undefined ? { [PROJECT_FIELD]: project } : {}),
content_hash: contentHash,
dedupe_key: dedupeKey,
},
});
return toDigest(record);
}
/** Latest digest for a session, or null when none was ever written. */
export function getSessionSummary(vault: string, sessionId: string): SessionSummaryDigest | null {
return getSessionSummaryReport(vault, sessionId)?.digest ?? null;
}
/**
* How many divergence records the report samples, at most. The count is
* always the honest total; the sample keeps the NEWEST entries so the list
* reads as "the digests behind the latest answer", never a payload echo.
*/
export const DIVERGENCE_RECORD_SAMPLE_LIMIT = 20;
/** One divergent digest, named by identity and content hash, never its payload. */
export interface SessionSummaryRecordRef {
readonly id: string;
readonly createdAt: string;
readonly contentHash: string;
}
export interface SessionSummaryReport {
/** The sorted-latest digest - the same answer {@link getSessionSummary} gives. */
readonly digest: SessionSummaryDigest;
/**
* How many DISTINCT digests exist for this session id, content-hash
* dedupe applied. The same digest appended twice - the shape two
* devices produce when both summarized a session before their vaults
* synced - counts once.
*/
readonly digestCount: number;
/**
* How many digest records exist for this session id BEFORE the
* content-hash dedupe - the revision count. A session re-summarized as
* it evolves accumulates rows without disagreeing; this keeps that
* stream visible without calling it divergence.
*/
readonly revisions: number;
/**
* Present, always `true`, only when DISTINCT content hashes coexist at
* one `created_at` instant - the one shape the store's read model
* cannot order (two devices distilled the session differently before
* syncing, or two contents landed in the same second), so
* latest-wins is not a safe answer. A later revision wins
* deterministically and is a revision (counted in {@link revisions}),
* not divergence.
*/
readonly divergent?: true;
/**
* Bounded newest-first-sample of the session's distinct digests, oldest
* first, present only alongside `divergent`.
*/
readonly records?: ReadonlyArray<SessionSummaryRecordRef>;
}
/**
* Divergence-aware single-session read (t_59d4c919). The continuity store
* is append-only, so one session id can hold several digest records; the
* plain read answers latest-wins without saying so. This read names the
* fact: the sorted-latest digest, `digest_count` over DISTINCT content
* (two devices writing the same digest before their vaults sync count
* once), `revisions` for the honest record count, and, only when distinct
* content hashes meet at one instant - the one shape the store cannot
* order - `divergent: true` plus a bounded id/created_at/content_hash
* sample. Divergence is REPORTED here - never merged, deleted, or
* reconciled.
*/
export function getSessionSummaryReport(
vault: string,
sessionId: string,
): SessionSummaryReport | null {
const id = sessionId.trim();
// A record naming no session is skipped, never matched: the reads used
// to coerce the missing key to "" and answer a `""`-scoped read with
// every unrelated no-session digest lumped into one phantom session.
const records = sessionDigestRecords(vault).filter(
(record) => sessionIdOf(record.payload) === id,
);
if (records.length === 0) return null;
const revisions = records.length;
// Dedupe by content hash on read, keeping the newest record per hash -
// the store order is the tie-break the latest-wins answer already
// trusts. What survives is one entry per distinct digest content, in
// store order. The project axis joins the key because the write-side
// contract files the same content under two projects as two digests.
const newestPerKey = new Map<string, ContinuityRecord>();
for (const record of records) newestPerKey.set(readDedupeKey(record), record);
const distinct = records.filter((record) => newestPerKey.get(readDedupeKey(record)) === record);
// Divergence = distinct content hashes meeting at one created_at
// instant. Anything ordered by distinct instants is a revision stream
// (latest wins deterministically); only the same-instant meeting is a
// genuine "which one is the answer" conflict.
const hashesByInstant = new Map<string, Set<string>>();
for (const record of distinct) {
const instant = instantKey(record.createdAt);
const hashes = hashesByInstant.get(instant) ?? new Set<string>();
hashes.add(contentHashOf(record));
hashesByInstant.set(instant, hashes);
}
const divergent = [...hashesByInstant.values()].some((hashes) => hashes.size > 1);
return Object.freeze({
digest: toDigest(records[records.length - 1]!),
digestCount: distinct.length,
revisions,
...(divergent
? {
divergent: true as const,
records: Object.freeze(
distinct.slice(-DIVERGENCE_RECORD_SAMPLE_LIMIT).map((record) =>
Object.freeze({
id: record.id,
createdAt: record.createdAt,
contentHash: String(record.payload["content_hash"] ?? ""),
}),
),
),
}
: {}),
});
}
/** The read-side dedupe key: content hash within the digest's project scope. */
function readDedupeKey(record: ContinuityRecord): string {
return `${readProject(record.payload) ?? ""}\u0000${contentHashOf(record)}`;
}
/** The record's content hash as stored; legacy or clipped records read as "". */
function contentHashOf(record: ContinuityRecord): string {
return String(record.payload["content_hash"] ?? "");
}
/**
* The instant a record was created at, at millisecond precision, so the
* second- and millisecond-precision spellings both on disk compare equal.
* A shape Date cannot parse compares as its raw string - records are
* canonical-UTC-validated at the store boundary, so this is a floorslip,
* not a path.
*/
function instantKey(createdAt: string): string {
const ms = Date.parse(createdAt);
return Number.isFinite(ms) ? String(ms) : createdAt;
}
export interface ListSessionSummariesOptions {
readonly sessionId?: string;
/** Raw project value; normalized by the same rule the write applies. */
readonly project?: string;
}
/**
* All digests, oldest first; optionally scoped to one session and/or one
* project.
*
* The project filter is an exact match on the normalized slug, mirroring
* the sibling session filter. It deliberately does NOT use
* {@link scopeAxisReachable}: that helper governs RETRIEVAL, where an
* unscoped shared page must stay visible to every scoped request. This is
* an explicit narrowing of a list, so an unscoped digest is not in the
* asked-for project and is not returned.
*/
export function listSessionSummaries(
vault: string,
opts: ListSessionSummariesOptions = {},
): ReadonlyArray<SessionSummaryDigest> {
const scope = opts.sessionId?.trim();
const project = normalizeProject(opts.project);
return Object.freeze(
sessionDigestRecords(vault)
// Same skip-not-match rule as the single-session read: a record
// naming no session is not in the asked-for session, and a coerced
// "" must never make it look like it is.
.filter((record) => scope === undefined || sessionIdOf(record.payload) === scope)
.filter((record) => project === undefined || readProject(record.payload) === project)
.map(toDigest),
);
}
function sessionDigestRecords(vault: string): ReadonlyArray<ContinuityRecord> {
// `toSorted` is stable, so records the store reads in the same
// created_at instant keep the store's own arrival order - the tie-break
// that says which of two same-instant writes was written second. An id
// tie-break here would order same-instant digests by content hash,
// which is arbitrary, and "latest wins" would answer randomly.
return listContinuityRecords(vault, { kind: KIND }).toSorted((left, right) =>
left.createdAt.localeCompare(right.createdAt),
);
}
function buildSourceRefs(
sessionId: string,
turnIds: ReadonlyArray<string> | undefined,
): ReadonlyArray<ContinuitySourceRef> {
const refs: ContinuitySourceRef[] = [Object.freeze({ kind: "session", id: sessionId })];
for (const turnId of turnIds ?? []) {
const id = turnId.trim();
if (id.length > 0) refs.push(Object.freeze({ kind: "session_turn", id }));
}
return Object.freeze(refs);
}
function toDigest(record: ContinuityRecord): SessionSummaryDigest {
const payload = record.payload;
const host = typeof payload["host"] === "string" ? (payload["host"] as string) : undefined;
const project = readProject(payload);
const sessionId = sessionIdOf(payload);
return Object.freeze({
id: record.id,
...(sessionId !== undefined ? { sessionId } : {}),
request: typeof payload["request"] === "string" ? (payload["request"] as string) : null,
decisions: readList(payload["decisions"]),
learnings: readList(payload["learnings"]),
nextSteps: readList(payload["next_steps"]),
createdAt: record.createdAt,
...(host !== undefined ? { host } : {}),
...(project !== undefined ? { [PROJECT_FIELD]: project } : {}),
});
}
function readProject(payload: ContinuityRecord["payload"]): string | undefined {
const value = payload[PROJECT_FIELD];
return typeof value === "string" && value.length > 0 ? value : undefined;
}
function findByDedupeKey(vault: string, dedupeKey: string): ContinuityRecord | null {
return (
listContinuityRecords(vault, { kind: KIND }).find(
(record) => record.payload["dedupe_key"] === dedupeKey,
) ?? null
);
}
function normalizeLine(value: string | undefined): string | null {
if (typeof value !== "string") return null;
const trimmed = value.trim();
return trimmed.length > 0 ? trimmed : null;
}
function normalizeList(values: ReadonlyArray<string> | undefined): ReadonlyArray<string> {
if (values === undefined) return Object.freeze([]);
return Object.freeze(values.map((value) => value.trim()).filter((value) => value.length > 0));
}
function readList(value: unknown): ReadonlyArray<string> {
if (!Array.isArray(value)) return Object.freeze([]);
return Object.freeze(value.filter((item): item is string => typeof item === "string"));
}
function hash(value: string): string {
return createHash("sha256").update(value).digest("hex").slice(0, 16);
}