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.5 KB
Raw Blame
import type { BrainLogEntry } from "../log.ts";
import { readAllLogEntries } from "../query.ts";
import { preferenceOwner } from "../owner-scoped-facts.ts";
import { memoryFolderPages, type MemoryFolder } from "../memory-pages.ts";
import { parsePreferenceMeta, parseRetiredMeta } from "../preference.ts";
import { parseSignalPage } from "../signal.ts";
import {
  BRAIN_LOG_EVENT_KIND,
  type BrainPreference,
  type BrainRetired,
  type BrainSignal,
} from "../types.ts";
import { normaliseWikilinkTarget } from "../wikilink.ts";
import { deepFreeze } from "./freeze.ts";
import type { AgentSourceContribution, AgentSourceProvider } from "./types.ts";

const PROVIDER_ID = "vault";

export const vaultAgentSourceProvider: AgentSourceProvider = Object.freeze({
  id: PROVIDER_ID,
  label: "Brain vault provenance",
  collect(vault: string): ReadonlyArray<AgentSourceContribution> {
    return collectVaultContributions(vault);
  },
});

function collectVaultContributions(vault: string): ReadonlyArray<AgentSourceContribution> {
  const signals = collectSignals(vault, "inbox", "processed", "archived");
  const signalAgentById = new Map(signals.map((signal) => [signal.id, signal.agent]));

  const contributions: AgentSourceContribution[] = [];
  for (const signal of signals) {
    contributions.push(signalContribution(signal));
  }
  for (const owned of collectPreferences(vault)) {
    contributions.push(preferenceContribution(owned, signalAgentById));
  }
  for (const entry of readAllLogEntries(vault)) {
    const contribution = logContribution(entry);
    if (contribution !== null) contributions.push(contribution);
  }
  contributions.sort((a, b) => {
    const byTimestamp = a.timestamp.localeCompare(b.timestamp);
    if (byTimestamp !== 0) return byTimestamp;
    const byKind = a.kind.localeCompare(b.kind);
    if (byKind !== 0) return byKind;
    return a.id.localeCompare(b.id);
  });
  return deepFreeze(contributions);
}

/** The signal pages of the folders: files when unswitched, the signal fold once switched. */
function collectSignals(vault: string, ...folders: MemoryFolder[]): BrainSignal[] {
  const signals: BrainSignal[] = [];
  for (const folder of folders) {
    const entries = memoryFolderPages(vault, folder, { regularFilesOnly: true }).toSorted((a, b) =>
      a.name.localeCompare(b.name),
    );
    for (const entry of entries) {
      if (!entry.name.startsWith("sig-") || !entry.name.endsWith(".md")) {
        continue;
      }
      try {
        const [meta, body] = entry.read();
        signals.push(parseSignalPage(meta, body, entry.path));
      } catch {
        continue;
      }
    }
  }
  return signals;
}

/**
 * A parsed preference or retired record with the owner token its page
 * declares (context-integrity-gates, Unit A). Both kinds carry `owner`
 * since A7 made retirement KEEP ownership, so the token is read from the
 * parsed record and resolved through the one shared rule - no second
 * frontmatter read, and no way for the two kinds to disagree.
 */
interface OwnedRecord {
  readonly record: BrainPreference | BrainRetired;
  readonly owner: string | null;
}

function collectPreferences(vault: string): OwnedRecord[] {
  return [
    ...collectPreferenceDir(vault, "preferences", "pref-"),
    ...collectPreferenceDir(vault, "retired", "ret-"),
  ];
}

function collectPreferenceDir(
  vault: string,
  folder: "preferences" | "retired",
  prefix: "pref-" | "ret-",
): OwnedRecord[] {
  const out: OwnedRecord[] = [];
  const entries = memoryFolderPages(vault, folder, { regularFilesOnly: true }).toSorted((a, b) =>
    a.name.localeCompare(b.name),
  );
  for (const entry of entries) {
    if (!entry.name.startsWith(prefix) || !entry.name.endsWith(".md")) {
      continue;
    }
    const path = entry.path;
    try {
      const [meta] = entry.read();
      const record =
        prefix === "pref-" ? parsePreferenceMeta(meta, path) : parseRetiredMeta(meta, path);
      out.push({ record, owner: preferenceOwner(record) });
    } catch {
      continue;
    }
  }
  return out;
}

function signalContribution(signal: BrainSignal): AgentSourceContribution {
  return deepFreeze({
    provider_id: PROVIDER_ID,
    kind: "signal",
    id: signal.id,
    agents: Object.freeze([signal.agent]),
    timestamp: signal.created_at,
    topic: signal.topic,
    ...(signal.scope !== undefined ? { scope: signal.scope } : {}),
    // Attribution written by the shared-namespace mirror, surfaced here so
    // a shared vault's roster can say which vault a contribution came from
    // (a-label-is-not-a-boundary, U5).
    ...(signal.origin_vault !== undefined ? { origin_vault: signal.origin_vault } : {}),
    title: signal.topic,
    text: [signal.topic, signal.signal, signal.principle, signal.raw ?? ""].join("\n").trim(),
    data: {
      signal: signal.signal,
      principle: signal.principle,
      ...(signal.source !== undefined ? { source: [...signal.source] } : {}),
      ...(signal.source_type !== undefined ? { source_type: signal.source_type } : {}),
      ...(signal.session_ref !== undefined ? { session_ref: signal.session_ref } : {}),
    },
  });
}

function preferenceContribution(
  owned: OwnedRecord,
  signalAgentById: ReadonlyMap<string, string>,
): AgentSourceContribution {
  const preference = owned.record;
  const agents = new Set<string>();
  for (const evidence of preference.evidenced_by) {
    const id = normaliseWikilinkTarget(evidence);
    if (!id) continue;
    const agent = signalAgentById.get(id);
    if (agent !== undefined) agents.add(agent);
  }
  return deepFreeze({
    provider_id: PROVIDER_ID,
    kind: "preference",
    id: preference.id,
    agents: Object.freeze([...agents].toSorted()),
    timestamp: preference.kind === "brain-retired" ? preference.retired_at : preference.created_at,
    topic: preference.topic,
    ...(preference.scope !== undefined ? { scope: preference.scope } : {}),
    ...(owned.owner !== null ? { owner: owned.owner } : {}),
    title: preference.topic,
    text: [preference.topic, preference.status, preference.principle].join("\n"),
    data: {
      status: preference.status,
      principle: preference.principle,
      evidenced_by: [...preference.evidenced_by],
      applied_count: preference.applied_count,
      violated_count: preference.violated_count,
      last_evidence_at: preference.last_evidence_at,
      confidence: preference.confidence,
    },
  });
}

function logContribution(entry: BrainLogEntry): AgentSourceContribution | null {
  const agents = entry.agent ? [entry.agent] : [];
  if (agents.length === 0) return null;
  const note = noteWriteContribution(entry, agents);
  if (note !== null) return note;
  return deepFreeze({
    provider_id: PROVIDER_ID,
    kind: "log",
    id: `${entry.timestamp}:${entry.eventType}`,
    agents: Object.freeze(agents),
    timestamp: entry.timestamp,
    topic: logTopic(entry),
    title: entry.eventType,
    text: logText(entry),
    data: {
      event_type: entry.eventType,
      body: cloneLogBody(entry.body),
    },
    ...privateMark(entry),
  });
}

/**
 * A `note-write` event as a contribution of kind `note`
 * (who-wrote-what, Task A / t_662f4e82).
 *
 * The whole point of the kind is that the ANSWER is the page: `path`
 * carries the note the write touched, so `brain_agent_query --kind note`
 * lists the notes an agent produced with no new reader and no second
 * index. `title` is the operation and the target together, because a
 * roster row that read only "note-write" would name the event kind and
 * not the work.
 *
 * A line missing its target is left to fall through to the generic log
 * contribution rather than being projected as a note with no page: a
 * pathless `note` row is one an operator could select and never open.
 */
function noteWriteContribution(
  entry: BrainLogEntry,
  agents: ReadonlyArray<string>,
): AgentSourceContribution | null {
  if (entry.eventType !== BRAIN_LOG_EVENT_KIND.noteWrite) return null;
  const target = entry.body["target"];
  const op = entry.body["op"];
  if (typeof target !== "string" || typeof op !== "string") return null;
  const writeId = entry.body["write_id"];
  return deepFreeze({
    provider_id: PROVIDER_ID,
    kind: "note",
    id: typeof writeId === "string" ? writeId : `${entry.timestamp}:${entry.eventType}`,
    agents: Object.freeze([...agents]),
    timestamp: entry.timestamp,
    title: `${op} ${target}`,
    text: logText(entry),
    path: target,
    data: {
      event_type: entry.eventType,
      body: cloneLogBody(entry.body),
    },
    ...privateMark(entry),
  });
}

/** The mark of an event read from the store's `private` partition, or nothing. */
function privateMark(entry: BrainLogEntry): { readonly fromPrivatePartition?: true } {
  return entry.fromPrivatePartition === true ? { fromPrivatePartition: true } : {};
}

function logTopic(entry: BrainLogEntry): string | undefined {
  const topic = entry.body["topic"];
  return typeof topic === "string" && topic.trim().length > 0 ? topic : undefined;
}

function logText(entry: BrainLogEntry): string {
  const parts: string[] = [entry.eventType];
  for (const [key, value] of Object.entries(entry.body)) {
    if (Array.isArray(value)) {
      parts.push(`${key}: ${value.join(", ")}`);
    } else {
      parts.push(`${key}: ${value}`);
    }
  }
  return parts.join("\n");
}

function cloneLogBody(
  body: Readonly<Record<string, string | ReadonlyArray<string>>>,
): Record<string, string | string[]> {
  const out: Record<string, string | string[]> = {};
  for (const [key, value] of Object.entries(body)) {
    if (typeof value === "string") {
      out[key] = value;
    } else {
      out[key] = [...value];
    }
  }
  return out;
}