Agent memory

{
  "$schema": "https://docs.nylorun.com/schemas/agent-manifest/v8.json",
  "manifestSchemaVersion": 8,
  "name": "releases",
  "harness": {
    "instructions": ["Help the team ship releases."],
    "memory": { "access": "read_write", "instructions": "Keep the team's release conventions." }
  },
  "runtime": { "kind": "none" }
}

import { readFile } from "node:fs/promises";

await client.agentManifests.save(JSON.parse(await readFile("releases.json", "utf8")));
await client.agents.put("teams/web/releases", { manifest: "releases" });

// Seed it: the agent finds this note in its first session.
await client.agents.memories.put(
  "teams/web/releases",
  "conventions/release.md",
  "---\ndescription: How the web team tags and ships a release\n---\n\nTag releases vX.Y.Z from main.\n",
);

harness.memory in an agent manifest gives each Agent made from it a memory: Markdown files under /memories that the agent reads and edits, and that stay with the Agent across its sessions, triggered turns and wakes, and its moves to new versions.

Turn it onCopy Anchor Link

Set memory wherever you write the harness section:

// releases is the Agent() from agents/releases/agent.ts.
await client.agentManifests.save({
  agent: releases,
  runtime: { kind: "none" },
  memory: { access: "read_write", instructions: "Keep the team's release conventions." },
});

A flow's harness section has no memory; the SDK refuses it for a flow.

Each turn reads harness.memory from the manifest version it runs, so a save that adds it turns memory on at each session's next turn on an Agent that tracks the manifest.

What the agent getsCopy Anchor Link

Our harness gives the agent one memory tool, the commands of Anthropic's memory tool: view, create, str_replace, insert, delete, and rename.

• Paths start with /memories/, end in .md, and are at most 512 characters. Folders are the prefixes of memory paths.
• An index opens each session: a line per memory, newest first, with the description from its YAML frontmatter when it has one, within memoryIndexLines (200) lines and memoryIndexBytes (25 KiB). When some are left out, the agent views folders for the rest. A compaction refreshes it.
• Instructions: our harness's memory rules, which tell the agent never to keep secrets, then harness.memory.instructions.
• Access holds for every turn, whoever starts it: a person, an app, a trigger, or a wake. With read_only, and for an agent used as a tool, a write fails with memory.forbidden; only the session's own agent writes.

Each call is a tool.completed with kind: "runtime": the Runtime serves it in the turn's own record, so a replayed turn applies a write once. The tool policy does not hold memory calls. A call that changed something writes memory.updated in the session (effectId, and changes, each { path, operation, version }) and agent.memory_updated on the Agent's stream, with its sessionId and turnId.

Where it livesCopy Anchor Link

Memories are the Agent's, kept in the Runtime with it:

Every change is a version that names who made it: agent:<manifest>@<version> with the session, turn, and trigger run for a turn, or the caller for an API write. Versions keep the content each change left.

Manage itCopy Anchor Link

const id = "teams/web/releases";
const { memories } = await client.agents.memories.list(id, { pathPrefix: "conventions" });

const memory = await client.agents.memories.get(id, "conventions/release.md");
await client.agents.memories.put(id, "conventions/release.md", `${memory.content}\nShip on Tuesdays.\n`, {
  contentSha256: memory.contentSha256,
});

const { versions } = await client.agents.memories.versions(id, { path: "conventions/release.md" });

A path may be given as conventions/release.md or /memories/conventions/release.md. put with contentSha256 writes only while the memory still has that content, and "" writes only while no memory has the path; otherwise it is 409 memory_conflict with the current memory. Reading takes agents:read, agents:write, or sessions:own for an Agent the caller reaches; writing takes agents:write. Request and response shapes are on Write a memory and List an Agent's memories.

In Studio, the Agent page's Memory tab lists each memory with its description, version, and who changed it last. A row opens its content and history, and Delete removes it.

Keep secrets outCopy Anchor Link

Our harness tells the agent never to keep secrets, but nothing scans what it writes. Read an Agent's memory before you share it, fork it, or give another person's sessions access to it.

LimitsCopy Anchor Link

They are Runtime limits, set per Tenant.

Next stepCopy Anchor Link