Skip to content

Memory API Reference ​

User Endpoints ​

Store Memory ​

POST /api/memory

Request:

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=false

Recall Memories ​

GET /api/memory/recall?q=what programming language&limit=20

Get Memory Config ​

GET /api/memory/config

Update Memory Config ​

PUT /api/memory/config

Request (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:

PresetValueBehavior
Broad0.3More memories, looser matching
Balanced0.5Default balance
Conservative0.7Fewer 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_memory invocations per assistant turn (interleave round cap).
  • 5 recall_memory calls 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=true

Delete Memory ​

DELETE /api/memory/{id}

Bulk Delete (GDPR) ​

DELETE /api/memory

Export Memories ​

GET /api/memory/export

Conversation 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=0

Add Org Knowledge ​

POST /api/memory/admin

Bulk Import ​

POST /api/memory/admin/import

Usage Stats ​

GET /api/memory/admin/stats

Group Endpoints ​

List Groups ​

GET /api/memory/groups

Create Group ​

POST /api/memory/groups

List Group Memories ​

GET /api/memory/groups/{group_id}/memories

Add Group Memory ​

POST /api/memory/groups/{group_id}/memories

Tag Endpoints ​

List Tags ​

GET /api/memory/tags

Returns tags visible to the current user (owned or shared within their organization).

Create Tag ​

POST /api/memory/tags

Request:

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=memory

Query parameters:

ParameterTypeDefaultDescription
methodpca | tsnepcaDimensionality reduction method
scopestring—Filter by memory scope
categorystring—Filter by category
limitint (1-5000)2000Max points to return
refreshboolfalseBypass cache
sourcesstringmemoryComma-separated: memory, file_chunk, content_library
adminboolfalseCross-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=8

Returns 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=500

Returns all pairwise edges above the cosine similarity threshold. Used by the force graph overlay.

ParameterTypeDefaultDescription
thresholdfloat (0.5-1.0)0.85Minimum similarity to include
max_edgesint (1-2000)500Cap on returned edges

Get Explorer Stats ​

GET /api/memory/explorer/stats

Returns total_memories, memories_with_embeddings, by_scope, by_category, and embedding_coverage_pct.

Platform Admin Endpoints ​

List Platform Knowledge ​

GET /api/memory/platform

Add Platform Knowledge ​

POST /api/memory/platform

Add Subject Knowledge ​

POST /api/memory/platform/subject/{subject}

SOC 2 Type II Certified | BAA Available | HIPAA-Ready