Memories API

Read, update, and delete memories. For creating memories, use the extraction endpoints.

Creating Memories

Use Extraction Endpoints

Memories are created through intelligent extraction endpoints that provide higher-quality memories with automatic deduplication, entity extraction, and conflict resolution.

To create memories, use:

• Memory Extraction - Extract from conversations and text
• Document Ingestion - Process files and URLs

# Extract memories from a conversation
curl -X POST https://memoryapi.tensorheart.com/v1/query/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User works as a data scientist at TechCorp and prefers Python.",
    "content_type": "conversation"
  }'

---

List Memories

GET /v1/memories

Query Parameters

Parameter	Type	Default	Description
page	int	1	Page number
per_page	int	50	Items per page (max 100)
space_id	string	null	Filter by memory space

Example

curl "https://memoryapi.tensorheart.com/v1/memories?page=1&per_page=20&space_id=work" \
  -H "Authorization: Bearer $API_KEY"

---

Get Memory Count

Get the total count of memories.

GET /v1/memories/count

Response

{
  "success": true,
  "data": {
    "count": 156
  }
}

---

Get Memory

GET /v1/memories/{memory_id}

Example

curl https://memoryapi.tensorheart.com/v1/memories/mem_abc123 \
  -H "Authorization: Bearer $API_KEY"

---

Get Memory History

Retrieve the version history of a memory. When using smart updates, old versions are preserved and linked together.

GET /v1/memories/{memory_id}/history

Example

curl https://memoryapi.tensorheart.com/v1/memories/mem_abc123/history \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "success": true,
  "data": {
    "versions": [
      {
        "id": "mem_xyz789",
        "text": "Alice has 6 years of experience",
        "valid_from": "2024-12-15T10:30:00Z",
        "superseded_at": null,
        "is_current": true
      },
      {
        "id": "mem_abc123",
        "text": "Alice has 5 years of experience",
        "valid_from": "2024-06-01T09:00:00Z",
        "superseded_at": "2024-12-15T10:30:00Z",
        "is_current": false
      }
    ],
    "total_versions": 2
  },
  "meta": {
    "request_id": "req_xyz123",
    "processing_time_ms": 35,
    "usage": {
      "memories_accessed": 2
    }
  }
}

Temporal Queries

You can query memories as they existed at a specific point in time using the as_of parameter in the Query API.

---

Update Memory

PUT /v1/memories/{memory_id}

Request Body

Field	Type	Required	Description
text	string	No	Updated text
metadata	object	No	Updated metadata (replaces existing)

Example

curl -X PUT https://memoryapi.tensorheart.com/v1/memories/mem_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "User is a senior data scientist at TechCorp"}'

---

Delete Memory

DELETE /v1/memories/{memory_id}

Example

curl -X DELETE https://memoryapi.tensorheart.com/v1/memories/mem_abc123 \
  -H "Authorization: Bearer $API_KEY"

---

Delete All Memories

DELETE /v1/memories?confirm=true

Destructive Action

This permanently deletes all memories. The confirm=true parameter is required.

Example

curl -X DELETE "https://memoryapi.tensorheart.com/v1/memories?confirm=true" \
  -H "Authorization: Bearer $API_KEY"

---

Consolidate Memories

Merge similar memories to reduce redundancy.

POST /v1/memories/consolidate

Request Body

Field	Type	Default	Description
space_id	string	null	Limit to specific space
similarity_threshold	float	0.85	Similarity threshold (0.5-1.0)
max_consolidations	int	50	Max merges to perform
dry_run	bool	false	Preview without applying

Example

curl -X POST https://memoryapi.tensorheart.com/v1/memories/consolidate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "similarity_threshold": 0.85,
    "dry_run": true
  }'

Response

{
  "success": true,
  "data": {
    "dry_run": true,
    "would_consolidate": 5,
    "would_merge": 12,
    "preview": [
      {
        "memory_ids": ["mem_1", "mem_2"],
        "texts": ["User likes coffee", "User enjoys coffee"]
      }
    ]
  },
  "meta": {
    "request_id": "req_cons123",
    "processing_time_ms": 250
  }
}