REST API
HTTP endpoints for ingest, recall, and digest operations.
Base URL: https://api.neuromem.cloud
Authentication
All API requests require an API key passed as a Bearer token in the Authorization header. API keys are created in the Dashboard and use the nm_sk_ prefix.
Authorization: Bearer nm_sk_your_api_key_here
POST
/api/v1/ingest
Store a conversation message. Automatically extracts facts, episodes, and knowledge graph triples.
Request Body
Name
Type
Req
Default
Description
content
string
Yes
—
Message content (1 – 50,000 characters).
role
string
No
"user"
Sender role. Either "user" or "assistant".
user_id
string
No
"default"
User identifier for multi-user memory isolation.
Request
curl -X POST https://api.neuromem.cloud/api/v1/ingest \
-H "Authorization: Bearer nm_sk_..." \
-H "Content-Type: application/json" \
-d '{
"content": "User prefers dark mode and uses TypeScript daily",
"user_id": "user-123",
"role": "user"
}'Response
{
"id": "mem_abc123",
"user_id": "default",
"role": "user",
"extraction_required": false,
"extraction_prompt": null
}When ONE LLM mode is enabled on the agent,
extraction_required will be true and extraction_prompt will contain the prompt for client-side extraction. Submit the result via /api/v1/ingest_extracted.POST
/api/v1/ingest_extracted
Submit client-extracted data for a previously ingested memory (ONE LLM mode).
Request Body
Name
Type
Req
Default
Description
memory_id
string
Yes
—
Memory ID returned from the ingest response.
user_id
string
No
"default"
User identifier.
data
object
Yes
—
Extracted data. Contains facts, episodes, and triples arrays.
data object structure
Name
Type
Req
Default
Description
facts
array
No
—
Array of {content: "..."} objects representing extracted facts.
episodes
array
No
—
Array of {content: "..."} objects representing episodic memories.
triples
array
No
—
Array of {subject, predicate, object} knowledge graph triples.
Request
curl -X POST https://api.neuromem.cloud/api/v1/ingest_extracted \
-H "Authorization: Bearer nm_sk_..." \
-H "Content-Type: application/json" \
-d '{
"memory_id": "mem_abc123",
"user_id": "user-123",
"data": {
"facts": [
{"content": "User prefers dark mode"},
{"content": "User uses TypeScript daily"}
],
"episodes": [
{"content": "User discussed UI preferences on 2026-03-10"}
],
"triples": [
{"subject": "User", "predicate": "prefers", "object": "dark mode"},
{"subject": "User", "predicate": "uses", "object": "TypeScript"},
{"subject": "User", "predicate": "uses_frequency", "object": "daily"}
]
}
}'Response
{
"memory_id": "mem_abc123",
"user_id": "user-123",
"facts_stored": 2,
"episodes_stored": 1,
"triples_stored": 3
}POST
/api/v1/recall
Search memories with natural language. Hybrid retrieval combines vector similarity, BM25 full-text search, and knowledge graph traversal.
Request Body
Name
Type
Req
Default
Description
query
string
Yes
—
Natural language search query (1 – 10,000 characters).
limit
int
No
10
Maximum number of results to return (1 – 100).
user_id
string
No
"default"
User identifier.
Request
curl -X POST https://api.neuromem.cloud/api/v1/recall \
-H "Authorization: Bearer nm_sk_..." \
-H "Content-Type: application/json" \
-d '{
"query": "user preferences",
"user_id": "user-123",
"limit": 5
}'Response
{
"query": "user preferences",
"user_id": "user-123",
"memories": [
{
"content": "User prefers dark mode and TypeScript",
"score": 0.92,
"memory_type": "fact",
"source": "vector",
"created_at": "2026-03-10T08:30:00Z"
}
],
"total": 5,
"inferred_context": "technology preferences",
"context_confidence": 0.85
}POST
/api/v1/digest
Trigger behavioral pattern analysis. Discovers traits and preferences from accumulated memories.
Request Body
Name
Type
Req
Default
Description
user_id
string
No
"default"
User identifier.
Request
curl -X POST https://api.neuromem.cloud/api/v1/digest \
-H "Authorization: Bearer nm_sk_..." \
-H "Content-Type: application/json" \
-d '{
"user_id": "user-123"
}'Response (normal mode)
{
"user_id": "user-123",
"traits_generated": 3
}Response (ONE LLM mode)
{
"user_id": "user-123",
"one_llm_mode": true,
"memories": ["..."],
"existing_traits": ["..."],
"unreflected_count": 15,
"reflection_prompt": "Based on these memories, identify behavioral patterns..."
}In ONE LLM mode, the response includes a
reflection_prompt for client-side trait extraction. Submit the result via /api/v1/digest_extracted.POST
/api/v1/digest_extracted
Submit client-extracted traits from digest analysis (ONE LLM mode).
Request Body
Name
Type
Req
Default
Description
user_id
string
No
"default"
User identifier.
data
object
Yes
—
Contains the traits array.
data object structure
Name
Type
Req
Default
Description
traits
array
Yes
—
Array of {content, category, importance} objects. Only traits with importance >= 7 are stored.
Request
curl -X POST https://api.neuromem.cloud/api/v1/digest_extracted \
-H "Authorization: Bearer nm_sk_..." \
-H "Content-Type: application/json" \
-d '{
"user_id": "user-123",
"data": {
"traits": [
{
"content": "Strongly prefers functional programming patterns",
"category": "behavior",
"importance": 8
},
{
"content": "Values code readability over cleverness",
"category": "preference",
"importance": 9
}
]
}
}'Response
{
"user_id": "user-123",
"traits_stored": 2
}Only traits with
importance >= 7 are persisted. Lower-importance traits are silently discarded.GET
/api/v1/memories
List stored memories with pagination and optional type filtering.
Query Parameters
Name
Type
Req
Default
Description
user_id
string
No
"default"
User identifier.
memory_type
string
No
—
Filter by type: "fact", "episodic", or "trait".
limit
int
No
20
Number of results per page (1 – 100).
offset
int
No
0
Number of results to skip for pagination.
Request
curl "https://api.neuromem.cloud/api/v1/memories?user_id=user-123&memory_type=fact&limit=20&offset=0" \ -H "Authorization: Bearer nm_sk_..."
Response
{
"memories": [
{
"id": "mem_abc123",
"content": "User prefers dark mode and TypeScript",
"memory_type": "fact",
"importance": 7,
"access_count": 3,
"created_at": "2026-03-10T08:30:00Z",
"updated_at": null,
"metadata": {}
}
],
"total": 42,
"limit": 20,
"offset": 0
}PATCH
/api/v1/memories/{memory_id}
Update a memory's content or type. Changing content automatically re-generates the embedding vector.
Request Body
Name
Type
Req
Default
Description
user_id
string
Yes
—
User identifier (must match the memory owner).
content
string
No
—
New content. Triggers embedding re-generation.
memory_type
string
No
—
New memory type: "fact", "episodic", or "trait".
Request
curl -X PATCH https://api.neuromem.cloud/api/v1/memories/mem_abc123 \
-H "Authorization: Bearer nm_sk_..." \
-H "Content-Type: application/json" \
-d '{
"user_id": "user-123",
"content": "User strongly prefers dark mode across all applications"
}'Response
{
"status": "updated",
"memory_id": "mem_abc123"
}DELETE
/api/v1/memories/{memory_id}
Permanently delete a specific memory by ID.
Query Parameters
Name
Type
Req
Default
Description
user_id
string
No
"default"
User identifier.
Request
curl -X DELETE "https://api.neuromem.cloud/api/v1/memories/mem_abc123?user_id=user-123" \ -H "Authorization: Bearer nm_sk_..."
Response
{
"status": "deleted",
"memory_id": "mem_abc123"
}POST
/api/v1/memories/batch-delete
Delete multiple memories in a single request. Supports dry-run mode for previewing the operation.
Request Body
Name
Type
Req
Default
Description
user_id
string
Yes
—
User identifier.
memory_ids
array
Yes
—
Array of memory IDs to delete (max 1,000).
dry_run
bool
No
false
When true, returns the count without actually deleting.
Request
curl -X POST https://api.neuromem.cloud/api/v1/memories/batch-delete \
-H "Authorization: Bearer nm_sk_..." \
-H "Content-Type: application/json" \
-d '{
"user_id": "user-123",
"memory_ids": ["mem_abc123", "mem_def456", "mem_ghi789"],
"dry_run": false
}'Response
{
"deleted": 3,
"dry_run": false,
"count": 3
}