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".

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",
    "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.
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",
    "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).

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",
    "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. The request body is an empty object.

Request

curl -X POST https://api.neuromem.cloud/api/v1/digest \
  -H "Authorization: Bearer nm_sk_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "user_id": "3f0c...",
  "traits_generated": 3
}
In ONE LLM mode, reflection runs automatically via the scheduled routine; this endpoint is a no-op and returns traits_generated: 0.
GET

/api/v1/memories

List stored memories with pagination and optional type filtering.

Query Parameters

Name
Type
Req
Default
Description
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?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
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 '{
    "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.

Request

curl -X DELETE "https://api.neuromem.cloud/api/v1/memories/mem_abc123" \
  -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
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 '{
    "memory_ids": ["mem_abc123", "mem_def456", "mem_ghi789"],
    "dry_run": false
  }'

Response

{
  "deleted": 3,
  "dry_run": false,
  "count": 3
}