Skip to main content
This guide demonstrates the fundamental operations in Ryumem: initialization, adding episodes, and performing searches.

​
Initialize Ryumem

First, import and initialize Ryumem with your server URL and API key: 
from ryumem import Ryumem

# Initialize with your self-hosted Ryumem server
ryumem = Ryumem(
    api_url="http://localhost:8000",
    api_key="ryu_your_api_key_here",
)
Need to set up Ryumem? See the Setup Guide for Docker Compose or local installation instructions.

​
Add Episodes

Episodes are the fundamental unit of memory in Ryumem. Each episode contains content that gets parsed into entities and relationships: 
# Add your first episode
ryumem.add_episode(
    content="Alice works at Google in Mountain View as a Software Engineer.",
    user_id="user_123",
    session_id="session_abc",
)

# Add a related episode
ryumem.add_episode(
    content="Bob is Alice's colleague and recently moved to Meta.",
    user_id="user_123",
    session_id="session_abc",
)
The user_id parameter is used for multi-tenancy to isolate memories by user. The session_id groups related episodes together within a conversation or session.

​
Search Memories

Ryumem supports multiple search strategies. The hybrid strategy combines semantic search, keyword search (BM25), and graph traversal: 
# Search using hybrid strategy
results = ryumem.search(
    query="Where does Alice work?",
    user_id="user_123",
    session_id="session_abc",
    strategy="hybrid",  # Combines semantic + BM25 + graph traversal
    limit=10,
)

# Display entities found
for entity in results.entities:
    score = results.scores.get(entity.uuid, 0.0)
    print(f"{entity.name} ({entity.entity_type}) - Score: {score:.3f}")

# Display relationships (edges) found
for edge in results.edges:
    print(f"Relationship: {edge.fact}")

​
Search Strategies

  • semantic - Uses embeddings for meaning-based search
  • bm25 - Traditional keyword-based search
  • traversal - Explores connected entities via graph traversal
  • hybrid - Combines all three methods (recommended)
Learn more in Search Strategies.

​
Get Entity Context

Retrieve comprehensive information about a specific entity: 
# Get all context for an entity
context = ryumem.get_entity_context(
    entity_name="Alice",
    user_id="user_123",
    session_id="session_abc",
)

print(f"Entity: {context['entity']['name']}")
print(f"Type: {context['entity']['entity_type']}")
print(f"Relationships: {context['relationship_count']}")

​
Complete Example

Here’s a complete working example: 
from ryumem import Ryumem

# Initialize with your self-hosted server
ryumem = Ryumem(
    api_url="http://localhost:8000",
    api_key="ryu_your_api_key_here"
)

# Add knowledge
ryumem.add_episode(
    content="Alice works at Google in Mountain View as a Software Engineer.",
    user_id="user_123",
    session_id="session_abc",
)

ryumem.add_episode(
    content="Bob is Alice's colleague and recently moved to Meta.",
    user_id="user_123",
    session_id="session_abc",
)

# Search
results = ryumem.search(
    query="Where does Alice work?",
    user_id="user_123",
    session_id="session_abc",
    strategy="hybrid",
    limit=10,
)

# Process results
for entity in results.entities:
    score = results.scores.get(entity.uuid, 0.0)
    print(f"{entity.name} - {score:.3f}")

​
Password Guessing Game Example

This example demonstrates Ryumem’s query augmentation with Google ADK. An AI agent learns from previous attempts to guess a password more intelligently. 
from ryumem import Ryumem
from ryumem.integrations import add_memory_to_agent, wrap_runner_with_tracking
from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.runners import Runner

# Initialize Ryumem with query augmentation
ryumem = Ryumem(
    track_tools=True,           # Enable tool tracking
    augment_queries=True,       # Enable query augmentation
    similarity_threshold=0.3,   # Match queries with 30%+ similarity
    top_k_similar=5,            # Use top 5 similar queries for context
)

# Create your agent with tools
agent = Agent(
    model="gemini-2.0-flash-exp",
    name="password_guesser",
    instruction="You are a strategic password guesser...",
    tools=[validate_tool, history_tool, hint_tool]
)

# Add memory to the agent
agent = add_memory_to_agent(agent, ryumem)

# Wrap the runner for automatic query tracking
runner = wrap_runner_with_tracking(runner, agent)
The full example is available at examples/integrations/google-adk/password_guessing_game.py.

​
Next Steps

Episodes

Learn more about episodes and how they’re processed

Search Strategies

Deep dive into search methods

Google ADK Integration

Add memory to AI agents

Multi-Tenancy

Isolate memories by user or session