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.2 KB
Raw Blame
/**
 * Idea lineage (Session Knowledge Synthesis, t_635a3ea5).
 *
 * A read-only provenance tracer: given a derived artifact, reconstruct
 * the observation -> synthesis -> conclusion chain from edges that
 * already exist - it writes nothing and computes nothing new.
 *
 * Two resolvers behind one shape:
 *   - continuity records (a ctn_ id): walk the `sourceRefs` graph
 *     backward. A raw `session_turn` is an observation, intermediate
 *     summary/extract/digest records are synthesis, the queried record
 *     is the conclusion. Edges resolve by record id (`session_summary_node`
 *     -> continuity_record) or by turn id (`session_summary_digest` ->
 *     `session_turn.payload.turn_id`). A seen-set guards cycles and a
 *     depth bound caps traversal (reported as `truncated`).
 *   - preferences (a pref-/ret- id): adapt the existing
 *     `buildBeliefEvolution` lifecycle into the same node/edge shape -
 *     creation is the observation, promotion the synthesis, retirement a
 *     terminal conclusion. No belief logic is reimplemented here.
 *
 * Unknown ids fail with {@link IdeaLineageError} rather than returning a
 * silent empty chain.
 */

import { listContinuityRecords } from "./continuity/store.ts";
import type { ContinuityRecord } from "./continuity/types.ts";
import { sessionIdOf } from "./session-recall.ts";
import { buildTimelineIndex } from "./temporal/build-index.ts";
import { buildBeliefEvolution } from "./temporal/belief-evolution.ts";

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

export type LineageStage = "observation" | "synthesis" | "conclusion";

export interface IdeaLineageNode {
  readonly id: string;
  readonly kind: string;
  readonly stage: LineageStage;
  /** 0 for the queried artifact, increasing toward observations. */
  readonly depth: number;
  readonly createdAt: string | null;
  readonly label: string;
}

export interface IdeaLineageEdge {
  /** The more-derived node. */
  readonly from: string;
  /** The source it was derived from. */
  readonly to: string;
  readonly relation: string;
}

export interface IdeaLineageResult {
  readonly root: IdeaLineageNode;
  readonly nodes: ReadonlyArray<IdeaLineageNode>;
  readonly edges: ReadonlyArray<IdeaLineageEdge>;
  /** True when the depth bound stopped traversal before exhausting sources. */
  readonly truncated: boolean;
}

export interface TraceIdeaLineageInput {
  readonly id: string;
}

export interface TraceIdeaLineageOptions {
  /** Maximum backward hops from the queried artifact. Default 8. */
  readonly maxDepth?: number;
  /**
   * Leave out continuity rows flagged `private`, and a preference's log
   * events of the store's `private` partition, as if they did not exist.
   * Set for a caller at remote reach.
   */
  readonly withholdPrivate?: boolean;
}

const DEFAULT_MAX_DEPTH = 8;
const SNIPPET = 80;

export function traceIdeaLineage(
  vault: string,
  input: TraceIdeaLineageInput,
  opts: TraceIdeaLineageOptions = {},
): IdeaLineageResult {
  const id = input.id.trim();
  if (id.length === 0) throw new IdeaLineageError("idea lineage requires a non-empty id");
  if (id.startsWith("pref-") || id.startsWith("ret-")) {
    return preferenceLineage(vault, id, opts.withholdPrivate === true);
  }
  return continuityLineage(
    vault,
    id,
    Math.max(1, opts.maxDepth ?? DEFAULT_MAX_DEPTH),
    opts.withholdPrivate === true,
  );
}

// ----- continuity source graph ---------------------------------------------

function continuityLineage(
  vault: string,
  id: string,
  maxDepth: number,
  withholdPrivate: boolean,
): IdeaLineageResult {
  const records = listContinuityRecords(vault).filter(
    (record) => !(withholdPrivate && record.private),
  );
  const byId = new Map<string, ContinuityRecord>();
  const byTurnId = new Map<string, ContinuityRecord>();
  const bySessionTurnId = new Map<string, ContinuityRecord>();
  for (const record of records) {
    byId.set(record.id, record);
    if (record.kind === "session_turn") {
      const turnId = String(record.payload["turn_id"] ?? "");
      if (turnId.length === 0) continue;
      if (!byTurnId.has(turnId)) byTurnId.set(turnId, record);
      // A record naming no session joins only the global turn index -
      // never the session-scoped one, where a coerced "" or a stringified
      // non-string id would merge unrelated records into one group.
      const sessionId = sessionIdOf(record.payload);
      if (sessionId !== undefined) {
        const scoped = sessionTurnKey(sessionId, turnId);
        if (!bySessionTurnId.has(scoped)) bySessionTurnId.set(scoped, record);
      }
    }
  }
  const lookup: Lookup = { byId, byTurnId, bySessionTurnId };

  const root = byId.get(id);
  if (root === undefined) throw new IdeaLineageError(`no continuity record with id ${id}`);

  const nodes: IdeaLineageNode[] = [continuityNode(root, 0, true)];
  const edges: IdeaLineageEdge[] = [];
  const seen = new Set<string>([root.id]);
  const edgeKeys = new Set<string>();
  let truncated = false;

  let frontier: ContinuityRecord[] = [root];
  let depth = 0;
  while (frontier.length > 0) {
    if (depth >= maxDepth) {
      if (frontier.some((record) => hasUnseenSource(record, lookup, seen))) truncated = true;
      break;
    }
    const next: ContinuityRecord[] = [];
    for (const record of frontier) {
      for (const source of resolveSources(record, lookup)) {
        const edgeKey = `${record.id}->${source.record.id}`;
        if (!edgeKeys.has(edgeKey)) {
          edgeKeys.add(edgeKey);
          edges.push(
            Object.freeze({ from: record.id, to: source.record.id, relation: source.relation }),
          );
        }
        if (!seen.has(source.record.id)) {
          seen.add(source.record.id);
          nodes.push(continuityNode(source.record, depth + 1, false));
          next.push(source.record);
        }
      }
    }
    frontier = next;
    depth += 1;
  }

  return Object.freeze({
    root: nodes[0]!,
    nodes: Object.freeze(nodes),
    edges: Object.freeze(edges),
    truncated,
  });
}

interface ResolvedSource {
  readonly record: ContinuityRecord;
  readonly relation: string;
}

/**
 * Record lookups for source resolution. `bySessionTurnId` is keyed
 * `<session_id>:<turn_id>` so a turn reference resolves within the
 * referring record's own session first, preventing a cross-session
 * mislink when two sessions reuse the same `turn_id`.
 */
interface Lookup {
  readonly byId: ReadonlyMap<string, ContinuityRecord>;
  readonly byTurnId: ReadonlyMap<string, ContinuityRecord>;
  readonly bySessionTurnId: ReadonlyMap<string, ContinuityRecord>;
}

function sessionTurnKey(sessionId: string, turnId: string): string {
  return `${sessionId}:${turnId}`;
}

function resolveSources(record: ContinuityRecord, lookup: Lookup): ResolvedSource[] {
  const sources: ResolvedSource[] = [];
  const claimed = new Set<string>();
  // Undefined - never "" - when the record names no session: the scoped
  // lookup is then unreachable and the global turn index (first record in
  // store order) is the documented fallback for an unknown session.
  const recordSessionId = sessionIdOf(record.payload);
  for (const ref of record.sourceRefs) {
    const refId = typeof ref.id === "string" ? ref.id : "";
    if (refId.length === 0 || refId === record.id) continue;
    // A record-id edge wins; otherwise a turn id resolves within the
    // referring record's own session before falling back to the global
    // turn index (only reachable when the session is unknown).
    const scoped =
      recordSessionId !== undefined
        ? lookup.bySessionTurnId.get(sessionTurnKey(recordSessionId, refId))
        : undefined;
    const candidate = lookup.byId.get(refId) ?? scoped ?? lookup.byTurnId.get(refId);
    if (candidate === undefined || candidate.id === record.id || claimed.has(candidate.id))
      continue;
    claimed.add(candidate.id);
    sources.push({ record: candidate, relation: refRelation(ref) });
  }
  return sources;
}

function hasUnseenSource(
  record: ContinuityRecord,
  lookup: Lookup,
  seen: ReadonlySet<string>,
): boolean {
  return resolveSources(record, lookup).some((source) => !seen.has(source.record.id));
}

function refRelation(ref: { readonly kind?: string }): string {
  return typeof ref.kind === "string" && ref.kind.length > 0 ? ref.kind : "source";
}

function continuityNode(record: ContinuityRecord, depth: number, isRoot: boolean): IdeaLineageNode {
  return Object.freeze({
    id: record.id,
    kind: record.kind,
    stage: continuityStage(record, isRoot),
    depth,
    createdAt: record.createdAt,
    label: continuityLabel(record),
  });
}

function continuityStage(record: ContinuityRecord, isRoot: boolean): LineageStage {
  if (record.kind === "session_turn") return "observation";
  if (isRoot) return "conclusion";
  return "synthesis";
}

function continuityLabel(record: ContinuityRecord): string {
  const payload = record.payload;
  if (record.kind === "session_turn") {
    const role = String(payload["role"] ?? "");
    return `${role}: ${snippet(String(payload["text"] ?? ""))}`.trim();
  }
  if (record.kind === "session_summary_node") {
    return `summary depth ${String(payload["depth"] ?? "?")}`;
  }
  if (record.kind === "session_summary_digest") {
    return "session summary digest";
  }
  if (record.kind === "pre_compact_extract") {
    return `${String(payload["extract_type"] ?? "extract")}: ${snippet(String(payload["text"] ?? ""))}`;
  }
  return record.kind;
}

function snippet(text: string): string {
  const oneLine = text.replace(/\s+/g, " ").trim();
  return oneLine.length > SNIPPET ? `${oneLine.slice(0, SNIPPET - 3)}...` : oneLine;
}

// ----- preference belief evolution -----------------------------------------

function preferenceLineage(
  vault: string,
  prefId: string,
  withholdPrivate: boolean,
): IdeaLineageResult {
  const index = buildTimelineIndex(vault, { withholdsPrivate: withholdPrivate });
  const evo = buildBeliefEvolution(index, vault, { prefId });
  if (evo.transitions.length === 0 && evo.evidence.length === 0 && evo.retirements.length === 0) {
    throw new IdeaLineageError(`no belief lineage for ${prefId}`);
  }

  const firstAt = evo.transitions[0]?.at ?? null;
  const root: IdeaLineageNode = Object.freeze({
    id: prefId,
    kind: "preference",
    stage: "conclusion",
    depth: 0,
    createdAt: firstAt,
    label: prefId,
  });
  const nodes: IdeaLineageNode[] = [root];
  const edges: IdeaLineageEdge[] = [];
  for (const transition of evo.transitions) {
    const nodeId = `${transition.kind}:${transition.prefId}:${transition.at}`;
    nodes.push(
      Object.freeze({
        id: nodeId,
        kind: "belief_transition",
        stage: transitionStage(transition.kind),
        depth: 1,
        createdAt: transition.at,
        label: `${transition.kind} ${transition.at}`,
      }),
    );
    edges.push(Object.freeze({ from: prefId, to: nodeId, relation: transition.kind }));
  }

  return Object.freeze({
    root,
    nodes: Object.freeze(nodes),
    edges: Object.freeze(edges),
    truncated: false,
  });
}

function transitionStage(kind: "creation" | "promotion" | "retirement"): LineageStage {
  if (kind === "creation") return "observation";
  if (kind === "promotion") return "synthesis";
  return "conclusion";
}