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
11.1 KB
Raw Blame
/**
 * Cross-type tombstone + supersede + correct lifecycle MCP tool (Belief
 * lifecycle suite, Track A anchor, t_7d5a3589; correct verb from
 * truth-correctable-time-aware).
 *
 * One tool, `brain_lifecycle`, dispatching on `action`:
 *   - `tombstone`         mark a memory `_status: tombstoned` in place
 *   - `supersede`         tombstone a predecessor and record its successor
 *   - `temporal-replace`  close one fact and open another at a shared instant
 *   - `tip`               resolve a supersede chain to its live tip
 *   - `curator`           read slices over observed-use verdicts
 *   - `correct`           sweep one record's correction: discovery,
 *                         per-target retirement through the end-state
 *                         policy, mention retargeting, ledger correction
 *                         events and bundle-correlated receipts
 *
 * MCP mirror of the `o2b brain lifecycle` CLI verb; both delegate to the
 * core lifecycle module so the on-disk shape cannot drift.
 */

import { everyArtifactRefView } from "../../core/brain/artifact-ref-view.ts";
import { curatorSlices, type CuratorEntry } from "../../core/brain/lifecycle/curator.ts";
import { correct, CorrectionError } from "../../core/brain/lifecycle/correction.ts";
import {
  temporalReplace,
  TemporalReplaceError,
} from "../../core/brain/lifecycle/temporal-replace.ts";
import {
  resolveChainTipInVault,
  supersede,
  tombstone,
  TombstoneError,
} from "../../core/brain/lifecycle/tombstone.ts";
import { gatedOwnerScopeView } from "../../core/brain/owner-scope-view.ts";
import { reachView } from "../../core/brain/reach-view.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
import { contextReach, type ServerContext, type ToolDefinition } from "../tool-contract.ts";
import { coerceStr, unknownOperationError } from "../coerce.ts";
import { readableAtContextReachOrUndefined } from "./reach-readable.ts";
import { coerceNonNegativeInteger, wrapToolErrors } from "./shared.ts";

const TOOL = "brain_lifecycle";

/** Project curator slice rows into the tool's snake_cased response shape. */
function renderCuratorRows(rows: ReadonlyArray<CuratorEntry>): Array<Record<string, unknown>> {
  return rows.map((r) => ({
    key: r.key,
    used: r.reuse.used,
    ignored: r.reuse.ignored,
    contradicted: r.reuse.contradicted,
  }));
}

async function toolBrainLifecycle(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  return wrapToolErrors(TOOL, [TombstoneError, TemporalReplaceError, CorrectionError], async () => {
    const action = coerceStr(args, "action", true)!;
    const agent = coerceStr(args, "agent", false) ?? undefined;
    // Every write answers at the caller's reach: a page it may not read is
    // refused as a missing one, before anything is written.
    const readable = readableAtContextReachOrUndefined(ctx);
    const reachOpt = readable !== undefined ? { readable } : {};

    switch (action) {
      case "tombstone": {
        const path = coerceStr(args, "path", true)!;
        const reason = coerceStr(args, "reason", true)!;
        const supersededBy = coerceStr(args, "superseded_by", false) ?? undefined;
        const res = tombstone({
          vault: ctx.vault,
          path,
          reason,
          ...(supersededBy ? { supersededBy } : {}),
          ...(agent ? { agent } : {}),
          ...reachOpt,
        });
        return {
          action,
          changed: res.changed,
          path: res.path,
          tombstoned: res.state.tombstoned,
          superseded_by: res.state.supersededBy,
        };
      }
      case "supersede": {
        const predecessor = coerceStr(args, "predecessor", true)!;
        const successor = coerceStr(args, "successor", true)!;
        const reason = coerceStr(args, "reason", false) ?? undefined;
        const res = supersede({
          vault: ctx.vault,
          predecessor,
          successor,
          ...(reason ? { reason } : {}),
          ...(agent ? { agent } : {}),
          ...reachOpt,
        });
        return {
          action,
          changed: res.changed,
          path: res.path,
          superseded_by: res.state.supersededBy,
        };
      }
      case "temporal-replace": {
        const predecessor = coerceStr(args, "predecessor", true)!;
        const successor = coerceStr(args, "successor", true)!;
        const at = coerceStr(args, "at", true)!;
        const res = temporalReplace({
          vault: ctx.vault,
          predecessor,
          successor,
          at,
          ...(agent ? { agent } : {}),
          ...reachOpt,
        });
        return {
          action,
          at: res.at,
          predecessor: res.predecessor,
          successor: res.successor,
          agent: res.agent,
        };
      }
      case "tip": {
        const id = coerceStr(args, "id", true)!;
        // A page the caller may not read is no chain node: it reads as an
        // unknown id, and a walk never steps onto or through it.
        const res = resolveChainTipInVault(ctx.vault, id, reachOpt);
        return {
          action,
          tip: res.tip,
          steps: res.steps,
          cycle: res.cycle,
          resolved_all: res.resolvedAll,
        };
      }
      case "correct": {
        const target = coerceStr(args, "target", true)!;
        const value = coerceStr(args, "value", false) ?? undefined;
        const successor = coerceStr(args, "successor", false) ?? undefined;
        const windowEnd = coerceStr(args, "window_end", false) ?? undefined;
        const reason = coerceStr(args, "reason", false) ?? undefined;
        const flatlyWrong = args["flatly_wrong"] === true;
        // Dry run is the DEFAULT: the applied sequence needs an explicit
        // false, so a caller that omits the flag gets the blast radius
        // and nothing else.
        const dryRun = args["dry_run"] !== false;
        const res = correct({
          vault: ctx.vault,
          target,
          ...(value !== undefined ? { value } : {}),
          ...(successor !== undefined ? { successor } : {}),
          ...(windowEnd !== undefined ? { windowEnd } : {}),
          ...(reason !== undefined ? { reason } : {}),
          flatlyWrong,
          dryRun,
          ...(agent ? { agent } : {}),
          ...reachOpt,
        });
        return {
          action,
          bundle_id: res.bundleId,
          dry_run: res.dryRun,
          blast_radius: {
            target: res.blastRadius.target,
            replaced_by: res.blastRadius.replacedBy,
            contests: res.blastRadius.contests,
            mentions: res.blastRadius.mentions,
            claims: res.blastRadius.claims,
          },
          retirements: res.retirements.map((r) => ({
            path: r.path,
            end_state: r.endState,
            valid_until: r.validUntil,
            reason_code: r.reasonCode,
            changed: r.changed,
          })),
          retarget: res.retarget,
          ledger: res.ledger,
          receipts: res.receipts,
        };
      }
      case "curator": {
        const highUseMin = coerceNonNegativeInteger(TOOL, "high_use_min", args["high_use_min"]);
        const slices = curatorSlices(ctx.vault, highUseMin !== undefined ? { highUseMin } : {});
        // A row's key is the page path or the memory id; a row naming a
        // page the caller may not see is left out.
        const view = everyArtifactRefView(
          gatedOwnerScopeView(ctx.vault, ctx.agentName),
          reachView(ctx.vault, contextReach(ctx)),
        );
        const rows = (entries: ReadonlyArray<CuratorEntry>) =>
          renderCuratorRows(view.keep(entries, (e) => [e.key]));
        return {
          action,
          injected_never_used: rows(slices.injectedNeverUsed),
          contradicted: rows(slices.contradicted),
          high_used: rows(slices.highUsed),
        };
      }
      default:
        throw unknownOperationError(
          `${TOOL}: 'action' must be one of tombstone, supersede, temporal-replace, tip, curator, correct`,
        );
    }
  });
}

export const LIFECYCLE_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
  {
    name: TOOL,
    kind: "write",
    description:
      "Cross-type lifecycle. action: tombstone marks a memory tombstoned in place; supersede links a successor; temporal-replace closes one fact and opens another at a shared instant; tip resolves a chain tip; curator slices observed-use verdicts; correct sweeps a correction, dry run by default.",
    inputSchema: {
      type: "object",
      properties: {
        action: {
          type: "string",
          enum: ["tombstone", "supersede", "temporal-replace", "tip", "curator", "correct"],
          description: "Which lifecycle operation to run.",
        },
        path: {
          type: "string",
          description: "tombstone: vault-relative path of the target memory file.",
        },
        reason: {
          type: "string",
          description: "tombstone/supersede/correct: operator-facing reason for the change.",
        },
        superseded_by: {
          type: "string",
          description: "tombstone: optional successor id/wikilink stored as superseded_by.",
        },
        predecessor: {
          type: "string",
          description:
            "supersede/temporal-replace: vault-relative path of the predecessor being replaced.",
        },
        successor: {
          type: "string",
          description:
            "supersede: successor id/wikilink. temporal-replace: successor path. correct: successor id/wikilink for the superseded_by pointer and retarget.",
        },
        at: {
          type: "string",
          description:
            "temporal-replace: shared instant T (ISO-8601 UTC instant or YYYY-MM-DD date).",
        },
        id: { type: "string", description: "tip: id/wikilink whose chain tip to resolve." },
        high_use_min: {
          type: "integer",
          minimum: 0,
          description: "curator: minimum USED count for the high-used slice.",
        },
        target: {
          type: "string",
          description: "correct: vault-relative path of the record being corrected.",
        },
        value: {
          type: "string",
          description:
            "correct: the corrected value the ledger correction events assert; absent appends nothing to the ledger.",
        },
        flatly_wrong: {
          type: "boolean",
          description:
            "correct: the caller declares the prior claim was never true, so the target tombstones instead of validity-closing.",
        },
        window_end: {
          type: "string",
          description:
            "correct: explicit window end for a time-scoped correction (canonical ISO-8601 UTC); defaults to the correction instant.",
        },
        dry_run: {
          type: "boolean",
          description:
            "correct: report the blast radius and write nothing (the default). Pass false to apply the sweep.",
        },
        agent: {
          type: "string",
          description: "Optional agent identity override; defaults to the server-resolved name.",
        },
      },
      required: ["action"],
      additionalProperties: false,
    },
    previewBudget: MCP_PREVIEW_BUDGET,
    handler: toolBrainLifecycle,
  },
]);