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
16.0 KB
Raw Blame
/**
 * A4 (t_f79b4fe0): write-time conflict advisory seam.
 *
 * Two advisories live here, both built to the same shape: computed
 * AROUND an operator-facing feedback write, never gating it, returned as
 * a structured value the CLI and MCP surfaces render, and recorded under
 * its own log-event kind so what fired stays countable.
 *
 *   - {@link adviseIncomingFeedback} - the incoming principle resembles a
 *     confirmed same-scope preference (t_f79b4fe0).
 *   - {@link adviseUnroutableCapture} - the capture resolved NO scope, so
 *     it lands in the one bucket scoped recall never reaches
 *     (signals-that-survive, unit 4 / t_75597bb9).
 *
 * When an operator records a feedback signal, this seam compares the
 * incoming principle against confirmed same-scope preferences and, when a
 * near-duplicate is found, returns a non-blocking advisory naming the
 * resembling preference ids. The advisory is surfaced in the feedback
 * response / CLI output and logged under a dedicated event kind.
 *
 * Two invariants, straight from the design doc:
 *
 *   - The write ALWAYS proceeds. This helper runs AROUND the write and
 *     never gates it. Advisory computation is best-effort: a failure
 *     (e.g. an unreadable preferences dir) degrades to a visible stderr
 *     warning and a `null` result, never a swallowed exception and never a
 *     failed feedback call.
 *   - The advisory fires only on the operator-facing feedback path, NOT
 *     inside `routeExtractedFacts`, so the extracted-fact path and the
 *     feedback path never double-fire on a single write.
 *
 * Only the incoming signal's scope bucket is read (confirmed preferences
 * whose scope matches the incoming scope; an unscoped signal compares
 * against the unscoped bucket), mirroring `detectContradictions`.
 */

import { existsSync, readdirSync } from "node:fs";
import { join } from "node:path";

import { vaultRelative } from "../path-safety.ts";
import { ROUTE_STAGE, timeStageSync } from "../route-scope.ts";

import { adviseOnIncoming, type PreferenceForContradiction } from "./health/contradiction.ts";
import { appendLogEvent } from "./log.ts";
import { nextCommandField, requireNextStep, type NextCommandField } from "./next-step.ts";
import { brainDirsOf } from "./paths.ts";
import {
  memoryFromStore,
  signalPageRaw,
  type StoreMemoryPage,
  storePagesIn,
} from "./memory-pages.ts";
import { parsePreference, parsePreferenceMeta } from "./preference.ts";
import { parseSignal, parseStoreSignal } from "./signal.ts";
import { isoSecond } from "./time.ts";
import { BRAIN_LOG_EVENT_KIND, BRAIN_PREFERENCE_STATUS } from "./types.ts";

/** Extension every Brain corpus document on disk carries. */
const MARKDOWN_EXT = ".md";

/** Bucket key standing for "carries no scope", shared with `adviseOnIncoming`. */
const UNSCOPED_BUCKET = "";

/** One resembling preference: its id and the incoming-vs-confirmed jaccard. */
export interface WriteConflictEvidence {
  readonly pref_id: string;
  readonly jaccard: number;
}

/**
 * The advisory surfaced to the feedback response / CLI output. Present
 * only when at least one confirmed same-scope preference clears the
 * similarity threshold.
 */
export interface WriteConflictAdvisory {
  /** The scope bucket compared against; `null` for the unscoped bucket. */
  readonly scope: string | null;
  /** Non-empty, sorted by descending similarity then id. */
  readonly conflicts: ReadonlyArray<WriteConflictEvidence>;
}

export interface AdviseIncomingFeedbackParams {
  /** The incoming feedback principle to compare. */
  readonly principle: string;
  /** The signal's effective scope (already resolved against the default). */
  readonly scope?: string;
  /** Agent identity stamped on the advisory log event. */
  readonly agent: string;
  /** Injected clock for a deterministic log timestamp. Defaults to now. */
  readonly now?: Date;
  /**
   * The vault-relative paths the caller may read. A preference it may
   * not read is left out before scoring, so the advisory never names it.
   * Absent, every preference counts.
   */
  readonly readable?: ReadablePath;
}

/** A vault-relative path test bound to one caller. */
type ReadablePath = (rel: string) => boolean;

/** The Markdown documents in `dir`, or nothing when it does not exist. */
function markdownNames(dir: string): ReadonlyArray<string> {
  if (!existsSync(dir)) return [];
  return readdirSync(dir).filter((name) => name.endsWith(MARKDOWN_EXT));
}

/**
 * The Markdown documents in `dir` the caller may read: a document it may
 * not read is passed over as if it were not there.
 */
function readableMarkdownNames(
  vault: string,
  dir: string,
  readable: ReadablePath | undefined,
): ReadonlyArray<string> {
  const names = markdownNames(dir);
  if (readable === undefined) return names;
  return names.filter((name) => readable(vaultRelative(join(dir, name), vault)));
}

/**
 * The Markdown documents of `dir` the caller may read, each with its page
 * when it comes from the store: on a store-only machine (task 2.10) the
 * fold's records whose page sat in `dir`, on an unswitched one the files.
 */
function readableMemoryFiles(
  vault: string | null,
  dir: string,
  readable: ReadablePath | undefined,
): ReadonlyArray<{ readonly path: string; readonly page: StoreMemoryPage | null }> {
  if (vault === null || memoryFromStore(vault)) {
    return storePagesIn(vault, dir)
      .filter((page) => readable === undefined || readable(page.rel))
      .map((page) => ({ path: page.path, page }));
  }
  return readableMarkdownNames(vault, dir, readable).map((name) => ({
    path: join(dir, name),
    page: null,
  }));
}

/**
 * Every confirmed preference in the vault. A corrupt / mis-foldered
 * preference file is skipped (that is the doctor's concern, not the write
 * path's).
 */
function loadConfirmedPrefs(
  vault: string | null,
  readable: ReadablePath | undefined,
): PreferenceForContradiction[] {
  const dir = brainDirsOf(vault).preferences;
  const out: PreferenceForContradiction[] = [];
  for (const { path, page } of readableMemoryFiles(vault, dir, readable)) {
    let pref;
    try {
      pref = page === null ? parsePreference(path) : parsePreferenceMeta(page.meta, path);
    } catch {
      continue;
    }
    if (pref.status !== BRAIN_PREFERENCE_STATUS.confirmed) continue;
    out.push(pref);
  }
  return out;
}

/**
 * Load the confirmed preferences in the incoming signal's scope bucket.
 * Scope-bucket loading only: preferences in a different scope (and every
 * non-confirmed preference) are dropped here rather than compared.
 */
function loadConfirmedScopePrefs(
  vault: string | null,
  scope: string | undefined,
  readable: ReadablePath | undefined,
): PreferenceForContradiction[] {
  const bucketKey = scope ?? UNSCOPED_BUCKET;
  return loadConfirmedPrefs(vault, readable).filter(
    (pref) => (pref.scope ?? UNSCOPED_BUCKET) === bucketKey,
  );
}

/**
 * Compute (and log) the write-time conflict advisory for an incoming
 * feedback signal. Returns the advisory when a confirmed same-scope
 * preference resembles the incoming principle, otherwise `null`.
 *
 * Never throws: any failure is reported as a stderr warning and returns
 * `null`, so the surrounding feedback write is never affected.
 */
export function adviseIncomingFeedback(
  vault: string | null,
  params: AdviseIncomingFeedbackParams,
): WriteConflictAdvisory | null {
  try {
    // Loading the comparison pool and scoring it is the near-duplicate
    // lookup of the feedback route; the log append below is its own stage.
    const advisory = timeStageSync(ROUTE_STAGE.nearDuplicateLookup, () =>
      adviseOnIncoming(
        params.principle,
        params.scope,
        loadConfirmedScopePrefs(vault, params.scope, params.readable),
      ),
    );
    if (advisory === null) return null;

    const result: WriteConflictAdvisory = {
      scope: advisory.scope,
      conflicts: advisory.conflicts.map((c) => ({ pref_id: c.prefId, jaccard: c.jaccard })),
    };

    try {
      appendLogEvent(
        vault,
        {
          timestamp: isoSecond(params.now ?? new Date()),
          eventType: BRAIN_LOG_EVENT_KIND.writeConflictAdvisory,
          agent: params.agent,
          body: {
            scope: advisory.scope ?? "(unscoped)",
            // One bullet per resembling preference: wikilink + similarity, so
            // the audit row is both human-readable and grep-friendly.
            conflicts: result.conflicts.map(
              (c) => `[[${c.pref_id}]] jaccard=${c.jaccard.toFixed(3)}`,
            ),
            agent: params.agent,
          },
        },
        { failOpen: true },
      );
    } catch (err) {
      process.stderr.write(
        `warning: append write-conflict-advisory log failed: ${(err as Error).message}\n`,
      );
    }

    return result;
  } catch (err) {
    // Advisory computation is best-effort and NEVER blocks the write.
    process.stderr.write(
      `warning: write-conflict advisory computation failed: ${(err as Error).message}\n`,
    );
    return null;
  }
}

// ----- Unroutable-capture routing hint (unit 4, t_75597bb9) ----------------

/**
 * The routing signal a capture can be missing. Written once: it is the
 * signal frontmatter field, the flag name the exit command carries, and
 * the value the hint reports as absent.
 */
export const ROUTING_SIGNAL_FIELD = "scope";

/**
 * Registry code the routing hint's forward pointer resolves through. The
 * hint NAMES no command itself - the surfaces resolve this code, so the
 * exit is the registry's structural CLI string on every stream.
 */
export const CAPTURE_ROUTING_HINT_CODE = "capture-scope-absent";

/**
 * Resolved at module scope on purpose. This hint's whole value is telling
 * an operator how to route the capture, so an unregistered code is
 * registry drift rather than a case to handle: it fails at import instead
 * of inside the advisory it was meant to explain (see `next-step.ts`).
 */
const CAPTURE_ROUTING_HINT_STEP = requireNextStep(CAPTURE_ROUTING_HINT_CODE);

/** One scope slug the vault already uses, with the documents carrying it. */
export interface ScopeCandidate {
  readonly scope: string;
  /** Documents observed with this scope: its document frequency. */
  readonly documents: number;
}

/**
 * The routing hint surfaced to the feedback response / CLI output.
 * Present only when the capture resolved no scope AND the vault holds a
 * scope corpus to suggest from.
 */
export interface CaptureRoutingHint {
  /** The routing signal the capture lacked. */
  readonly missing_signal: string;
  /** Diagnostic code the surfaces resolve the forward pointer through. */
  readonly code: string;
  /** Non-empty, ranked by document frequency then slug. */
  readonly candidates: ReadonlyArray<ScopeCandidate>;
}

/**
 * The additive JSON key both machine-readable surfaces carry the hint
 * in, plus its forward pointer already resolved.
 *
 * Named and composed once for the same reason `NEXT_COMMAND_KEY` is: the
 * CLI `--json` renderer and its MCP twin must not drift on a spelling or
 * on which fields ride along. A consumer that learns the shape from one
 * surface reads it on the other.
 */
export const CAPTURE_ROUTING_HINT_KEY = "routing_hint";

export type CaptureRoutingHintField = {
  readonly [CAPTURE_ROUTING_HINT_KEY]?: CaptureRoutingHint & NextCommandField;
};

/** Absent case: no hint contributes no key whatsoever. */
const NO_CAPTURE_ROUTING_HINT: CaptureRoutingHintField = Object.freeze({});

/**
 * Resolve a hint into the object to spread onto a machine-readable
 * response. `null` yields the empty object, so the key is ABSENT rather
 * than present-and-null.
 */
export function captureRoutingHintField(hint: CaptureRoutingHint | null): CaptureRoutingHintField {
  if (hint === null) return NO_CAPTURE_ROUTING_HINT;
  return Object.freeze({
    [CAPTURE_ROUTING_HINT_KEY]: Object.freeze({ ...hint, ...nextCommandField(hint.code) }),
  });
}

export interface AdviseUnroutableCaptureParams {
  /**
   * The capture's effective scope (already resolved against
   * `feedback.default_scope`). Absent / blank is the unroutable case.
   */
  readonly scope?: string;
  /** Agent identity stamped on the hint log event. */
  readonly agent: string;
  /** Injected clock for a deterministic log timestamp. Defaults to now. */
  readonly now?: Date;
  /**
   * The vault-relative paths the caller may read. A preference or signal
   * it may not read adds no document to any scope. Absent, every
   * document counts.
   */
  readonly readable?: ReadablePath;
}

/**
 * Document frequency of every scope slug the vault declares.
 *
 * Two sources, both frontmatter: confirmed preferences (the rules scoped
 * recall actually reaches) and the OPEN signal inbox. The inbox is what
 * "recent" means structurally here - `inbox/processed/` is the archive
 * the dream pass has already consumed - so recency needs no window
 * constant and no clock.
 *
 * A corrupt signal is skipped, exactly as the conflict advisory skips a
 * corrupt preference - but the skip is REPORTED. Its scope is precisely
 * what could not be read, so it cannot be counted; leaving it silent
 * would change a ranking the operator reads with nothing to explain why.
 */
function countScopeDocuments(
  vault: string | null,
  readable: ReadablePath | undefined,
): ReadonlyMap<string, number> {
  const counts = new Map<string, number>();
  const tally = (scope: string | undefined): void => {
    const slug = scope?.trim();
    if (!slug) return;
    counts.set(slug, (counts.get(slug) ?? 0) + 1);
  };
  for (const pref of loadConfirmedPrefs(vault, readable)) tally(pref.scope);
  const inbox = brainDirsOf(vault).inbox;
  for (const { path, page } of readableMemoryFiles(vault, inbox, readable)) {
    try {
      tally(
        (page === null ? parseSignal(path) : parseStoreSignal(path, page.meta, signalPageRaw(page)))
          .scope,
      );
    } catch (err) {
      process.stderr.write(
        `warning: capture routing hint skipped unreadable signal ${path}: ${
          (err as Error).message
        }\n`,
      );
    }
  }
  return counts;
}

/**
 * Compute the routing hint for a capture that resolved no scope. Returns
 * `null` when the capture IS routable, and when the vault has no scope
 * corpus to suggest from - an empty candidate list would be prose that
 * names nothing, which is the dead end this unit removes rather than adds.
 *
 * Never throws: any failure is reported as a stderr warning and returns
 * `null`, so the surrounding feedback write is never affected.
 */
export function adviseUnroutableCapture(
  vault: string | null,
  params: AdviseUnroutableCaptureParams,
): CaptureRoutingHint | null {
  if (params.scope?.trim()) return null;
  try {
    const candidates = [...countScopeDocuments(vault, params.readable)]
      .map(([scope, documents]) => Object.freeze({ scope, documents }))
      .toSorted((a, b) => b.documents - a.documents || a.scope.localeCompare(b.scope));
    if (candidates.length === 0) return null;

    const result: CaptureRoutingHint = Object.freeze({
      missing_signal: ROUTING_SIGNAL_FIELD,
      code: CAPTURE_ROUTING_HINT_STEP.code,
      candidates: Object.freeze(candidates),
    });

    try {
      appendLogEvent(
        vault,
        {
          timestamp: isoSecond(params.now ?? new Date()),
          eventType: BRAIN_LOG_EVENT_KIND.captureRoutingHint,
          agent: params.agent,
          body: {
            missing_signal: result.missing_signal,
            // One bullet per eligible scope: slug + the document frequency
            // that ranked it, so the rate of unrouted captures AND what
            // they could have been routed to are both countable later.
            candidates: result.candidates.map((c) => `${c.scope} documents=${c.documents}`),
            agent: params.agent,
          },
        },
        { failOpen: true },
      );
    } catch (err) {
      process.stderr.write(
        `warning: append capture-routing-hint log failed: ${(err as Error).message}\n`,
      );
    }

    return result;
  } catch (err) {
    // Hint computation is best-effort and NEVER blocks the write.
    process.stderr.write(
      `warning: capture routing hint computation failed: ${(err as Error).message}\n`,
    );
    return null;
  }
}