Skip to content

Self-hosted MCP server + dashboard giving Claude Code, Cursor & Hermes agents shared long-term memory over a git-backed markdown vault. Agent-native, Obsidian-compatible second brain — markdown RAG, no vector DB.

19.5 KB
Raw Blame
import {
  getBacklinks,
  getGraph,
  getNote,
  getTree,
  listNotes,
  listRecent,
  readVaultFile,
  searchNotes,
  vaultConventions,
} from "@/lib/vault/store";
import { effectiveAuthority, isUnrecognizedStatus, knownStatusWords } from "@/lib/vault/authority";
import { extractSection, listHeadings } from "@/lib/vault/parse";
import {
  appendNote,
  createFolder,
  deleteNote,
  guardOverwrite,
  moveNote,
  normalizeNotePath,
  supersedeNote,
  writeNote,
  writeNoteRaw,
} from "@/lib/vault/write";
import { hasRead, recordRead } from "./session";

// eslint-disable-next-line @typescript-eslint/no-explicit-any
type Args = Record<string, any>;

export interface Tool {
  name: string;
  description: string;
  inputSchema: Record<string, unknown>;
  /** True when the tool mutates the vault. Read-only tokens may not call these. */
  write?: boolean;
  handler: (args: Args) => Promise<unknown> | unknown;
}

const s = (description: string) => ({ type: "string", description });

/**
 * Resolve a note write from whichever convention the caller used, so brain_write and
 * brain_edit are interchangeable and forgiving:
 *   - `content`: full raw markdown (frontmatter included) → written as-is.
 *   - `body` that already starts with `---` (embedded frontmatter, no fm object) → raw.
 *   - `body` (+ optional `frontmatter` object) → structured write.
 * Throws on an empty write instead of silently creating an empty note.
 */
async function writeFromArgs(a: Args): Promise<string> {
  const p = String(a.path);
  const fm = a.frontmatter && typeof a.frontmatter === "object" ? a.frontmatter : undefined;
  const hasFm = !!fm && Object.keys(fm).length > 0;
  const bodyStr = typeof a.body === "string" ? a.body : "";
  const contentStr = typeof a.content === "string" ? a.content : "";
  const raw = contentStr.trim() !== "" ? contentStr : !hasFm && bodyStr.trim().startsWith("---") ? bodyStr : "";
  // strict: an agent that hand-writes unparseable YAML is refused, not silently accepted.
  // allowShrink: only when the caller explicitly says it means to replace the note.
  // allowConflict: only when the caller says a near-duplicate note is deliberate.
  const opts = { strict: true, allowShrink: a.overwrite === true, allowConflict: a.allow_conflict === true };
  if (raw.trim() !== "") return writeNoteRaw(p, raw, opts);
  if (bodyStr.trim() !== "" || hasFm) return writeNote(p, bodyStr, fm, opts);
  throw new Error(
    "Nothing to write. Pass `body` (markdown, + optional `frontmatter` object) or `content` (full raw markdown incl. frontmatter). Refusing to create an empty note.",
  );
}

/**
 * Report a write, warning loudly when the note's frontmatter will not do what the writer meant.
 * Both failures here are silent on read: unparseable YAML is discarded wholesale, and an
 * unrecognised `status:` falls through to `current`. Either way a note claiming to be the source
 * of truth ranks as an ordinary one. The agent that wrote it should hear about it now.
 */
async function writeResult(a: Args, toolName: string) {
  // Read-before-overwrite. The Curator loop has enforced this for a while; over MCP a coding agent
  // could still clobber a note it had never opened, protected only by the size heuristic in write.ts.
  const blocked = guardOverwrite(toolName, a.path ? normalizeNotePath(String(a.path)) : "", hasRead);
  if (blocked) throw new Error(blocked);
  const p = await writeFromArgs(a);
  const n = getNote(p);
  if (n?.frontmatterError) {
    return {
      ok: true,
      path: p,
      warning: `Frontmatter was written but cannot be parsed (${n.frontmatterError}). Its status, tags and title are being ignored. Usual cause: an unquoted ":" in a value — quote it, e.g. title: "Decision: X". Re-write the note to fix.`,
    };
  }
  if (isUnrecognizedStatus(n?.status)) {
    return {
      ok: true,
      path: p,
      warning: `status: "${n?.status}" is not a status this vault's ranking model recognises, so the note is being treated as plain \`current\`. If you meant it to outrank or be outranked by others, use one of: ${knownStatusWords().join(", ")}. Check for a typo.`,
    };
  }
  return { ok: true, path: p };
}

export const TOOLS: Tool[] = [
  {
    name: "brain_schema",
    description:
      "READ THIS FIRST, before searching or writing. Returns the vault's SCHEMA.md (folder taxonomy, frontmatter conventions, wikilink model, write protocol) AND a live description of this specific vault: its folders, the `status:` values actually in use, how search ranks notes by authority, and any integrity warnings. Vaults differ — never assume conventions, read them here.",
    inputSchema: { type: "object", properties: {} },
    handler: () => ({
      schema: readVaultFile("SCHEMA.md") ?? "(no SCHEMA.md in this vault)",
      conventions: vaultConventions(),
    }),
  },
  {
    name: "brain_search",
    description:
      "Keyword search across the vault. Returns `{ hits, excluded }`. Each hit has `path`, `title`, `folder`, `status`, `snippet`, and `authority`.\n\n" +
      "IMPORTANT — ranking is by keyword relevance, NOT by truth. A superseded document repeats the query words just as often as the live one, so it can outrank it. Every hit carries an `authority`: `authoritative` (source of truth — prefer it), `current`, `provisional` (draft/proposed — never quote as settled), `superseded`, `archived`. Rank order is a suggestion; `authority` is the signal.\n\n" +
      "`excluded` is the explainable-rejection list: notes that matched the query but were withheld because they are archived, superseded, or **expired** (past their `valid_until`), each with a `reason` (e.g. \"superseded by price-live\", \"expired 2026-06-01\"). **When you deliberately ignore a stale note, cite its `excluded` entry** — say what you skipped and why, instead of quoting it. If you need a withheld note, re-search with `includeInvalid: true` (superseded/expired) or `includeArchive: true`.\n\n" +
      "Before quoting a price, guarantee, contract term, or any other single-valued fact, open the `authoritative` note. If two live notes disagree on such a fact, that is a defect in the vault — report it rather than averaging them.",
    inputSchema: {
      type: "object",
      properties: {
        query: s("search query — a few keywords beat a full sentence"),
        limit: { type: "number", description: "max hits (default 20)" },
        folder: s("restrict to one top-level folder, e.g. 'decisions'"),
        includeArchive: { type: "boolean", description: "return archived notes as hits (default false → they go to `excluded`)" },
        includeInvalid: { type: "boolean", description: "return superseded/expired notes as hits, still demoted (default false → `excluded`)" },
      },
      required: ["query"],
    },
    handler: ({ query, limit, folder, includeArchive, includeInvalid }) =>
      searchNotes(String(query ?? ""), {
        limit: typeof limit === "number" ? limit : 20,
        folder: folder ? String(folder) : undefined,
        includeArchive: includeArchive === true,
        includeInvalid: includeInvalid === true,
      }),
  },
  {
    name: "brain_read",
    description:
      "Read a note: full markdown (frontmatter + body), its `authority`, and its backlinks. Path is vault-relative, e.g. 'clients/mks/mks.md'.\n\n" +
      "Pass `section` to read just one heading's content instead of the whole file — cheaper on long documents. If the heading isn't found you get the list of available headings back.\n\n" +
      "Always check the returned `authority` before acting on the content: `archived` and `superseded` notes are history, not instructions.",
    inputSchema: {
      type: "object",
      properties: {
        path: s("vault-relative path"),
        section: s("optional heading to extract, e.g. 'Pricing' — matches case-insensitively by prefix"),
      },
      required: ["path"],
    },
    handler: ({ path, section }) => {
      const n = getNote(String(path));
      if (!n) return { error: "not found", path };
      const eff = effectiveAuthority(n);
      const base = {
        path: n.path,
        title: n.title,
        status: n.status,
        authority: eff.authority,
        tags: n.tags,
        frontmatter: n.frontmatter,
        backlinks: getBacklinks(n.path).map((b) => b.path),
        ...(n.frontmatterError
          ? {
              warning: `This note's frontmatter is unparseable (${n.frontmatterError}), so its status, tags and title are being ignored — whatever it claims about itself is NOT in effect. Usual cause: an unquoted ":" in a value.`,
            }
          : eff.retired
            ? {
                warning: `This note is ${eff.reason} — it is history, not a current fact. Do not quote it as current; find the note that replaced it.`,
              }
            : {}),
      };
      // Only a full read authorises a later overwrite. A section read shows you one heading, not
      // what you would destroy — so it deliberately does not unlock brain_write/brain_edit.
      if (!section) {
        recordRead(n.path);
        return { ...base, content: n.raw };
      }

      const found = extractSection(n.body, String(section));
      if (found === null) {
        return { ...base, error: `section "${section}" not found`, sections: listHeadings(n.body) };
      }
      return { ...base, section: String(section), content: found, sections: listHeadings(n.body) };
    },
  },
  {
    name: "brain_list",
    description:
      "List every note with metadata (path, title, folder, type, tags, status, authority). Use to discover what exists. `authority` tells you which notes are source-of-truth and which are history.",
    inputSchema: { type: "object", properties: {} },
    handler: () =>
      listNotes().map((n) => ({
        path: n.path,
        title: n.title,
        folder: n.folder,
        type: n.type,
        tags: n.tags,
        status: n.status,
        authority: effectiveAuthority(n).authority,
      })),
  },
  {
    name: "brain_recent",
    description:
      "Notes changed most recently, newest first. Use to catch up on what humans or other agents have done since you last looked.",
    inputSchema: {
      type: "object",
      properties: {
        since: s("optional ISO date/time — only notes modified at or after this"),
        limit: { type: "number", description: "max results (default 20)" },
      },
    },
    handler: ({ since, limit }) => {
      const t = since ? Date.parse(String(since)) : NaN;
      return listRecent(Number.isNaN(t) ? undefined : t, typeof limit === "number" ? limit : 20).map((n) => ({
        path: n.path,
        title: n.title,
        folder: n.folder,
        status: n.status,
        authority: effectiveAuthority(n).authority,
        modified: new Date(n.mtimeMs).toISOString(),
      }));
    },
  },
  {
    name: "brain_tree",
    description: "Return the folder/file tree of the vault.",
    inputSchema: { type: "object", properties: {} },
    handler: () => getTree(),
  },
  {
    name: "brain_backlinks",
    description: "Notes that link to the given note.",
    inputSchema: { type: "object", properties: { path: s("vault-relative path") }, required: ["path"] },
    handler: ({ path }) => ({ backlinks: getBacklinks(String(path)).map((n) => n.path) }),
  },
  {
    name: "brain_graph",
    description: "The knowledge graph (nodes + edges from wikilinks and related:). Optional folder filter.",
    inputSchema: { type: "object", properties: { folder: s("optional folder filter") } },
    handler: ({ folder }) => getGraph(folder ? String(folder) : undefined),
  },
  {
    name: "brain_write",
    write: true,
    description:
      "Create or overwrite a note. PREFER `body` (markdown, no frontmatter) + `frontmatter` (an object): the YAML is serialised for you and always parses. Hand-writing frontmatter into `content` risks invalid YAML — a note whose frontmatter fails to parse loses its status, tags and title on every read, so a note claiming `status: locked` would rank as an ordinary one. Such a write is REJECTED. Follow SCHEMA.md: kebab-case path, dated names for daily/decisions, frontmatter with title/type/tags/status. Path vault-relative (e.g. decisions/foo-2026-07-09.md).\n\n" +
      "WHEN A FACT CHANGED, DON'T CREATE A DATED SIBLING. Writing `acme-pricing-2026.md` next to a live `acme-pricing.md` leaves two live notes disagreeing about one number, and the older one usually matches the query better — this is exactly how a retired price gets quoted. Such a write is REJECTED; use brain_supersede instead, which retires the old note and adds the new one in a single commit. `allow_conflict: true` overrides it when both notes genuinely belong.",
    inputSchema: {
      type: "object",
      properties: {
        path: s("vault-relative path, e.g. decisions/foo-2026-07-09.md"),
        body: s("markdown body (pair with `frontmatter`)"),
        frontmatter: { type: "object", description: "YAML frontmatter object: title, type, tags, status, related, ..." },
        content: s("full raw markdown incl. frontmatter — alternative to body+frontmatter"),
        overwrite: { type: "boolean", description: "confirm you mean to replace an existing note with much shorter content (default false)" },
        allow_conflict: { type: "boolean", description: "confirm a near-duplicate of a live note is deliberate — prefer brain_supersede (default false)" },
      },
      required: ["path"],
    },
    handler: async (a) => await writeResult(a, "brain_write"),
  },
  {
    name: "brain_edit",
    write: true,
    description:
      "Overwrite a note. Pass `content` (full raw markdown incl. frontmatter) — read first with brain_read, then write the whole file back. Also accepts `body` (+ optional `frontmatter`) like brain_write.",
    inputSchema: {
      type: "object",
      properties: {
        path: s("vault-relative path"),
        content: s("full raw markdown incl. frontmatter"),
        body: s("markdown body (alternative to content; pair with `frontmatter`)"),
        frontmatter: { type: "object", description: "YAML frontmatter object (with `body`)" },
        overwrite: { type: "boolean", description: "confirm you mean to replace an existing note with much shorter content (default false)" },
        allow_conflict: { type: "boolean", description: "confirm a near-duplicate of a live note is deliberate — prefer brain_supersede (default false)" },
      },
      required: ["path"],
    },
    handler: async (a) => await writeResult(a, "brain_edit"),
  },
  {
    name: "brain_append",
    write: true,
    description: "Append text to a note (creates it if missing).",
    inputSchema: {
      type: "object",
      properties: { path: s("vault-relative path"), text: s("text to append") },
      required: ["path", "text"],
    },
    handler: async ({ path, text }) => {
      const p = await appendNote(String(path), String(text ?? ""));
      const n = getNote(p);
      return n?.frontmatterError ? { ok: true, path: p, warning: `Frontmatter unparseable (${n.frontmatterError}) — status and tags ignored.` } : { ok: true, path: p };
    },
  },
  {
    name: "brain_move",
    write: true,
    description:
      "Move or rename a note. This is how you retire something: when a note stops being true, move it to an archive folder (see brain_schema → conventions.ranking.archiveFolders) rather than deleting it. Archived notes are demoted in search and excluded by default, so they stop misleading agents while the reasoning trail survives. Leave a pointer in the replacement note saying what superseded what.",
    inputSchema: { type: "object", properties: { from: s("current path"), to: s("new path") }, required: ["from", "to"] },
    handler: async ({ from, to }) => ({ ok: true, path: await moveNote(String(from), String(to)) }),
  },
  {
    name: "brain_create_folder",
    write: true,
    description: "Create a new folder in the vault (with a .gitkeep).",
    inputSchema: { type: "object", properties: { path: s("folder path") }, required: ["path"] },
    handler: async ({ path }) => ({ ok: true, path: await createFolder(String(path)) }),
  },
  {
    name: "brain_supersede",
    write: true,
    description:
      "Retire a fact and replace it, atomically. When a fact changes (a price, a term, a decision), DON'T just add a new note — the old value keeps matching searches and gets quoted. `brain_supersede(from, to)` marks the old note superseded in place (body preserved) and links it to the new one, in a single commit, so add-and-retire can't drift apart. After this, search withholds the old note with the reason \"superseded by <to>\".\n\n" +
      "`from` = the note being retired; `to` = the note that replaces it. If `to` doesn't exist yet, pass `body` (its markdown) and it's created; otherwise write `to` first, then supersede. `reason` is recorded on the old note. Prefer this over brain_move for a value that changed (move is for relocation).",
    inputSchema: {
      type: "object",
      properties: {
        from: s("the note being retired (vault-relative path)"),
        to: s("the note that replaces it (vault-relative path)"),
        reason: s("optional — why it was retired, e.g. 'repriced Q3'"),
        body: s("optional — markdown for `to` if it doesn't exist yet"),
      },
      required: ["from", "to"],
    },
    handler: async ({ from, to, reason, body }) => {
      const r = await supersedeNote(
        String(from),
        String(to),
        reason ? String(reason) : undefined,
        body ? String(body) : undefined,
      );
      return { ok: true, ...r, path: r.to };
    },
  },
  {
    name: "brain_capture",
    write: true,
    description:
      "Hand over a ROUGH note / brain-dump and let the vault file it. An agent loop reads SCHEMA.md, searches for what already exists, then deliberately creates a new note, appends to a matching one, or archives what this supersedes — and returns a manifest of every path it touched. It reads a note before overwriting it, and never deletes. Use when you have unstructured input and don't want to choose the path yourself; use brain_write when you do.",
    inputSchema: { type: "object", properties: { text: s("the rough note / brain dump to file") }, required: ["text"] },
    // Imported lazily: harness -> agent -> tools would otherwise be a module cycle.
    handler: async ({ text }) => {
      const { captureNote } = await import("@/lib/harness");
      return await captureNote(String(text ?? ""));
    },
  },
  {
    name: "brain_delete",
    write: true,
    description:
      "Delete a note (recoverable via git history). Prefer brain_move into an archive folder — deleting destroys the reasoning trail, archiving only removes it from search. Delete when the note is wrong or duplicated, archive when it is merely no longer true.",
    inputSchema: { type: "object", properties: { path: s("vault-relative path") }, required: ["path"] },
    handler: async ({ path }) => {
      await deleteNote(String(path));
      return { ok: true };
    },
  },
];

export const TOOL_MAP = new Map(TOOLS.map((t) => [t.name, t]));

/**
 * The tools a caller may see, given its scope.
 *
 * A read-only token never sees the write tools — it cannot be tempted to call them, and the model
 * never wastes a turn discovering it is forbidden. This is a claim the README, DEPLOY.md and
 * docs/curator.md all make out loud, so it lives here as one function the route calls and the
 * tests can pin, rather than as a filter expression inline in a request handler.
 *
 * The auto-filing harness stays hidden unless it's turned on — agents file notes themselves.
 */
export function visibleTools(canWrite: boolean, harnessOn: boolean): Tool[] {
  return TOOLS.filter((t) => {
    if (t.name === "brain_capture" && !harnessOn) return false;
    if (t.write && !canWrite) return false;
    return true;
  });
}