Skip to main content
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

API Server

FastAPI backend providing REST endpoints for episode management, search, entity operations, and configuration.

Python SDK

Client library for Python applications. Includes Google ADK integration for automatic tool tracking.

MCP Server

TypeScript server implementing Model Context Protocol for Claude Desktop, Cursor, and other MCP-compatible agents.

Dashboard

Next.js web UI for graph visualization, entity browsing, and memory analytics.

​
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
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

Episodes

Learn how to add and manage episodes

Search Strategies

Explore the different search methods