Store memories

Engram supports three content types for storing memories. Each content type is a different entrypoint into the same pipeline.

All examples below use a connected client

See Connect to Engram for how to instantiate one.

Python

import os
from engram import EngramClient

client = EngramClient(api_key=os.environ["ENGRAM_API_KEY"])

Python (Async)

import os
from engram import AsyncEngramClient

client = AsyncEngramClient(api_key=os.environ["ENGRAM_API_KEY"])

cURL

export ENGRAM_API_KEY="eng_..."

String content

Send raw text and let Engram extract structured memories from it.

Python

run = client.memories.add(
    "The user prefers dark mode and works primarily in Python. They are building a RAG application.",
    user_id=test_user_id,
    group="default",
)

print(run.run_id)
print(run.status)

Python (Async)

run = await client.memories.add(
    "The user prefers dark mode and works primarily in Python. They are building a RAG application.",
    user_id=test_user_id,
)

print(run.run_id)
print(run.status)

cURL

curl -X POST https://api.engram.weaviate.io/v1/memories \
  -H "Authorization: Bearer $ENGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "string": {
        "content": [
          "The user prefers dark mode and works primarily in Python. They are building a RAG application."
        ]
      }
    },
    "user_id": "user-uuid",
    "group": "default"
  }'

The pipeline extracts individual facts from the text (e.g. "prefers dark mode", "works in Python") and stores them as separate memories.

Conversation content

Send multi-turn messages and let Engram extract memories from the dialogue. You can send new messages as they happen — there is no need to wait until a conversation is finished.

Python

run = client.memories.add(
    [
        {"role": "user", "content": "I just moved to Berlin and I am looking for a good coffee shop."},
        {"role": "assistant", "content": "Welcome to Berlin! Here are some popular coffee shops in the city..."},
        {"role": "user", "content": "I prefer specialty coffee, not chains."},
    ],
    user_id=test_user_id,
    group="default",
)

print(run.run_id)
print(run.status)

Python (Async)

run = await client.memories.add(
    [
        {"role": "user", "content": "I just moved to Berlin and I am looking for a good coffee shop."},
        {"role": "assistant", "content": "Welcome to Berlin! Here are some popular coffee shops in the city..."},
        {"role": "user", "content": "I prefer specialty coffee, not chains."},
    ],
    user_id=test_user_id,
)

cURL

curl -X POST https://api.engram.weaviate.io/v1/memories \
  -H "Authorization: Bearer $ENGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "conversation": {
        "messages": [
          {
            "role": "user",
            "content": "I just moved to Berlin and I am looking for a good coffee shop."
          },
          {
            "role": "assistant",
            "content": "Welcome to Berlin! Here are some popular coffee shops in the city..."
          },
          {
            "role": "user",
            "content": "I prefer specialty coffee, not chains."
          }
        ]
      }
    },
    "user_id": "user-uuid",
    "group": "default"
  }'

The pipeline reads the messages and extracts relevant facts (e.g. "lives in Berlin", "prefers specialty coffee").

Pre-extracted content

If you've already extracted structured content, send it directly. This bypasses the LLM extraction step, but the content still passes through the transform and commit pipeline stages.

Python

run = client.memories.add(
    PreExtractedInput(items=[
        PreExtractedItem(content="User prefers dark mode", topic="UserKnowledge"),
        PreExtractedItem(content="User works in Python", topic="UserKnowledge"),
    ]),
    user_id=test_user_id,
    group="default",
)

print(run.run_id)
print(run.status)

Python (Async)

run = await client.memories.add(
    PreExtractedInput(items=[
        PreExtractedItem(content="User prefers dark mode", topic="UserKnowledge"),
        PreExtractedItem(content="User works in Python", topic="UserKnowledge"),
    ]),
    user_id=test_user_id,
)

cURL

curl -X POST https://api.engram.weaviate.io/v1/memories \
  -H "Authorization: Bearer $ENGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "pre_extracted": {
        "items": [
          { "content": "User prefers dark mode", "topic": "UserKnowledge" },
          { "content": "User works in Python", "topic": "UserKnowledge" }
        ]
      }
    },
    "user_id": "user-uuid",
    "group": "default"
  }'

Response

All three content types return the same response format:

JSON

{
  "run_id": "run-uuid",
  "status": "running"
}

A successful response means the pipeline has started, not that the memories have been committed. In most cases you don't need to do anything else, since memories become available once the pipeline finishes. If you have a specific reason to confirm completion, you can use the run_id to check the pipeline status.

Optional parameters

Parameter	Type	Description
`user_id`	string	Scope the memory to a specific user. Required if the target topic is user-scoped.
`properties`	object<string, string>	Custom scope properties (e.g. `{"conversation_id": "abc-123"}`). Must include every key any target topic is scoped by.
`group`	string	Memory group name (defaults to `default`)
`root`	string	Pipeline root name (for advanced pipeline configurations)

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.