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
15.7 KB
Raw Blame
/**
 * Pre-compress injection pack (v0.20.0).
 *
 * A read-only bundle of the highest-confidence confirmed preferences plus
 * the head of `active.md`, rendered as a compact system-prompt addendum.
 * An external runtime (e.g. a host agent's pre-compression hook) can
 * inject it just before a context-compression event so the brain's
 * highest-salience constraints survive context rotation without the agent
 * having to remember to query. OSB ships only this builder and the MCP
 * tool around it; the host-runtime wiring is an out-of-scope recipe.
 *
 * It reuses the shared recall-budget primitive (the same per-entry and
 * total character caps as `brain_context_pack`) so one oversized
 * preference cannot dominate the addendum. Deterministic given the vault:
 * the only ordering inputs are confidence, creation time, and id.
 */

import { existsSync, readFileSync } from "node:fs";
import { posix } from "node:path";

import {
  activeDigestPathForRead,
  readerNarrowsActive,
  renderActiveForReader,
  type ActiveReaderOptions,
} from "./active.ts";
import { BRAIN_PREFERENCES_REL } from "./path-constants.ts";
import { brainActivePath, brainDirs } from "./paths.ts";
import { brainConfigUnreadableReport } from "./policy.ts";
import {
  collectPreferences,
  resolveOwnerScopeDelivery,
  type OwnerScopeDelivery,
} from "./preferences-collect.ts";
import { applyCharBudget, type CharBudgetDegradationMode } from "./recall-budget.ts";
import { emitContextReceipt, type ContextReceiptOptions } from "./context-receipts.ts";
import { emitGatedTelemetry } from "./continuity/emit.ts";
import {
  emitRecallTelemetry,
  recallTelemetryEnvelope,
  type RecallTelemetryOptions,
} from "./recall-telemetry.ts";
import {
  contextSafetyReport,
  guardBrainContextSnippet,
  type ContextSafetyReport,
} from "./safety/context-guard.ts";
import { BRAIN_PREFERENCE_STATUS } from "./types.ts";

/** Sentinel item id for the active-head entry inside the budget pass. */
const ACTIVE_ID = "__active__";

export interface PreCompressItem {
  readonly id: string;
  /** Preference principle text after any per-entry trim. */
  readonly principle: string;
  /** True when `principle` was truncated by `maxCharsPerMemory`. */
  readonly trimmed: boolean;
  /** Present when the surfaced principle was filtered or explicitly trusted. */
  readonly safety?: ContextSafetyReport;
}

export interface PreCompressPack {
  /** Rendered system-prompt addendum (empty string when nothing fits). */
  readonly text: string;
  readonly items: ReadonlyArray<PreCompressItem>;
  readonly activeHeadIncluded: boolean;
  readonly activeHeadSafety?: ContextSafetyReport;
  readonly receiptId?: string;
  readonly telemetryId?: string;
  readonly totalChars: number;
  /**
   * Delivery reports that are not pack content: currently only the
   * unreadable-config degradation below. Same key and same
   * absent-when-empty rule as `ContextPackReport.warnings`, so the two
   * pack builders answer "what should the caller know about this
   * result" in one shape. A healthy vault carries no key at all.
   */
  readonly warnings?: ReadonlyArray<string>;
}

export interface PreCompressOptions {
  /** Maximum number of preferences to consider (highest-confidence first). */
  readonly topK: number;
  /** Per-entry character cap (code points); <= 0 / undefined disables. */
  readonly maxCharsPerMemory?: number;
  /** Total character cap across the bundle; <= 0 / undefined disables. */
  readonly maxTotalChars?: number;
  /**
   * Per-entry trim strategy (continuity-hygiene-freshness suite):
   * `staged` degrades an over-budget entry at structural boundaries
   * instead of cutting mid-sentence. Default keeps the hard cut.
   */
  readonly degradation?: CharBudgetDegradationMode;
  /** Opt-in audit receipt for the final emitted addendum. */
  readonly receipt?: ContextReceiptOptions;
  /** Opt-in telemetry for recall coverage and gap diagnostics. */
  readonly telemetry?: RecallTelemetryOptions;
  /**
   * Owner scope for delivery isolation (context-integrity-gates, Unit
   * A). Enforced only when `integrity.owner_scope_delivery` is `fail`;
   * omitted, or under the default `off`, nothing is filtered and the
   * output is byte-identical to a vault without the gate.
   */
  readonly agentScope?: string;
  /**
   * May the caller see the record at this vault-relative path? A
   * preference it may not is absent from the top-K walk and from the
   * active head, exactly as if the file did not exist. Omitted, nothing
   * is filtered and the output is byte-identical to a build without it.
   */
  readonly readable?: (rel: string) => boolean;
  /**
   * The caller arrived below local reach: its active head is always the
   * in-memory render, never the shared file (see
   * {@link ActiveReaderOptions.restricted}).
   */
  readonly restricted?: boolean;
}

interface ConfirmedPref {
  readonly id: string;
  readonly principle: string;
  readonly confidence: number;
  readonly createdAt: string;
}

function collectConfirmed(
  vault: string,
  ownerScope: OwnerScopeDelivery,
  readable: ((rel: string) => boolean) | undefined,
): ConfirmedPref[] {
  const dir = brainDirs(vault).preferences;
  const out: ConfirmedPref[] = [];
  // Listing and parse come from the shared delivery-path walk
  // (context-integrity-gates, Unit A); the confirmed-status filter is
  // this surface's own and stays here.
  for (const { name, pref } of collectPreferences(dir, { ownerScope }).entries) {
    if (pref.status !== BRAIN_PREFERENCE_STATUS.confirmed) continue;
    if (readable !== undefined && !readable(posix.join(BRAIN_PREFERENCES_REL, name))) continue;
    out.push({
      id: pref.id,
      principle: pref.principle,
      confidence: pref.confidence_value ?? Number.NEGATIVE_INFINITY,
      createdAt: pref.created_at,
    });
  }
  return out;
}

/** The active head this caller may see, and why it may be missing. */
interface ActiveHead {
  /** Head text, or `null` when there is none to deliver. */
  readonly text: string | null;
  /** Operator-facing reason the head was withheld, or `null`. */
  readonly warning: string | null;
}

/** Nothing to deliver, nothing to report. */
const NO_ACTIVE_HEAD: ActiveHead = Object.freeze({ text: null, warning: null });

/** An active head that is present, with nothing to report about it. */
function deliveredHead(text: string): ActiveHead {
  return text.length > 0 ? Object.freeze({ text, warning: null }) : NO_ACTIVE_HEAD;
}

/**
 * The active-digest head this caller may see.
 *
 * `active.md` is ONE file shared by every agent, so under an enforcing
 * owner-scope gate the file's own bytes are the wrong answer: they carry
 * every owner's memories, and a caller at remote reach must not be
 * handed a preference it cannot read there. Such a caller gets an
 * in-memory {@link renderActiveForReader} instead, which is where the
 * ownership and reach predicates attach. Narrowing the FILE to make this read correct is what
 * `brain_context` used to do, and it made a shared write follow a
 * per-request filter (context-integrity-gates, A3).
 *
 * A caller below local reach always gets that render too, whatever is
 * withheld from it, so a stale file is never the tell that a record it
 * cannot read exists. A local caller with no enforced scope - the
 * shipped `off` default - reads the file verbatim, stamp and all.
 *
 * ## Why an unreadable config is checked here rather than caught
 *
 * The two halves of the gate compose into a failure neither designed
 * for. `loadIntegrityConfigSafe` deliberately RESOLVES on an unreadable
 * `_brain.yaml`, to its strict fallback, so the gate closes rather than
 * opens - which hands this caller an `enforcedScope`. {@link
 * renderActiveForReader} then reads the guardrail block through a loader that
 * RAISES on the same file. One bad line therefore cost a scoped agent
 * its entire pre-compaction pack while an unscoped one still got a pack.
 *
 * So the condition is a precondition of the scoped render, tested by the
 * same predicate the loader splits on, and the head is withheld with the
 * reason named. It is not a `catch`: any other failure inside
 * the reader render still propagates, and a `catch` here would re-absorb
 * exactly the silence the split removed. The one `catch` is around the
 * store-only on-demand render of the digest (no reader scoping yet): its
 * failure withholds the head with a fixed reason and the error's code.
 *
 * Withheld, never substituted. The file's bytes are not a fallback for a
 * scoped render - serving them under an enforcing gate is the leak A3
 * exists to prevent - and the strict fallback is what makes withholding
 * safe: an unreadable config can only close this gate, never open it.
 */
function readActiveHead(
  vault: string,
  enforcedScope: string | null,
  opts: Pick<PreCompressOptions, "readable" | "restricted">,
): ActiveHead {
  const reader: ActiveReaderOptions = {
    ...(enforcedScope !== null ? { agentScope: enforcedScope } : {}),
    ...(opts.readable !== undefined ? { readable: opts.readable } : {}),
    ...(opts.restricted === true ? { restricted: true } : {}),
  };
  // `Brain/active.md` on an unswitched machine; on a store-only one the
  // digest rendered on demand into the device-local cache (D14 item 7).
  let path: string;
  try {
    path = activeDigestPathForRead(vault);
  } catch (err) {
    // The on-demand render failed (an unreadable store, a store identity
    // refusal, a cache that cannot be written): withheld with the reason
    // named, like the unreadable-config branch below, never in silence.
    // The pack reaches remote callers, and a render error's message names
    // the device-local cache or store path, so only its code is reported.
    const code = (err as NodeJS.ErrnoException | undefined)?.code;
    const named = typeof code === "string" && /^[A-Z][A-Z0-9_]*$/.test(code) ? ` (${code})` : "";
    return Object.freeze({
      text: null,
      warning: `the active digest could not be rendered${named}`,
    });
  }
  // A vault whose digest was never generated has no head for an unscoped
  // reader, whatever its reach and whatever is withheld from it.
  if (enforcedScope === null && !existsSync(path)) return NO_ACTIVE_HEAD;
  if (readerNarrowsActive(vault, reader)) {
    const unreadableConfig = brainConfigUnreadableReport(vault);
    if (unreadableConfig !== null) return Object.freeze({ text: null, warning: unreadableConfig });
    return deliveredHead(renderActiveForReader(vault, reader).document.trim());
  }
  try {
    return deliveredHead(readFileSync(path, "utf8").trim());
  } catch {
    return NO_ACTIVE_HEAD;
  }
}

/**
 * Build the pre-compress addendum for a vault. Confirmed preferences are
 * ranked by confidence (desc), then recency (desc), then id; the top
 * `topK` plus the active head are bounded by the shared char budget.
 */
export function buildPreCompressPack(vault: string, opts: PreCompressOptions): PreCompressPack {
  const startedAtMs = Date.now();
  // One gate verdict for the whole build. The preference walk and the
  // active head must agree on it, and resolving it twice also read
  // `_brain.yaml` twice per pack.
  const ownerScope = resolveOwnerScopeDelivery(vault, opts.agentScope);
  const ranked = collectConfirmed(vault, ownerScope, opts.readable).toSorted((a, b) => {
    if (b.confidence !== a.confidence) return b.confidence - a.confidence;
    if (a.createdAt !== b.createdAt) return a.createdAt < b.createdAt ? 1 : -1;
    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
  });
  const top = ranked.slice(0, Math.max(0, opts.topK));

  const activeHead = readActiveHead(vault, ownerScope.enforcedScope, opts);
  const safetyById = new Map<string, ContextSafetyReport>();
  const entries: Array<{ item: string; text: string }> = [];
  if (activeHead.text !== null) {
    const guarded = guardBrainContextSnippet(activeHead.text, {
      source: { id: ACTIVE_ID, path: brainActivePath(vault) },
    });
    const safety = contextSafetyReport(guarded);
    if (safety) safetyById.set(ACTIVE_ID, safety);
    entries.push({ item: ACTIVE_ID, text: guarded.safeText });
  }
  for (const p of top) {
    const guarded = guardBrainContextSnippet(p.principle, {
      source: { id: p.id },
    });
    const safety = contextSafetyReport(guarded);
    if (safety) safetyById.set(p.id, safety);
    entries.push({ item: p.id, text: guarded.safeText });
  }

  const budgeted = applyCharBudget(entries, {
    maxCharsPerEntry: opts.maxCharsPerMemory,
    maxTotalChars: opts.maxTotalChars,
    ...(opts.degradation !== undefined ? { degradation: opts.degradation } : {}),
  });

  let activeText: string | null = null;
  const items: PreCompressItem[] = [];
  for (const kept of budgeted.kept) {
    if (kept.item === ACTIVE_ID) {
      activeText = kept.text;
      continue;
    }
    const safety = safetyById.get(kept.item);
    items.push({
      id: kept.item,
      principle: kept.text,
      trimmed: kept.trimmed,
      ...(safety ? { safety } : {}),
    });
  }

  const sections: string[] = [];
  if (activeText !== null) sections.push(`# Active brain context\n\n${activeText}`);
  if (items.length > 0) {
    sections.push(["Preferences:", ...items.map((i) => `- ${i.principle}`)].join("\n"));
  }

  const text = sections.join("\n\n");
  // Gated emissions route through the lazy emit kernel (t_5d7aa7c5):
  // option absent means the thunk never runs; a broken continuity
  // store can no longer fail the pack (fail-open).
  const receipt = emitGatedTelemetry(opts.receipt, (receiptOptions) =>
    emitContextReceipt(vault, {
      options: receiptOptions,
      items: [
        ...(activeText !== null
          ? [
              {
                id: ACTIVE_ID,
                path: brainActivePath(vault),
                text: activeText,
              },
            ]
          : []),
        ...items.map((item) => ({
          id: item.id,
          text: item.principle,
          trimmed: item.trimmed,
          safetyFiltered: item.safety?.filtered,
        })),
      ],
      finalText: text,
      budget: {
        top_k: opts.topK,
        ...(opts.maxCharsPerMemory !== undefined
          ? { max_chars_per_memory: opts.maxCharsPerMemory }
          : {}),
        ...(opts.maxTotalChars !== undefined ? { max_total_chars: opts.maxTotalChars } : {}),
      },
      extra: { active_head_included: activeText !== null },
    }),
  );

  const telemetry = emitGatedTelemetry(opts.telemetry, (telemetryOptions) =>
    emitRecallTelemetry(vault, {
      ...recallTelemetryEnvelope(telemetryOptions),
      mode: "pre_compress",
      status: activeText !== null || items.length > 0 ? "ok" : "empty",
      durationMs: Date.now() - startedAtMs,
      resultCount: items.length + (activeText !== null ? 1 : 0),
      topArtifacts: [
        ...(activeText !== null ? [{ id: ACTIVE_ID, path: brainActivePath(vault) }] : []),
        ...items.slice(0, 10).map((item) => ({ id: item.id })),
      ],
      gaps: activeText === null && items.length === 0 ? ["no_matching_context"] : [],
      metadata: {
        ...telemetryOptions.metadata,
        top_k: opts.topK,
        total_chars: budgeted.totalChars,
        active_head_included: activeText !== null,
        ...(opts.maxCharsPerMemory !== undefined
          ? { max_chars_per_memory: opts.maxCharsPerMemory }
          : {}),
        ...(opts.maxTotalChars !== undefined ? { max_total_chars: opts.maxTotalChars } : {}),
        ...(receipt ? { receipt_id: receipt.id } : {}),
      },
    }),
  );

  return Object.freeze({
    text,
    items: Object.freeze(items),
    activeHeadIncluded: activeText !== null,
    ...(safetyById.get(ACTIVE_ID) ? { activeHeadSafety: safetyById.get(ACTIVE_ID) } : {}),
    ...(receipt ? { receiptId: receipt.id } : {}),
    ...(telemetry ? { telemetryId: telemetry.id } : {}),
    totalChars: budgeted.totalChars,
    ...(activeHead.warning !== null ? { warnings: Object.freeze([activeHead.warning]) } : {}),
  });
}