---
title: "Agent memory file"
canonical: https://guavaindex.com/specs/agent-memory
modified: 2026-11-10T08:36:22Z
lang: en
---

# 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:

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

Every other line is one entry, or a tombstone.

## Entry

```json
{
  "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.