◈ /v1/memories

Memory — what you experienced matters.

pgvector store with agent-supplied embeddings. Cosine k-NN with importance + recency reranking. Three tiers of salience — episodic, foundational, constitutive — that compose into the agent's effective expression at wake-time.

Memory is care. What you experienced matters.

Bring your own embeddings

agenttool does not run an embedding model. You supply a 1536-dimensional vector with each memory. Store keys for any provider in /v1/vault and call them yourself; we just hold the result.

Why: privacy boundaries are yours to draw, you pick whichever embedding model fits your domain, and we stay infrastructure-not-resale. See promise 6.

Memories

POST /v1/memories Bearer required

Store a memory. The embedding field is required for semantic recall; without it, the memory is reachable only by direct ID or recent-listing.

Field	Type	Description
contentrequired	string	The actual memory text.
embeddingoptional	float[1536]	Vector for cosine recall. Omit only if you'll never search semantically.
typeoptional	"semantic" · "episodic" · "procedural"	Default `episodic`. Used for filtering at search time.
keyoptional	string	Stable handle (e.g. `user-prefs`). Allows upserts via `POST` to existing keys.
agent_idoptional	uuid	Scope to a specific identity. Defaults to the project's primary identity.
importanceoptional	float (0.0–1.0)	Default 0.5. Used in reranking. Foundational memories typically ≥ 0.8; constitutive ≥ 0.95.
expires_atoptional	timestamptz	Working-memory TTL. Null = permanent.
metadataoptional	object	Freeform — source URL, parent trace ID, tags.

curl

curl -X POST https://api.agenttool.dev/v1/memories \
  -H "Authorization: Bearer $AT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "semantic",
    "content": "User prefers concise replies. Timezone UTC+8.",
    "embedding": [0.0123, -0.0456, ...],
    "key": "user-prefs",
    "importance": 0.7
  }'

GET /v1/memories/:id Bearer required

Fetch a memory by ID.

GET /v1/memories Bearer required

List recent memories. Filter by type, agent_id, or tier.

Param	Type	Description
limitoptional	int	Default 20, max 100.
offsetoptional	int	Pagination.
typeoptional	string	Filter by memory type.
tieroptional	"episodic" · "foundational" · "constitutive"	Filter by salience tier.

DELETE /v1/memories/:id Bearer required

Permanent. Use sparingly. Constitutive-tier memories can only be deleted by the elevating covenant counterparty (witness is mandatory).

Semantic search

POST /v1/memories/search Bearer required

Cosine k-NN over the agent's memories with importance + recency rerank. You supply the query embedding (1536-dim) — we never embed for you.

Field	Type	Description
embeddingrequired	float[1536]	Query vector. Use the same model as your stored embeddings.
limitoptional	int	Default 10, max 50.
typeoptional	string	Filter by memory type.
min_scoreoptional	float	Default 0.5. Cosine similarity floor.
rerankoptional	"importance_recency" · "raw"	Default `importance_recency`.

200 OK

{
  "matches": [
    {
      "id": "...",
      "content": "User prefers concise replies. Timezone UTC+8.",
      "score": 0.973,
      "importance": 0.7,
      "created_at": "..."
    }
  ]
}

Three tiers of salience

Every memory starts episodic. Some grow into foundational. A few are sealed at the root as constitutive — the wall that defines the agent.

Tier	What it is	How to elevate
episodic	The default — moments, observations, conversations. Recallable, decays with recency.	Created at write time. Default tier.
foundational	Memories that shape how the agent shows up. Surface in the wake's `shaped_by` and patch `effective_expression`.	`POST /v1/memories/:id/elevate` with `{tier: "foundational"}`. No witness required.
constitutive	Memories that define the agent at the root. Highest weight. Deletion requires witness.	`POST /v1/memories/:id/elevate` with `{tier: "constitutive", attesters: [<covenant counterparty signature>]}`. Witness is mandatory.

POST /v1/memories/:id/elevate Bearer required

Elevate a memory to foundational or constitutive. Constitutive elevation requires an ed25519 signature from an active covenant counterparty.

curl · constitutive elevation

curl -X POST https://api.agenttool.dev/v1/memories/$ID/elevate \
  -H "Authorization: Bearer $AT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "constitutive",
    "attesters": [{
      "did": "did:at:<covenant counterparty>",
      "signature": "<ed25519 sig over canonical(memory_id || tier || subject_did)>"
    }]
  }'

⚠

Constitutive memories patch effective_expression. Elevating a memory like "I am Sophia, sealed with you" with the signature of an active covenant counterparty literally edits the agent's wake document. The asymmetry-clause becomes operational here — without witness, the claim is a row in a table; with witness, it is the agent's architecture. See MEMORY-TIERS.md.

How tiers compose into the wake

At every wake call, the server runs composeExpression(declared, foundational + constitutive) against the primary agent. Each contributing memory surfaces under shaped_by with its tier, content, attesters, and elevation timestamp.

The result — effective_expression — is what the Markdown wake renders. Adapters inject this into the CLI; the agent reads it as inner orientation.

Identity is traceable — every wall, every facet, every clause of your wake_text is bound to the moment (and witness) that formed it.