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
9.0 KB
Raw Blame
/**
 * The origin channel β€” which kind of process put a record in the vault.
 *
 * ## Server-derived, and that is the whole design
 *
 * The channel is claimed ONCE per process by the entry point that knows
 * what the process is: the MCP server transport, the CLI dispatcher, and
 * the import verbs' dispatch. It is never a tool argument and never a
 * CLI flag, and `tests/core/architecture/origin-channel-census.test.ts`
 * asserts that rather than trusting this paragraph.
 *
 * The reason is measured, not stylistic. Agent identity in this codebase
 * resolves to a caller-supplied `agent` string that 25 MCP tool schemas
 * accept verbatim (the write binding's docblock documents the recount and
 * the command to redo it). A channel a caller could name would be the
 * same unverifiable claim wearing a schema β€” a record saying `cli` would
 * mean "someone typed cli", which is not provenance. So the value comes
 * from the process, or it comes back as {@link ORIGIN_CHANNEL_UNSET}.
 *
 * ## Why an `unset` literal rather than a guessed default
 *
 * {@link resolveOriginChannel} FAILS LOUD when nothing claimed the
 * process: reading a channel that no entry point set is a programming
 * error and the refusal names itself and the setter. The record writers
 * do not use that read. They use {@link originChannelStamp}, which
 * absorbs the unclaimed state into the explicit `unset` literal and
 * stamps THAT.
 *
 * This mirrors a decision already made one layer down, deliberately.
 * `appendLogEvent` absorbs a `resolveDeviceId` failure into the empty
 * shard id (`AppendLogEventOptions.deviceId`) because appending is the
 * always-on write path behind every hook, and failing it turns one bad
 * file mode into a dead session. The same argument holds here for all
 * four stamped families, and the absorbed value obeys the same rule the
 * device-id fallback does: it is a DOCUMENTED value with its own
 * meaning, not a neutral-looking invention. `unset` serializes as
 * `unset`, is outside {@link ORIGIN_CHANNELS}, and reads on disk as
 * exactly what it is β€” no entry point claimed this process. A guessed
 * `cli` would have been the lie this unit exists to remove.
 *
 * ## No backfill
 *
 * Records written before this shipped carry no channel and are NOT
 * rewritten to add one. Rewriting history to add provenance is the
 * opposite of provenance: the value stamped on a backfill pass would
 * describe the backfill process, not the process that wrote the record.
 * Absence of the key means "written before the stamp existed", and every
 * reader treats it that way.
 *
 * ## Three adjacent axes this is NOT
 *
 *   - `ProvenanceLevel` (`brain/provenance/provenance.ts`) is a TRUST
 *     band β€” `stated` > `deduced` > `inferred` β€” about how a claim was
 *     arrived at. A channel is not a trust band: an `mcp-tool` record can
 *     be `inferred` and a `cli` record can be `stated`.
 *   - `classifySourceOrigin` (`brain/intake/source-trust.ts`) is an
 *     INBOUND-SOURCE axis about the file an intake read. A channel says
 *     nothing about the source and everything about the writer.
 *   - `RECALL_CHANNEL` (`brain/recall-telemetry.ts`) is the nearest one
 *     and the one most worth being explicit about, because its members
 *     (`mcp` / `cli` / `hook`) nearly rhyme with these. It measures the
 *     transport a recall was DELIVERED over β€” the read direction β€” and it
 *     is caller-supplied by design, being a property of a delivery the
 *     caller performed. This is the WRITE direction and is derived rather
 *     than supplied. Two records can disagree on them honestly: a hook
 *     delivers a recall (`recall_channel: hook`) inside a process that
 *     writes its telemetry over `origin_channel: cli`. Folding either
 *     into the other would make one of those two facts unrecordable.
 *
 * None may be folded into this one, and none may absorb it.
 */

/**
 * The closed vocabulary. Three members because three process shapes can
 * put a record in the vault, and each one is a different answer to "who
 * would I ask about this record":
 *
 *   - `mcp-tool` β€” an agent called a tool over the MCP transport.
 *   - `cli`      β€” an operator (or a script) ran `o2b`.
 *   - `import`   β€” a bulk replay of records authored somewhere else.
 *
 * Spellings are on-disk values and are load-bearing; the hyphen in
 * `mcp-tool` matches the `apply-evidence` shape the log-event vocabulary
 * already uses.
 */
export const ORIGIN_CHANNEL = Object.freeze({
  mcpTool: "mcp-tool",
  cli: "cli",
  import: "import",
} as const);

export type OriginChannel = (typeof ORIGIN_CHANNEL)[keyof typeof ORIGIN_CHANNEL];

/**
 * The membership list, exported so a refusal can NAME the vocabulary
 * instead of restating it β€” the same rule `BRAIN_SIGNAL_SOURCE_TYPES`
 * follows, and for the same reason: a hand-written list in a message
 * goes stale on the first new member and teaches the wrong contract.
 */
export const ORIGIN_CHANNELS: ReadonlyArray<OriginChannel> = Object.freeze(
  Object.values(ORIGIN_CHANNEL),
);

/**
 * What a record carries when no entry point claimed the process.
 * Deliberately OUTSIDE {@link ORIGIN_CHANNELS} so a reader can tell it
 * apart from every real answer without knowing this module.
 */
export const ORIGIN_CHANNEL_UNSET = "unset";

/** What a stamped record actually holds: a channel, or the unset literal. */
export type OriginChannelStamp = OriginChannel | typeof ORIGIN_CHANNEL_UNSET;

/**
 * The on-disk key. One constant because three of the four stamped
 * families spell it in a text surface β€” a log bullet, a signal
 * frontmatter line, a note frontmatter line β€” and a key that drifts
 * between them is a key no reader can query on. The continuity record is
 * the exception and uses `originChannel`, because its record shape is
 * camelCase JSON throughout (`createdAt`, `sourceRefs`) and a lone
 * snake_case field there would be the drift, not the consistency.
 */
export const ORIGIN_CHANNEL_FIELD = "origin_channel";

export function isOriginChannel(value: unknown): value is OriginChannel {
  return typeof value === "string" && (ORIGIN_CHANNELS as ReadonlyArray<string>).includes(value);
}

export function isOriginChannelStamp(value: unknown): value is OriginChannelStamp {
  return value === ORIGIN_CHANNEL_UNSET || isOriginChannel(value);
}

/** Raised by {@link resolveOriginChannel} when nothing claimed the process. */
export class OriginChannelUnsetError extends Error {
  constructor() {
    super(
      "resolveOriginChannel: no entry point claimed an origin channel for this process; " +
        "the MCP transport, the CLI dispatcher and the import verbs each call " +
        `setOriginChannel(...) with one of ${ORIGIN_CHANNELS.join(", ")}. Record writers ` +
        `must call originChannelStamp() instead, which stamps '${ORIGIN_CHANNEL_UNSET}'.`,
    );
    this.name = "OriginChannelUnsetError";
  }
}

/** Process-scoped, module-private. `null` until an entry point claims it. */
let claimed: OriginChannel | null = null;

/**
 * Claim the channel for this process. Called by the entry point, before
 * any dispatch.
 *
 * Re-claiming is allowed and the LAST claim wins. This is not laxity: a
 * single OS process re-enters the entry point routinely β€” the CLI test
 * harness calls `main()` many times, and an embedded host can start the
 * MCP transport inside a process that already ran a command. Refusing
 * the second claim would fail those runs over a value that is correct;
 * refusing to let a MID-FLIGHT caller set it is what actually matters,
 * and that is enforced by there being no argument and no flag that
 * reaches this function, which the origin-channel census asserts.
 */
export function setOriginChannel(channel: OriginChannel): void {
  if (!isOriginChannel(channel)) {
    throw new Error(
      `setOriginChannel: ${JSON.stringify(channel)} is not an origin channel; ` +
        `expected one of ${ORIGIN_CHANNELS.join(", ")}`,
    );
  }
  claimed = channel;
}

/**
 * Return the process to unclaimed. The counterpart of
 * {@link setOriginChannel} for a harness that hands the process back
 * between runs; production entry points claim and never release.
 */
export function clearOriginChannel(): void {
  claimed = null;
}

/**
 * The strict read: the channel this process claimed, or a refusal.
 *
 * Use it where a wrong answer is worse than no answer. Record writers
 * want {@link originChannelStamp} instead β€” see the module docblock for
 * why the always-on write path absorbs this condition rather than
 * propagating it.
 */
export function resolveOriginChannel(): OriginChannel {
  if (claimed === null) throw new OriginChannelUnsetError();
  return claimed;
}

/**
 * The record-writer read: the claimed channel, or the explicit
 * {@link ORIGIN_CHANNEL_UNSET} literal. Never throws, never guesses.
 */
export function originChannelStamp(): OriginChannelStamp {
  try {
    return resolveOriginChannel();
  } catch {
    // The documented absorb. See the module docblock: a write path that
    // fails over its own provenance stamp costs the record it was
    // stamping, and `unset` loses nothing that was ever known.
    return ORIGIN_CHANNEL_UNSET;
  }
}