Project memory

Project memory is durable, per-user and per-project notes that the agent can read and write across sessions. The relay stores them keyed by your account and a project_id; on each agent streaming leg the relay injects relevant notes server-side, and the agent itself uses the remember/recall tools to update them.

All memory endpoints require auth — identity comes from the Bearer token (see Overview & auth). project_id accepts the client-computed hash (sha256(git remote ?: root ?: cwd)[:12]); the legacy alias field project is also accepted. When the memory store is unavailable, endpoints return 503 with an error string and an empty payload of the usual shape.

POST /v1/memory/remember

Store one note.

curl -s https://<relay-host>/v1/memory/remember \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"note": "API uses cursor pagination, not offsets", "project_id": "a1b2c3d4e5f6", "author": "agent"}'
# {"ok": true}

author is optional. Invalid bodies return 400 {"error": "invalid_request", "message": "..."}.

Recall — GET or POST /v1/memory/recall

Return the project's notes as plain strings, oldest first. Both forms are equivalent:

curl -s "https://<relay-host>/v1/memory/recall?project_id=a1b2c3d4e5f6" \
  -H "Authorization: Bearer $TOKEN"

curl -s https://<relay-host>/v1/memory/recall \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"project_id": "a1b2c3d4e5f6"}'
# {"notes": ["API uses cursor pagination, not offsets", ...]}

GET /v1/memory/list

Structured notes for UI use. Omit project_id to list across all your projects. limit defaults to 50 (max 200); offset defaults to 0.

curl -s "https://<relay-host>/v1/memory/list?project_id=a1b2c3d4e5f6&limit=50&offset=0" \
  -H "Authorization: Bearer $TOKEN"

{
  "total": 3,
  "items": [
    {
      "id": "mem#<user>#<project>#<i>",
      "project_id": "a1b2c3d4e5f6",
      "note": "API uses cursor pagination, not offsets",
      "author": "agent",
      "created_at": 0,
      "pinned": false,
      "mem_type": "note"
    }
  ]
}

POST /v1/memory/delete

Body carries exactly one selector — priority order id → project_id → all:

• {"id": "mem#..."} — delete one note
• {"project_id": "..."} — delete one project's notes
• {"all": true} — the full GDPR cascade for the caller

curl -s https://<relay-host>/v1/memory/delete \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"project_id": "a1b2c3d4e5f6"}'
# {"ok": true, "deleted": 3}

REST aliases

The same operations are available REST-style:

How the agent uses memory

Inside a conversation the model never supplies a project or query argument: the remember tool takes only {"note"} and recall takes no parameters at all — the project is derived automatically from the working directory server-side. See Tool definitions for the exact schemas and which roles receive them.