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)
sortBy	createdAt \	updatedAt \	eventTime
order	asc \	desc	No
from	string	No	Filter memories created on or after this ISO 8601 timestamp (ingestion time lower bound)
to	string	No	Filter memories created on or before this ISO 8601 timestamp (ingestion time upper bound)
recent	string	No	Shorthand time filter relative to now (e.g. "24h", "7d", "2w"). Sets the lower bound for ingestion time. Takes precedence over from when both are provided.

Response: 200 List of memories

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

Example:

curl -X GET "https://api.dev.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	No	Conversation ID - use "NEW" to always create a new conversation, provide an existing ID to append to it, or omit to auto-assign via claudeSessionId session grouping.
claudeSessionId	string	No	Agent session ID (e.g. MCP session ID, Claude Code session UUID). When conversationId is omitted, reuses or creates a conversation for this session (automatic grouping). Ignored when conversationId is explicitly provided. Works with any MCP client (Claude, Copilot, Cursor, etc.).
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.dev.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

Query parameters:

Parameter	Type	Required	Description
detail	minimal \	standard \	full

Response: 200 Memory retrieved successfully

Field	Type	Required	Description
data	Memory	Yes

Example:

curl -X GET "https://api.dev.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.dev.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.dev.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.dev.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.dev.memnexus.ai/api/memories/mem_abc123/detect-relationships" \
  -H "Authorization: Bearer cmk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{}'

---

POST /api/memories/{id}/explain-relationship

Generate LLM explanation for a memory relationship

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The ID of the source memory

Request body:

Field	Type	Required	Description
otherMemoryId	string	Yes
relationshipType	string	Yes

Response: 200 Explanation generated

Field	Type	Required	Description
data	object	No

Example:

curl -X POST "https://api.dev.memnexus.ai/api/memories/mem_abc123/explain-relationship" \
  -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.dev.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.dev.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.dev.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.dev.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.dev.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.dev.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. Non-existent or malformed IDs are returned in the 'missing' array rather than failing the request.
detail	minimal \	standard \	full

Response: 200 Memories retrieved successfully

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

Example:

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

---

POST /api/memories/build-context

Build a context briefing

Request body:

Field	Type	Required	Description
context	string	Yes	What you are about to work on
files	string[]	No	File paths you will be touching
recentHours	number	No	How far back to look for recent activity (hours, default 24)

Response: 200 Context briefing generated successfully

Field	Type	Required	Description
activeWork	BuildContextActiveWork	Yes
relevantFacts	BuildContextFact[]	Yes	Facts related to the context terms
gotchas	BuildContextGotcha[]	Yes	Gotchas — facts appearing in 2+ source memories
recentActivity	BuildContextActivity[]	Yes	Recent relevant memories within the time window
relatedPatterns	BuildContextPattern[]	Yes	Behavioral patterns related to the context
meta	BuildContextMeta	Yes

Example:

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

---

DELETE /api/memories/bulk

Bulk delete multiple memories

Request body:

Field	Type	Required	Description
ids	string[]	Yes	Memory IDs to delete (max 100)
confirmDeletion	true	Yes	Must be true to confirm bulk deletion

Response: 200 Bulk delete results

Field	Type	Required	Description
deleted	integer	Yes	Number of memories successfully deleted
failed	integer	Yes	Number of memories that failed to delete
errors	object[]	Yes	Per-item error details

Example:

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

---

POST /api/memories/bulk-tag

Bulk add or remove topics from memories

Request body:

Field	Type	Required	Description
ids	string[]	Yes	Memory IDs to modify tags on (max 100)
addTopics	string[]	No	Topics to add to all specified memories
removeTopics	string[]	No	Topics to remove from all specified memories

Response: 200 Bulk tag results

Field	Type	Required	Description
modified	integer	Yes	Number of memories successfully modified
failed	integer	Yes	Number of memories that failed to modify
errors	object[]	Yes	Per-item error details

Example:

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

---

POST /api/memories/bulk-update

Bulk update multiple memories

Request body:

Field	Type	Required	Description
ids	string[]	Yes	Memory IDs to update (max 100)
updates	object	Yes	Fields to update on all specified memories

Response: 200 Bulk update results

Field	Type	Required	Description
updated	integer	Yes	Number of memories successfully updated
failed	integer	Yes	Number of memories that failed to update
errors	object[]	Yes	Per-item error details

Example:

curl -X POST "https://api.dev.memnexus.ai/api/memories/bulk-update" \
  -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
keyFacts	DigestKeyFact[]	No	Top extracted facts relevant to the digest, deduplicated and ranked by frequency
entities	DigestEntity[]	No	Key entities mentioned across source memories
effectiveStateBreakdown	EffectiveStateBreakdown	No

Example:

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

---

POST /api/memories/export

Export memories matching filters

Request body:

Field	Type	Required	Description
query	string	No	Optional search query to filter memories for export
topics	string[]	No	Filter by topics
memoryType	episodic \	semantic \	procedural
format	json \	csv	No
fields	string[]	No	Optional field selection. If omitted, all standard fields are included.
limit	integer	No	Maximum results to export (default 100, max 1000)

Response: 200 Exported memories

Example:

curl -X POST "https://api.dev.memnexus.ai/api/memories/export" \
  -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)

Query parameters:

Parameter	Type	Required	Description
detail	minimal \	standard \	full

Response: 200 Memory retrieved successfully

Field	Type	Required	Description
data	Memory	Yes

Example:

curl -X GET "https://api.dev.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.dev.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.dev.memnexus.ai/api/memories/named/{name}/history" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

POST /api/memories/repair-effective-state

Repair orphaned effectiveState values

Response: 200 Repair results

Field	Type	Required	Description
repaired	integer	No
memories	object[]	No

Example:

curl -X POST "https://api.dev.memnexus.ai/api/memories/repair-effective-state" \
  -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
includeFacts	boolean	No	Include extracted facts 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
sortBy	relevance \	createdAt \	updatedAt \
order	asc \	desc	No
expandEntities	boolean	No	Enable entity graph traversal branch in hybrid search
expandTopics	boolean	No	Enable topic graph traversal branch in hybrid search
expandFacts	boolean	No	Enable fact graph traversal branch in hybrid search
includeSuperseded	boolean	No	Include superseded and contradicted memories in results
entityWeight	number	No	Weight for entity graph branch in hybrid search
topicWeight	number	No	Weight for topic graph branch in hybrid search
factWeight	number	No	Weight for fact graph branch in hybrid search
includeFacets	boolean	No	Include facet aggregation (topics, memoryType, effectiveState) in response

Response: 200 Search results

Field	Type	Required	Description
data	SearchResult[]	Yes	Flattened search results with memory fields and search metadata
meta	SearchMeta	Yes
facets	Facets	No

Example:

curl -X GET "https://api.dev.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)
expandEntities	boolean	No	Enable entity graph traversal branch in hybrid search (default false)
expandTopics	boolean	No	Enable topic graph traversal branch in hybrid search (default false)
expandFacts	boolean	No	Enable fact graph traversal branch in hybrid search (default false)
includeSuperseded	boolean	No	Include superseded and contradicted memories in results (default false)
entityWeight	number	No	Weight for entity graph branch in hybrid search (0-1, default 0.7)
topicWeight	number	No	Weight for topic graph branch in hybrid search (0-1, default 0.5)
factWeight	number	No	Weight for fact graph branch in hybrid search (0-1, default 0.6)
sortBy	relevance \	createdAt \	updatedAt \
order	asc \	desc	No
includeFacets	boolean	No	Include facet aggregation (topics, memoryType, effectiveState) in response (defaults to false)

Response: 200 Search results

Field	Type	Required	Description
data	SearchResult[]	Yes	Flattened search results with memory fields and search metadata
meta	SearchMeta	Yes
facets	Facets	No

Example:

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

---

POST /api/memories/search/feedback

Record behavioral feedback on a search result

Request body:

Field	Type	Required	Description
memoryId	string	Yes	ID of the memory result being rated
action	selected \	not_selected	Yes
searchMethod	string	No	Search method used (hybrid, semantic, keyword)

Response: 204 Feedback recorded

Example:

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

---

GET /api/memories/stats

Aggregated memory analytics

Query parameters:

Parameter	Type	Required	Description
groupBy	day \	week \	month \
after	string	No	Filter memories on or after this ISO 8601 timestamp
before	string	No	Filter memories on or before this ISO 8601 timestamp
recent	string	No	Shorthand time window relative to now (e.g. 7d, 2w, 1mo). Sets the lower bound. Takes precedence over after.
topic	string	No	Pre-filter to memories that contain this topic before grouping
limit	integer	No	Maximum number of buckets to return

Response: 200 Aggregated memory statistics

Field	Type	Required	Description
groupBy	day \	week \	month \
data	object[]	No
total	integer	No
filters	object	No

Example:

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

---