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.3 KB
Raw Blame
/**
 * Destinations for the two `@osb` marker kinds that materialise a Brain
 * artifact directly: `fact` and `skill` (signals-that-survive, unit 7).
 *
 * Both destinations already carry a review gate, so this module adds
 * none of its own:
 *
 *   - a `fact` marker goes through `deriveFact`, which validates every
 *     premise against the preferences on disk and commits the
 *     conclusion as an UNCONFIRMED preference. The dream pass is what
 *     later confirms or expires it. An unresolvable premise throws
 *     {@link DeriveFactError} and nothing is written - never a partial
 *     write, never a silent drop.
 *   - a `skill` marker goes through `draftDeclaredSkillProposal`, which
 *     writes into the PENDING proposal queue only. `acceptSkillProposal`
 *     remains the human step that promotes it.
 *
 * The module owns exactly the translation between the marker's fields
 * and each writer's input - the derived slug, the source reference -
 * and delegates every validation to the writer that owns the rule.
 *
 * {@link previewCaptureMarker} is the same walk with the write removed,
 * for `scan-inline --dry-run`: same input, same identity, same outcome
 * vocabulary, nothing touched.
 */

import { slugify } from "../vault.ts";
import {
  DeriveFactError,
  deriveFact,
  parseDeriveFactInput,
  type DeriveFactInput,
} from "./derived-fact.ts";
import {
  isFactMarker,
  isSkillMarker,
  type FactMarker,
  type MarkerKind,
  type ParsedMarker,
  type SkillMarker,
} from "./inline.ts";
import { memoryPageExists } from "./memory-pages.ts";
import { preferencePath, vaultRelative } from "./paths.ts";
import {
  draftDeclaredSkillProposal,
  previewDeclaredSkillProposal,
  type DeclaredSkillProposalInput,
  type DeclaredSkillProposalResult,
} from "./skill-proposals.ts";

/**
 * The marker kinds this module has a destination for. Callers gate on
 * this set and then call {@link routeCaptureMarker}; the two stay in
 * step because a kind in the set with no route is a hard error rather
 * than a skipped marker.
 */
export const ROUTED_MARKER_KINDS: ReadonlySet<MarkerKind> = new Set<MarkerKind>(["fact", "skill"]);

/** Where the marker was found, and the clock to stamp the artifact with. */
export interface CaptureRouteContext {
  /** Wikilink to the source note, e.g. `[[Daily/2026-07-27]]`. */
  readonly sourceRef: string;
  readonly now: Date;
}

/**
 * What a routed marker did at its destination. Same vocabulary for both
 * kinds, so a caller counts and reports one set of outcomes:
 *
 *   - `created`   - the artifact was written.
 *   - `deduped`   - an equivalent artifact already existed; nothing was
 *                   written and nothing was lost.
 *   - `suppressed`- the destination declined and the marker's content is
 *                   stored nowhere. Named, never silent.
 */
export type CaptureRouteOutcome = "created" | "deduped" | "suppressed";

interface CaptureRouteResultBase {
  /** Id of the artifact the marker landed in; embedded in the consumed sentinel. */
  readonly id: string;
}

export type CaptureRouteResult = CaptureRouteResultBase &
  (
    | { readonly outcome: "created" | "deduped" }
    /** `reason` is required here so a decline can never reach a caller unexplained. */
    | { readonly outcome: "suppressed"; readonly reason: string }
  );

/**
 * Send one marker to the store its kind belongs in. Callers must have
 * checked {@link ROUTED_MARKER_KINDS} first; a kind in that set with no
 * branch here throws by name rather than returning a marker-shaped
 * nothing.
 */
export function routeCaptureMarker(
  vault: string,
  marker: ParsedMarker,
  ctx: CaptureRouteContext,
): CaptureRouteResult {
  if (isFactMarker(marker)) return routeFactMarker(vault, marker, ctx);
  if (isSkillMarker(marker)) return routeSkillMarker(vault, marker, ctx);
  throw new Error(`no capture route for marker kind: ${marker.kind}`);
}

/**
 * What {@link routeCaptureMarker} would do, without writing anything.
 *
 * This is what `scan-inline --dry-run` walks. A preview that reported
 * nothing while two vault writes were queued would be a result computed
 * and dropped, so the preview resolves the same identity, refuses the
 * same markers, and returns the same outcome vocabulary as the write.
 */
export function previewCaptureMarker(
  vault: string,
  marker: ParsedMarker,
  ctx: CaptureRouteContext,
): CaptureRouteResult {
  if (isFactMarker(marker)) return previewFactMarker(vault, marker);
  if (isSkillMarker(marker)) {
    return skillRouteResult(previewDeclaredSkillProposal(vault, skillInput(marker, ctx)));
  }
  throw new Error(`no capture route for marker kind: ${marker.kind}`);
}

/**
 * Commit a fact marker as an unconfirmed preference. The slug is derived
 * from the topic, the same derivation `scanInline` already applies when
 * it slugs a feedback signal, so a fact keeps one stable identity across
 * rescans instead of needing an author-supplied id.
 *
 * The outcome is `created` because that is `deriveFact`'s whole contract:
 * it validates, writes, and returns an id, with no branch that resolves
 * to an artifact it did not write. The census test
 * `DeriveFactResult carries only the id` fails the moment that result
 * grows a field describing what it did - at which point this mapping must
 * read that field instead of standing on the contract.
 */
function routeFactMarker(
  vault: string,
  marker: FactMarker,
  ctx: CaptureRouteContext,
): CaptureRouteResult {
  const result = deriveFact(vault, factInput(marker), { now: ctx.now });
  return { id: result.id, outcome: "created" };
}

/** Draft a skill marker as a pending proposal. Never reaches accepted. */
function routeSkillMarker(
  vault: string,
  marker: SkillMarker,
  ctx: CaptureRouteContext,
): CaptureRouteResult {
  return skillRouteResult(draftDeclaredSkillProposal(vault, skillInput(marker, ctx)));
}

/** The declaration input, identical for the write and the preview. */
function skillInput(marker: SkillMarker, ctx: CaptureRouteContext): DeclaredSkillProposalInput {
  return {
    name: marker.name,
    body: marker.body,
    sourceRefs: [ctx.sourceRef],
    now: ctx.now,
  };
}

/** Carry the queue's own outcome up unchanged; the vocabularies are one. */
function skillRouteResult(result: DeclaredSkillProposalResult): CaptureRouteResult {
  return result.outcome === "suppressed"
    ? { id: result.id, outcome: "suppressed", reason: result.reason }
    : { id: result.id, outcome: result.outcome };
}

/**
 * The derive-fact input, identical for the write and the preview.
 *
 * Routed through `parseDeriveFactInput` so the marker's verbatim `level`
 * meets the destination's own vocabulary check on both paths, instead of
 * being cast into the type and validated only where a write follows.
 */
function factInput(marker: FactMarker): DeriveFactInput {
  return parseDeriveFactInput({
    slug: slugify(marker.topic),
    topic: marker.topic,
    principle: marker.principle,
    premises: [...marker.premise],
    level: marker.level,
  });
}

/**
 * What a fact marker WOULD do. `parseDeriveFactInput` covers everything
 * `deriveFact` checks without touching the vault; the two conditions
 * below are the ones it checks against the vault, restated here because
 * a preview cannot run the writer.
 *
 * They are pinned to the writer by the test "a dry run refuses exactly
 * the markers a real run refuses", which runs both paths over the same
 * fixtures: a precondition that drifts out of `derived-fact.ts` fails
 * there rather than turning a preview into a comfortable lie.
 */
function previewFactMarker(vault: string, marker: FactMarker): CaptureRouteResult {
  const input = factInput(marker);
  for (const premise of input.premises) {
    const slug = premiseSlug(premise);
    if (!slug) throw new DeriveFactError("premise id must not be empty");
    if (!memoryPageExists(vault, vaultRelative(preferencePath(vault, slug), vault))) {
      throw new DeriveFactError(`premise preference not found: ${JSON.stringify(premise)}`);
    }
  }
  if (memoryPageExists(vault, vaultRelative(preferencePath(vault, input.slug), vault))) {
    throw new DeriveFactError(`a preference already exists for slug: ${input.slug}`);
  }
  return { id: `pref-${input.slug}`, outcome: "created" };
}

/** 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;
}