What is Weaviate Engram as a managed memory service?

Weaviate Engram is a managed memory service built on the Weaviate vector database. It turns raw conversations, notes, and events into searchable memories without asking your application to run extraction, deduplication, and indexing by hand. You send content through a project API key. An asynchronous pipeline extracts facts, reconciles them with what already exists, and commits the result into Weaviate. This chapter explains why agents need that managed layer, how projects, groups, topics, and scopes shape memory, how the add-and-search loop works in the real SDK, and why hybrid retrieval on Weaviate is the default way Engram answers recall questions.

Why Do Agents Need a Managed Memory Service Instead of Raw Logs?

Long context windows look like memory until they fail. Models get lost in long prompts. Token cost rises on every turn. Raw chat logs stay noisy, contradictory, and hard to reuse across sessions. Dumping every message into a vector index helps latency, but it still leaves conflict resolution to the next prompt. Agents that must learn preferences, procedures, and corrections need actively maintained facts, not an ever-growing transcript pile.

Engram treats memory as infrastructure. The service extracts discrete memories that match your configured topics. Transform steps merge duplicates and update changed facts. Commit steps persist the outcome into Weaviate with embeddings ready for search. Your app stays on a thin API. The heavy work runs asynchronously so the request path stays fast.

That split also protects product teams from rebuilding the same glue in every agent. One service owns extraction quality, isolation, and retrieval. Many surfaces can call it with the same project key and the same scoping rules.

Once you accept managed memory, the next question is how Engram organizes what gets remembered.

How Do Projects, Groups, Topics, and Scopes Fit Together?

Every memory belongs to a project. The API key carries that project boundary. Inside a project, a group bundles topics with a pipeline for one use case. Most apps start with the default group. Separate groups when personalization and continual learning need different extraction rules.

Topics are the magnets for extraction. Each topic has a natural-language description that tells the pipeline what kind of fact to keep, such as user knowledge or a tech stack. Topics also declare scopes. User-scoped topics require a user_id and stay hard-isolated between users through Weaviate multi-tenancy. Property scopes add soft cuts like a conversation or job id. Bounded topics keep at most one memory per scope, which fits profiles and running summaries.

That model is the product schema for memory. You do not start by inventing collection JSON for every agent. You name what matters, how isolation works, and which pipeline owns the use case. Weaviate remains the storage and search engine underneath. Templates such as personalization seed a sensible default topic set so you can ship a first loop before you tune descriptions.

Concepts become concrete when you see the write path and the read path in one shop-floor loop.

What Does the Core Engram Loop Look Like in Code?

A luthier bench assistant stores rehair notes as string input, waits for the run when tests need certainty, then hybrid-searches before the next answer. The bench id is the verified user scope.

import os
from engram import EngramClient, HybridRetrieval

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

bench = "bow-rehair-west"
group = "luthier_bench"

run = client.memories.add(
    "West bench rehaired a pernambuco cello bow with 3.2g of unbleached hair. "
    "Keep the tip wedge slightly proud on this frog. "
    "Customer wants less spring than the last rehair on bow RB-118.",
    user_id=bench,
    group=group,
)
client.runs.wait(run.run_id)

hits = client.memories.search(
    query="cello bow RB-118 hair weight and tip wedge preference",
    user_id=bench,
    group=group,
    retrieval_config=HybridRetrieval(limit=5),
)

assert any("RB-118" in m.content for m in hits)
assert any("3.2g" in m.content for m in hits)

memories.add returns a run_id immediately while the pipeline extracts and commits. runs.wait is optional in production fire-and-forget paths. It is useful in tests and demos when you must prove the memory exists before search. memories.search with HybridRetrieval is the recommended recall path because shop talk mixes codes like RB-118 with paraphrases about spring and wedge height.

Conversation-shaped input works the same way when your agent already speaks in role and content turns. Pre-extracted input is available when another agent decided the topic. The SDK shape stays familiar across those entry points.

The loop is simple on purpose. The flexibility lives in how you configure topics and how you choose retrieval.

How Does Engram Use Weaviate Without Making You Operate the Index?

Engram persists memories as vector-embedded objects in Weaviate. Search can use vector similarity, BM25, or hybrid fusion. Hybrid is the default recommendation for agent memory because operators mix exact tokens with fuzzy language. User and group isolation map onto Weaviate multi-tenancy so one bench cannot read another by accident. You still benefit from Weaviate’s native hybrid operator and tenancy model. You do not have to wire extraction prompts, conflict merges, and collection ops for every product surface.

Input stays flexible. Strings cover events and notes. Conversations cover chat turns. Pre-extracted facts cover cases where your own agent already decided the topic. All three enter the same pipeline family through different extract steps, then share transform and commit behavior downstream. Runs expose statuses such as running, completed, or failed, and completed runs can list which memories were created, updated, or deleted.

Managed does not mean opaque. You still need habits that keep memory trustworthy as traffic grows.

What Operating Habits Make Engram Succeed in Production?

Derive user_id from authenticated sessions. Never let the model invent the isolation key. Prefer deterministic recall before each turn rather than hoping the agent remembers to call a memory tool. Keep recent messages for local dialogue continuity, and let Engram supply the durable facts. Tune topic descriptions when extraction drifts. Use separate groups when two use cases would otherwise collide.

Poll runs when you need audit detail about created, updated, or deleted memories. Otherwise treat memory as eventually consistent and keep the user path non-blocking. Measure hybrid recall on real phrases from your domain, including the codes your operators type by muscle memory. Pair those checks with cross-user probes so a search under the wrong bench id returns nothing. Engram is the managed memory layer. Weaviate is the engine that makes scoped hybrid recall fast enough for agents that cannot afford to start every session cold.

Our next chapter, What are memories as Engram’s core unit?, zooms in on the memory object itself. It covers the fields, lifecycle, and retrieval scores that sit behind every successful add and search call you just saw.