> ## 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.

# Architecture

> How Ryumem's components work together to provide memory for AI agents.

Ryumem is a modular system with four main layers that work together to give AI agents intelligent, long-term memory.

## System Overview

```
        SDK / MCP / REST API
               |
               v
        +--------------+
        |  API Server  |
        |   (FastAPI)  |
        +--------------+
               |
               v
        +--------------+
        |  Processing  |
        | Ingestion,   |
        | Search, LLM  |
        +--------------+
               |
               v
        +--------------+
        |   Storage    |
        | (RyugraphDB) |
        +--------------+
```

## Components

<CardGroup cols={2}>
  <Card title="API Server" icon="server">
    FastAPI backend providing REST endpoints for episode management, search, entity operations, and configuration.
  </Card>

  <Card title="Python SDK" icon="python">
    Client library for Python applications. Includes Google ADK integration for automatic tool tracking.
  </Card>

  <Card title="MCP Server" icon="plug">
    TypeScript server implementing Model Context Protocol for Claude Desktop, Cursor, and other MCP-compatible agents.
  </Card>

  <Card title="Dashboard" icon="chart-line">
    Next.js web UI for graph visualization, entity browsing, and memory analytics.
  </Card>
</CardGroup>

## Data Flow: Ingestion

When you add an episode:

```
  Content (text/message/json)
            |
            v
     Deduplication Check
     (semantic + BM25)
            |
            v
     Episode Storage
     (save + embed)
            |
            v
   [If extraction enabled]
            |
    +-------+-------+
    |               |
    v               v
 Entities    Relationships
 (dedup)      (extract)
    |               |
    +-------+-------+
            |
            v
    Link via MENTIONS
```

**Key Points:**

* Episodes are deduplicated using both semantic similarity and BM25 keyword matching
* Entity extraction is optional and configurable per-user
* Entities are deduplicated by name similarity (threshold: 0.65)
* Relationships link entities with bi-temporal metadata

## Data Flow: Search

When you search memory:

```
        Query
          |
          v
   +------+------+
   |      |      |
   v      v      v
Semantic BM25  Graph
          |
          v
    RRF Fusion
    (combine scores)
          |
          v
    Temporal Decay
    (recent > old)
          |
          v
       Results
```

**Search Strategies:**

* **Semantic**: Embedding cosine similarity on content
* **BM25**: Traditional keyword/lexical matching
* **Traversal**: Follow entity relationships in the graph
* **Hybrid**: Combines all three (recommended)

## Data Model

Ryumem stores knowledge as a graph:

```
+----------+          +----------+
| EPISODES |--MENTIONS-->| ENTITIES |
+----------+          +----------+
                           |
                       RELATES_TO
                           |
                           v
                      +----------+
                      | ENTITIES |
                      +----------+
```

**Episodes** - The fundamental unit. Every fact starts as an episode.

* `uuid`, `content`, `source`, `kind`
* `created_at`, `valid_at`, `content_embedding`

**Entities** - Extracted concepts: people, places, organizations.

* `uuid`, `name`, `entity_type`, `summary`

**Relationships** - Connections between entities with bi-temporal metadata.

* `name`, `fact`, `fact_embedding`
* `created_at`, `valid_at`, `invalid_at`, `expired_at`

## Bi-Temporal Tracking

Relationships track two dimensions of time:

* **System time**: When the fact was recorded (`created_at`)
* **Business time**: When the fact was/is true (`valid_at`, `invalid_at`)

This allows Ryumem to handle contradictions - when a new fact supersedes an old one, the old relationship is marked as `expired_at` but preserved for history.

## Next Steps

<CardGroup cols={2}>
  <Card title="Episodes" icon="layer-group" href="/core-concepts/episodes">
    Learn how to add and manage episodes
  </Card>

  <Card title="Search Strategies" icon="magnifying-glass" href="/core-concepts/search-strategies">
    Explore the different search methods
  </Card>
</CardGroup>