Ryumem - Semantic Memory for AI Agents

Ryumem is fully open source and can be self-hosted on your own infrastructure. Choose between Docker Compose (recommended), Helm Chart for Kubernetes, or local development setup.

Option 1: Docker Compose (Recommended)

The fastest way to get Ryumem running with all components.

Clone the Repository

git clone https://github.com/predictable-labs/ryumem.git
cd ryumem

Configure Environment

# Configure server
cp server/.env.example server/.env
# Edit server/.env and add your LLM API key (GOOGLE_API_KEY or OPENAI_API_KEY)

# Configure dashboard
cp dashboard/env.template dashboard/.env

You need at least one LLM API key (Google Gemini or OpenAI) for entity extraction and embeddings.

Start All Services

docker-compose up -d

This starts:

API Server: http://localhost:8000
Dashboard: http://localhost:3000
API Docs: http://localhost:8000/docs

Generate Your API Key

curl -X POST "http://localhost:8000/register" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "my_project"}'

The response includes your API key (starts with ryu_). Save this securely.

Option 2: Helm Chart (Kubernetes)

Deploy Ryumem to Kubernetes using the official Helm chart.

Add the Helm Repository

# Clone the repository to get the Helm chart
git clone https://github.com/predictable-labs/ryumem.git
cd ryumem

Configure Values

Create a custom values file:

# custom-values.yaml
secrets:
  googleApiKey: "your-google-api-key"  # or openaiApiKey
  adminApiKey: "your-admin-key"

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: ryumem.your-domain.com
      paths:
        - path: /
          pathType: Prefix

dashboard:
  enabled: true
  ingress:
    enabled: true
    className: nginx
    hosts:
      - host: ryumem-dashboard.your-domain.com
        paths:
          - path: /
            pathType: Prefix

persistence:
  enabled: true
  size: 20Gi

Install the Chart

helm install ryumem ./helm/ryumem \
  -f custom-values.yaml \
  --namespace ryumem \
  --create-namespace

Verify Installation

# Check pods are running
kubectl get pods -n ryumem

# Get the API endpoint
kubectl get ingress -n ryumem

Generate Your API Key

Port-forward and register:

kubectl port-forward -n ryumem svc/ryumem 8000:8000

curl -X POST "http://localhost:8000/register" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "my_project"}'

Helm Chart Configuration

Key configuration options in values.yaml:

Parameter	Default	Description
`replicaCount`	`1`	Number of API server replicas
`image.repository`	`ghcr.io/predictable-labs/ryumem`	Container image
`image.tag`	`latest`	Image tag
`secrets.googleApiKey`	`""`	Google Gemini API key
`secrets.openaiApiKey`	`""`	OpenAI API key
`secrets.adminApiKey`	`""`	Admin API key for registration
`ryumem.llm.provider`	`gemini`	LLM provider
`ryumem.llm.model`	`gemini-2.0-flash-exp`	LLM model
`ryumem.embedding.provider`	`gemini`	Embedding provider
`ryumem.embedding.model`	`text-embedding-004`	Embedding model
`persistence.enabled`	`true`	Enable persistent storage
`persistence.size`	`10Gi`	Storage size
`dashboard.enabled`	`true`	Deploy dashboard
`ingress.enabled`	`false`	Enable API ingress
`dashboard.ingress.enabled`	`false`	Enable dashboard ingress

For production deployments, use external secret management (like Kubernetes Secrets, Vault, or External Secrets Operator) instead of storing API keys in values files.

Option 3: Local Development

For development or when you want more control over individual components.

Prerequisites

Python 3.10+
Node.js 18+
An LLM API key (Google Gemini, OpenAI, or local Ollama)

Start the API Server

Install the SDK

pip install -e .

Install Server Dependencies

cd server
pip install -r requirements.txt

Configure Environment

cp .env.example .env
# Edit .env and set your LLM API key

Start the Server

uvicorn main:app --reload --host 0.0.0.0 --port 8000

Start the Dashboard

cd dashboard
npm install
cp env.template .env
npm run dev

The dashboard will be available at http://localhost:3000.

Environment Variables

Server Configuration (`server/.env`)

Variable	Required	Default	Description
`GOOGLE_API_KEY`	Yes*	-	Google Gemini API key
`OPENAI_API_KEY`	Yes*	-	OpenAI API key
`RYUMEM_DB_FOLDER`	Yes	`./data`	Database storage path
`ADMIN_API_KEY`	Yes	-	Admin key for registration
`LLM_PROVIDER`	No	`gemini`	LLM provider (gemini, openai, ollama, litellm)
`LLM_MODEL`	No	`gemini-2.0-flash-exp`	LLM model name
`EMBEDDING_PROVIDER`	No	`gemini`	Embedding provider
`EMBEDDING_MODEL`	No	`text-embedding-004`	Embedding model
`CORS_ORIGINS`	No	`http://localhost:3000`	Allowed CORS origins

*At least one LLM API key is required

Dashboard Configuration (`dashboard/.env`)

Variable	Required	Default	Description
`NEXT_PUBLIC_API_URL`	Yes	`http://localhost:8000`	Ryumem API server URL

Quick Start with Python SDK

Once your server is running, install the Python SDK:

pip install ryumem

Initialize and use Ryumem:

from ryumem import Ryumem

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

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

# Search your memories
results = ryumem.search(
    query="Where does Alice work?",
    user_id="user_123",
    session_id="session_abc",
)

print(results)

Accessing the Dashboard

Once Ryumem is running:

Navigate to http://localhost:3000
Enter your API key (starts with ryu_)
Click “Sign in”

Your API key is stored securely in your browser and used for all API requests. Dashboard Features:

Search and query your knowledge graph
Visualize entities and relationships
View episodes and memories
Track tool execution analytics
Configure system settings

Dashboard Guide

Complete guide to dashboard features and navigation

Using with Ollama (Local LLMs)

For fully local deployment without cloud API keys:

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama3.2

# Configure server/.env
LLM_PROVIDER=ollama
LLM_MODEL=llama3.2
EMBEDDING_PROVIDER=ollama
EMBEDDING_MODEL=nomic-embed-text

Local LLMs may have different performance characteristics compared to cloud providers. Test with your use case.

Next Steps

Quickstart Tutorial

Build your first memory-enabled agent

MCP Server

Add memory to Claude Desktop

Google ADK Integration

Add memory to Google ADK agents

Core Concepts

Understand how Ryumem works

Getting Started

Core Concepts

Integrations

Dashboard

Setup

Option 1: Docker Compose (Recommended)

Option 2: Helm Chart (Kubernetes)

Helm Chart Configuration

Option 3: Local Development

Prerequisites

Start the API Server

Start the Dashboard

Environment Variables

Server Configuration (`server/.env`)

Dashboard Configuration (`dashboard/.env`)

Quick Start with Python SDK

Accessing the Dashboard

Dashboard Guide

Using with Ollama (Local LLMs)

Next Steps

Quickstart Tutorial

MCP Server

Google ADK Integration

Core Concepts

​Option 1: Docker Compose (Recommended)

​Option 2: Helm Chart (Kubernetes)

​Helm Chart Configuration

​Option 3: Local Development

​Prerequisites

​Start the API Server

​Start the Dashboard

​Environment Variables

​Server Configuration (server/.env)

​Dashboard Configuration (dashboard/.env)

​Quick Start with Python SDK

​Accessing the Dashboard

Dashboard Guide

​Using with Ollama (Local LLMs)

​Next Steps

Quickstart Tutorial

MCP Server

Google ADK Integration

Core Concepts

Option 1: Docker Compose (Recommended)

Option 2: Helm Chart (Kubernetes)

Helm Chart Configuration

Option 3: Local Development

Prerequisites

Start the API Server

Start the Dashboard

Environment Variables

Server Configuration (`server/.env`)

Dashboard Configuration (`dashboard/.env`)

Quick Start with Python SDK

Accessing the Dashboard

Using with Ollama (Local LLMs)

Next Steps