Memories API

Create, read, update, and delete memories.

Create Memory

POST /v1/memories

Request Body

Field	Type	Required	Description
text	string	Yes	Memory content (1-50,000 chars)
metadata	object	No	Key-value metadata
memory_id	string	No	Custom ID
space_id	string	No	Memory space to store in

Example

curl -X POST https://api.memory.tensorheart.com/v1/memories \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "User works as a data scientist at TechCorp",
    "metadata": {"category": "professional"},
    "space_id": "work"
  }'

Response

{
  "success": true,
  "data": {
    "id": "mem_abc123",
    "text": "User works as a data scientist at TechCorp",
    "metadata": {"category": "professional"},
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

---

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://api.memory.tensorheart.com/v1/memories?page=1&per_page=20&space_id=work" \
  -H "Authorization: Bearer $API_KEY"

---

Get Memory

GET /v1/memories/{memory_id}

Example

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

---

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://api.memory.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://api.memory.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://api.memory.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://api.memory.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"]
      }
    ]
  }
}