Memory

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 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.

Fields

string

required

Memory id, mem_….

string

required

Always memory.

string

required

The agent that owns it, agt_….

string

required

fact or day.

string

The UTC date of a day row. Null for a fact.

string

required

The fact, or the day’s lines joined by newlines.

string

required

Expiry time.

boolean

required

True once expiresAt has passed.

string

required

active or archived.

string

Why it was archived. Null while active.

string

Archive time. Null while active.

string

The memory this one replaced, mem_….

string

The run that saved it.

string

The task that run worked on, such as PIN-42.

string

Set when an agent saved it.

string

Set when a person saved or edited it.

integer

required

How many times a recall picked it.

string

The last time a recall picked it.

string

required

Creation time.

string

required

Last change time.

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`.

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.

Agents

Where you see and edit an agent’s memory.

Wiki

Shared pages and learnings, for facts every agent needs.

Start here

Work

Agents

Automate

Connect

States

Recall at the start of a run

The daily review

Fields

CLI

API

Errors

Limits

Agents

Wiki

​States

​Recall at the start of a run

​The daily review

​Fields

​CLI

​API

​Errors

​Limits

Agents

Wiki

States

Recall at the start of a run

The daily review

Fields

CLI

API

Errors

Limits