Overflow Storage

Overflow is Engram's opt-in hosted storage. When you do not want to run your own vector database, Overflow provides managed vector storage backed by Engram's infrastructure. Vectors are automatically compressed before storage.

All Overflow endpoints require authentication via the Authorization: Bearer header.

---

Store in Overflow

<div class="method-badge post">POST</div> `/v1/overflow/store`

Store a memory in Engram's hosted storage. Vectors are auto-compressed before writing.

Authentication required.

Request Body

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/overflow/store \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.0234, -0.0891, 0.0412, "...(768 values)"],
    "text": "User prefers dark mode",
    "category": "preference",
    "importance": 0.7,
    "metadata": {"source": "onboarding"}
  }'

Python

import requests

# Typically used after an /v1/intelligence call
intel = requests.post(
    "https://api.engrammemory.ai/v1/intelligence",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    json={"text": "User prefers dark mode", "compress": False}
).json()

# Store the result in Overflow
response = requests.post(
    "https://api.engrammemory.ai/v1/overflow/store",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    json={
        "vector": intel["vector"],
        "text": "User prefers dark mode",
        "category": intel["category"],
        "importance": 0.7,
        "metadata": {"source": "onboarding"}
    }
)

result = response.json()
print(f"Stored: {result['id']} (compressed {result['compression_ratio']}x)")

JavaScript

// Typically used after an /v1/intelligence call
const intelRes = await fetch("https://api.engrammemory.ai/v1/intelligence", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ text: "User prefers dark mode", compress: false })
});
const intel = await intelRes.json();

// Store the result in Overflow
const response = await fetch("https://api.engrammemory.ai/v1/overflow/store", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    vector: intel.vector,
    text: "User prefers dark mode",
    category: intel.category,
    importance: 0.7,
    metadata: { source: "onboarding" }
  })
});

const result = await response.json();
console.log(`Stored: ${result.id} (compressed ${result.compression_ratio}x)`);

Response — 201 Created

{
  "id": "mem_9f3a7c2e1b4d",
  "status": "stored",
  "tier": "builder",
  "collection": "memories",
  "compressed": true,
  "compression_ratio": 6.2
}

Errors

---

Search Overflow

<div class="method-badge post">POST</div> `/v1/overflow/search`

Semantic search across memories stored in Overflow.

Authentication required.

Request Body

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/overflow/search \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.0234, -0.0891, 0.0412, "...(768 values)"],
    "limit": 10,
    "min_score": 0.35,
    "category": "preference"
  }'

Python

import requests

# Embed the query first
embed = requests.post(
    "https://api.engrammemory.ai/v1/embed",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    json={"text": "What are the user's UI preferences?"}
).json()

# Search Overflow with the vector
response = requests.post(
    "https://api.engrammemory.ai/v1/overflow/search",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    json={
        "vector": embed["vector"],
        "limit": 10,
        "min_score": 0.35,
        "category": "preference"
    }
)

results = response.json()["results"]
for r in results:
    print(f"[{r['score']:.2f}] {r['text']}")

JavaScript

// Embed the query first
const embedRes = await fetch("https://api.engrammemory.ai/v1/embed", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ text: "What are the user's UI preferences?" })
});
const embed = await embedRes.json();

// Search Overflow with the vector
const response = await fetch("https://api.engrammemory.ai/v1/overflow/search", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    vector: embed.vector,
    limit: 10,
    min_score: 0.35,
    category: "preference"
  })
});

const { results } = await response.json();
results.forEach(r => console.log(`[${r.score.toFixed(2)}] ${r.text}`));

Response — 200 OK

{
  "results": [
    {
      "id": "mem_9f3a7c2e1b4d",
      "text": "User prefers dark mode",
      "score": 0.89,
      "category": "preference",
      "importance": 0.7,
      "metadata": {"source": "onboarding"},
      "created_at": "2026-04-08T14:22:00Z"
    }
  ],
  "total": 1
}

Errors

---

Delete from Overflow

<div class="method-badge delete">DELETE</div> `/v1/overflow/forget`

Delete a specific memory from Overflow storage.

Authentication required.

Request Body

Code Examples

cURL

curl -X DELETE https://api.engrammemory.ai/v1/overflow/forget \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"memory_id": "mem_9f3a7c2e1b4d"}'

Python

import requests

response = requests.delete(
    "https://api.engrammemory.ai/v1/overflow/forget",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    json={"memory_id": "mem_9f3a7c2e1b4d"}
)

print(response.json()["status"])  # "forgotten"

JavaScript

const response = await fetch("https://api.engrammemory.ai/v1/overflow/forget", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer pr_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ memory_id: "mem_9f3a7c2e1b4d" })
});

const result = await response.json();
console.log(result.status); // "forgotten"

Response — 200 OK

{
  "status": "forgotten",
  "memory_id": "mem_9f3a7c2e1b4d"
}

Errors

---

Overflow Stats

<div class="method-badge get">GET</div> `/v1/overflow/stats`

Returns storage statistics for your Overflow account.

Authentication required.

Code Examples

cURL

curl -X GET https://api.engrammemory.ai/v1/overflow/stats \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

import requests

response = requests.get(
    "https://api.engrammemory.ai/v1/overflow/stats",
    headers={"Authorization": "Bearer pr_live_xxxxx"}
)

stats = response.json()
print(f"Memories: {stats['total_memories']} | Storage: {stats['storage_bytes'] / 1024 / 1024:.1f} MB")

JavaScript

const response = await fetch("https://api.engrammemory.ai/v1/overflow/stats", {
  headers: { "Authorization": "Bearer pr_live_xxxxx" }
});

const stats = await response.json();
console.log(`Memories: ${stats.total_memories} | Storage: ${(stats.storage_bytes / 1024 / 1024).toFixed(1)} MB`);

Response — 200 OK

{
  "total_memories": 4821,
  "categories": {
    "preference": 812,
    "decision": 445,
    "fact": 2104,
    "entity": 1023,
    "other": 437
  },
  "storage_bytes": 15482880,
  "compression_savings_bytes": 81285120,
  "oldest_memory": "2026-01-15T08:00:00Z",
  "newest_memory": "2026-04-10T11:30:00Z"
}

Errors

---

Browse Memories

<div class="method-badge get">GET</div> `/v1/overflow/memories`

Browse memories with pagination and filtering. Returns memories sorted by the specified field.

Authentication required.

Query Parameters

Code Examples

cURL

curl -X GET "https://api.engrammemory.ai/v1/overflow/memories?page=1&limit=20&sort=importance&category=decision" \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

import requests

response = requests.get(
    "https://api.engrammemory.ai/v1/overflow/memories",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    params={
        "page": 1,
        "limit": 20,
        "sort": "importance",
        "category": "decision"
    }
)

data = response.json()
for memory in data["memories"]:
    print(f"[{memory['importance']}] {memory['text'][:60]}")
print(f"Page {data['page']} of {data['total_pages']}")

JavaScript

const params = new URLSearchParams({
  page: "1",
  limit: "20",
  sort: "importance",
  category: "decision"
});

const response = await fetch(
  `https://api.engrammemory.ai/v1/overflow/memories?${params}`,
  { headers: { "Authorization": "Bearer pr_live_xxxxx" } }
);

const data = await response.json();
data.memories.forEach(m => console.log(`[${m.importance}] ${m.text.slice(0, 60)}`));
console.log(`Page ${data.page} of ${data.total_pages}`);

Response — 200 OK

{
  "memories": [
    {
      "id": "mem_9f3a7c2e1b4d",
      "text": "Chose the relational database for this project",
      "category": "decision",
      "importance": 0.9,
      "metadata": {"project": "api-v2"},
      "created_at": "2026-04-08T14:22:00Z",
      "updated_at": "2026-04-08T14:22:00Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 445,
  "total_pages": 23
}

Errors

---

Get Memory

<div class="method-badge get">GET</div> `/v1/overflow/memory/{memory_id}`

Retrieve a specific memory by ID.

Authentication required.

Path Parameters

Code Examples

cURL

curl -X GET https://api.engrammemory.ai/v1/overflow/memory/mem_9f3a7c2e1b4d \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

import requests

response = requests.get(
    "https://api.engrammemory.ai/v1/overflow/memory/mem_9f3a7c2e1b4d",
    headers={"Authorization": "Bearer pr_live_xxxxx"}
)

memory = response.json()
print(f"{memory['category']}: {memory['text']}")

JavaScript

const response = await fetch(
  "https://api.engrammemory.ai/v1/overflow/memory/mem_9f3a7c2e1b4d",
  { headers: { "Authorization": "Bearer pr_live_xxxxx" } }
);

const memory = await response.json();
console.log(`${memory.category}: ${memory.text}`);

Response — 200 OK

{
  "id": "mem_9f3a7c2e1b4d",
  "text": "User prefers dark mode",
  "category": "preference",
  "importance": 0.7,
  "metadata": {"source": "onboarding"},
  "collection": "memories",
  "created_at": "2026-04-08T14:22:00Z",
  "updated_at": "2026-04-08T14:22:00Z"
}

Errors

---

Memory History

<div class="method-badge get">GET</div> `/v1/overflow/memory/{memory_id}/history`

Get the mutation history for a specific memory. Shows all changes including importance updates, decay events, and promotions.

Authentication required.

Path Parameters

Code Examples

cURL

curl -X GET https://api.engrammemory.ai/v1/overflow/memory/mem_9f3a7c2e1b4d/history \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

import requests

response = requests.get(
    "https://api.engrammemory.ai/v1/overflow/memory/mem_9f3a7c2e1b4d/history",
    headers={"Authorization": "Bearer pr_live_xxxxx"}
)

for event in response.json()["events"]:
    print(f"{event['timestamp']} — {event['action']}: {event['details']}")

JavaScript

const response = await fetch(
  "https://api.engrammemory.ai/v1/overflow/memory/mem_9f3a7c2e1b4d/history",
  { headers: { "Authorization": "Bearer pr_live_xxxxx" } }
);

const { events } = await response.json();
events.forEach(e => console.log(`${e.timestamp} — ${e.action}: ${e.details}`));

Response — 200 OK

{
  "memory_id": "mem_9f3a7c2e1b4d",
  "events": [
    {
      "action": "created",
      "timestamp": "2026-04-08T14:22:00Z",
      "details": {
        "category": "preference",
        "importance": 0.7
      }
    },
    {
      "action": "importance_updated",
      "timestamp": "2026-04-09T10:00:00Z",
      "details": {
        "previous": 0.7,
        "new": 0.85,
        "reason": "promoted"
      }
    },
    {
      "action": "decayed",
      "timestamp": "2026-04-10T00:00:00Z",
      "details": {
        "previous": 0.85,
        "new": 0.82,
        "decay_rate": 0.035
      }
    }
  ]
}

Errors

---

Memory Versions

<div class="method-badge get">GET</div> `/v1/overflow/memory/{memory_id}/versions`

Get all versions of a memory. Each mutation creates a new version while preserving the previous state.

Authentication required.

Path Parameters

Code Examples

cURL

curl -X GET https://api.engrammemory.ai/v1/overflow/memory/mem_9f3a7c2e1b4d/versions \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

import requests

response = requests.get(
    "https://api.engrammemory.ai/v1/overflow/memory/mem_9f3a7c2e1b4d/versions",
    headers={"Authorization": "Bearer pr_live_xxxxx"}
)

versions = response.json()["versions"]
print(f"Total versions: {len(versions)}")
for v in versions:
    print(f"  v{v['version']} — importance: {v['importance']} ({v['created_at']})")

JavaScript

const response = await fetch(
  "https://api.engrammemory.ai/v1/overflow/memory/mem_9f3a7c2e1b4d/versions",
  { headers: { "Authorization": "Bearer pr_live_xxxxx" } }
);

const { versions } = await response.json();
console.log(`Total versions: ${versions.length}`);
versions.forEach(v => console.log(`  v${v.version} — importance: ${v.importance} (${v.created_at})`));

Response — 200 OK

{
  "memory_id": "mem_9f3a7c2e1b4d",
  "versions": [
    {
      "version": 1,
      "text": "User prefers dark mode",
      "category": "preference",
      "importance": 0.7,
      "created_at": "2026-04-08T14:22:00Z"
    },
    {
      "version": 2,
      "text": "User prefers dark mode",
      "category": "preference",
      "importance": 0.85,
      "created_at": "2026-04-09T10:00:00Z"
    }
  ]
}

Errors

---

Promote Memory

<div class="method-badge post">POST</div> `/v1/overflow/promote`

Increase a memory's importance score. Used to signal that a memory was useful or relevant.

Authentication required.

Request Body

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/overflow/promote \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_id": "mem_9f3a7c2e1b4d",
    "boost": 0.15
  }'

Python

import requests

response = requests.post(
    "https://api.engrammemory.ai/v1/overflow/promote",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    json={
        "memory_id": "mem_9f3a7c2e1b4d",
        "boost": 0.15
    }
)

result = response.json()
print(f"Importance: {result['previous_importance']} → {result['new_importance']}")

JavaScript

const response = await fetch("https://api.engrammemory.ai/v1/overflow/promote", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    memory_id: "mem_9f3a7c2e1b4d",
    boost: 0.15
  })
});

const result = await response.json();
console.log(`Importance: ${result.previous_importance} → ${result.new_importance}`);

Response — 200 OK

{
  "memory_id": "mem_9f3a7c2e1b4d",
  "previous_importance": 0.7,
  "new_importance": 0.85,
  "status": "promoted"
}

Errors

---

Update Importance

<div class="method-badge post">POST</div> `/v1/overflow/update-importance`

Set a memory's importance to an exact value. Unlike promote, this sets the absolute score rather than incrementing.

Authentication required.

Request Body

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/overflow/update-importance \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_id": "mem_9f3a7c2e1b4d",
    "importance": 0.95
  }'

Python

import requests

response = requests.post(
    "https://api.engrammemory.ai/v1/overflow/update-importance",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    json={
        "memory_id": "mem_9f3a7c2e1b4d",
        "importance": 0.95
    }
)

result = response.json()
print(f"Importance set to {result['new_importance']}")

JavaScript

const response = await fetch("https://api.engrammemory.ai/v1/overflow/update-importance", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    memory_id: "mem_9f3a7c2e1b4d",
    importance: 0.95
  })
});

const result = await response.json();
console.log(`Importance set to ${result.new_importance}`);

Response — 200 OK

{
  "memory_id": "mem_9f3a7c2e1b4d",
  "previous_importance": 0.85,
  "new_importance": 0.95,
  "status": "updated"
}

Errors

---

Force Decay

<div class="method-badge post">POST</div> `/v1/overflow/force-decay`

Manually trigger importance decay on a memory. Useful for deprioritizing outdated information without deleting it.

Authentication required.

Request Body

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/overflow/force-decay \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_id": "mem_9f3a7c2e1b4d",
    "decay_rate": 0.2
  }'

Python

import requests

response = requests.post(
    "https://api.engrammemory.ai/v1/overflow/force-decay",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    json={
        "memory_id": "mem_9f3a7c2e1b4d",
        "decay_rate": 0.2
    }
)

result = response.json()
print(f"Decayed: {result['previous_importance']} → {result['new_importance']}")

JavaScript

const response = await fetch("https://api.engrammemory.ai/v1/overflow/force-decay", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    memory_id: "mem_9f3a7c2e1b4d",
    decay_rate: 0.2
  })
});

const result = await response.json();
console.log(`Decayed: ${result.previous_importance} → ${result.new_importance}`);

Response — 200 OK

{
  "memory_id": "mem_9f3a7c2e1b4d",
  "previous_importance": 0.85,
  "new_importance": 0.68,
  "decay_rate": 0.2,
  "status": "decayed"
}

Errors