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
6.9 KB
Raw Blame
import { isOwnerVisible, normalizeAgentScope } from "../../graph/agent-scope.ts";
import type { ArtifactRefView } from "../artifact-ref-view.ts";
import { collectAgentSourceContributions, summarizeAgentSources } from "./registry.ts";
import { summarizeAgentContributions } from "./summary.ts";
import type {
  AgentSourceContribution,
  AgentSourceContributionKind,
  AgentSourceSummary,
} from "./types.ts";

export interface AgentSourceQueryOptions {
  readonly agents?: ReadonlyArray<string>;
  readonly topic?: string;
  readonly query?: string;
  readonly kind?: AgentSourceContributionKind;
  readonly limit?: number;
  /**
   * Owner scope of the caller (context-integrity-gates, Unit A). A
   * contribution whose page declares a different owner is withheld;
   * ownerless contributions - including every log event, which has no
   * page to own it - always match. Absent filters nothing, so an
   * unscoped call is byte-identical to before.
   */
  readonly ownerScope?: string;
  /**
   * A reference view each contribution must also pass, typically the
   * caller's reach (`reachView`). It is asked over the contribution's id,
   * the page a `note` contribution names and every string of an event body,
   * which carries the written page's digest and size. Like the owner
   * scope it runs before the roster is folded, so a withheld contribution
   * is neither listed nor counted. Absent filters nothing.
   */
  readonly view?: ArtifactRefView;
}

export interface AgentSourceQueryFilters {
  readonly agents: ReadonlyArray<string>;
  readonly topic: string | null;
  readonly query: string | null;
  readonly kind: AgentSourceContributionKind | null;
  readonly limit: number;
}

export interface AgentSourceQueryResult {
  readonly mode: "agent-query";
  readonly filters: AgentSourceQueryFilters;
  readonly available_agents: ReadonlyArray<AgentSourceSummary>;
  readonly unknown_agents: ReadonlyArray<string>;
  readonly total_matched: number;
  readonly returned: number;
  readonly contributions: ReadonlyArray<AgentSourceContribution>;
  readonly summary: string;
}

const DEFAULT_LIMIT = 50;

export function queryAgentSources(
  vault: string,
  opts: AgentSourceQueryOptions = {},
): AgentSourceQueryResult {
  const ownerScope = normalizeAgentScope(opts.ownerScope);

  // The ownership filter runs FIRST, and the roster is folded from what
  // survives it. Listing the agents independently of the filter reported
  // the withheld contributions' topics verbatim and counted them, so a
  // correct `total_matched` sat next to a roster that named exactly what
  // it withheld (context-integrity-gates, A5). An unscoped call filters
  // nothing, so the roster is the same array it always was.
  // A contribution read from the store's `private` partition is withheld
  // below local reach whatever it names, and the mark itself never leaves.
  const withholdsPrivate = opts.view?.withholdsPrivate === true;
  const visible = collectAgentSourceContributions(vault)
    .filter(
      (contribution) =>
        !(withholdsPrivate && contribution.fromPrivatePartition === true) &&
        (ownerScope === null || isOwnerVisible(contribution.owner ?? null, ownerScope)) &&
        (opts.view === undefined || opts.view.row(...contributionRefs(contribution))),
    )
    .map(withoutPrivateMark);
  const availableAgents = summarizeAgentSources(visible);
  const availableIds = new Set(availableAgents.map((a) => a.id));
  const selectedAgents = normalizeAgents(
    opts.agents,
    availableAgents.map((a) => a.id),
  );
  const selectedSet = new Set(selectedAgents);
  const unknownAgents = selectedAgents.filter((agent) => !availableIds.has(agent));
  const topic = normalizeTextFilter(opts.topic);
  const query = normalizeTextFilter(opts.query);
  const limit = normalizeLimit(opts.limit);

  const matched = visible.filter((contribution) => {
    if (!contribution.agents.some((agent) => selectedSet.has(agent))) return false;
    if (opts.kind !== undefined && contribution.kind !== opts.kind) return false;
    if (topic !== null && contribution.topic !== topic) return false;
    if (query !== null && !matchesText(contribution, query)) return false;
    return true;
  });
  const returned = Object.freeze(matched.slice(0, limit));

  return Object.freeze({
    mode: "agent-query",
    filters: Object.freeze({
      agents: Object.freeze(selectedAgents),
      topic,
      query,
      kind: opts.kind ?? null,
      limit,
    }),
    available_agents: availableAgents,
    unknown_agents: Object.freeze(unknownAgents),
    total_matched: matched.length,
    returned: returned.length,
    contributions: returned,
    summary: summarizeAgentContributions(returned, selectedAgents),
  });
}

function normalizeAgents(
  agents: ReadonlyArray<string> | undefined,
  fallbackAgents: ReadonlyArray<string>,
): string[] {
  const raw = agents === undefined || agents.length === 0 ? fallbackAgents : agents;
  const out: string[] = [];
  const seen = new Set<string>();
  for (const value of raw) {
    const agent = value.trim();
    if (!agent || seen.has(agent)) continue;
    seen.add(agent);
    out.push(agent);
  }
  return out;
}

function normalizeTextFilter(value: string | undefined): string | null {
  if (value === undefined) return null;
  const trimmed = value.trim();
  return trimmed.length > 0 ? trimmed : null;
}

function normalizeLimit(value: number | undefined): number {
  if (value === undefined) return DEFAULT_LIMIT;
  if (!Number.isInteger(value) || value < 1) {
    throw new TypeError("agent-source query limit must be a positive integer");
  }
  return value;
}

function matchesText(contribution: AgentSourceContribution, query: string): boolean {
  const needle = query.toLowerCase();
  const fields = [
    contribution.id,
    contribution.title,
    contribution.text,
    contribution.topic ?? "",
    contribution.scope ?? "",
    contribution.agents.join(" "),
  ];
  return fields.some((field) => field.toLowerCase().includes(needle));
}

/**
 * The references a contribution answers for: its id (a preference or
 * signal id resolves to that Brain page), the page a `note` contribution
 * names, and every string of the event body it echoes.
 */
function contributionRefs(
  contribution: AgentSourceContribution,
): ReadonlyArray<string | undefined> {
  const refs: Array<string | undefined> = [contribution.id, contribution.path];
  const body = contribution.data["body"];
  if (body !== null && typeof body === "object") {
    for (const value of Object.values(body as Record<string, unknown>)) {
      for (const item of Array.isArray(value) ? value : [value]) {
        if (typeof item === "string" && item.length > 0) refs.push(item);
      }
    }
  }
  return refs;
}

/** The contribution as it leaves this module: without the private mark. */
function withoutPrivateMark(contribution: AgentSourceContribution): AgentSourceContribution {
  if (contribution.fromPrivatePartition === undefined) return contribution;
  const { fromPrivatePartition: _mark, ...rest } = contribution;
  return Object.freeze(rest);
}