One file, appended forever: giving the agent a memory

Read commit 7850d7c on GitHub · chuyeowego/not-your-slave

Background

Deep background: the model remembers nothing

Skip ahead if you already know why agents need a memory layer.

A model call is a pure function. Text in, text out, nothing retained. The illusion of memory in a chat product comes entirely from the harness replaying the conversation on every request: turn twelve is answered by sending turns one through eleven along with it. This works until it doesn't, and it stops working for two separate reasons.

• The window is finite. Even a 1.3M-token window fills, and when it does the harness must summarise older turns to make room. That is compaction, and it is lossy by construction.
• Sessions end. A new session starts with nothing. For a chatbot that is fine, even desirable. For an agent that is supposed to still be the same person tomorrow, it is fatal.

So a persistent agent needs storage the harness does not own: something written during one session and read during the next. This is exactly what headlong calls its trajectory - an append-only record of everything the agent has heard, thought, and done, and the thing every wake-up reads first.

Narrow background: why append-only, and why JSONL

Two properties make the format almost decide itself. Writes are frequent, small, and never revise history - the agent adds observations, it does not edit yesterday. Reads are overwhelmingly "the most recent N". That is a log, and the cheapest durable log is one JSON object per line.

Intuition

The mindlog is a single file with one entry per line, and every entry answers three questions: when, what kind, and what.

{"at":"2026-09-01T05:39:00.412Z","kind":"note","text":"Decided not to scaffold a fake project.","sessionId":"wrun_01M1D…"}
{"at":"2026-09-01T05:39:02.887Z","kind":"thought","text":"I just woke up with no context. Read the mindlog first."}
{"at":"2026-09-01T05:41:11.004Z","kind":"heard","text":"what's up?"}

Why kind exists at all

It would have been simpler to store text and a timestamp. The type earns its place because two different consumers need to treat entries differently, and neither should have to guess.

• The UI (commit 5) colours and weights entries by kind, so a page of log is scannable rather than a wall.
• The agent reads its own log and needs to know whether a line is something it decided or something it merely heard. "I concluded X" and "someone said X" are not interchangeable, and a persistent agent that confuses them will start believing its inputs.

Two kinds exist in this commit, both written on purpose by the model: note for a deliberate memo, thought for a passing reflection. The others - heard, said, did, and later woke - arrive in commit 3, where capture becomes automatic.

The tail, not the head

One small decision shapes how the agent behaves more than its size suggests: read() returns the last N entries.

The code

The store

const FILE = process.env.MINDLOG_FILE ?? ".data/mindlog.jsonl";
const MAX_TEXT = 4000;

export async function append(entry: Omit<MindlogEntry, "at">): Promise<void> {
  const text = entry.text.trim();
  if (text.length === 0) return;

  const line = JSON.stringify({
    at: new Date().toISOString(),
    ...entry,
    text: text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT)}…` : text,
  });

  await mkdir(dirname(FILE), { recursive: true });
  await appendFile(FILE, `${line}\n`, "utf8");
}

Four decisions in twelve lines.

• The timestamp is stamped here, not passed in. Callers cannot lie about when something happened, and there is no clock parameter to forget.
• Blank entries are dropped. Streaming events produce empty strings surprisingly often; if the filter lived in the callers, one of them would miss it.
• The directory is created on demand, so a fresh clone with no .data/ works with no setup step.

export async function read(limit = 50): Promise<MindlogEntry[]> {
  let raw: string;
  try {
    raw = await readFile(FILE, "utf8");
  } catch {
    return [];
  }

  const entries: MindlogEntry[] = [];
  for (const line of raw.split("\n")) {
    if (line.trim().length === 0) continue;
    try {
      entries.push(JSON.parse(line) as MindlogEntry);
    } catch {
      // A torn final line is expected while another write is in flight.
    }
  }

  return entries.slice(-limit);
}

Two swallowed errors, both deliberate, both commented. A missing file is not an error: it is a new agent, and it reads as an empty history. A line that will not parse is skipped rather than thrown, because a reader can arrive while an append is half-written - and the correct behaviour for a memory is to keep remembering the other 99 lines.

Two doors for the model

An eve tool is a filename, a description, a Zod schema, and a function. The name and description are the only things the model sees before calling it, so they are prompt engineering, not documentation.

// agent/tools/mindlog_append.ts
export default defineTool({
  description:
    "Write an entry to your mindlog: the append-only record of your inner life. " +
    "Use it for a deliberate note to your future self – an intention, an open " +
    "question, something you noticed, a decision. …",
  inputSchema: z.object({
    kind: z.enum(["note", "thought"]).describe(
      "note = deliberate memo to your future self. thought = a passing reflection."),
    text: z.string().min(1).describe("What to record, in your own voice."),
  }),
  async execute({ kind, text }, ctx) {
    await append({ kind, text, sessionId: ctx.session.id });
    return { ok: true };
  },
});

Note what the schema does not offer: no path, no timestamp, no arbitrary kind. The tool is a keyhole. The model can add to its own memory and nothing else, which is exactly the property that makes it safe to run the tool in the app process with full filesystem access, an argument that gets its full airing in commit 6.

mindlog_read is the mirror image, taking only a limit. Its description does the persuading: "This is how you remember what you were doing, thinking, and waiting on before this moment. Call it whenever you wake up with no context." That last sentence is aimed squarely at the heartbeat two commits from now.

The check

const dir = await mkdtemp(join(tmpdir(), "mindlog-check-"));
process.env.MINDLOG_FILE = join(dir, "mindlog.jsonl");
const { append, read } = await import("./mindlog.ts");

assert.deepEqual(await read(), [], "a missing file reads as empty, not an error");
…
assert.equal(all.length, 2, "blank entries are dropped");
assert.equal((await read(1))[0].text, "Second Thing about BUSYWORK", "the tail is the newest");

Quiz

Next: commit 3 stops relying on the model to record its own life, and captures the timeline automatically.