Search memories

You can retrieve stored memories using different search techniques.

All examples below use a connected client

See Connect to Engram for how to instantiate one.

Python

import os
from engram import EngramClient

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

Python (Async)

import os
from engram import AsyncEngramClient

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

cURL

export ENGRAM_API_KEY="eng_..."

Basic search

Provide a query and Engram returns the most relevant memories.

Python

results = client.memories.search(
    query="What programming language does the user prefer?",
    user_id=test_user_id,
)

for memory in results:
    print(memory.content)

Python (Async)

results = await client.memories.search(
    query="What programming language does the user prefer?",
    user_id=test_user_id,
)

for memory in results:
    print(memory.content)

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 programming language does the user prefer?",
    "user_id": "user-uuid",
    "group": "default",
    "retrieval_config": {
      "retrieval_type": "hybrid",
      "limit": 5
    }
  }'

JSON

{
  "memories": [
    {
      "id": "memory-uuid",
      "project_id": "project-uuid",
      "user_id": "user-uuid",
      "content": "The user works primarily in Python.",
      "topic": "UserKnowledge",
      "group": "default",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z",
      "score": 0.89
    }
  ],
  "total": 1
}

Retrieval types

Set the retrieval type with retrieval_config. Pass a retrieval model — VectorRetrieval, BM25Retrieval, or HybridRetrieval — each with an optional limit. To use a type with its default settings, you can also pass its name as a string ("vector", "bm25", "hybrid", or "fetch").

Vector search

Pure semantic search using embeddings. Finds memories that are conceptually similar to your query, even without matching keywords.

Python

results = client.memories.search(
    query="What programming language does the user prefer?",
    user_id=test_user_id,
    retrieval_config=VectorRetrieval(limit=10),
)

Python (Async)

results = await client.memories.search(
    query="What programming language does the user prefer?",
    user_id=test_user_id,
    retrieval_config=VectorRetrieval(limit=10),
)

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 programming language does the user prefer?",
    "user_id": "user-uuid",
    "group": "default",
    "retrieval_config": {
      "retrieval_type": "vector",
      "limit": 10
    }
  }'

BM25 search

Full-text keyword search. Best for finding memories that contain specific terms.

Python

results = client.memories.search(
    query="What programming language does the user prefer?",
    user_id=test_user_id,
    retrieval_config=BM25Retrieval(limit=10),
)

Python (Async)

results = await client.memories.search(
    query="What programming language does the user prefer?",
    user_id=test_user_id,
    retrieval_config=BM25Retrieval(limit=10),
)

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": "Python",
    "user_id": "user-uuid",
    "group": "default",
    "retrieval_config": {
      "retrieval_type": "bm25",
      "limit": 10
    }
  }'

Hybrid search

Combines vector and BM25 for the best of both approaches. This is the recommended retrieval type for most use cases.

Python

results = client.memories.search(
    query="What programming language does the user prefer?",
    user_id=test_user_id,
    retrieval_config=HybridRetrieval(limit=10),
)

Python (Async)

results = await client.memories.search(
    query="What programming language does the user prefer?",
    user_id=test_user_id,
    retrieval_config=HybridRetrieval(limit=10),
)

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 programming language does the user prefer?",
    "user_id": "user-uuid",
    "group": "default",
    "retrieval_config": {
      "retrieval_type": "hybrid",
      "limit": 10
    }
  }'

Filter by topic

Restrict your search to specific topics by providing a topics array.

Python

results = client.memories.search(
    query="user preferences",
    topics=["UserKnowledge"],
    user_id=test_user_id,
    retrieval_config=HybridRetrieval(limit=10),
)

for memory in results:
    print(memory.content)

Python (Async)

results = await client.memories.search(
    query="user preferences",
    topics=["UserKnowledge"],
    user_id=test_user_id,
    retrieval_config=HybridRetrieval(limit=10),
)

for memory in results:
    print(memory.content)

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": "user preferences",
    "topics": ["UserKnowledge"],
    "user_id": "user-uuid",
    "group": "default",
    "retrieval_config": {
      "retrieval_type": "hybrid",
      "limit": 10
    }
  }'

If you omit topics, Engram searches across all topics in the group.

Scoping

Search results are scoped to match the parameters you provide:

user_id — Required for user-scoped topics. Only returns memories for this user.
properties — Optional map of custom scope properties (e.g. {"conversation_id": "abc-123"}). Including a key narrows results; omitting a key searches across all values for that key.
group — Search within this group. Defaults to default.

Per-topic property filters

When searching multiple topics with different scope requirements, you can override the global properties filter on a per-topic basis. Pass an object instead of a string in the topics array:

Python

from engram import Topic

results = client.memories.search(
    query="...",
    user_id="alice",
    properties={"conversation_id": "abc-123"},  # global default
    topics=[
        "user_facts",                                            # not conversation-scoped, ignores the filter
        Topic(name="conversation_summary"),                      # uses the global filter
        Topic(name="messages", properties={"conversation_id": None}),  # clear filter — all conversations
    ],
)

A null value clears an inherited global filter for that topic only.

Questions and feedback

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

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.