Each Agent Keeps Its Own Notes

// One file per agent, written by the harness, owned by that agent.
//
// Role: name, find and create the scratchpad an agent may append to. Nothing
// here reads a scratchpad, parses one, or decides what goes in it after the
// stub. The agent writes the body; this module writes the header and gets out
// of the way.
//
// The file lives under `knowledge-base/agents/`, one directory below the wiki.
// That placement is the whole of what separates working notes from curated
// pages, and `tools/kb-lint.mjs` reads it the same way: `listMarkdown` is
// non-recursive, so nothing under `agents/` is ever linted. See
// docs/decisions/0116.
//
// Invariants:
// - The file name carries the agentId AND the name slug, id first:
//   `agent-1-research.md`. Two agents both called "Research" get two files.
//   Record 0115.
// - Lookup is by id prefix, never by the current name. A rename does not move
//   the file, so recomputing the name from the record would name a file that is
//   not there. Record 0117.
// - Creating a scratchpad never blocks a start. Every failure is logged and
//   swallowed, and the caller gets `undefined` rather than an exception.
//   Record 0118.
// - The header is written schema-clean even though nothing lints it. Record
//   0116 says why both halves of that sentence are true at once.
// - No date is written into the body. `last-verified` is the only date, which
//   is `knowledge-base/_schema.md`'s rule and applies here whether or not the
//   lint is watching.

import { mkdirSync, readdirSync, writeFileSync } from "node:fs";
import path from "node:path";

/** @typedef {import("./roster.js").AgentRecord} AgentRecord */
/** @typedef {import("./log.js").Logger} Logger */

/**
* The directory scratchpads live in, under the knowledge base.
*
* A subdirectory rather than a prefix on a root-level file name. The wiki's
* schema says a page is one Markdown file at the root of the wiki directory and
* that the lint walks exactly those; a scratchpad at the root would be a page by
* that definition, whatever it was called, and would be judged as one.
*/
export const AGENT_NOTES_DIRNAME = "agents";

/**
* The volatility tier a scratchpad's header carries.
*
* `high` is chosen for a reader rather than for the lint, which never sees this
* file. An agent's working notes are the fastest-rotting thing in the
* repository: they are true for one session and stop being true when the agent
* is told something else.
*/
export const NOTES_VOLATILITY = "high";

/**
* The provenance tier a scratchpad's header carries.
*
* `extracted` is the honest one of the five for a stub. A tool wrote it and no
* person has read it against anything, which is the value's definition. It also
* pairs correctly with `verified-by: machine` under the schema's first pairing
* rule, and it is the one tier that does not demand a checker under the fourth.
*/
export const NOTES_PROVENANCE = "extracted";

/**
* Turn an agent's name into the slug half of its file name.
*
* Lower-case, runs of anything that is not a letter or a digit collapsed to one
* hyphen, no hyphen at either end. A name that leaves nothing behind, punctuation
* only, or a script this crude rule does not keep, becomes `agent`, so the file
* is still distinct: the id in front of the slug is what makes it so.
*
* @param {string} name
* @returns {string}
*/
export function slugify(name) {
const slug = name
  .toLowerCase()
  .replace(/[^a-z0-9]+/g, "-")
  .replace(/^-+|-+$/g, "");
return slug === "" ? "agent" : slug;
}

/**
* The file name for one agent's scratchpad. The id comes first.
*
* The id first is not a formatting choice. Two agents may be called "Research"
*, the roster trims names and caps their length and does nothing at all about
* uniqueness, and a file named `research.md` would be one file that two agents
* were both told was theirs. The first would write notes, the second would
* append to them, and each would read the other's as its own. The id is the only
* thing on a record that cannot collide, so the id is what the name rests on.
*
* Leading rather than trailing so a directory listing sorts by agent, and so a
* lookup can match on `${agentId}-` and cannot half-match a longer id:
* `agent-1-` is not a prefix of `agent-11-scout.md`, because the hyphen after
* the number is part of what is compared.
*
* @param {AgentRecord} agent
* @returns {string}
*/
export function scratchpadFileName(agent) {
return `${agent.agentId}-${slugify(agent.name)}.md`;
}

/**
* The scratchpad this agent already has, or undefined.
*
* By id prefix, never by the current name. `agent-rename` changes the record and
* leaves the file where it is (record 0117), so the name in the file is the name
* the agent had when the file was made and computing the name again would look
* for a file nobody wrote.
*
* A missing directory is not an error here. It means no scratchpad has ever been
* written, which is the answer.
*
* @param {string} dir The scratchpad directory.
* @param {string} agentId
* @returns {string | undefined} The absolute path, if one exists.
*/
export function findScratchpad(dir, agentId) {
const prefix = `${agentId}-`;
let names;
try {
  names = readdirSync(dir);
} catch {
  return undefined;
}
const found = names
  .filter((name) => name.startsWith(prefix) && name.endsWith(".md"))
  .sort();
return found.length === 0 ? undefined : path.join(dir, found[0]);
}

/**
* The whole of a fresh scratchpad: header, then one paragraph.
*
* The body says two things and no more. Whose notes these are, and that the
* agent appends below. It does not tell the agent what to write, because a
* harness that filled in the headings would be deciding what an agent's own
* notes are for.
*
* @param {AgentRecord} agent
* @param {string} today `YYYY-MM-DD`. An argument, so a test can assert on the
*   whole file and so the clock lives at one seam. The same argument-not-a-call
*   rule `tools/kb-lint.mjs` took for its own clock.
* @returns {string}
*/
export function scratchpadText(agent, today) {
return [
  "---",
  `owner: ${agent.agentId}`,
  `volatility: ${NOTES_VOLATILITY}`,
  `last-verified: ${today}`,
  "verified-by: machine",
  `provenance: ${NOTES_PROVENANCE}`,
  "---",
  "",
  `# ${agent.name}'s notes`,
  "",
  `These are ${agent.name}'s working notes, and nothing else writes below this`,
  "line. The harness wrote the header and this paragraph when the agent record",
  "was created; everything under it is the agent's own, appended as it goes.",
  "Every other file in the knowledge base is shared.",
  "",
].join("\n");
}

/**
* Make sure this agent has a scratchpad, and say where it is.
*
* Called when a record is created, including the orchestrator's, on a first
* boot, and again when a conversation starts, which is the repair path for a
* record that predates this module or whose file was deleted. It is idempotent:
* an agent that already has a file gets that file's path back and nothing is
* written.
*
* Nothing here throws. A read-only knowledge base, a full disk, a permission
* refusal, every one of them is a reason a person's agent should still start.
* A harness that refused to run an agent because it could not write the agent's
* notebook would have made the notebook more important than the agent, and the
* failure would arrive as a dead chat window rather than as a log line. So the
* failure is logged, `undefined` comes back, and the caller carries on without
* the notes sentences in the persona, which is the honest persona for an agent
* that has no file. Record 0118.
*
* @param {object} deps
* @param {AgentRecord} deps.agent
* @param {string} deps.dir The scratchpad directory, absolute.
* @param {string} deps.today `YYYY-MM-DD`.
* @param {Logger} deps.logger
* @param {{ mkdirSync: typeof mkdirSync, writeFileSync: typeof writeFileSync }}
*   [deps.fs] The two writes, injected so a test can make them fail. Reading is
*   `findScratchpad`'s and is already failure-tolerant.
* @returns {string | undefined} The scratchpad's absolute path, or undefined
*   when there is not one and could not be one.
*/
export function ensureAgentMemory({
agent,
dir,
today,
logger,
fs = { mkdirSync, writeFileSync },
}) {
const existing = findScratchpad(dir, agent.agentId);
if (existing !== undefined) return existing;

const file = path.join(dir, scratchpadFileName(agent));
try {
  fs.mkdirSync(dir, { recursive: true });
  fs.writeFileSync(file, scratchpadText(agent, today), "utf8");
} catch (cause) {
  logger.warn("notes.write_failed", {
    agentId: agent.agentId,
    file,
    message: String(cause),
  });
  return undefined;
}
logger.info("notes.created", { agentId: agent.agentId, file });
return file;
}

/**
* Today, as `YYYY-MM-DD`, in the local timezone.
*
* The one place in this module that reads a clock, and it is not called from
* anywhere below, `ensureAgentMemory` takes the date. Callers that have no
* opinion use this.
*
* @param {Date} [now]
* @returns {string}
*/
export function isoDay(now = new Date()) {
const pad = (/** @type {number} */ value) => String(value).padStart(2, "0");
return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
}

// What the turn actually did, collected by the harness.
//
// This is the file the module exists for. An agent's own account of its work is
// prose it wrote; this is a list the server assembled from the events it was
// already routing. When the two disagree, the agent says it updated the wiki
// and this list holds no write, the disagreement is the finding, and
// docs/PROTOCOL.md says which of the two the client trusts. Record 0119.
//
// Role: hold one turn's entries and hand back the capped list that rides out on
// the `result` frame's `did` field. It formats strings. It has never heard of a
// socket, a session, or the SDK.
//
// Invariants:
// - Every entry is written here. Nothing a model produced is copied into one:
//   the tool's name and its input come off the SDK's `tool_use` block, and the
//   outcome comes off the matching `tool_result`. A model can choose which tools
//   to call and cannot choose what this says about the call.
// - The collector hangs on events, not on the SDK. `conversation.js` feeds it
//   the same tool blocks it feeds the `activity` frames, so the scripted stream
//   produces real entries by the same route the real one does. Record 0121.
// - Entries are in the order the calls finished, which is the order a person
//   watching the activity feed saw them.
// - The list is capped, oldest kept. Record 0120.
// - A call that started and never finished is still an entry. A turn that was
//   interrupted halfway through a write is exactly the turn somebody needs the
//   record of.

import { SEND_TO_AGENT_WIRE_NAME } from "./agent-mail.js";

/**
* How many tool and delivery entries one turn's `did` may carry before the
* tail is replaced with a count.
*
* Twenty. A turn that ran more than twenty tools is a turn whose footer stopped
* being a footer, and the number has to be small enough that a client can render
* the list without deciding to hide it. Nothing in the protocol names a number;
* this one is the server's, and it is the only thing standing between a long
* agentic turn and a `result` frame the size of the transcript.
*
* The entries kept are the first ones, not the last. A turn's opening moves say
* what it set out to do; its closing moves are usually the model writing its
* answer. The tail is what is safe to summarise, which is also why the count
* goes at the end where a reader meets it after what survived.
*/
export const MAX_DID_ENTRIES = 20;

/** How the ending entry is spelled, per ending. */
export const ENDINGS = Object.freeze({
success: "turn ended: success",
interrupted: "turn ended: interrupted",
error: "turn ended: error",
});

/**
* The word appended to an entry whose call came back marked as an error.
*
* "failed" and not an exit code, because an exit code is not in what reaches
* this server. The bundled Claude Code process runs the tool and hands back a
* `tool_result` block; `is_error` is the whole of what that block says about how
* it went. A footer that printed `exit=1` would be inventing a number. Record
* 0122.
*/
export const FAILED_SUFFIX = ", failed";

/**
* The word appended to a call that was open when the turn ended.
*/
export const UNFINISHED_SUFFIX = ", unfinished";

---
owner: agent-1
volatility: high
last-verified: 2026-08-30
verified-by: machine
provenance: extracted
---

# Scout's notes

These are Scout's working notes, and nothing else writes below this
line. The harness wrote the header and this paragraph when the agent record
was created; everything under it is the agent's own, appended as it goes.
Every other file in the knowledge base is shared.