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
16.7 KB
Raw Blame
/**
 * `o2b brain truth <op>` (Entity Truth & Self-Improving Dream Suite):
 * operator surface over the claim ledger - `ingest` appends one claim
 * (optionally validity-windowed), `slots` and `conflicts` render the
 * fold (with conflict detection), `aggregate` sums exact-match
 * quantities, `collisions` reports cross-agent convergence, `events`
 * recalls a windowed slice of the ledger, `state` grounds one
 * agent-stated claim with an anchoring verdict, `sweep` bounds the
 * ledger.
 *
 * Exit codes: 0 on success, 1 on an operational failure, 2 on usage
 * errors.
 */

import { aggregateQuantities } from "../../../core/brain/truth/aggregate.ts";
import { detectAgentCollisions } from "../../../core/brain/truth/collision.ts";
import { computeTruthStateWithConflicts } from "../../../core/brain/truth/conflicts.ts";
import { claimEventLimit } from "../../../core/brain/truth/events-window.ts";
import {
  appendClaimEvent,
  CLAIM_EVENT_MAX_COUNT,
  ClaimWindowRefusal,
  readClaimEvents,
  sweepClaimEvents,
} from "../../../core/brain/truth/store.ts";
import {
  appendStatedClaims,
  StatedClaimsRefusal,
} from "../../../core/brain/truth/stated-claims.ts";
import { normalizeEntityName } from "../../../core/brain/entities/canonical.ts";
import { isoSecond } from "../../../core/brain/time.ts";
import { SearchError } from "../../../core/search/types.ts";
import { TRANSPORT_REACH } from "../../../core/graph/transport-reach.ts";
import { resolveAgentName } from "../../../core/config.ts";
import { claimEventsReport, statedClaimEntities } from "../../../mcp/brain/knowledge-tools.ts";
import { parseTimeBounds } from "../../../mcp/brain/time-bounds.ts";
import { brainVerbContext, fail, ok, okJson, parse, resolveBrainAgent } from "../helpers.ts";

const OPS = [
  "ingest",
  "slots",
  "conflicts",
  "aggregate",
  "collisions",
  "events",
  "state",
  "sweep",
] as const;
type TruthOp = (typeof OPS)[number];

const USAGE =
  "usage: o2b brain truth <ingest|slots|conflicts|aggregate|collisions|events|state|sweep>\n" +
  "  ingest     --entity E --aspect A --value V --source S [--agent N] [--ts ISO]\n" +
  "             [--valid-from X --valid-until Y]\n" +
  "             [--quantity-value N --quantity-unit U --quantity-action W]\n" +
  "  slots      [--entity E]\n" +
  "  conflicts  [--window-days N]\n" +
  "  aggregate  --action W [--unit U] [--entity E]\n" +
  "  collisions [--window-days N]\n" +
  "  events     [--entity E] [--since X] [--until Y] [--limit N]\n" +
  "  state      --subject S --relation R --object O --text T --source S\n" +
  "             [--agent N] [--sample-id ID]\n" +
  "  sweep      [--max-events N]\n" +
  "  common     [--vault <path>] [--json]";

function requireString(flags: Record<string, unknown>, name: string): string {
  const value = flags[name];
  if (typeof value !== "string" || value.trim() === "") {
    throw new UsageError(`--${name} is required`);
  }
  return value;
}

class UsageError extends Error {}

export async function cmdBrainTruth(argv: string[]): Promise<number> {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    entity: { type: "string" },
    aspect: { type: "string" },
    value: { type: "string" },
    source: { type: "string" },
    agent: { type: "string" },
    ts: { type: "string" },
    "valid-from": { type: "string" },
    "valid-until": { type: "string" },
    subject: { type: "string" },
    relation: { type: "string" },
    object: { type: "string" },
    text: { type: "string" },
    "sample-id": { type: "string" },
    since: { type: "string" },
    until: { type: "string" },
    limit: { type: "string" },
    "quantity-value": { type: "string" },
    "quantity-unit": { type: "string" },
    "quantity-action": { type: "string" },
    action: { type: "string" },
    unit: { type: "string" },
    "window-days": { type: "string" },
    "max-events": { type: "string" },
    json: { type: "boolean" },
  });
  const op = positional[0] as TruthOp | undefined;
  if (op === undefined || !OPS.includes(op)) {
    process.stderr.write(`${USAGE}\n`);
    return 2;
  }
  const asJson = flags["json"] === true;
  const { config, vault } = brainVerbContext(flags);

  try {
    switch (op) {
      case "ingest": {
        const quantityValueRaw = flags["quantity-value"] as string | undefined;
        if (
          quantityValueRaw === undefined &&
          (flags["quantity-unit"] !== undefined || flags["quantity-action"] !== undefined)
        ) {
          throw new UsageError(
            "--quantity-value is required when --quantity-unit or --quantity-action is provided",
          );
        }
        let valueKind: "text" | "quantity" = "text";
        let quantity: { value: number; unit: string | null; action: string | null } | undefined;
        if (quantityValueRaw !== undefined) {
          const qv = Number(quantityValueRaw);
          if (!Number.isFinite(qv))
            throw new UsageError("--quantity-value must be a finite number");
          valueKind = "quantity";
          quantity = {
            value: qv,
            unit: (flags["quantity-unit"] as string | undefined) ?? null,
            action: (flags["quantity-action"] as string | undefined) ?? null,
          };
        }
        const validFrom = flags["valid-from"] as string | undefined;
        const validUntil = flags["valid-until"] as string | undefined;
        // Validity windows (contract item 1): presence-gated passthrough;
        // the store refuses an unparseable or inverted window by name,
        // mapped to the usage failure class - a mistyped window is the
        // same kind of mistake as --since garbage or --limit 0.
        let result;
        try {
          result = appendClaimEvent(vault, {
            ts: (flags["ts"] as string | undefined) ?? isoSecond(new Date()),
            agent: resolveBrainAgent(flags, config),
            entity: requireString(flags, "entity"),
            aspect: requireString(flags, "aspect"),
            value: requireString(flags, "value"),
            valueKind,
            ...(quantity !== undefined ? { quantity } : {}),
            ...(validFrom !== undefined ? { validFrom } : {}),
            ...(validUntil !== undefined ? { validUntil } : {}),
            source: requireString(flags, "source"),
          });
        } catch (exc) {
          if (exc instanceof ClaimWindowRefusal) throw new UsageError((exc as Error).message);
          throw exc;
        }
        const body = {
          ok: true,
          entity: result.event.entity,
          aspect: result.event.aspect,
          value: result.event.value,
          path: result.path,
          ...(result.event.validFrom !== undefined ? { valid_from: result.event.validFrom } : {}),
          ...(result.event.validUntil !== undefined
            ? { valid_until: result.event.validUntil }
            : {}),
        };
        if (asJson) okJson(body);
        else ok(`claim recorded: ${body.entity} / ${body.aspect} = ${body.value}`);
        return 0;
      }
      case "slots": {
        const state = computeTruthStateWithConflicts(readClaimEvents(vault).events);
        const entityFilter = flags["entity"] as string | undefined;
        const slots = state.slots.filter(
          (s) => entityFilter === undefined || s.entity === normalizeEntityName(entityFilter),
        );
        if (asJson) {
          okJson({ events: state.events, slots });
        } else {
          ok(`truth: ${state.events} event(s), ${slots.length} slot(s)`);
          for (const s of slots) {
            const flag = s.contested ? " [CONTESTED]" : "";
            ok(`  ${s.entity} / ${s.aspect} = ${s.current.value}${flag}`);
            for (const h of s.history) ok(`    superseded: ${h.value} (${h.ts}, ${h.source})`);
          }
        }
        return 0;
      }
      case "conflicts": {
        const windowRaw = flags["window-days"] as string | undefined;
        const windowDays = windowRaw !== undefined ? Number(windowRaw) : undefined;
        if (windowDays !== undefined && (!Number.isInteger(windowDays) || windowDays <= 0)) {
          throw new UsageError("--window-days must be a positive integer");
        }
        const state = computeTruthStateWithConflicts(
          readClaimEvents(vault).events,
          windowDays !== undefined ? { windowDays } : {},
        );
        if (asJson) {
          okJson({ conflicts: state.conflicts });
        } else {
          ok(`conflicts: ${state.conflicts.length}`);
          for (const c of state.conflicts) {
            ok(
              `  ${c.entity} / ${c.aspect}: ${c.values.map((v) => v.value).join(" vs ")} ` +
                `(priority ${c.priority}, ${c.resolution})`,
            );
          }
        }
        return 0;
      }
      case "aggregate": {
        const state = computeTruthStateWithConflicts(readClaimEvents(vault).events);
        const result = aggregateQuantities(state.slots, {
          ...(typeof flags["action"] === "string" ? { action: flags["action"] } : {}),
          unit: (flags["unit"] as string | undefined) ?? null,
          ...(typeof flags["entity"] === "string" ? { entity: flags["entity"] } : {}),
        });
        if (asJson) {
          okJson({ ...result });
        } else {
          ok(
            `${result.action ?? "all actions"}${result.unit !== null ? ` (${result.unit})` : ""}: ` +
              `total ${result.total} across ${result.count} value(s)`,
          );
          for (const c of result.contributions) {
            ok(`  ${c.value}  ${c.entity} / ${c.aspect}  ${c.source}`);
          }
        }
        return 0;
      }
      case "collisions": {
        const windowRaw = flags["window-days"] as string | undefined;
        const windowDays = windowRaw !== undefined ? Number(windowRaw) : undefined;
        if (windowDays !== undefined && (!Number.isInteger(windowDays) || windowDays <= 0)) {
          throw new UsageError("--window-days must be a positive integer");
        }
        const collisions = detectAgentCollisions(readClaimEvents(vault).events, {
          now: new Date(),
          ...(windowDays !== undefined ? { windowDays } : {}),
        });
        if (asJson) {
          okJson({ collisions });
        } else {
          ok(`collisions: ${collisions.length}`);
          for (const c of collisions) {
            ok(`  ${c.entity}: ${c.agents.join(" + ")} (${c.claims} claim(s))`);
          }
        }
        return 0;
      }
      case "events": {
        // Bounds parse through the shared time-bounds wrapper - the same
        // parser the MCP events operation refuses with - mapped to the
        // INVALID_PARAMS-equivalent exit-2 usage error.
        let sinceMs: number | null;
        let untilMs: number | null;
        try {
          const bounds = parseTimeBounds(
            flags["since"] as string | undefined,
            flags["until"] as string | undefined,
          );
          sinceMs = bounds.sinceMs;
          untilMs = bounds.untilMs;
        } catch (exc) {
          if (exc instanceof SearchError) throw new UsageError(exc.message);
          throw exc;
        }
        const limitRaw = flags["limit"] as string | undefined;
        // A non-numeric --limit reaches the shared limit guard as NaN,
        // and that guard's refusal would stringify the NaN as "null" -
        // naming nothing the operator typed. Validate the flag is finite
        // here, before that message is composed, and name the raw value.
        if (limitRaw !== undefined && !Number.isFinite(Number(limitRaw))) {
          throw new UsageError(
            `--limit must be a positive integer, got ${JSON.stringify(limitRaw)}`,
          );
        }
        let limit: number;
        try {
          limit = claimEventLimit(limitRaw === undefined ? undefined : Number(limitRaw));
        } catch (exc) {
          throw new UsageError((exc as Error).message);
        }
        // The CLI runs at local reach (stdio child of the caller); the
        // owner-scope gate still binds the server-resolved identity. The
        // body is the shared claimEventsReport, so this surface answers
        // byte-identically to the MCP operation at the same query.
        const body = claimEventsReport(vault, resolveAgentName(config), TRANSPORT_REACH.local, {
          entity: flags["entity"] as string | undefined,
          sinceMs,
          untilMs,
          limit,
        });
        if (asJson) {
          okJson(body);
        } else {
          const rows = body.events as ReadonlyArray<{
            ts: string;
            entity: string;
            aspect: string;
            value: string;
            source: string;
          }>;
          ok(
            `events: ${body.total} matched, ${rows.length} shown` +
              `${body.truncated ? ", truncated" : ""}`,
          );
          for (const e of rows) {
            ok(`  ${e.ts}  ${e.entity} / ${e.aspect} = ${e.value}  ${e.source}`);
          }
        }
        return 0;
      }
      case "state": {
        // One agent-stated claim per invocation, through the same
        // grounded-claim core the MCP state operation calls: the payload
        // boundary refuses whole (unknown relation, missing text or
        // source) as the INVALID_PARAMS-equivalent usage error, and the
        // anchoring verdict - committed event or reported-back reasons -
        // is the answer.
        const body = (() => {
          try {
            const outcome = appendStatedClaims(
              vault,
              {
                claims: [
                  {
                    subject: requireString(flags, "subject"),
                    relation: requireString(flags, "relation"),
                    object: requireString(flags, "object"),
                  },
                ],
                text: requireString(flags, "text"),
                agent: resolveBrainAgent(flags, config),
                ts: isoSecond(new Date()),
                source: requireString(flags, "source"),
                // Answer-trust (task B5): an optional attribution id,
                // validated by the same payload-boundary refusal the MCP
                // state operation answers (mapped to the usage-error
                // class below); committed events echo it verbatim.
                ...(flags["sample-id"] !== undefined
                  ? { sampleId: flags["sample-id"] as string }
                  : {}),
              },
              { entities: statedClaimEntities(vault), configPath: config },
            );
            return {
              ok: true,
              operation: "state" as const,
              committed: outcome.committed.map((result) => ({ ...result.event })),
              ungrounded: outcome.ungrounded.map(({ claim, reasons }) => ({
                subject: claim.subject,
                relation: claim.relation,
                object: claim.object,
                reasons,
              })),
            };
          } catch (exc) {
            // Both refusal channels are mistyped-input refusals, so both
            // answer as the usage failure class - the same mapping the
            // ingest case applies, so the state verb never answers a
            // window the SOURCE record carries as an operational failure.
            if (exc instanceof StatedClaimsRefusal || exc instanceof ClaimWindowRefusal) {
              throw new UsageError((exc as Error).message);
            }
            throw exc;
          }
        })();
        if (asJson) {
          okJson(body);
        } else {
          if (body.committed.length > 0) {
            for (const row of body.committed) {
              const r = row as { entity: string; aspect: string; value: string };
              ok(`anchored claim recorded: ${r.entity} / ${r.aspect} = ${r.value}`);
            }
          }
          for (const u of body.ungrounded) {
            ok(
              `ungrounded claim reported back: ${u.subject} / ${u.relation} / ${u.object}` +
                ` (${u.reasons.join(", ")})`,
            );
          }
        }
        return 0;
      }
      case "sweep": {
        const maxRaw = flags["max-events"] as string | undefined;
        const maxEvents = maxRaw !== undefined ? Number(maxRaw) : CLAIM_EVENT_MAX_COUNT;
        if (!Number.isInteger(maxEvents) || maxEvents < 0) {
          throw new UsageError("--max-events must be a non-negative integer");
        }
        const outcome = sweepClaimEvents(vault, { maxEvents });
        if (asJson) okJson({ removed: outcome.removed, kept: outcome.kept });
        else ok(`truth sweep: removed ${outcome.removed}, kept ${outcome.kept}`);
        return 0;
      }
    }
  } catch (exc) {
    if (exc instanceof UsageError) {
      process.stderr.write(`brain truth ${op}: ${exc.message}\n${USAGE}\n`);
      return 2;
    }
    const message = `truth ${op} failed: ${(exc as Error).message ?? exc}`;
    if (asJson) {
      okJson({ ok: false, message });
      return 1;
    }
    return fail(message);
  }
}