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
8.7 KB
Raw Blame
/**
 * Read-time provenance join for surfaced preferences (recall lane).
 *
 * A preference's `evidenced_by` frontmatter cites its origin signals as
 * wikilinks (`[[sig-...]]`), and a signal may carry a `session_ref` β€”
 * the coordinates of the conversation moment the fact came from. This
 * module joins the two at READ time: parse the ref, order the origins
 * by the preference's own evidence order, and hand the caller the
 * earliest cited one. The order is the preference's `evidenced_by`
 * order β€” never re-sorted, and never a chronological claim: merges
 * sort evidence lexically and windowed rewrites can drop older
 * signals from the list, so `origins[0]` is the earliest origin the
 * preference cites, not the earliest signal in time. Nothing is
 * written: no new frontmatter field, no preference rewrite, so a join
 * cannot corrupt the provenance it only reads.
 *
 * Three producers write `session_ref` today, each with its own shape,
 * and the parser is per-producer aware rather than shape-guessing:
 *
 *   - import-session: `<portable basename>#<turn id>` (the ref is
 *     composed in `src/core/brain/sessions/import.ts` from
 *     `sessionRefIdentity`'s basename key; the fragment is a real
 *     turn id) β€” resolves with kind `turn`;
 *   - capture lifecycle: `session:<id>#<event>` (composed in
 *     `src/core/brain/session-lifecycle.ts`; the fragment is a hook
 *     event NAME β€” UserPromptSubmit, Stop, SessionEnd β€” not an event
 *     id, so every prompt-sourced signal in a session shares the one
 *     coordinate) β€” resolves with kind `session`: session-level
 *     provenance, labeled as what it is;
 *   - auto-extract: a bare session reference with no fragment
 *     (`src/core/brain/extract-signals.ts` stores the caller's
 *     session id verbatim) β€” resolves to NOTHING, because no turn is
 *     available.
 *
 * The never-guess rule governs every shape outside those three: a ref
 * that is blank, fragment-less, double-hashed, or half-empty yields no
 * provenance rather than a best-effort reading. Callers report an
 * honestly-unresolved preference instead of an invented coordinate.
 *
 * Pure and deterministic, in the `detectThreadFacets` mold
 * (thread-topics.ts): no I/O, no clock, no randomness, no imports at
 * all β€” the signal lookup is injected, so the same input yields the
 * same origins in the same order across calls.
 */

/** How the fragment of a parsed `session_ref` should be read. */
export type SessionRefOriginKind = "turn" | "session";

/**
 * One origin coordinate parsed from a signal's `session_ref`.
 * `sessionKey` is the ref's key segment verbatim β€” the portable
 * session basename for import-session refs, the `session:<id>` form
 * for capture-lifecycle refs β€” so a consumer never sees a rewritten
 * identity.
 */
export interface SessionRefOrigin {
  readonly sessionKey: string;
  /** The ref's fragment: a turn id (`turn`) or a hook event name (`session`). */
  readonly fragment: string;
  readonly kind: SessionRefOriginKind;
}

/** The slice of a parsed preference the join needs. */
export interface PreferenceEvidenceSource {
  /** Preference id (`pref-<slug>`); becomes the stable `pref:<id>` key. */
  readonly id: string;
  /** Origin-signal wikilinks, in the preference's own evidence order. */
  readonly evidenced_by: ReadonlyArray<string>;
}

/**
 * Signal-id β†’ `session_ref` lookup, injected so this module stays a
 * leaf. Returns `undefined` when the signal does not exist or carries
 * no `session_ref` β€” both mean "contributes no origin", never an error.
 */
export type SignalSessionRefLookup = (signalId: string) => string | undefined;

/**
 * The resolved provenance of one preference. `origins` follows the
 * preference's `evidenced_by` order (never re-sorted), with duplicate
 * coordinates folded into their first position, so `origins[0]` is the
 * earliest cited origin - an evidence-order figure, never a
 * chronological claim.
 */
export interface PreferenceProvenance {
  /** Stable facet key: `pref:<preference id>`. */
  readonly key: string;
  readonly preferenceId: string;
  readonly origins: ReadonlyArray<SessionRefOrigin>;
}

/** The capture-lifecycle key prefix; the one producer key that is not a basename. */
const CAPTURE_LIFECYCLE_SCHEME = "session:";
/** The stand-in id the lifecycle writer emits when the payload carries none. */
const CAPTURE_LIFECYCLE_UNKNOWN_ID = "unknown";
/**
 * The lifecycle writer's session-id grammar: the host's session id is a
 * UUID. The prefix alone is not evidence - an imported session file could
 * be named with the same prefix, and import keys are verbatim basenames -
 * so only the documented producer shapes mark a session-level fragment.
 */
const CAPTURE_LIFECYCLE_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

/**
 * Parse one signal `session_ref` into its origin coordinates, or
 * `null` when the ref is absent, blank, fragment-less (the auto-extract
 * shape β€” no turn exists to cite), double-hashed (no producer emits
 * it), halves-empty, or `session:`-prefixed in a form neither producer
 * writes. The split is on the FIRST `#`, per the documented
 * `<key>#<fragment>` contract. A key in the capture-lifecycle writer's
 * exact forms - `session:<uuid>` or the `session:unknown` stand-in -
 * marks a hook-event fragment and resolves as `session` (session-level
 * provenance: the fragment names the hook, never a turn). Import keys
 * are verbatim basenames, so a basename that merely starts with the
 * scheme cannot be told from a lifecycle key by the ref alone: such a
 * ref yields no provenance rather than a guessed label - the
 * coordinates are never wrong, and no origin reads as no mention.
 */
export function parseSessionRef(ref: string): SessionRefOrigin | null {
  const trimmed = ref.trim();
  if (trimmed.length === 0) return null;
  const hash = trimmed.indexOf("#");
  // Bare reference: the auto-extract producer's shape, and no other
  // writer's. No fragment means no turn to cite β€” no provenance.
  if (hash < 0) return null;
  // A second `#` is a shape no producer emits; reading one would be a
  // guess about which segment is the fragment.
  if (trimmed.indexOf("#", hash + 1) >= 0) return null;
  const sessionKey = trimmed.slice(0, hash);
  const fragment = trimmed.slice(hash + 1);
  if (sessionKey.length === 0 || fragment.length === 0) return null;
  if (sessionKey.startsWith(CAPTURE_LIFECYCLE_SCHEME)) {
    const id = sessionKey.slice(CAPTURE_LIFECYCLE_SCHEME.length);
    if (id === CAPTURE_LIFECYCLE_UNKNOWN_ID || CAPTURE_LIFECYCLE_ID_RE.test(id)) {
      return Object.freeze({ sessionKey, fragment, kind: "session" });
    }
    // Neither lifecycle shape: a basename that collides with the scheme
    // (or an id no writer emits). The kind cannot be read without
    // guessing - no provenance, never a guessed label.
    return null;
  }
  return Object.freeze({ sessionKey, fragment, kind: "turn" });
}

/**
 * Evidence wikilinks are written as the exact `[[<signal id>]]` form;
 * anything else (a bare id, prose embedding a link, an aliased variant)
 * is not an evidence link this join may interpret, and yields no
 * target rather than a guessed one.
 */
const EXACT_EVIDENCE_WIKILINK_RE = /^\[\[([^[\]]+)\]\]$/;

function evidenceTarget(entry: string): string | null {
  // Inside a character class a lone `[` needs no escape, so the class
  // reads "one or more characters that are neither bracket kind".
  const match = EXACT_EVIDENCE_WIKILINK_RE.exec(entry.trim());
  if (match === null) return null;
  const target = match[1]?.trim() ?? "";
  return target.length > 0 ? target : null;
}

/**
 * Resolve one preference's origin provenance: walk `evidenced_by` in
 * order, resolve each exact evidence wikilink through `lookup`, parse
 * the signal's `session_ref`, and keep the origins that resolve β€”
 * duplicates folded into their first position. Returns `null` when
 * nothing resolves: an honestly-unresolved preference, never an empty
 * stand-in that could read as provenance.
 */
export function resolvePreferenceProvenance(
  preference: PreferenceEvidenceSource,
  lookup: SignalSessionRefLookup,
): PreferenceProvenance | null {
  const origins: SessionRefOrigin[] = [];
  const seen = new Set<string>();
  for (const entry of preference.evidenced_by) {
    const target = evidenceTarget(entry);
    if (target === null) continue;
    const ref = lookup(target);
    if (ref === undefined) continue;
    const origin = parseSessionRef(ref);
    if (origin === null) continue;
    const dedupKey = `${origin.kind}\u0000${origin.sessionKey}\u0000${origin.fragment}`;
    if (seen.has(dedupKey)) continue;
    seen.add(dedupKey);
    origins.push(origin);
  }
  if (origins.length === 0) return null;
  return Object.freeze({
    key: `pref:${preference.id}`,
    preferenceId: preference.id,
    origins: Object.freeze(origins),
  });
}