Skip to content

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
11.8 KB
Raw Blame
/**
 * Batch session checkpoint (C4 / t_1a3a9eba).
 *
 * A whole session's extracted memories (taste signals), decisions,
 * learnings, an optional request/next-steps summary, and an optional
 * diary note, persisted in ONE call. OSB already exposes per-signal
 * writes and a session-summary digest, but closing a session cleanly
 * means several independent writes; a partial failure mid-way leaves the
 * vault in a half-captured state and a naive retry double-appends.
 *
 * This module makes an end-of-session save atomic FROM THE CALLER'S
 * PERSPECTIVE by giving the whole checkpoint a single idempotency key
 * (session id) over the C1 idempotency ledger:
 *
 *   - A first checkpoint for a session writes every item and records the
 *     session key -> whole-checkpoint content hash.
 *   - A retry with the SAME session id + SAME content short-circuits to a
 *     deduped no-op (`deduped: true`) BEFORE touching disk — the
 *     multi-runtime retry / double-delivery case.
 *   - A retry with the SAME session id + DIFFERENT content is an explicit
 *     {@link IdempotencyPayloadMismatchError} (never a silent overwrite).
 *
 * Within a single checkpoint, each item is written independently and a
 * per-item failure (a malformed signal, an empty summary) is COLLECTED
 * into `partial` rather than aborting the batch — the result is
 * `status: "mixed"` and nothing is silently dropped. A mixed checkpoint
 * does NOT record the session key, so a corrected retry re-attempts the
 * items that need review while the already-written items dedupe through
 * their own per-item keys.
 *
 * The kernel stays deterministic: no LLM, no wall-clock beyond the
 * caller-supplied (or defaulted) `createdAt`.
 */

import { relative } from "node:path";

import { appendBrainNote } from "./note.ts";
import {
  computePayloadHash,
  IdempotencyPayloadMismatchError,
  lookupKey,
  rememberKey,
} from "./idempotency-ledger.ts";
import { appendSessionSummary, type SessionSummaryDigest } from "./session-summary.ts";
import { writeSignal, type WriteSignalOptions } from "./signal.ts";
import { isoDate, isoSecond } from "./time.ts";
import { slugify } from "../vault.ts";
import type { BrainSignalSign } from "./types.ts";

export const SESSION_CHECKPOINT_STATUS = Object.freeze({
  ok: "ok",
  mixed: "mixed",
} as const);

export type SessionCheckpointStatus =
  (typeof SESSION_CHECKPOINT_STATUS)[keyof typeof SESSION_CHECKPOINT_STATUS];

/** One extracted memory (taste signal) in a checkpoint batch. */
export interface CheckpointSignalInput {
  readonly topic: string;
  readonly signal: BrainSignalSign;
  readonly principle: string;
  readonly scope?: string;
  readonly raw?: string;
  readonly source?: ReadonlyArray<string>;
}

export interface SessionCheckpointInput {
  readonly sessionId: string;
  /** Identity stamped on every written signal / diary note. */
  readonly agent: string;
  /** Extracted memories to persist as `sig-*` signals. */
  readonly signals?: ReadonlyArray<CheckpointSignalInput>;
  /** Session summary digest fields (folded into one digest record). */
  readonly request?: string;
  readonly decisions?: ReadonlyArray<string>;
  readonly learnings?: ReadonlyArray<string>;
  readonly nextSteps?: ReadonlyArray<string>;
  readonly sourceTurnIds?: ReadonlyArray<string>;
  readonly host?: string;
  /** Optional narrative diary line appended to today's Brain log. */
  readonly diary?: string;
  /**
   * Canonical UTC ISO-8601 write time. Defaults to `isoSecond(new Date())`;
   * supplied by tests for deterministic fixtures.
   */
  readonly createdAt?: string;
}

/** One item that needs review — never silently dropped. */
export interface CheckpointPartialItem {
  readonly kind: "signal" | "summary" | "diary";
  readonly index?: number;
  readonly topic?: string;
  readonly reason: string;
}

export interface CheckpointSignalResult {
  readonly id: string;
  /** Vault-relative POSIX path of the written (or deduped) signal. */
  readonly path: string;
  /** True when this signal deduped against a prior write of the same key. */
  readonly deduped: boolean;
}

export interface SessionCheckpointResult {
  readonly status: SessionCheckpointStatus;
  readonly sessionId: string;
  /** True when the whole checkpoint deduped at the session key (a retry). */
  readonly deduped: boolean;
  readonly signals: ReadonlyArray<CheckpointSignalResult>;
  readonly summary: { readonly id: string } | null;
  readonly diaryWritten: boolean;
  readonly partial: ReadonlyArray<CheckpointPartialItem>;
}

export class SessionCheckpointError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "SessionCheckpointError";
  }
}

/**
 * The whole-checkpoint idempotency key. Scoped to the session id so a
 * retry of the same session collides here, and DISTINCT from the C1
 * feedback keys (which are `<session>:<slug>` shaped) by the `checkpoint:`
 * prefix.
 */
function checkpointKey(sessionId: string): string {
  return `checkpoint:${sessionId}`;
}

/** Per-signal key so a mixed-then-corrected retry dedupes items already
 * written by the earlier attempt. Index-scoped: a stable slot within the
 * batch, disambiguated by the ledger's content hash. */
function signalKey(sessionId: string, index: number): string {
  return `${checkpointKey(sessionId)}:sig:${index}`;
}

/** The semantic identity of a whole checkpoint for idempotency hashing:
 * every item's content, never timestamps or allocated slugs. */
function checkpointPayloadFields(input: SessionCheckpointInput): Record<string, unknown> {
  return {
    session_id: input.sessionId.trim(),
    signals: (input.signals ?? []).map((s) => ({
      topic: s.topic,
      signal: s.signal,
      principle: s.principle,
      scope: s.scope,
      raw: s.raw,
      source: s.source ? [...s.source] : undefined,
    })),
    request: input.request,
    decisions: input.decisions ? [...input.decisions] : undefined,
    learnings: input.learnings ? [...input.learnings] : undefined,
    next_steps: input.nextSteps ? [...input.nextSteps] : undefined,
    diary: input.diary,
    // `host` and `sourceTurnIds` are written to disk (appendSessionSummary), so
    // a retry with the same session id but different provenance must raise the
    // mismatch error rather than silently deduping.
    host: input.host,
    source_turn_ids: input.sourceTurnIds ? [...input.sourceTurnIds] : undefined,
  };
}

function hasSummaryContent(input: SessionCheckpointInput): boolean {
  return (
    (input.request?.trim().length ?? 0) > 0 ||
    (input.decisions?.length ?? 0) > 0 ||
    (input.learnings?.length ?? 0) > 0 ||
    (input.nextSteps?.length ?? 0) > 0
  );
}

/**
 * Save a whole session's memories + summary (+ optional diary) in one
 * idempotent batch. See the module header for the idempotency contract.
 *
 * @throws SessionCheckpointError when the session id is empty or the
 *   checkpoint carries no items at all.
 * @throws IdempotencyPayloadMismatchError when the session id was already
 *   checkpointed with different content.
 */
export function saveSessionCheckpoint(
  vault: string,
  input: SessionCheckpointInput,
  writeOptions: WriteSignalOptions = {},
): SessionCheckpointResult {
  const sessionId = input.sessionId.trim();
  if (sessionId.length === 0) {
    throw new SessionCheckpointError("session checkpoint requires a non-empty session id");
  }
  const signals = input.signals ?? [];
  const summaryWanted = hasSummaryContent(input);
  if (signals.length === 0 && !summaryWanted && !input.diary?.trim()) {
    throw new SessionCheckpointError(
      "session checkpoint requires at least one signal, summary field, or diary line",
    );
  }

  const createdAt = input.createdAt ?? isoSecond(new Date());
  const key = checkpointKey(sessionId);
  const contentHash = computePayloadHash(checkpointPayloadFields(input));

  // Whole-checkpoint idempotency consult BEFORE any write: a matching
  // retry short-circuits to a deduped no-op; a differing payload for the
  // same session throws rather than silently overwriting the checkpoint.
  const existing = lookupKey(vault, key);
  if (existing) {
    if (existing.contentHash === contentHash) {
      const ref = (existing.ref ?? {}) as {
        signals?: ReadonlyArray<CheckpointSignalResult>;
        summary?: { id: string } | null;
        diaryWritten?: boolean;
      };
      return Object.freeze({
        status: SESSION_CHECKPOINT_STATUS.ok,
        sessionId,
        deduped: true,
        signals: Object.freeze([...(ref.signals ?? [])]),
        summary: ref.summary ?? null,
        diaryWritten: ref.diaryWritten ?? false,
        partial: Object.freeze([]),
      });
    }
    throw new IdempotencyPayloadMismatchError(key, existing.contentHash, contentHash);
  }

  const signalDate = isoDate(new Date(createdAt));
  const signalResults: CheckpointSignalResult[] = [];
  const partial: CheckpointPartialItem[] = [];

  signals.forEach((sig, index) => {
    try {
      const res = writeSignal(
        vault,
        {
          topic: sig.topic,
          signal: sig.signal,
          agent: input.agent,
          principle: sig.principle,
          created_at: createdAt,
          date: signalDate,
          slug: slugify(sig.topic),
          ...(sig.scope ? { scope: sig.scope } : {}),
          ...(sig.raw ? { raw: sig.raw } : {}),
          ...(sig.source && sig.source.length > 0 ? { source: [...sig.source] } : {}),
          idempotency_key: signalKey(sessionId, index),
        },
        writeOptions,
      );
      signalResults.push(
        Object.freeze({
          id: res.id,
          path: res.path ? relative(vault, res.path) : "",
          deduped: res.deduped === true,
        }),
      );
    } catch (err) {
      // A malformed signal or a per-item payload mismatch needs review —
      // collect it, never abort the whole batch.
      partial.push(
        Object.freeze({
          kind: "signal",
          index,
          topic: sig.topic,
          reason: err instanceof Error ? err.message : String(err),
        }),
      );
    }
  });

  let summary: { id: string } | null = null;
  if (summaryWanted) {
    try {
      const digest: SessionSummaryDigest = appendSessionSummary(vault, {
        sessionId,
        ...(input.request !== undefined ? { request: input.request } : {}),
        ...(input.decisions !== undefined ? { decisions: input.decisions } : {}),
        ...(input.learnings !== undefined ? { learnings: input.learnings } : {}),
        ...(input.nextSteps !== undefined ? { nextSteps: input.nextSteps } : {}),
        ...(input.sourceTurnIds !== undefined ? { sourceTurnIds: input.sourceTurnIds } : {}),
        ...(input.host !== undefined ? { host: input.host } : {}),
        createdAt,
      });
      summary = Object.freeze({ id: digest.id });
    } catch (err) {
      partial.push(
        Object.freeze({
          kind: "summary",
          reason: err instanceof Error ? err.message : String(err),
        }),
      );
    }
  }

  let diaryWritten = false;
  if (input.diary?.trim()) {
    try {
      appendBrainNote({ vault, text: input.diary, agent: input.agent });
      diaryWritten = true;
    } catch (err) {
      partial.push(
        Object.freeze({
          kind: "diary",
          reason: err instanceof Error ? err.message : String(err),
        }),
      );
    }
  }

  const status =
    partial.length === 0 ? SESSION_CHECKPOINT_STATUS.ok : SESSION_CHECKPOINT_STATUS.mixed;

  // Record the session key ONLY on a clean checkpoint. A mixed result
  // leaves the key unset so a corrected retry re-attempts the items that
  // needed review; the items that already landed dedupe via their own
  // per-item keys.
  if (status === SESSION_CHECKPOINT_STATUS.ok) {
    rememberKey(vault, {
      key,
      contentHash,
      createdAt,
      ref: { signals: signalResults, summary, diaryWritten },
    });
  }

  return Object.freeze({
    status,
    sessionId,
    deduped: false,
    signals: Object.freeze(signalResults),
    summary,
    diaryWritten,
    partial: Object.freeze(partial),
  });
}