Memory Operations

Core endpoints for storing, searching, and managing memories. These endpoints interact with your vector database directly — Engram processes the intelligence pipeline and writes results to your storage.

All endpoints require authentication via the Authorization: Bearer header.

---

Store Memory

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

Store a new memory. Engram embeds the text, auto-classifies it, checks for duplicates, and writes the vector to your vector database.

Authentication required.

Request Body

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/store \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "User prefers dark mode and minimal UI animations",
    "importance": 0.7,
    "metadata": {
      "source": "onboarding",
      "session_id": "s_abc123"
    }
  }'

Python

import requests

response = requests.post(
    "https://api.engrammemory.ai/v1/store",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    json={
        "text": "User prefers dark mode and minimal UI animations",
        "importance": 0.7,
        "metadata": {
            "source": "onboarding",
            "session_id": "s_abc123"
        }
    }
)

memory = response.json()
print(f"Stored: {memory['id']} — Category: {memory['category']}")

JavaScript

const response = await fetch("https://api.engrammemory.ai/v1/store", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "User prefers dark mode and minimal UI animations",
    importance: 0.7,
    metadata: {
      source: "onboarding",
      session_id: "s_abc123"
    }
  })
});

const memory = await response.json();
console.log(`Stored: ${memory.id} — Category: ${memory.category}`);

Response — 201 Created

{
  "id": "mem_9f3a7c2e1b4d",
  "status": "stored",
  "category": "preference",
  "duplicate": false,
  "message": "Memory stored successfully"
}

When a duplicate is detected:

{
  "id": "mem_existing_id",
  "status": "duplicate",
  "category": "preference",
  "duplicate": true,
  "message": "Duplicate memory detected (similarity: 0.97). Existing memory returned."
}

Auto-Classification

If category is not provided, Engram classifies the memory automatically:

Errors

---

Semantic Search

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

Search memories using natural language. Engram embeds the query and performs semantic similarity search against your stored memories.

Authentication required.

Request Body

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/search \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What UI preferences does the user have?",
    "limit": 5,
    "category": "preference",
    "min_score": 0.4
  }'

Python

import requests

response = requests.post(
    "https://api.engrammemory.ai/v1/search",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    json={
        "query": "What UI preferences does the user have?",
        "limit": 5,
        "category": "preference",
        "min_score": 0.4
    }
)

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

JavaScript

const response = await fetch("https://api.engrammemory.ai/v1/search", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query: "What UI preferences does the user have?",
    limit: 5,
    category: "preference",
    min_score: 0.4
  })
});

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

Response — 200 OK

{
  "results": [
    {
      "id": "mem_9f3a7c2e1b4d",
      "text": "User prefers dark mode and minimal UI animations",
      "score": 0.89,
      "category": "preference",
      "importance": 0.7,
      "metadata": {
        "source": "onboarding",
        "session_id": "s_abc123"
      },
      "created_at": "2026-04-08T14:22:00Z"
    },
    {
      "id": "mem_2e8b4f1a9c3d",
      "text": "User wants large font sizes for accessibility",
      "score": 0.72,
      "category": "preference",
      "importance": 0.8,
      "metadata": {},
      "created_at": "2026-04-07T09:15:00Z"
    }
  ],
  "query_tokens": 9
}

Errors

---

Forget Memory

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

Delete a memory by ID or by semantic match. When using query, Engram finds the closest matching memory and deletes it.

Authentication required.

Request Body

Code Examples

cURL

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

# Delete by semantic match
curl -X POST https://api.engrammemory.ai/v1/forget \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query": "dark mode preference"}'

Python

import requests

# Delete by ID
response = requests.post(
    "https://api.engrammemory.ai/v1/forget",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    json={"memory_id": "mem_9f3a7c2e1b4d"}
)

# Delete by semantic match
response = requests.post(
    "https://api.engrammemory.ai/v1/forget",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    json={"query": "dark mode preference"}
)

JavaScript

// Delete by ID
await fetch("https://api.engrammemory.ai/v1/forget", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ memory_id: "mem_9f3a7c2e1b4d" })
});

// Delete by semantic match
await fetch("https://api.engrammemory.ai/v1/forget", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ query: "dark mode preference" })
});

Response — 200 OK

{
  "status": "forgotten",
  "memory_id": "mem_9f3a7c2e1b4d",
  "message": "Memory deleted successfully"
}

Errors

---

Generate Embedding

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

Generate a vector embedding for the given text. This endpoint is stateless — no data is stored. Use it when you need raw vectors for your own pipeline.

Authentication required.

Request Body

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/embed \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "Semantic memory for AI agents"}'

Python

import requests

response = requests.post(
    "https://api.engrammemory.ai/v1/embed",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    json={"text": "Semantic memory for AI agents"}
)

data = response.json()
vector = data["vector"]       # 768-dimensional float array
dim = data["dimension"]       # 768
tokens = data["tokens_used"]  # Token count

JavaScript

const response = await fetch("https://api.engrammemory.ai/v1/embed", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ text: "Semantic memory for AI agents" })
});

const data = await response.json();
const vector = data.vector;     // 768-dimensional float array
const dim = data.dimension;     // 768
const tokens = data.tokens_used;

Response — 200 OK

{
  "vector": [0.0234, -0.0891, 0.0412, "...(768 values)"],
  "dimension": 768,
  "tokens_used": 5
}

Errors

---

Collection Stats

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

Returns statistics about your memory collection.

Authentication required.

Query Parameters

Code Examples

cURL

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

Python

import requests

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

stats = response.json()
print(f"Total memories: {stats['total_memories']}")

JavaScript

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

const stats = await response.json();
console.log(`Total memories: ${stats.total_memories}`);

Response — 200 OK

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

Errors