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
7.7 KB
Raw Blame
/**
 * Session-end observed-use verdict per injected memory (Retrieval &
 * Ranking Quality, t_65588d8b).
 *
 * At session end each memory that was injected this session is classified
 * as USED / IGNORED / CONTRADICTED, persisted as a `recall_observed_use`
 * continuity record, and folded into an observed-reuse rate per artifact
 * that recall ranking prefers over predicted importance.
 *
 * NO-LLM KERNEL INVARIANT. The kernel never calls a model to read the
 * transcript. A verdict is either:
 *   - computed DETERMINISTICALLY here ({@link classifyObservedUse}) by
 *     matching an injected memory's distinctive tokens against later
 *     transcript turns, with CONTRADICTED derived from a structural stance
 *     flip via the shared `deriveNoteStance` primitive (no vocabulary), or
 *   - supplied ALREADY-STRUCTURED by the host via the MCP write tool,
 *     mirroring `brain_apply_evidence`.
 * The kernel only stores and aggregates.
 */

import { appendContinuityRecord, listContinuityRecords } from "./continuity/store.ts";
import type { ContinuityRecord } from "./continuity/types.ts";
import { DEFAULT_NEGATION_MARKERS, deriveNoteStance } from "./health/contradiction.ts";

export const OBSERVED_USE_VERDICTS = ["USED", "IGNORED", "CONTRADICTED"] as const;
export type ObservedUseVerdict = (typeof OBSERVED_USE_VERDICTS)[number];

export function isObservedUseVerdict(value: unknown): value is ObservedUseVerdict {
  return value === "USED" || value === "IGNORED" || value === "CONTRADICTED";
}

/** One injected memory's observed-use verdict. */
export interface ObservedUseEntry {
  /** Stable memory id (e.g. "docId:chunkId" or a note id). */
  readonly id: string;
  /** Vault-relative path, when known (the ranking join key prefers it). */
  readonly path?: string;
  readonly verdict: ObservedUseVerdict;
}

export interface ObservedUseInput {
  readonly createdAt?: string;
  readonly host: string;
  readonly sessionId?: string;
  readonly turnId?: string;
  readonly entries: ReadonlyArray<ObservedUseEntry>;
}

/** An injected memory to classify against the transcript. */
export interface InjectedMemory {
  readonly id: string;
  readonly path?: string;
  readonly content: string;
}

const TOKEN_RE = /[\p{L}\p{N}]{2,}/gu;
const MIN_SHARED_TOKENS = 2;

function tokenSet(text: string): Set<string> {
  const out = new Set<string>();
  for (const m of text.toLowerCase().matchAll(TOKEN_RE)) out.add(m[0]);
  return out;
}

function sharedCount(a: ReadonlySet<string>, b: ReadonlySet<string>): number {
  let n = 0;
  const [small, large] = a.size <= b.size ? [a, b] : [b, a];
  for (const t of small) if (large.has(t)) n++;
  return n;
}

/**
 * Deterministically classify each injected memory against the session
 * transcript turns. A memory is USED when a later turn echoes at least
 * {@link MIN_SHARED_TOKENS} of its distinctive tokens; CONTRADICTED when
 * such an overlapping turn takes the opposite structural stance (a
 * `deriveNoteStance` sign flip); IGNORED otherwise. No model, no
 * per-language vocabulary beyond the shared structural negation markers.
 */
export function classifyObservedUse(
  injected: ReadonlyArray<InjectedMemory>,
  transcriptTurns: ReadonlyArray<string>,
): ObservedUseEntry[] {
  const turns = transcriptTurns.map((t) => tokenSet(t));
  return injected.map((mem) => {
    const memTokens = tokenSet(mem.content);
    const memStance = deriveNoteStance(memTokens, DEFAULT_NEGATION_MARKERS);
    let verdict: ObservedUseVerdict = "IGNORED";
    for (const turn of turns) {
      if (sharedCount(memTokens, turn) < MIN_SHARED_TOKENS) continue;
      const turnStance = deriveNoteStance(turn, DEFAULT_NEGATION_MARKERS);
      if (turnStance !== memStance) {
        verdict = "CONTRADICTED";
        break; // a contradiction outranks a plain reuse.
      }
      verdict = "USED";
    }
    return {
      id: mem.id,
      ...(mem.path ? { path: mem.path } : {}),
      verdict,
    };
  });
}

/**
 * Persist a session's observed-use verdicts as one continuity record.
 * `sourceRefs` point at the injected artifacts so a fold can join by id or
 * path. Returns the appended record.
 */
export function emitObservedUse(vault: string, input: ObservedUseInput): ContinuityRecord {
  const createdAt = input.createdAt ?? new Date().toISOString();
  const entries = [...input.entries];
  return appendContinuityRecord(vault, {
    kind: "recall_observed_use",
    createdAt,
    sourceRefs: entries.map((e) => ({ id: e.id, ...(e.path ? { path: e.path } : {}) })),
    payload: {
      host: input.host,
      ...(input.sessionId ? { session_id: input.sessionId } : {}),
      ...(input.turnId ? { turn_id: input.turnId } : {}),
      entries: entries.map((e) => ({
        id: e.id,
        ...(e.path ? { path: e.path } : {}),
        verdict: e.verdict,
      })),
    },
  });
}

/** Aggregated observed-use for one artifact. */
export interface ObservedReuse {
  readonly used: number;
  readonly ignored: number;
  readonly contradicted: number;
  readonly total: number;
  /**
   * Ranking signal in [0, 1]: `(used - contradicted) / total`, clamped.
   * Contradictions demote; a purely-ignored memory scores 0.
   */
  readonly score: number;
}

/**
 * Narrows {@link observedReuseRates} from its lifetime default to one
 * session or one window. Every field is optional and an empty filter is
 * byte-identical to the unfiltered lifetime fold, so no existing caller
 * changes behaviour.
 */
export interface ObservedReuseFilter {
  /** Only records carrying this `session_id`. */
  readonly sessionId?: string;
  /** Inclusive lower bound on `createdAt` (canonical UTC ISO-8601). */
  readonly since?: string;
  /** Inclusive upper bound on `createdAt` (canonical UTC ISO-8601). */
  readonly until?: string;
}

/**
 * Fold `recall_observed_use` records into a per-artifact reuse map,
 * keyed by `path` when present else `id`. Order-insensitive.
 *
 * Unfiltered this is the lifetime rate ranking consumes. A filter makes
 * the same fold answerable for one session or one window, which is what
 * a session-scoped retrieval report needs: a lifetime rate cannot say
 * whether the material injected THIS session was used.
 */
export function observedReuseRates(
  vault: string | null,
  filter: ObservedReuseFilter = {},
): Map<string, ObservedReuse> {
  const acc = new Map<string, { used: number; ignored: number; contradicted: number }>();
  for (const record of listContinuityRecords(vault, {
    kind: "recall_observed_use",
    ...(filter.since !== undefined ? { since: filter.since } : {}),
    ...(filter.until !== undefined ? { until: filter.until } : {}),
  })) {
    if (filter.sessionId !== undefined && record.payload["session_id"] !== filter.sessionId) {
      continue;
    }
    const entries = record.payload["entries"];
    if (!Array.isArray(entries)) continue;
    for (const raw of entries) {
      if (raw === null || typeof raw !== "object") continue;
      const e = raw as Record<string, unknown>;
      const verdict = e["verdict"];
      if (!isObservedUseVerdict(verdict)) continue;
      const key =
        typeof e["path"] === "string" && e["path"] !== ""
          ? (e["path"] as string)
          : typeof e["id"] === "string"
            ? (e["id"] as string)
            : null;
      if (key === null) continue;
      const cur = acc.get(key) ?? { used: 0, ignored: 0, contradicted: 0 };
      if (verdict === "USED") cur.used++;
      else if (verdict === "IGNORED") cur.ignored++;
      else cur.contradicted++;
      acc.set(key, cur);
    }
  }
  const out = new Map<string, ObservedReuse>();
  for (const [key, c] of acc) {
    const total = c.used + c.ignored + c.contradicted;
    const score = total > 0 ? Math.max(0, Math.min(1, (c.used - c.contradicted) / total)) : 0;
    out.set(key, { used: c.used, ignored: c.ignored, contradicted: c.contradicted, total, score });
  }
  return out;
}