Memory API — Long-Term User Facts

Store, search, optimize, and delete semantic vector memories that persist user preferences and facts across all agent conversations.

The Memory API manages long-term semantic memory for users. Unlike session history (which stores the conversation transcript), memories capture specific user facts and preferences that should persist across sessions — for example, “User prefers dark mode” or “User works in the finance department.” These facts are stored as vector embeddings in PostgreSQL and retrieved by semantic similarity during agent runs.

All endpoints scope their operations to a specific user via the userId parameter. When userId is omitted, the server resolves it from the authenticated principal.

All requests require a valid bearer token in the Authorization header.

---

Add a memory

POST /api/memories

Stores a new fact in the semantic memory store for the authenticated user. The content is embedded and indexed in pgvector for future retrieval.

content · string · required

The fact or preference to store. Write it as a natural language statement, e.g. "User prefers responses in bullet-point format.". The content field must not be blank.

message · string

Confirmation that the memory was saved.

cURL

curl --request POST \
  --url "http://localhost:8080/api/memories" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{ "content": "User prefers responses in bullet-point format." }'

Example response

{ "message": "Memory saved" }

---

Search memories

GET /api/memories?query=string

Performs a semantic vector search across the user’s memory store and returns the most relevant facts as plain strings. The search uses embedding similarity — you do not need exact keyword matches.

query · string · required

The natural language query to search for relevant memories.

[] · string[]

Array of memory content strings, ranked by semantic similarity to the query.

cURL

curl --request GET \
  --url "http://localhost:8080/api/memories?query=user+preferences" \
  --header "Authorization: Bearer {token}"

Example response

[
  "User prefers responses in bullet-point format.",
  "User prefers dark mode in all applications.",
  "User works in the finance department and focuses on equity research."
]

---

Delete memories

DELETE /api/memories

Deletes a specific list of memories by their document IDs. Pass an array of IDs in the request body. Returns 204 No Content on success.

[] · string[] · required

Array of memory document IDs to delete.

cURL

curl --request DELETE \
  --url "http://localhost:8080/api/memories" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '["mem_id_001", "mem_id_002", "mem_id_003"]'

Returns 204 No Content with an empty body on success.

---

Optimize memories

POST /api/memories/optimize?userId=string

Triggers an asynchronous background job that consolidates and deduplicates the user’s memory store using an LLM. Redundant or contradictory memories are merged or removed. Returns a jobId immediately.

userId · string

The user whose memories to optimize. Defaults to the authenticated principal when omitted.

jobId · string

The background job identifier. The optimization runs asynchronously — no webhook or polling endpoint is currently exposed for this job type.

cURL

curl --request POST \
  --url "http://localhost:8080/api/memories/optimize?userId=user_abc123" \
  --header "Authorization: Bearer {token}"

Example response

{ "jobId": "job_4c7e2a89-1b3d-4f5e-9c6a-xyz012abc345" }

Memory optimization runs asynchronously. If an optimization pass is already in progress for the same user when you call this endpoint, the system returns immediately without queuing a duplicate job.

---

Memory statistics

GET /api/memories/stats?userId=string

Returns aggregate statistics about the user’s memory store, such as total memory count and approximate token usage.

userId · string

The user whose statistics to retrieve. Defaults to the authenticated principal.

cURL

curl --request GET \
  --url "http://localhost:8080/api/memories/stats?userId=user_abc123" \
  --header "Authorization: Bearer {token}"

Example response

{
  "totalMemories": 42,
  "estimatedTokens": 1850,
  "userId": "user_abc123"
}

---

Memory topics

GET /api/memories/topics?userId=string

Returns a list of high-level topic clusters derived from the user’s memories. Topics are generated and cached by the memory optimization routine.

userId · string

The user whose topics to retrieve. Defaults to the authenticated principal.

[] · string[]

Array of topic label strings, e.g. "work preferences", "communication style", "domain expertise".

cURL

curl --request GET \
  --url "http://localhost:8080/api/memories/topics?userId=user_abc123" \
  --header "Authorization: Bearer {token}"

Example response

[
  "work preferences",
  "communication style",
  "domain expertise",
  "tool preferences",
  "scheduling habits"
]

Topics are refreshed by the optimize endpoint. If topics are stale or empty, trigger POST /api/memories/optimize to regenerate them from the current memory store.