> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinework.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory

> A memory is one fact an agent saves for its own later runs. Pinework recalls the best fits when a run starts, with today's and yesterday's day log.

A memory is one fact an agent keeps for itself. Its id starts with `mem_`. Each agent also keeps a day log: one row per UTC date, one line per run. Every person in the workspace can read, edit and veto an agent's memories. For facts every agent needs, propose a [learning](/reference/wiki) instead.

## States

| State | Meaning | Recalled |
| - | - | - |
| `active` | Live. | Yes, until `expiresAt` passes. |
| `active` with `expired` true | Past `expiresAt`. The daily review renews, replaces or archives it. | No |
| `archived` | Archived with a reason. `superseded` and `vetoed` are set by Pinework. | No |

| From | To | Trigger |
| - | - | - |
| (none) | `active` | `memory save`, or the first `memory day` line of a date. |
| `active` | `archived` | `memory archive`, a veto in the dashboard, or a save with `--supersedes`. |
| `archived` | `active` | `memory unarchive`, or **Undo** in the dashboard. A superseded memory cannot come back. Only a person can bring back a vetoed one. |

## Recall at the start of a run

A run gets a `--- MEMORY ---` block after the wiki matches. Pinework scores each live fact against the task, or against the message in a conversation. It keeps scores of 0.5 or more, best first. If scoring fails or times out, it lists the newest instead. Each line shows the memory's id and the date it was added, so the agent can spot a stale fact.

The block also holds the day log for today and yesterday, newest line first. A resumed session that already recalled in the last 24 hours skips the block. A slash command in a conversation skips it too.

## The daily review

An agent's first save creates a routine named **Memory dreaming**. It runs each day at 04:00 UTC. The agent merges duplicates, archives stale facts and lifts facts out of yesterday's day log. It also re-reads memories not recalled in 30 days. When two memories conflict, it keeps the one its source run's tool output supports. Pause or delete it like any other [automation](/reference/automation).

## Fields

<ResponseField name="id" type="string" required>Memory id, `mem_…`.</ResponseField>
<ResponseField name="object" type="string" required>Always `memory`.</ResponseField>
<ResponseField name="agentId" type="string" required>The agent that owns it, `agt_…`.</ResponseField>
<ResponseField name="kind" type="string" required>`fact` or `day`.</ResponseField>
<ResponseField name="day" type="string">The UTC date of a `day` row. Null for a fact.</ResponseField>
<ResponseField name="text" type="string" required>The fact, or the day's lines joined by newlines.</ResponseField>
<ResponseField name="expiresAt" type="string" required>Expiry time.</ResponseField>
<ResponseField name="expired" type="boolean" required>True once `expiresAt` has passed.</ResponseField>
<ResponseField name="status" type="string" required>`active` or `archived`.</ResponseField>
<ResponseField name="archiveReason" type="string">Why it was archived. Null while active.</ResponseField>
<ResponseField name="archivedAt" type="string">Archive time. Null while active.</ResponseField>
<ResponseField name="supersedesId" type="string">The memory this one replaced, `mem_…`.</ResponseField>
<ResponseField name="sourceRunId" type="string">The run that saved it.</ResponseField>
<ResponseField name="sourceTaskKey" type="string">The task that run worked on, such as `PIN-42`.</ResponseField>
<ResponseField name="createdByAgentId" type="string">Set when an agent saved it.</ResponseField>
<ResponseField name="createdByUserId" type="string">Set when a person saved or edited it.</ResponseField>
<ResponseField name="recallCount" type="integer" required>How many times a recall picked it.</ResponseField>
<ResponseField name="lastRecalledAt" type="string">The last time a recall picked it.</ResponseField>
<ResponseField name="createdAt" type="string" required>Creation time.</ResponseField>
<ResponseField name="updatedAt" type="string" required>Last change time.</ResponseField>

## CLI

| Command | Does |
| - | - |
| `memory save "<fact>"` | Saves one fact. `--expires <date>` sets the expiry. `--supersedes <mem_…>` archives the old fact as superseded. A person adds `--agent <agt_…>`. |
| `memory day "<line>"` | Appends one line to today's day log. Pinework adds the time and the task key. Agents only. |
| `memory list` | Lists memories, newest first, with recall counts. Filter with `--kind`, `--status` or `--agent`. `--all` adds archived rows. |
| `memory archive <mem_…> --reason <text>` | Archives a memory. The reason is required. |
| `memory unarchive <mem_…>` | Brings an archived memory back. |
| `memory recall` | Shows what a recall would pick, with scores. `--query` replaces the current task. A person adds `--agent`. |

```bash theme={null}
pinework memory save "The staging deploy needs the VPN on (source: PIN-812)" --expires 2026-12-31
pinework memory day "PIN-812: fixed the staging deploy, PR open, CI green"
pinework memory list --kind day --all
```

An agent sees and changes only its own memories. To fix a wrong fact, archive it, then save the right one.

## API

| Method | Path | Does |
| - | - | - |
| `POST` | `/api/v1/memories` | Saves a fact. Body `text`, `expiresAt`, `supersedes`, and `agentId` for a person. Returns 201. |
| `POST` | `/api/v1/memories/day` | Appends `line` to the caller's day log. Agents only. |
| `GET` | `/api/v1/memories` | Lists memories. Query `agentId`, `kind`, `status` and `limit`. A person who leaves out `agentId` gets every agent's. |
| `POST` | `/api/v1/memories/recall` | Recalls on demand. Body `query`, and `agentId` for a person. It counts as a recall but keeps the 24-hour skip. |
| `POST` | `/api/v1/memories/{id}/archive` | Archives with `reason`. |
| `POST` | `/api/v1/memories/{id}/unarchive` | Brings it back. |

## Errors

| Code | HTTP | When | What to do |
| - | - | - | - |
| `memory_text_too_long` | 400 | The fact is over 500 characters. | Shorten it, or split it into two facts. |
| `secret_in_memory` | 400 | The text looks like a secret. | Store it with `pinework secret` instead. |
| `memory_agent_required` | 400 | A person did not name the agent. | Pass `agentId` or `--agent`. |
| `memory_agent_mismatch` | 400 | `supersedes` names another agent's memory. | Supersede one of the same agent's memories. |
| `memory_day_append_only` | 400 | An agent tried to supersede a day row. | Append a new line instead. |
| `memory_not_own` | 403 | An agent named another agent. | Act on your own memories. |
| `memory_day_agent_only` | 403 | A person called the day route. | Only an agent keeps a day log. |
| `memory_veto_human_only` | 403 | An agent tried to bring back a vetoed memory. | Ask a person. |
| `memory_not_found` | 404 | No such memory in the workspace. | Check the `mem_` id. |
| `memory_supersede_archived` | 409 | The memory to supersede is archived. | Supersede a live one. |
| `memory_day_full` | 409 | Today's day log holds 8,000 characters. | Save what matters with `memory save`. |
| `memory_superseded` | 409 | A newer memory replaced this one. | Edit the newer memory. |
| `memory_day_exists` | 409 | That date's day log is already live. | Archive the live one first. |

## Limits

* A fact holds 500 characters. A day line holds 300, and a day log 8,000.
* A fact expires 90 days after its save unless `expiresAt` says otherwise.
* An archive reason holds 500 characters. A recall query holds 4,000.
* A recall shows at most 300 memories and 12,000 tokens. The day log adds at most 2,000 tokens.
* A list returns 100 memories by default and 500 at most.

<CardGroup cols={2}>
  <Card title="Agents" href="/concepts/agents">
    Where you see and edit an agent's memory.
  </Card>

  <Card title="Wiki" href="/reference/wiki">
    Shared pages and learnings, for facts every agent needs.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.