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
10.9 KB
Raw Blame
/**
 * Cross-agent shared memory namespace (Agent Write Contract Suite,
 * t_936a1a61).
 *
 * Opt-in: the `shared_namespace` device-config key names a second
 * vault root. When set, explicit remember-writes (feedback signals and
 * narrative notes) MIRROR there after the primary write succeeds, so
 * facts learned by one agent become visible to every agent sharing the
 * namespace. Attribution is carried twice: the existing `agent` field
 * plus `origin_vault` (basename of the primary vault), which
 * `parseSignal` reads back and the agent-source provider surfaces.
 *
 * Mirror semantics are FAIL-SOFT by contract: a mirror failure must never
 * break, delay, or alter the primary write. Fail-soft is not the same as
 * mute, and it used to be (a-label-is-not-a-boundary, U5): both writes sat
 * behind a bare `catch { return "failed" }`, so a permissions problem, a
 * missing shared vault, a full disk and a schema violation reached the
 * operator as one indistinguishable bit - on the one path they cannot
 * observe by any other means. Every outcome that is not `ok` now carries
 * the reason that produced it.
 *
 * Unlike the cross-vault union, the reason here carries the underlying
 * message: the shared vault is the operator's OWN configured path on their
 * OWN machine, not a foreign index whose location is a disclosure.
 *
 * One-way by design: the shared vault's own dream pass treats mirrored
 * records as ordinary first-class signals. Reading it back is a separate
 * mechanism - it is enumerated as a search origin by
 * `portability/origins.ts`.
 *
 * The brain store (task 3.12, design D19 item 3): the namespace gets no
 * store of its own. A write to a vault that is store-only on this machine
 * lands in this machine's brain store, which every store-only agent of
 * every machine of the store reads, so a store-only namespace IS that
 * store. The mirror writes there only when the origin record is not in it
 * already: the origin vault still writes the legacy layout here and dual
 * writes are off. It refuses, before any I/O, on a switched machine, for a
 * store-only origin vault, with dual writes on (each would put the record
 * into the store a second time), and when there is no store at all.
 */

import { realpathSync, statSync } from "node:fs";
import { basename, resolve } from "node:path";

import { isDualWriteEnabled } from "../store/dual-write.ts";
import { configuredStore } from "../store/read/store-entities.ts";
import { storeOnlyMode } from "../store/store-only.ts";
import { resolveSharedNamespace } from "../config.ts";
import { appendLogEvent } from "./log.ts";
import { writeSignal, type WriteSignalInput, type WriteSignalOptions } from "./signal.ts";
import { isoSecond } from "./time.ts";
import { BRAIN_LOG_EVENT_KIND } from "./types.ts";

export { resolveSharedNamespace };

/**
 * How one mirror write ended.
 *
 * `off` is not a member: the key being absent is expressed by the caller
 * never asking, and every caller reports the absence by omitting the field
 * entirely. A member no producer can return is a promise the surface does
 * not keep, so the token was retracted rather than kept "for later".
 *
 * `misconfigured` is split from `failed` because the two are the same word
 * for opposite situations: a shared namespace pointing at the origin vault
 * is decided before any I/O and is repaired by editing one config key,
 * while `failed` is a write that was attempted and raised. Reporting a
 * self-mirror identically to an unmounted disk sent the operator after the
 * wrong fault.
 */
export const MIRROR_OUTCOME = Object.freeze({
  /** The record landed in the shared vault. */
  ok: "ok",
  /** The write was attempted and raised; `reason` carries the message. */
  failed: "failed",
  /** Refused before any I/O; `reason` names the operator's misconfiguration. */
  misconfigured: "misconfigured",
} as const);

/** Closed union over {@link MIRROR_OUTCOME}. */
export type MirrorOutcome = (typeof MIRROR_OUTCOME)[keyof typeof MIRROR_OUTCOME];

/** Membership list, best outcome first. */
export const MIRROR_OUTCOMES: ReadonlyArray<MirrorOutcome> = Object.freeze([
  MIRROR_OUTCOME.ok,
  MIRROR_OUTCOME.failed,
  MIRROR_OUTCOME.misconfigured,
]);

/** Narrow a value read back off a payload or across a tool boundary. */
export function isMirrorOutcome(value: unknown): value is MirrorOutcome {
  return typeof value === "string" && (MIRROR_OUTCOMES as ReadonlyArray<string>).includes(value);
}

/** One mirror write's outcome and, unless it succeeded, why. */
export interface MirrorReport {
  readonly outcome: MirrorOutcome;
  /** Absent exactly when the outcome is `ok`. */
  readonly reason?: string;
}

/** The one sentence the self-mirror guard reports, so no caller reinvents it. */
const SELF_MIRROR_REASON =
  "shared_namespace resolves to the origin vault, which would double-write every record";

const OK: MirrorReport = Object.freeze({ outcome: MIRROR_OUTCOME.ok });

const SELF_MIRROR: MirrorReport = Object.freeze({
  outcome: MIRROR_OUTCOME.misconfigured,
  reason: SELF_MIRROR_REASON,
});

/**
 * The refusal when the shared vault is store-only on this machine and the
 * origin record is already in this machine's store (this machine switched,
 * the origin vault is store-only too, or dual writes copied it there): a
 * mirror would only write the same record into the same store again.
 */
const STORE_ONLY_MIRROR: MirrorReport = Object.freeze({
  outcome: MIRROR_OUTCOME.misconfigured,
  reason:
    "the shared namespace is store-only on this machine, and the origin record is already in " +
    "this machine's brain store, which is that namespace; nothing was mirrored",
});

/** The refusal when the shared vault is store-only but this machine has no store. */
const NO_STORE_MIRROR: MirrorReport = Object.freeze({
  outcome: MIRROR_OUTCOME.misconfigured,
  reason:
    "the shared namespace is store-only on this machine (it has no legacy tree), but this " +
    "machine has no brain store to write it into; run `o2b store init`, or `o2b brain init` " +
    "in the shared vault; nothing was mirrored",
});

/** The report when the shared namespace path is no directory. */
const NOT_A_DIRECTORY: MirrorReport = Object.freeze({
  outcome: MIRROR_OUTCOME.failed,
  reason:
    "shared_namespace is not a directory (unmounted, missing, or a file); nothing was mirrored",
});

/**
 * Why a mirror cannot run before any I/O, or `null` when it can. Every
 * check reads the caller's machine config (`configPath`, default: the
 * resolved one), the same config the origin write and the namespace came
 * from.
 */
function mirrorRefusal(
  sharedVault: string,
  originVault: string,
  configPath: string | undefined,
): MirrorReport | null {
  if (isSelfMirror(sharedVault, originVault)) return SELF_MIRROR;
  const withConfig = configPath !== undefined ? { configPath } : {};
  const mode = storeOnlyMode({ vault: sharedVault, ...withConfig });
  if (mode.reason === "device-switched") return STORE_ONLY_MIRROR;
  if (mode.reason !== "no-legacy-tree") return null;
  // A shared path that is no directory at all (an unmounted share, a
  // file) is a broken namespace, not a store-only one: reported `failed`
  // before any write, never mirrored into this machine's store.
  if (!isDirectory(sharedVault)) return NOT_A_DIRECTORY;
  if (configuredStore(configPath) === null) return NO_STORE_MIRROR;
  if (
    storeOnlyMode({ vault: originVault, ...withConfig }).storeOnly ||
    isDualWriteEnabled(configPath)
  ) {
    return STORE_ONLY_MIRROR;
  }
  return null;
}

function isDirectory(path: string): boolean {
  try {
    return statSync(path).isDirectory();
  } catch {
    return false;
  }
}

/** Keep a thrown non-Error readable instead of casting it to one unchecked. */
function failureReason(exc: unknown): MirrorReport {
  return Object.freeze({
    outcome: MIRROR_OUTCOME.failed,
    reason: exc instanceof Error ? exc.message : String(exc),
  });
}

/**
 * Mirror a feedback signal into the shared vault. The record is the
 * same signal with `origin_vault` attribution; slug collisions resolve
 * through the normal allocator. `configPath` is the caller's machine
 * config: the refusal checks read it. The signal writer itself resolves
 * the process's config, as the origin write did.
 */
export function mirrorSignal(
  sharedVault: string,
  originVault: string,
  input: WriteSignalInput,
  options: WriteSignalOptions = {},
  configPath?: string | null,
): MirrorReport {
  const refused = mirrorRefusal(sharedVault, originVault, configPath ?? undefined);
  if (refused !== null) return refused;
  try {
    writeSignal(sharedVault, { ...input, origin_vault: basename(originVault) }, options);
    return OK;
  } catch (exc) {
    return failureReason(exc);
  }
}

export interface MirrorNoteInput {
  readonly text: string;
  readonly agent: string;
  readonly now?: Date;
}

/**
 * Mirror a narrative note event into the shared vault's log. The refusal
 * checks and the write read the caller's machine config (`configPath`).
 */
export function mirrorNote(
  sharedVault: string,
  originVault: string,
  input: MirrorNoteInput,
  configPath?: string | null,
): MirrorReport {
  const refused = mirrorRefusal(sharedVault, originVault, configPath ?? undefined);
  if (refused !== null) return refused;
  try {
    appendLogEvent(
      sharedVault,
      {
        timestamp: isoSecond(input.now ?? new Date()),
        eventType: BRAIN_LOG_EVENT_KIND.note,
        body: {
          text: input.text,
          agent: input.agent,
          origin_vault: basename(originVault),
        },
      },
      // Not fail-open: the mirror reports its own failure to the caller.
      configPath !== undefined && configPath !== null ? { configPath } : {},
    );
    return OK;
  } catch (exc) {
    return failureReason(exc);
  }
}

/** The fields a result surface adds for a mirror it performed. */
export interface MirrorReportFields {
  readonly mirror?: MirrorOutcome;
  readonly mirror_reason?: string;
}

/**
 * Flatten a report onto a result payload, or contribute nothing when no
 * mirror was configured. One composer for the three surfaces that report a
 * mirror - the MCP feedback tool, the note writer and the CLI - so a
 * diagnosis cannot reach a caller on one surface and be dropped on another.
 */
export function mirrorReportFields(report: MirrorReport | undefined): MirrorReportFields {
  if (report === undefined) return {};
  return {
    mirror: report.outcome,
    ...(report.reason !== undefined ? { mirror_reason: report.reason } : {}),
  };
}

/**
 * A shared namespace pointing back at the origin vault would
 * double-write every record into its own store. That is always an
 * operator misconfiguration, and it is reported as one.
 */
function isSelfMirror(sharedVault: string, originVault: string): boolean {
  return canonicalPath(sharedVault) === canonicalPath(originVault);
}

/** Realpath when resolvable (catches symlink aliases), lexical otherwise. */
function canonicalPath(path: string): string {
  try {
    return realpathSync(path);
  } catch {
    return resolve(path);
  }
}