> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryumem.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Basic Usage

> Learn how to use the core features of Ryumem.

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:

```python theme={null}
from ryumem import Ryumem

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

<Note>
  Need to set up Ryumem? See the [Setup Guide](/setup) for Docker Compose or local installation instructions.
</Note>

## Add Episodes

Episodes are the fundamental unit of memory in Ryumem. Each episode contains content that gets parsed into entities and relationships:

```python theme={null}
# 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",
)
```

<Tip>
  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.
</Tip>

## Search Memories

Ryumem supports multiple search strategies. The hybrid strategy combines semantic search, keyword search (BM25), and graph traversal:

```python theme={null}
# 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](/core-concepts/search-strategies).

## Get Entity Context

Retrieve comprehensive information about a specific entity:

```python theme={null}
# 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:

```python theme={null}
from ryumem import Ryumem

# Initialize with your self-hosted server
ryumem = Ryumem(
    server_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.

```python theme={null}
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`](https://github.com/predictable-labs/ryumem/blob/main/examples/integrations/google-adk/password_guessing_game.py).

## Next Steps

<CardGroup cols={2}>
  <Card title="Episodes" icon="book" href="/core-concepts/episodes">
    Learn more about episodes and how they're processed
  </Card>

  <Card title="Search Strategies" icon="magnifying-glass" href="/core-concepts/search-strategies">
    Deep dive into search methods
  </Card>

  <Card title="Google ADK Integration" icon="plug" href="/integrations/google-adk">
    Add memory to AI agents
  </Card>

  <Card title="Multi-Tenancy" icon="users" href="/core-concepts/multi-tenancy">
    Isolate memories by user or session
  </Card>
</CardGroup>