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
6.2 KB
Raw Blame
/**
 * Derived-fact synthesis with premise provenance (Knowledge Provenance suite).
 *
 * A derived fact is a second-order conclusion ("because A and B, therefore C")
 * the calling agent reasons out from existing premise preferences. OSB is
 * provider-agnostic and runs no model: the agent supplies the conclusion and
 * names its premises; OSB owns the deterministic half - it validates that each
 * premise preference exists, then commits the derived fact as an unconfirmed
 * preference carrying a `deduced`/`inferred` provenance level and premise
 * wikilinks in `evidenced_by`.
 *
 * Recall trusts an operator-stated rule above a machine-derived one; the
 * provenance level is what makes that ordering possible (see
 * provenance/provenance.ts and the recall trust-ordering helper).
 */

import { vaultRelative } from "../path-safety.ts";
import { loadBrainConfig, DEFAULT_BRAIN_CONFIG } from "./policy.ts";
import { memoryPageExists } from "./memory-pages.ts";
import { preferencePath } from "./paths.ts";
import { writePreference } from "./preference.ts";
import { DERIVED_FACT_SHAPE, DERIVED_FACT_SURFACE, assertResponseShape } from "./response-shape.ts";
import { isoSecond } from "./time.ts";
import { asProvenanceLevel, type ProvenanceLevel } from "./provenance/provenance.ts";

export interface DeriveFactInput {
  readonly slug: string;
  readonly topic: string;
  readonly principle: string;
  /** Premise preference ids (`pref-<slug>` or bare `<slug>`), at least one. */
  readonly premises: readonly string[];
  /** Trust level of the derivation: `deduced` (entailed) or `inferred` (pattern). */
  readonly level: ProvenanceLevel;
}

export interface DeriveFactOptions {
  readonly now: Date;
  /**
   * Plugin config the writing agent's identity is resolved from when the
   * ownership gate stamps the new preference. Absent falls back to the
   * default config discovery; a surface running against a non-default
   * config passes its own.
   */
  readonly configPath?: string;
  /**
   * The vault-relative paths the caller may read. A premise preference it
   * may not read is refused exactly as a missing one is, before anything
   * is written. Absent, every preference counts.
   */
  readonly readable?: (rel: string) => boolean;
}

export interface DeriveFactResult {
  readonly id: string;
}

/** A derived-fact request failed validation; nothing was written. */
export class DeriveFactError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "DeriveFactError";
  }
}

/**
 * Narrow an agent-supplied level to a derivation level. Shared by the payload
 * ingress and {@link deriveFact} so the rejection reads identically wherever
 * an unusable level arrives.
 */
function requireDerivationLevel(raw: unknown): ProvenanceLevel {
  const level = asProvenanceLevel(raw);
  if (level === null || level === "stated") {
    throw new DeriveFactError(
      `a derived fact must be 'deduced' or 'inferred', not ${JSON.stringify(raw)}`,
    );
  }
  return level;
}

/**
 * Ingress of the agent-authored derived-fact payload. The payload is checked
 * against the frozen derived-fact shape BEFORE any field is read, so a
 * structurally wrong premise list is refused by path rather than silently
 * stringified. A violation throws `ResponseShapeError` and nothing is written.
 */
export function parseDeriveFactInput(payload: unknown): DeriveFactInput {
  assertResponseShape(DERIVED_FACT_SURFACE, DERIVED_FACT_SHAPE, payload);
  const rec = payload as Record<string, unknown>;
  return {
    slug: rec["slug"] as string,
    topic: rec["topic"] as string,
    principle: rec["principle"] as string,
    premises: Object.freeze([...(rec["premises"] as ReadonlyArray<string>)]),
    level: requireDerivationLevel(rec["level"]),
  };
}

/** Strip a leading `pref-` so a premise can be given as an id or a bare slug. */
function premiseSlug(premise: string): string {
  const trimmed = premise.trim();
  return trimmed.startsWith("pref-") ? trimmed.slice("pref-".length) : trimmed;
}

function addDays(date: Date, days: number): Date {
  const next = new Date(date.getTime());
  next.setUTCDate(next.getUTCDate() + days);
  return next;
}

function unconfirmedWindowDays(vault: string): number {
  try {
    return loadBrainConfig(vault).dream.unconfirmed_window_days;
  } catch {
    return DEFAULT_BRAIN_CONFIG.dream.unconfirmed_window_days;
  }
}

/**
 * Commit a derived fact. Validates the level is a derivation (not `stated`)
 * and that every premise preference exists, then writes an unconfirmed
 * preference with the provenance level and premise wikilinks. Throws
 * {@link DeriveFactError} with no write on any validation failure.
 */
export function deriveFact(
  vault: string,
  input: DeriveFactInput,
  opts: DeriveFactOptions,
): DeriveFactResult {
  const level = requireDerivationLevel(input.level);
  if (!input.slug.trim()) throw new DeriveFactError("derived fact missing slug");
  if (!input.topic.trim()) throw new DeriveFactError("derived fact missing topic");
  if (!input.principle.trim()) throw new DeriveFactError("derived fact missing principle");
  if (input.premises.length === 0) {
    throw new DeriveFactError("a derived fact must cite at least one premise");
  }

  const evidencedBy: string[] = [];
  for (const premise of input.premises) {
    const slug = premiseSlug(premise);
    if (!slug) throw new DeriveFactError("premise id must not be empty");
    const premisePath = preferencePath(vault, slug);
    if (
      !memoryPageExists(vault, vaultRelative(premisePath, vault)) ||
      (opts.readable !== undefined && !opts.readable(vaultRelative(premisePath, vault)))
    ) {
      throw new DeriveFactError(`premise preference not found: ${JSON.stringify(premise)}`);
    }
    evidencedBy.push(`[[pref-${slug}]]`);
  }

  const now = opts.now;
  writePreference(
    vault,
    {
      slug: input.slug,
      topic: input.topic,
      principle: input.principle,
      created_at: isoSecond(now),
      unconfirmed_until: isoSecond(addDays(now, unconfirmedWindowDays(vault))),
      status: "unconfirmed",
      evidenced_by: evidencedBy,
      provenance: level,
    },
    opts.configPath !== undefined ? { configPath: opts.configPath } : {},
  );

  return { id: `pref-${input.slug.trim()}` };
}