# Agent Memory

Cross-run persistent state for managed agents. Each row records what an agent learned, decided, or intends to revisit about a subject. Supports semantic search via vector embeddings. Required scopes: memory:read (GET/search), memory:write (POST/PATCH/DELETE).

**Base URL:** `https://api.trustpager.com/functions/v1/api/v1`

## Endpoints

### GET /memory

List agent memories for this workspace. Filter by subject_type, subject_id, kind, agent_registry_id, visibility, tag, linked entity, or time. Cursor-paginated (newest first).

**Scopes:** `memory:read` — [full detail](./memory/get-memory.md)

### POST /memory

Write an agent memory. If `key` is provided, behaves as upsert on (agent_registry_id, subject_type, subject_id, kind, key) -- re-using the same key UPDATES the existing memory rather than creating a duplicate. A soft-deleted memory with the same key is revived. Embedding auto-generated for semantic search.

**Scopes:** `memory:write` — [full detail](./memory/post-memory.md)

### GET /memory/:id

Fetch a single agent memory by its UUID. Returns NOT_FOUND if the memory is soft-deleted.

**Scopes:** `memory:read` — [full detail](./memory/get-memory-id.md)

### PATCH /memory/:id

Partial update on a memory. Can change content, metadata, tags, linked_entities, confidence, expires_at, or visibility. Re-embeds automatically if content changes.

**Scopes:** `memory:write` — [full detail](./memory/patch-memory-id.md)

### DELETE /memory/:id

Soft-delete a memory. Sets deleted_at; the row is preserved for audit but no longer surfaces in list/search/get. Reversible only via admin SQL.

**Scopes:** `memory:write` — [full detail](./memory/delete-memory-id.md)

### POST /memory/search

Semantic search over agent memories. Embeds the query and returns the top-K most similar memories by cosine similarity. Use for fuzzy/topic-based lookup ("have I discussed pricing with this contact?"). Use GET /memory for exact key lookup.

**Scopes:** `memory:read` — [full detail](./memory/post-memory-search.md)