Quickstart

Engram is a memory server for LLM agents and applications. It automatically extracts, transforms, and stores memories using vector embeddings and LLM-powered processing.

This guide walks you through the core Engram workflow: create a project, get an API key, store a memory, and search for it.

• A Weaviate Cloud account
• curl or install the Engram Python SDK:

pip install weaviate-engram

uv add weaviate-engram

Every memory in Engram belongs to a project. Create one in the Weaviate Cloud console.

Follow this interactive walkthrough to create a project with the Personalization template, set up its group and the UserKnowledge topic, and generate an API key to connect to it:

You can select a predefined template when creating a project. For this tutorial, use the Personalization template.

The template sets up the project's default group with default topics, such as UserKnowledge for general information about the user. This is enough to get started.

The template also lets you optionally add a ConversationSummary topic, which maintains a single summary per conversation. Enabling this option makes a conversation_id property required when adding memories that target it, which is why it's disabled by default.

Generate an API key for your project in the Weaviate Cloud console. The full key is only shown once — save it securely.

Set it as an environment variable for the examples below:

export ENGRAM_API_KEY="eng_abcdef123456..."

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

-H "Authorization: Bearer $ENGRAM_API_KEY"

Send content to Engram using the memory API. This example sends a plain text string.

run = client.memories.add(
    "The user prefers dark mode and uses VS Code as their primary editor.",
    user_id="alice",  # any unique string per user (e.g. a username)
)

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

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 uses VS Code as their primary editor."
        ]
      }
    },
    "user_id": "user-uuid"
  }'

Engram processes memories asynchronously and immediately returns a run_id. In most cases you don't need to wait, since memories become available for search once the pipeline finishes. If you want to confirm when a run completes, see Check run status.

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

Search for relevant memories using a natural language query.

results = client.memories.search(
    query="What editor does the user prefer?",
    user_id="alice",
)

for memory in results:
    print(memory.content)

curl -X POST https://api.engram.weaviate.io/v1/memories/search \
  -H "Authorization: Bearer $ENGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What editor does the user prefer?",
    "user_id": "user-uuid",
    "retrieval_config": {
      "retrieval_type": "hybrid",
      "limit": 5
    }
  }'

{
  "memories": [
    {
      "id": "memory-uuid",
      "project_id": "project-uuid",
      "user_id": "user-uuid",
      "content": "The user prefers dark mode.",
      "topic": "UserKnowledge",
      "group": "default",
      "created_at": "2025-01-01T00:00:01Z",
      "updated_at": "2025-01-01T00:00:01Z",
      "score": 1
    },
    {
      "id": "memory-uuid-2",
      "project_id": "project-uuid",
      "user_id": "user-uuid",
      "content": "The user uses VS Code as their primary editor.",
      "topic": "UserKnowledge",
      "group": "default",
      "created_at": "2025-01-01T00:00:01Z",
      "updated_at": "2025-01-01T00:00:01Z",
      "score": 1
    }
  ],
  "total": 2
}

• Learn about core concepts like topics, groups, and pipelines.
• Explore different ways to store memories, including conversations and pre-extracted data.
• See all search options including vector, BM25, and hybrid retrieval.

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