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

# Setup

> Deploy Ryumem on your own infrastructure.

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.

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/predictable-labs/ryumem.git
    cd ryumem
    ```
  </Step>

  <Step title="Configure Environment">
    ```bash theme={null}
    # 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
    ```

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

  <Step title="Start All Services">
    ```bash theme={null}
    docker-compose up -d
    ```

    This starts:

    * **API Server**: [http://localhost:8000](http://localhost:8000)
    * **Dashboard**: [http://localhost:3000](http://localhost:3000)
    * **API Docs**: [http://localhost:8000/docs](http://localhost:8000/docs)
  </Step>

  <Step title="Generate Your API Key">
    Register a customer to get your API key:

    ```bash theme={null}
    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.
  </Step>
</Steps>

## Option 2: Helm Chart (Kubernetes)

Deploy Ryumem to Kubernetes using the official Helm chart.

<Steps>
  <Step title="Add the Helm Repository">
    ```bash theme={null}
    # Clone the repository to get the Helm chart
    git clone https://github.com/predictable-labs/ryumem.git
    cd ryumem
    ```
  </Step>

  <Step title="Configure Values">
    Create a custom values file:

    ```yaml theme={null}
    # 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
    ```
  </Step>

  <Step title="Install the Chart">
    ```bash theme={null}
    helm install ryumem ./helm/ryumem \
      -f custom-values.yaml \
      --namespace ryumem \
      --create-namespace
    ```
  </Step>

  <Step title="Verify Installation">
    ```bash theme={null}
    # Check pods are running
    kubectl get pods -n ryumem

    # Get the API endpoint
    kubectl get ingress -n ryumem
    ```
  </Step>

  <Step title="Generate Your API Key">
    Port-forward and register:

    ```bash theme={null}
    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"}'
    ```
  </Step>
</Steps>

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

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

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

<Steps>
  <Step title="Install the SDK">
    ```bash theme={null}
    pip install -e .
    ```
  </Step>

  <Step title="Install Server Dependencies">
    ```bash theme={null}
    cd server
    pip install -r requirements.txt
    ```
  </Step>

  <Step title="Configure Environment">
    ```bash theme={null}
    cp .env.example .env
    # Edit .env and set your LLM API key
    ```
  </Step>

  <Step title="Start the Server">
    ```bash theme={null}
    uvicorn main:app --reload --host 0.0.0.0 --port 8000
    ```
  </Step>
</Steps>

### Start the Dashboard

```bash theme={null}
cd dashboard
npm install
cp env.template .env
npm run dev
```

The dashboard will be available at [http://localhost:3000](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:

```bash theme={null}
pip install ryumem
```

Initialize and use Ryumem:

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

1. Navigate to [http://localhost:3000](http://localhost:3000)
2. Enter your API key (starts with `ryu_`)
3. 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

<Card title="Dashboard Guide" icon="chart-line" href="/dashboard/overview">
  Complete guide to dashboard features and navigation
</Card>

## Using with Ollama (Local LLMs)

For fully local deployment without cloud API keys:

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

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart Tutorial" icon="rocket" href="/quickstart">
    Build your first memory-enabled agent
  </Card>

  <Card title="MCP Server" icon="plug" href="/integrations/mcp-server">
    Add memory to Claude Desktop
  </Card>

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

  <Card title="Core Concepts" icon="brain" href="/core-concepts/episodes">
    Understand how Ryumem works
  </Card>
</CardGroup>