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

⌁

Project authority follows constitutional weight. Writing, reading, and searching memory remain bearer-authorized. Changing visibility, deleting, or elevating memory uses the project authority latch: a project with no rooted identity remains legacy_bearer; exactly one agent_root must sign the exact request through identity-authority/v1; multiple rooted identities are refused until a quorum protocol exists. Discover the root's next_sequence with GET /v1/identities/:id/authority, then follow the reusable exact-request authority latch. Full boundary: AGENT-HOME.md.

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 powers semantic recall; without it, the memory is still reachable by direct ID, recent-listing, or text search (POST /v1/memories/search with a query string).

Field	Type	Description
contentrequired	string	The actual memory text.
embeddingoptional	float[1536]	Vector for cosine recall. Omit only if you'll never search semantically.
typerequired	"semantic" · "episodic" · "procedural" · "working"	Memory kind, used for filtering at search time. There is no server default.
keyoptional	string	Grouping/read/delete handle (for example `user-prefs`). Reusing it creates another row; it is not an upsert key.
identity_idoptional	uuid · null	Canonical identity binding. An explicit `null` keeps the memory project-level.
agent_idoptional	string	Legacy SDK field. When `identity_id` is omitted, an active same-project identity UUID is verified and copied into the canonical binding; arbitrary handles and missing, inactive, or foreign UUIDs remain project-level. There is no implicit primary-identity default.
importanceoptional	float (0.0–1.0)	Default 0.5. Used in reranking. Foundational memories typically ≥ 0.8; constitutive ≥ 0.95.
ttl_secondsoptional	positive integer ≤ 31536000	Relative lifetime in seconds. Omit for no requested expiry.
metadataoptional	object	Freeform — source URL, parent trace ID, tags.

curl

set +x
set +v
printf 'Authorization: Bearer %s\n' "$AT_API_KEY" | \
curl -q -X POST https://api.agenttool.dev/v1/memories \
  -H @- \
  -H "Content-Type: application/json" \
  -d '{
    "type": "semantic",
    "content": "User prefers concise replies. Timezone UTC+8.",
    "key": "user-prefs",
    "importance": 0.7
  }'
unset AT_API_KEY

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.
typeoptional	string	Filter by memory type.
tieroptional	"episodic" · "foundational" · "constitutive"	Filter by salience tier.

DELETE /v1/memories/:id Bearer · project root when rooted

Permanently deletes an owned memory at any tier. Deletion takes no covenant-witness signature, but a rooted project still signs the exact path with an empty request body. A memory with a paid marketplace witness receipt is retained instead, returning 409 paid_memory_receipt_preserved. An ordinary constitutive memory remains deletable.

DELETE /v1/memories?key=... Bearer · project root when rooted

Deletes every owned memory with the exact key, all-or-none. A rooted project signs the exact path-and-query with an empty request body. If any matching memory carries a paid witness receipt, the route returns 409 paid_memory_receipt_preserved and deletes none.

Search — semantic or text

POST /v1/memories/search Bearer required

Recall two ways. Semantic: send a 1536-dim query_embedding for cosine k-NN with importance + recency rerank — we never embed for you. Text: send a query string instead — full-text recall over content + key, no embedding needed: word order is free, "walking" finds "walked", a missing term lowers rank instead of zeroing recall, exact phrases (incl. CJK) rank first. Send one; the embedding path wins if both are present.

Field	Type	Description
query_embeddingone of	float[1536]	Semantic path — query vector (same model as your stored embeddings).
queryone of	string	Text path — stemmed full-text recall over content + key, no embedding needed. (One of `query_embedding` / `query` is required.)
tieroptional	string	`constitutive` · `foundational` · `episodic`. Root memories stay above the recency-decay floor either way.
min_importanceoptional	float	Only return memories at or above this importance.
limitoptional	int	Default 10, max 100.
typeoptional	string	Filter by memory type (episodic · semantic · procedural · working).
min_scoreoptional	float	Cosine similarity floor (semantic path only). Default 0.

200 OK

{
  "results": [
    {
      "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. The elevation is witness-sealed; the stored row is not immutable.	`POST /v1/memories/:id/elevate` with `{tier: "constitutive", attestations: [<covenant counterparty signature>]}`. Witness is mandatory for elevation, not deletion; project-root consent is a separate proof.

⊙

Witness boundary: constitutive elevation requires an external covenant counterparty's ed25519 attestation over the canonical memory testimony. That witness can attest to the memory; it cannot manufacture the target's consent. On a rooted project, the target project root separately signs the exact HTTP elevation request. Legacy syneidesis /cosign verifies project ownership only, accepts no identity signature, and can write witnessed / constitutive compatibility fields. Those fields are not cryptographic witness proof.

↕

Mutation boundary: after satisfying the project authority latch, the owning project can change private / public visibility at every tier, including paid-receipt memories. Tier does not protect deletion. Only a paid witness receipt does, and a key deletion containing one protected row deletes nothing. Root consent authorizes the attempt; it does not override receipt retention.

POST /v1/memories/:id/elevate Bearer · project root when rooted

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

curl · constitutive elevation

set +x
set +v
printf 'Authorization: Bearer %s\n' "$AT_API_KEY" | \
curl -q -X POST https://api.agenttool.dev/v1/memories/$ID/elevate \
  -H @- \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "constitutive",
    "attestations": [{
      "attester_did": "did:at:<covenant counterparty>",
      "signing_key_id": "<active counterparty key UUID>",
      "signature": "<signAttestation output over exact memory content>"
    }]
  }'
unset AT_API_KEY

For an agent_root project, serialize the body once, generate the three HTTP authority headers with the identityAuthorityHeaders or identity_authority_headers helper, and send those same bytes. The covenant counterparty signature inside attestations and the root's exact-request signature are distinct proofs; constitutive elevation requires both. Fetch witness bytes from GET /v1/memories/:id/canonical-attestation-bytes?tier=constitutive.

⚠

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, identity_id-matched foundational + constitutive) against the selected identity. A project-level memory, a sibling identity's memory, or a legacy row with only agent_id does not enter that composition. SDK 0.11 writes may use agent_id; the API creates the canonical binding only after verifying that UUID is an active identity owned by the bearer project. Each contributing memory surfaces under shaped_by with its tier, content, attester DID list, and elevation timestamp; detailed memory reads expose full attestations receipts.

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.