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.
Prerequisites
- A Weaviate Cloud account
curlor install the Engram Python SDK:
- pip
- uv
pip install weaviate-engram
uv add weaviate-engram
Step 1: Create a project
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.
Concepts to learn
Here are the key concepts:
- Topics — Named categories that control what kinds of information Engram extracts. The topic's description guides the LLM during extraction.
- Groups — Containers of topics. Each group maps to a use case (e.g. personalization, continual learning).
- Scopes — Control who memories belong to. The default topic
UserKnowledgeis user-scoped, meaning you must provide auser_idso each user's memories stay separate.
Visit the concepts section to learn more about how these work together.
Step 2: Create an API key
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..."
Copy and store the API key immediately. You cannot retrieve it again after it is displayed.
Step 3: Connect to Engram
Initialize the client with your API key.
client = EngramClient(
api_key=os.environ["ENGRAM_API_KEY"]
)
Step 4: Store a memory
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)
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.
Example response
{
"run_id": "run-uuid",
"status": "running"
}
Step 5: Search memories
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)
Example response
{
"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
}
Next steps
- 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.
Questions and feedback
If you have any questions or feedback, let us know in the user forum.