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
6.0 KB
Raw Blame
/**
 * Episodic note-history decomposition (Session Knowledge Synthesis,
 * t_6a201155).
 *
 * Turns a note's git commit chain into recallable episodic phases. The
 * split rule is deterministic and structural - a new phase starts when
 * the gap between consecutive commits exceeds a threshold - so it is
 * language-agnostic (commit-message wording never affects the split)
 * and reproducible. Each phase carries the real commit subjects the
 * author wrote, which is its summary; nothing is generated and the
 * kernel never calls an LLM.
 *
 * Fail-soft and honest about absence: a missing repo or a git failure
 * reports `available: false` (the underlying reader returns null); a
 * real repo where no commit touches the path reports `available: true`
 * with zero phases (empty != broken). No fabricated phase is ever
 * returned for a path with no history.
 */

import { relative, resolve, sep } from "node:path";

import { readCommits } from "./git/reader.ts";
import type { GitCommit } from "./git/reader.ts";

export interface NoteHistoryPhase {
  /** 0-based phase index, oldest first. */
  readonly index: number;
  readonly firstSha: string;
  readonly lastSha: string;
  /** Author date of the earliest / latest commit in the phase (ISO-8601). */
  readonly firstDate: string;
  readonly lastDate: string;
  readonly commitCount: number;
  /** Distinct author names in the phase, first-seen order. */
  readonly authors: ReadonlyArray<string>;
  /** Commit subjects in the phase, oldest first - the phase's summary. */
  readonly subjects: ReadonlyArray<string>;
}

export interface NoteHistoryResult {
  readonly notePath: string;
  /** False only when there is no git history to read (no repo / git failed). */
  readonly available: boolean;
  /** Human-readable reason when there are no phases. */
  readonly reason?: string;
  readonly commitCount: number;
  readonly phases: ReadonlyArray<NoteHistoryPhase>;
}

export interface DecomposeNoteHistoryOptions {
  /** A gap larger than this between consecutive commits starts a new phase. Default 72h. */
  readonly gapHours?: number;
  /** Repository root to read from. Default: the vault directory. */
  readonly repoPath?: string;
  /** Bound the walk to the newest N commits touching the path. */
  readonly maxCount?: number;
  /**
   * May the caller read the page at this vault-relative POSIX path? Asked
   * before the history is read. A refused path answers exactly as a path
   * no commit touches, because a page the caller may not read must not
   * disclose its existence or edit timeline. Absent (the CLI) refuses
   * nothing.
   */
  readonly include?: (rel: string) => boolean;
}

const DEFAULT_GAP_HOURS = 72;
const HOUR_MS = 60 * 60 * 1000;

export function decomposeNoteHistory(
  vault: string,
  notePath: string,
  opts: DecomposeNoteHistoryOptions = {},
): NoteHistoryResult {
  const path = notePath.trim();
  if (path.length === 0) {
    return Object.freeze({
      notePath,
      available: false,
      reason: "no note path given",
      commitCount: 0,
      phases: Object.freeze([]),
    });
  }

  const repoPath = opts.repoPath ?? vault;
  if (opts.include !== undefined && !opts.include(vaultRelativePosix(vault, path))) {
    // The repository's own availability is asked without the path, so the
    // answer is the one a never-written path gets in this same vault.
    const available = readCommits(repoPath, { maxCount: 1 }) !== null;
    return available ? noCommits(path) : noHistory(path);
  }
  const commits = readCommits(repoPath, {
    path,
    ...(opts.maxCount !== undefined ? { maxCount: opts.maxCount } : {}),
  });

  if (commits === null) return noHistory(path);
  if (commits.length === 0) return noCommits(path);

  const gapMs = Math.max(0, opts.gapHours ?? DEFAULT_GAP_HOURS) * HOUR_MS;
  const phases = splitIntoPhases(commits, gapMs);
  return Object.freeze({
    notePath: path,
    available: true,
    commitCount: commits.length,
    phases: Object.freeze(phases),
  });
}

function splitIntoPhases(commits: ReadonlyArray<GitCommit>, gapMs: number): NoteHistoryPhase[] {
  const groups: GitCommit[][] = [];
  let current: GitCommit[] = [];
  let prevMs: number | null = null;
  for (const commit of commits) {
    const ms = parseMs(commit.committedAt);
    const gap = prevMs !== null && ms !== null ? ms - prevMs : 0;
    if (current.length > 0 && gap > gapMs) {
      groups.push(current);
      current = [];
    }
    current.push(commit);
    if (ms !== null) prevMs = ms;
  }
  if (current.length > 0) groups.push(current);
  return groups.map((group, index) => toPhase(group, index));
}

function toPhase(group: ReadonlyArray<GitCommit>, index: number): NoteHistoryPhase {
  const first = group[0]!;
  const last = group[group.length - 1]!;
  const authors: string[] = [];
  for (const commit of group) {
    if (commit.authorName.length > 0 && !authors.includes(commit.authorName)) {
      authors.push(commit.authorName);
    }
  }
  return Object.freeze({
    index,
    firstSha: first.sha,
    lastSha: last.sha,
    firstDate: first.committedAt,
    lastDate: last.committedAt,
    commitCount: group.length,
    authors: Object.freeze(authors),
    subjects: Object.freeze(group.map((commit) => commit.subject)),
  });
}

function parseMs(iso: string): number | null {
  const ms = Date.parse(iso);
  return Number.isNaN(ms) ? null : ms;
}

function noHistory(notePath: string): NoteHistoryResult {
  return Object.freeze({
    notePath,
    available: false,
    reason: "no history available (not a git repository or git unavailable)",
    commitCount: 0,
    phases: Object.freeze([]),
  });
}

function noCommits(notePath: string): NoteHistoryResult {
  return Object.freeze({
    notePath,
    available: true,
    reason: "no commits touch this path",
    commitCount: 0,
    phases: Object.freeze([]),
  });
}

/** `path` as the vault-relative POSIX form the visibility predicate speaks. */
function vaultRelativePosix(vault: string, path: string): string {
  return relative(resolve(vault), resolve(vault, path)).split(sep).join("/");
}