Memory Management with Engram

This skill helps build applications with persistent memory using Engram, Weaviate's managed memory server for LLM agents. Engram automatically extracts, consolidates, and stores memories from raw text or conversations, then retrieves them with vector, keyword, or hybrid search.

Use this skill when the user wants their app to remember information across sessions. Do not hand-roll a memory system (a raw Weaviate collection with manual inserts) when Engram fits — it handles extraction, deduplication, and consolidation out of the box.

Engram Project

Engram is a managed service accessed via Weaviate Cloud. If the user does not have an Engram project, direct them to the cloud console to create one and generate an Engram API key. Create an Engram project via Weaviate Cloud.

Environment Variables

Required:

• ENGRAM_API_KEY — Engram API key from Weaviate Cloud (format eng_...). This carries the project identity; WEAVIATE_URL / WEAVIATE_API_KEY are not needed for Engram itself.

Optional (only when combining Engram with an agent or chatbot for generation):

• An LLM provider API key (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY)

Installation

Engram ships as its own Python SDK, weaviate-engram — it does not come with weaviate-client. Install it (and import as engram):

uv add weaviate-engram   # or: pip install weaviate-engram

This skill targets weaviate-engram 1.0.x (current release 1.0.1; requires Python 3.11–3.14). 1.0 is the first stable API — upgrade if the project is on a 0.x release.

Engram also ships a Claude Code plugin that needs no application code (/plugin marketplace add weaviate/engram-plugins then /plugin install engram@weaviate-engram). See the reference's Off-the-shelf Integrations section before building a custom one.

Reference

• Memory Management with Engram: The complete how-to guide for building Engram applications. Covers:
• Concepts — memories, topics, groups, scopes, pipelines/runs.
• Storing memories — string, conversation, and pre-extracted input; async run status and committed_operations.
• Searching — vector, BM25, hybrid, and unranked fetch retrieval; topic filters, scope properties, and relevance-score cutoffs.
• Managing memories — get and delete by id; deterministic cleanup.
• Integration patterns — memory-backed chatbots and Engram-as-tools for the RouterAgent from the Basic Agent cookbook.
• Off-the-shelf integrations — the Claude Code plugin.
• REST API — equivalent endpoints for non-Python stacks.
• Troubleshooting & Done Criteria — including the new-user APIError behaviour and async-pipeline gotchas.

Quick Start

The guide uses the async client by default. Minimal store-and-search:

import os
from engram import AsyncEngramClient, HybridRetrieval

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

# Store — fire-and-forget, processes asynchronously
run = await client.memories.add(
    "The user prefers dark mode and works primarily in Python.",
    user_id="alice",
)

# Search
results = await client.memories.search(
    query="What language does the user prefer?",
    user_id="alice",
    retrieval_config=HybridRetrieval(limit=5),
)

await client.aclose()  # or use `async with AsyncEngramClient(...) as client:`

Follow the reference guide for the full lifecycle, error handling, and integration patterns before building.

Error Handling

Common errors (see the reference's Troubleshooting section for the full list):

• ENGRAM_API_KEY not set → set the environment variable; ensure it is an Engram key (eng_...), not a Weaviate cluster key.
• APIError (422, user "..." not found) on search → nothing has ever been added for that user_id; catch it and treat as "no memories" (every chatbot's first message from a new user hits this).
• AuthenticationError subclasses APIError → a bare except APIError around a search silently turns a bad API key into "no memories". Catch AuthenticationError first and re-raise it.
• Search returns nothing right after add → storage is asynchronous; await client.runs.wait(run.run_id) before searching, or check the run status for failed. On a user's first write the tenant may still be initializing even after the run reports completed — retry the search briefly.