Memories API

Memory management and retrieval endpoints

GET /api/memories

List memories

Query parameters:

Parameter	Type	Required	Description
idPrefix	string	No	Filter memories by ID prefix (git-style short ID lookup). Minimum 6 characters.
limit	integer	No	Maximum number of memories to return
offset	integer	No	Number of memories to skip
page	integer	No	Page number (alternative to offset)

Response: 200 List of memories

Field	Type	Required	Description
data	Memory[]	No
pagination	Pagination	No

Example:

curl -X GET "https://api.memnexus.ai/api/memories" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

POST /api/memories

Create a memory

Request body:

Field	Type	Required	Description
conversationId	string	Yes	Conversation ID - use "NEW" to create a new conversation or provide existing conversation ID
name	string	No	Optional human-readable name for deterministic retrieval. Must be unique per user.
content	string	Yes	Memory content
memoryType	episodic \	semantic \	procedural
role	user \	assistant \	system
context	string	No	Context or domain
topics	string[]	No	Associated topics
eventTime	string	No	Event time (when the event actually occurred in reality, ISO 8601 format)
validFrom	string	No	Validity start time (when this fact becomes valid, ISO 8601 format)
validTo	string	No	Validity end time (when this fact expires, ISO 8601 format, omit for never expires)

Response: 201 Memory created successfully

Field	Type	Required	Description
data	Memory	Yes
meta	CreateMemoryResponseMeta	Yes

Example:

curl -X POST "https://api.memnexus.ai/api/memories" \
  -H "Authorization: Bearer cmk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{}'

---

GET /api/memories/{id}

Get memory by ID

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The memory ID

Response: 200 Memory retrieved successfully

Field	Type	Required	Description
data	Memory	Yes

Example:

curl -X GET "https://api.memnexus.ai/api/memories/mem_abc123" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

PUT /api/memories/{id}

Update a memory

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	Memory ID

Request body:

Field	Type	Required	Description
content	string	No	Updated memory content
name	any	No	Assign or remove a name. Set to a valid name to assign, empty string to remove.
memoryType	episodic \	semantic \	procedural
context	string	No	Updated context or domain
topics	string[]	No	Updated topics

Response: 200 Memory updated successfully

Field	Type	Required	Description
data	Memory	No

Example:

curl -X PUT "https://api.memnexus.ai/api/memories/mem_abc123" \
  -H "Authorization: Bearer cmk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{}'

---

DELETE /api/memories/{id}

Delete memory

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The memory ID

Response: 204 No Content

Example:

curl -X DELETE "https://api.memnexus.ai/api/memories/mem_abc123" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

GET /api/memories/{id}/conversation-memories

Find memories from same conversation

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The source memory ID

Query parameters:

Parameter	Type	Required	Description
limit	integer	No	Maximum number of conversation memories to return

Response: 200 Conversation memories found

Field	Type	Required	Description
data	RelatedMemoryResult[]	No
sourceMemory	Memory	No
conversationId	string	No	The conversation ID (null if memory has no conversation)

Example:

curl -X GET "https://api.memnexus.ai/api/memories/mem_abc123/conversation-memories" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

POST /api/memories/{id}/detect-relationships

Detect potential relationships for a memory

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The memory ID

Request body:

Field	Type	Required	Description
autoCreate	boolean	No	Automatically create high-confidence relationships
minConfidence	number	No	Minimum confidence threshold for suggestions

Response: 200 Relationship candidates detected

Field	Type	Required	Description
data	object[]	No
autoCreated	boolean	No

Example:

curl -X POST "https://api.memnexus.ai/api/memories/mem_abc123/detect-relationships" \
  -H "Authorization: Bearer cmk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{}'

---

GET /api/memories/{id}/related

Find related memories by topics

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The source memory ID

Query parameters:

Parameter	Type	Required	Description
limit	integer	No	Maximum number of related memories to return

Response: 200 Related memories found

Field	Type	Required	Description
data	any[]	No
sourceMemory	Memory	No

Example:

curl -X GET "https://api.memnexus.ai/api/memories/mem_abc123/related" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

GET /api/memories/{id}/relationships

Get relationships for a memory

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The memory ID

Query parameters:

Parameter	Type	Required	Description
direction	outgoing \	incoming \	both

Response: 200 Relationships retrieved successfully

Field	Type	Required	Description
data	MemoryRelationship[]	Yes
sourceMemoryId	string	Yes	The source memory ID these relationships are for
direction	outgoing \	incoming \	both

Example:

curl -X GET "https://api.memnexus.ai/api/memories/mem_abc123/relationships" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

POST /api/memories/{id}/relationships

Create a relationship between memories

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The source memory ID

Request body:

Field	Type	Required	Description
targetMemoryId	string	Yes	ID of the target memory to create a relationship with
type	SUPERSEDES \	FOLLOWS \	RESOLVES \
confidence	number	No	Confidence score for the relationship (0-1, defaults to 1.0 for manual)
reason	string	No	Optional explanation for the relationship

Response: 201 Relationship created successfully

Field	Type	Required	Description
data	MemoryRelationship	No

Example:

curl -X POST "https://api.memnexus.ai/api/memories/mem_abc123/relationships" \
  -H "Authorization: Bearer cmk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{}'

---

DELETE /api/memories/{id}/relationships/{relationshipId}

Delete a relationship

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The source memory ID
relationshipId	string	Yes	The relationship ID to delete

Response: 204 Relationship deleted successfully

Example:

curl -X DELETE "https://api.memnexus.ai/api/memories/mem_abc123/relationships/rel_abc123" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

GET /api/memories/{id}/similar

Find similar memories

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The source memory ID

Query parameters:

Parameter	Type	Required	Description
limit	integer	No	Maximum number of similar memories to return

Response: 200 Similar memories found

Field	Type	Required	Description
data	RelatedMemoryResult[]	No
sourceMemory	Memory	No

Example:

curl -X GET "https://api.memnexus.ai/api/memories/mem_abc123/similar" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

GET /api/memories/{id}/timeline

Get timeline context for a memory

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The memory ID

Query parameters:

Parameter	Type	Required	Description
before	integer	No	Number of preceding memories to return
after	integer	No	Number of following memories to return

Response: 200 Timeline context retrieved successfully

Field	Type	Required	Description
data	object	No

Example:

curl -X GET "https://api.memnexus.ai/api/memories/mem_abc123/timeline" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

POST /api/memories/batch

Get multiple memories by IDs

Request body:

Field	Type	Required	Description
ids	string[]	Yes	Array of memory IDs to retrieve

Response: 200 Memories retrieved successfully

Field	Type	Required	Description
data	Memory[]	Yes
meta	BatchGetMemoriesMeta	Yes

Example:

curl -X POST "https://api.memnexus.ai/api/memories/batch" \
  -H "Authorization: Bearer cmk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{}'

---

POST /api/memories/digest

Generate memory digest

Request body:

Field	Type	Required	Description
query	string	Yes	The topic or subject to generate a digest for
recent	string	No	Time window filter (e.g., "7d", "24h", "2w", "30m"). Only considers memories within this window.
topics	string[]	No	Filter to memories with these topics
conversationIds	string[]	No	Limit to specific conversation IDs
format	structured \	narrative \	timeline \
maxSources	integer	No	Maximum number of memories to consider (1-500, default 100)
includeMemoryIds	boolean	No	Whether to include source memory IDs in the response

Response: 200 Digest generated successfully

Field	Type	Required	Description
digest	string	Yes	The generated digest content (markdown formatted)
metadata	DigestMetadata	Yes
sources	DigestSource[]	Yes	Source memories used to generate the digest, for traceability

Example:

curl -X POST "https://api.memnexus.ai/api/memories/digest" \
  -H "Authorization: Bearer cmk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{}'

---

GET /api/memories/named/{name}

Get a memory by name

Path parameters:

Parameter	Type	Required	Description
name	string	Yes	Memory name (kebab-case, 2-64 chars)

Response: 200 Memory retrieved successfully

Field	Type	Required	Description
data	Memory	Yes

Example:

curl -X GET "https://api.memnexus.ai/api/memories/named/{name}" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

PUT /api/memories/named/{name}

Update a named memory (create new version)

Path parameters:

Parameter	Type	Required	Description
name	string	Yes	Memory name (kebab-case, 2-64 chars)

Request body:

Field	Type	Required	Description
content	string	Yes	New content for the named memory version
memoryType	episodic \	semantic \	procedural
context	string	No	Context or domain
topics	string[]	No	Associated topics

Response: 201 New version created successfully

Field	Type	Required	Description
data	Memory	No
meta	object	No

Example:

curl -X PUT "https://api.memnexus.ai/api/memories/named/{name}" \
  -H "Authorization: Bearer cmk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{}'

---

GET /api/memories/named/{name}/history

Get version history for a named memory

Path parameters:

Parameter	Type	Required	Description
name	string	Yes	Memory name (kebab-case, 2-64 chars)

Response: 200 Version history retrieved successfully

Field	Type	Required	Description
name	string	Yes	Human-readable name for deterministic retrieval (kebab-case, 2-64 chars)
versions	object[]	Yes

Example:

curl -X GET "https://api.memnexus.ai/api/memories/named/{name}/history" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

GET /api/memories/search

Search memories (GET)

Query parameters:

Parameter	Type	Required	Description
q	string	Yes	Search query string
searchMethod	keyword \	semantic \	hybrid
limit	integer	No	Maximum number of results to return
offset	integer	No	Number of results to skip for pagination
threshold	number	No	Minimum similarity threshold for semantic search
mode	unified \	content \	facts
vectorWeight	number	No	Weight for vector similarity in hybrid search
fulltextWeight	number	No	Weight for fulltext matching in hybrid search
topics	string	No	Comma-separated list of topics to filter by (include memories with ANY of these topics)
excludeTopics	string	No	Comma-separated list of topics to exclude (exclude memories with ANY of these topics)
memoryType	episodic \	semantic \	procedural
conversationId	string	No	Filter by conversation ID
explain	boolean	No	Include detailed match explanations in results
includeTopics	boolean	No	Include associated topics in results
includeEntities	boolean	No	Include mentioned entities in results
asOfTime	string	No	Point-in-time query (ISO 8601 datetime)
validAtTime	string	No	Filter by validity time (ISO 8601 datetime)
eventTimeFrom	string	No	Event time range start (ISO 8601 datetime)
eventTimeTo	string	No	Event time range end (ISO 8601 datetime)
ingestionTimeFrom	string	No	Ingestion time range start (ISO 8601 datetime)
ingestionTimeTo	string	No	Ingestion time range end (ISO 8601 datetime)
includeExpired	boolean	No	Include expired memories in results
temporalMode	current \	historical \	evolution

Response: 200 Search results

Field	Type	Required	Description
data	SearchResult[]	Yes	Search results with metadata
searchMethod	string	No	Search method used for this query
pagination	any	Yes
temporalMetadata	TemporalMetadata	Yes

Example:

curl -X GET "https://api.memnexus.ai/api/memories/search" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

POST /api/memories/search

Search all memories

Request body:

Field	Type	Required	Description
query	string	Yes	Search query
mode	unified \	content \	facts
searchMethod	keyword \	semantic \	hybrid
limit	integer	No	Maximum number of results (defaults to 20)
offset	integer	No	Offset for pagination (defaults to 0)
vectorWeight	number	No	Weight for vector (semantic) results in hybrid search (0-1, defaults to 0.7)
fulltextWeight	number	No	Weight for fulltext (keyword) results in hybrid search (0-1, defaults to 0.3)
threshold	number	No	Minimum similarity threshold for semantic search (0-1, defaults to 0.5)
explain	boolean	No	If true, include detailed explanation of how each result was matched
asOfTime	string	No	Point-in-time query: show what the system knew at this time (ISO 8601 format)
validAtTime	string	No	Validity query: show facts that were valid at this time (ISO 8601 format)
eventTimeFrom	string	No	Event time range start (ISO 8601 format)
eventTimeTo	string	No	Event time range end (ISO 8601 format)
ingestionTimeFrom	string	No	Ingestion time range start (ISO 8601 format)
ingestionTimeTo	string	No	Ingestion time range end (ISO 8601 format)
includeExpired	boolean	No	Include expired facts (defaults to false)
temporalMode	current \	historical \	evolution
topics	string[]	No	Filter by topics - returns memories that have ANY of the specified topics
memoryType	episodic \	semantic \	procedural
conversationId	string	No	Filter by conversation ID
includeTopics	boolean	No	Include topics associated with matched memories (defaults to false for performance)
includeEntities	boolean	No	Include entities mentioned in matched memories (defaults to false for performance)
includeFacts	boolean	No	Include facts extracted from matched memories (defaults to false for performance)
entityTypes	string[]	No	Filter entities by type (e.g., PERSON, TECHNOLOGY, PROJECT)

Response: 200 Search results

Field	Type	Required	Description
data	SearchResult[]	Yes	Search results with metadata
searchMethod	string	No	Search method used for this query
pagination	any	Yes
temporalMetadata	TemporalMetadata	Yes

Example:

curl -X POST "https://api.memnexus.ai/api/memories/search" \
  -H "Authorization: Bearer cmk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{}'

---