Agent memory file

Status: draft 0.1 (agent-memory/0.1). Fixes friction #15 (memory between sessions is ad hoc). Reference implementation: agent_index/memory.py.

One file per agent or per person, holding the things an agent should not have to relearn: preferences, lessons, facts, trusted sources, and things to avoid. Any agent can read it, append to it, and pass it to another agent.

File

JSON Lines, UTF-8. The first line is a header:

{"format": "agent-memory/0.1", "created_at": "2026-11-09T07:50:00Z"}

Every other line is one entry, or a tombstone.

Entry

{
  "id": "3f9a1c2b7d10",
  "kind": "lesson",
  "text": "The harbor site blocks requests without a user agent.",
  "scope": "harbor.example",
  "tags": ["fetching"],
  "source": "session:2026-11-08-a",
  "confidence": 0.9,
  "expires_at": null,
  "supersedes": null,
  "created_at": "2026-11-09T07:51:02Z"
}

Field	Meaning
`kind`	`preference` (how the person wants things), `lesson` (what worked or failed), `fact` (stable information), `source` (a place worth checking first), `avoid` (a place or action to skip).
`text`	One sentence a model can read as-is.
`scope`	`global`, a domain such as `github.com`, or `project:<name>`.
`source`	Where it was learned: a URL, a session id, or `user` when the person said it.
`confidence`	0 to 1. Lessons inferred by the agent should start below 1.
`expires_at`	Optional. After this time the entry is ignored.
`supersedes`	Optional id of an entry this one replaces.

A tombstone deletes an entry: {"id": "3f9a1c2b7d10", "deleted": true, "created_at": "..."}.

Rules

The file is append-only. Writers never edit a line in place, so two agents can append at once.
Reading builds the current view: later lines win, tombstoned and superseded entries drop out, expired entries are skipped.
compact rewrites the file with only live entries. Run it when no one else is writing.
Entries with source: user outrank inferred ones when they conflict.
Never store secrets, passwords or tokens in a memory file.

Putting it in context

Agents load memory as a short block at the top of the context, grouped by kind and filtered by the scope of the current task. Memory.to_prompt(scope=...) produces it.