Ryumem - Semantic Memory for AI Agents

Ryumem provides zero-boilerplate integration for Google’s Agent Developer Kit, automatically adding memory tools to your agents.

Quick Start

Install Dependencies

pip install ryumem google-adk

Initialize Ryumem

from ryumem import Ryumem

# All configuration is done here
ryumem = Ryumem(
    server_url="http://localhost:8000",
    api_key="ryu_your_api_key_here",
    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 past queries
)

Need to set up a Ryumem server? See the Setup Guide.

Add Memory to Agent

from google.adk.agents import Agent
from ryumem.integrations import add_memory_to_agent

# Create your agent
agent = Agent(
    name="assistant",
    model="gemini-2.0-flash-exp",
    instruction="You are a helpful assistant with memory."
)

# Enable memory - configuration comes from ryumem instance
agent = add_memory_to_agent(agent, ryumem)

The agent now has auto-generated memory tools:

search_memory() - Find relevant information from past conversations
save_memory() - Store new information for later retrieval
get_entity_context() - Get comprehensive context about specific entities (when entity extraction is enabled)

All tool executions are automatically logged when track_tools=True, creating a complete history of what your agent has done.

Automatic Query Tracking & Augmentation

Wrap your runner to automatically track user queries and augment them with relevant historical context:

from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from ryumem.integrations import wrap_runner_with_tracking

# Setup session
session_service = InMemorySessionService()
await session_service.create_session(
    app_name="my_app",
    user_id="user_123",
    session_id="session_456"
)

# Create runner
runner = Runner(
    agent=agent,
    app_name="my_app",
    session_service=session_service
)

# Wrap for auto-tracking and query augmentation
# Configuration comes from the ryumem instance passed to add_memory_to_agent()
runner = wrap_runner_with_tracking(runner, agent)

What This Does

When augment_queries=True (configured in Ryumem instance):

Tracks user queries as episodes automatically
Finds similar past queries using semantic search
Augments new queries with context from similar past conversations
Links queries to tool executions hierarchically

Query augmentation helps agents learn from past interactions. If a user asks “What’s the weather in London?” and later asks “How about London today?”, the second query gets enriched with context from the first.

Configuration Options

All configuration is done when initializing the Ryumem instance:

ryumem = Ryumem(
    server_url="http://localhost:8000",
    api_key="ryu_your_api_key_here",

    # Tool tracking
    track_tools=True,              # Enable tool tracking
    track_queries=True,            # Track user queries as episodes

    # Query augmentation
    augment_queries=True,          # Enable query augmentation
    similarity_threshold=0.3,      # Minimum similarity for augmentation (0.0-1.0)
    top_k_similar=5,               # Number of similar queries to use

    # Entity extraction
    extract_entities=False,        # Extract entities/relationships (saves tokens when False)

    # Memory
    memory_enabled=True,           # Enable memory tools
)

This creates a complete audit trail of:

Which tools were called
What parameters were used
What results were returned
When they were executed

Perfect for debugging, analytics, and improving agent performance over time.

Complete Example

See a full working example in the repository:

Password Guessing Game

Advanced demo showing how query augmentation helps agents learn

Basic Usage

Basic example with memory and search

API Reference

`add_memory_to_agent()`

Adds memory tools to a Google ADK agent. Parameters:

agent - The Google ADK Agent instance
ryumem_instance - Initialized Ryumem instance (all configuration comes from this)

Returns:

The same agent instance (modified in-place with memory tools)

Note: Configuration options like track_tools, extract_entities, etc. are set when initializing the Ryumem instance, not when calling this function.

`wrap_runner_with_tracking()`

Wraps a Google ADK Runner to track queries and optionally augment them with history. Parameters:

original_runner - Google ADK Runner instance
agent_with_memory - Agent that has been enhanced with add_memory_to_agent()

Returns:

The same runner instance (modified in-place with tracking)

Note: Configuration options like augment_queries, similarity_threshold, top_k_similar are set when initializing the Ryumem instance.

Getting Started

Core Concepts

Integrations

Dashboard

Google ADK Integration

Quick Start

Automatic Query Tracking & Augmentation

What This Does

Configuration Options

Complete Example

Password Guessing Game

Basic Usage

API Reference

`add_memory_to_agent()`

`wrap_runner_with_tracking()`

​Quick Start

​Automatic Query Tracking & Augmentation

​What This Does

​Configuration Options

​Complete Example

Password Guessing Game

Basic Usage

​API Reference

​add_memory_to_agent()

​wrap_runner_with_tracking()

Quick Start

Automatic Query Tracking & Augmentation

What This Does

Configuration Options

Complete Example

API Reference

`add_memory_to_agent()`

`wrap_runner_with_tracking()`