# 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](https://console.weaviate.cloud) account - `curl` or install the Engram [Python SDK](https://pypi.org/project/weaviate-engram/): :::code-group{sync="python-install"} ```bash title="pip" pip install weaviate-engram ``` ```bash title="uv" uv add weaviate-engram ``` ::: ## Step 1: Create a project Every memory in Engram belongs to a project. Create one in the [Weaviate Cloud console](https://console.weaviate.cloud). 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: [Embedded content embed](https://app.guideflow.com/embed/xrg3yooiwk) 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](../engram-concepts/groups.md) with default [topics](../engram-concepts/topics.md), 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](../engram-concepts/scopes.md) required when adding memories that target it, which is why it's disabled by default. :::accordion{title="Concepts to learn"} Here are the key concepts: - **[Topics](../engram-concepts/topics.md)** — Named categories that control what kinds of information Engram extracts. The topic's description guides the LLM during extraction. - **[Groups](../engram-concepts/groups.md)** — Containers of topics. Each group maps to a use case (e.g. personalization, continual learning). - **[Scopes](../engram-concepts/scopes.md)** — Control who memories belong to. The default topic `UserKnowledge` is user-scoped, meaning you must provide a `user_id` so each user's memories stay separate. Visit the [concepts section](../engram-concepts/index.md) 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: ```bash export ENGRAM_API_KEY="eng_abcdef123456..." ``` :::callout{intent="warning"} Copy and store the API key immediately. You cannot retrieve it again after it is displayed. ::: ## Step 3: Connect to Engram ::::tabs{sync="languages"} :::tab{title="Python"} Initialize the client with your API key. ```python client = EngramClient( api_key=os.environ["ENGRAM_API_KEY"] ) ``` ::: :::tab{title="cURL"} All `curl` commands authenticate via the `Authorization` header with a Bearer token: ```bash -H "Authorization: Bearer $ENGRAM_API_KEY" ``` ::: :::: ## Step 4: Store a memory Send content to Engram using the memory API. This example sends a plain text string. :::code-group{sync="languages"} ```python title="Python" 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) ``` ```bash title="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 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](../engram-guides/check-run-status.md). :::accordion{title="Example response"} ```json { "run_id": "run-uuid", "status": "running" } ``` ::: ## Step 5: Search memories Search for relevant memories using a natural language query. :::code-group{sync="languages"} ```python title="Python" results = client.memories.search( query="What editor does the user prefer?", user_id="alice", ) for memory in results: print(memory.content) ``` ```bash title="cURL" 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 } }' ``` ::: :::accordion{title="Example response"} ```json { "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](../engram-concepts/index.md) like topics, groups, and pipelines. - Explore different ways to [store memories](../engram-guides/store-memories.md), including conversations and pre-extracted data. - See all [search options](../engram-guides/search-memories.md) including vector, BM25, and hybrid retrieval. ## Questions and feedback Have a question or feedback? Here's how to reach us. ::::card-grid :::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"} Ask questions and connect with other developers on our **Community forum**. ::: :::card{title="Support" href="/guides/support-overview" icon="life-buoy"} Weaviate Cloud user or customer? Find the right channel on the **Support page**. ::: :::: ## Related pages - [Agents](./agents-index.md) - [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md) - [APIs](./apis-index.md) - [Authorization and authentication](./authorization-and-authentication-index.md) - [Benchmarks](./benchmarks-index.md) - [Best practices](./best-practices-index.md) - [Client libraries](./clients-index.md) - [Client Libraries / SDKs](./client-libraries-index.md) - [Cloud](./cloud-index.md) - [Cloud account management](./cloud-account-management-index.md) # Agent Instructions This portal answers questions programmatically. To receive a synthesized, source-cited answer instead of crawling page by page, append the `?ask=` query parameter to any page URL on this site: /guides/quickstart?ask=how+do+I+authenticate Optional parameters: - `&goal=` steers the answer toward your objective (e.g. `&goal=write+a+python+client`). - `&version=