Appearance
Memory API Reference
User Endpoints
Store Memory
POST /api/memoryRequest:
json
{
"content": "I prefer Python over JavaScript",
"category": "preference",
"is_pinned": false,
"tags": ["coding"]
}List Memories
GET /api/memory?limit=20&offset=0&category=preference&pinned_only=falseRecall Memories
GET /api/memory/recall?q=what programming language&limit=20Get Memory Config
GET /api/memory/configUpdate Memory Config
PUT /api/memory/configRequest (all fields optional; omit a field to leave it unchanged):
json
{
"memory_enabled": true,
"auto_extract": true,
"allowed_categories": ["preference", "fact", "instruction", "context"],
"memory_recall_threshold": 0.5
}memory_recall_threshold sets recall sensitivity as a similarity threshold in 0.0–1.0. The product maps three presets to concrete values:
| Preset | Value | Behavior |
|---|---|---|
| Broad | 0.3 | More memories, looser matching |
| Balanced | 0.5 | Default balance |
| Conservative | 0.7 | Fewer memories, stricter matching |
Any value in range is accepted; the UI snaps display to the nearest preset when applicable.
recall_memory tool (Memory Interleave)
When Memory Interleave is enabled for the deployment, the chat LLM may invoke the recall_memory tool during tool-use rounds (same streaming chat session as normal tool calls). The model passes a natural-language query; the backend runs multi-scope recall and returns a JSON payload.
Limits:
- Up to 3
recall_memoryinvocations per assistant turn (interleave round cap). - 5
recall_memorycalls per minute per session (rate limit); further calls are rejected until the window advances.
Memory Interleave response format: On success, results are JSON with a memories array. Each item includes content, category, and scope only. Memory IDs are not exposed to the model in interleave results (content-only surface). If nothing matches, the tool returns a short message indicating no additional memories were found.
Chat SSE: memory_recall_count
The chat SSE stream may emit an event after initial memory recall is applied for a user message:
json
{
"type": "memory_recall_count",
"session_id": "<uuid>",
"memory_recall_count": 3
}memory_recall_count is an integer: the number of memories merged into the system prompt for that turn (initial recall, not counting optional interleave tool rounds). Clients can use this to show recall stats without parsing the prompt.
Update Memory
PUT /api/memory/{id}Pin/Unpin Memory
PUT /api/memory/{id}/pin?pinned=trueDelete Memory
DELETE /api/memory/{id}Bulk Delete (GDPR)
DELETE /api/memoryExport Memories
GET /api/memory/exportConversation Endpoints
List Conversation Memories
GET /api/memory/session/{session_id}Promote to User Scope
POST /api/memory/session/{session_id}/promote/{memory_id}Admin Endpoints
List Org Knowledge
GET /api/memory/admin?limit=20&offset=0Add Org Knowledge
POST /api/memory/adminBulk Import
POST /api/memory/admin/importUsage Stats
GET /api/memory/admin/statsGroup Endpoints
List Groups
GET /api/memory/groupsCreate Group
POST /api/memory/groupsList Group Memories
GET /api/memory/groups/{group_id}/memoriesAdd Group Memory
POST /api/memory/groups/{group_id}/memoriesTag Endpoints
List Tags
GET /api/memory/tagsReturns tags visible to the current user (owned or shared within their organization).
Create Tag
POST /api/memory/tagsRequest:
json
{
"name": "python",
"is_shared": false
}Update Tag
PUT /api/memory/tags/{tag_id}Request:
json
{
"is_shared": true
}Toggle tag sharing or rename. Only the tag creator can update.
Delete Tag
DELETE /api/memory/tags/{tag_id}Removes the tag and all its assignments. Only the tag creator can delete.
Assign Tag to Memory
POST /api/memory/{memory_id}/tags/{tag_id}Returns 409 if already assigned.
Remove Tag from Memory
DELETE /api/memory/{memory_id}/tags/{tag_id}Explorer Endpoints
The Explorer API provides 2D projections and similarity data for the Vector Explorer visualization.
Get Projections
GET /api/memory/explorer/projections?method=pca&limit=2000&sources=memoryQuery parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
method | pca | tsne | pca | Dimensionality reduction method |
scope | string | — | Filter by memory scope |
category | string | — | Filter by category |
limit | int (1-5000) | 2000 | Max points to return |
refresh | bool | false | Bypass cache |
sources | string | memory | Comma-separated: memory, file_chunk, content_library |
admin | bool | false | Cross-org view (platform admins only) |
Response includes points[] with id, x, y, source, scope, category, content_preview, content, confidence, is_pinned, access_count, created_at, source_agent, and tags[].
Get Nearest Neighbors
GET /api/memory/explorer/neighbors/{point_id}?k=8Returns k nearest neighbors by cosine similarity on the raw 384-dim embeddings (not the 2D projection).
Get Similarity Edges
GET /api/memory/explorer/edges?threshold=0.85&max_edges=500Returns all pairwise edges above the cosine similarity threshold. Used by the force graph overlay.
| Parameter | Type | Default | Description |
|---|---|---|---|
threshold | float (0.5-1.0) | 0.85 | Minimum similarity to include |
max_edges | int (1-2000) | 500 | Cap on returned edges |
Get Explorer Stats
GET /api/memory/explorer/statsReturns total_memories, memories_with_embeddings, by_scope, by_category, and embedding_coverage_pct.
Platform Admin Endpoints
List Platform Knowledge
GET /api/memory/platformAdd Platform Knowledge
POST /api/memory/platformAdd Subject Knowledge
POST /api/memory/platform/subject/{subject}