Ryvos has a multi-level memory system built on SQLite with FTS5 full-text search. Memory persists across sessions, enabling the agent to recall facts, preferences, and context from previous conversations.

Memory Architecture

┌──────────────────────────────────────────────┐
│              Memory Layers                    │
│                                               │
│  ┌─────────────────────────────────────┐     │
│  │  SQLite Store (ryvos-memory)        │     │
│  │  • Session history (messages)        │     │
│  │  • Memory entries (FTS5 searchable)  │     │
│  │  • Cost tracking                     │     │
│  │  • Session metadata                  │     │
│  │  • Checkpoints                       │     │
│  └─────────────────────────────────────┘     │
│                                               │
│  ┌─────────────────────────────────────┐     │
│  │  Workspace Files                     │     │
│  │  • MEMORY.md (agent read/write)      │     │
│  │  • SOUL.md (identity, read-only)     │     │
│  │  • USER.md (user info)               │     │
│  │  • Daily logs                        │     │
│  └─────────────────────────────────────┘     │
│                                               │
│  ┌─────────────────────────────────────┐     │
│  │  Viking (optional, hierarchical)     │     │
│  │  • L0/L1/L2 tiered context           │     │
│  │  • viking:// protocol                │     │
│  │  • See Viking page                    │     │
│  └─────────────────────────────────────┘     │
└──────────────────────────────────────────────┘

SQLite Store

The primary persistence layer uses SQLite in WAL (Write-Ahead Logging) mode for crash-safe writes. The database is located at ~/.ryvos/ryvos.db.

Session History

Every message in every session is stored:

CREATE TABLE messages (
    id INTEGER PRIMARY KEY,
    session_id TEXT NOT NULL,
    role TEXT NOT NULL,           -- system, user, assistant, tool
    content TEXT NOT NULL,        -- JSON array of ContentBlocks
    timestamp TEXT NOT NULL,
    metadata TEXT                 -- JSON: phase, protected, output_keys
);

The agent can search across all sessions using the memory_search tool.

FTS5 Full-Text Search

A FTS5 virtual table indexes all memory entries for fast keyword search:

CREATE VIRTUAL TABLE memory_fts USING fts5(
    key,
    value,
    content='memory',
    content_rowid='id'
);

Search supports:

• Keyword matching with BM25 ranking
• Phrase queries ("exact phrase")
• Boolean operators (word1 AND word2)
• Prefix queries (auto*)

When an embedding provider is configured, search uses hybrid BM25 + vector similarity for better semantic results.

Memory Tools

The agent has 5 built-in tools for memory management:

memory_write

Store a key-value pair in persistent memory:

{
  "key": "deploy_process",
  "value": "1. Run tests 2. Build Docker image 3. Push to registry 4. Deploy to k8s"
}

The agent uses this autonomously when it learns something worth remembering. Memory entries are searchable across all future sessions.

memory_search

Search memory using keywords:

{
  "query": "deploy process",
  "limit": 5
}

Returns matching entries ranked by relevance (BM25 or hybrid BM25+vector):

[
  {
    "key": "deploy_process",
    "value": "1. Run tests 2. Build Docker image...",
    "score": 12.4
  }
]

memory_get

Retrieve a specific memory entry by exact key:

{
  "key": "deploy_process"
}

memory_delete

Remove a memory entry:

{
  "key": "outdated_deploy_process"
}

daily_log_write

Append to the daily log for the current date:

{
  "content": "Fixed authentication bug in auth.rs. Root cause was expired JWT validation."
}

Daily logs are stored as ~/.ryvos/logs/daily/YYYY-MM-DD.md and are loaded into the agent's narrative context layer. They help the agent maintain continuity across sessions within the same day.

MEMORY.md

The MEMORY.md file in your workspace is a special file the agent can both read and write:

# Memory
 
## Project Facts
- Database: PostgreSQL 15 on port 5432
- CI: GitHub Actions with 3 workflows
- Deploy: Docker + Kubernetes on AWS EKS
 
## User Preferences
- Prefers concise responses
- Uses vim keybindings
- Timezone: US/Pacific
 
## Learned Patterns
- The staging server requires VPN access
- Database migrations need approval from @dbadmin

The agent reads MEMORY.md at the start of each session (as part of the narrative context layer) and can update it via the write tool. This provides human-readable persistent memory that you can also edit manually.

Memory Flush

When the conversation approaches the context token limit (at 85% of max_context_tokens), Ryvos triggers an automatic memory flush:

1. The agent receives a system prompt: "Important context is about to be pruned. Extract and save any facts you want to remember."
2. The agent calls memory_write for important facts
3. Old messages are safely pruned via summarize_and_prune()
4. A summary message replaces the removed messages

This ensures that important information survives context compaction.

Embeddings (Semantic Search)

By default, memory search uses BM25 (keyword matching). Configure an embedding provider for hybrid semantic search:

[embedding]
provider = "openai"
model = "text-embedding-3-small"
api_key = "$\{OPENAI_API_KEY\}"

OpenAI

[embedding]
provider = "openai"
model = "text-embedding-3-small"
api_key = "$\{OPENAI_API_KEY\}"

Ollama

[embedding]
provider = "ollama"
model = "nomic-embed-text"

Custom

[embedding]
provider = "custom"
model = "your-model"
api_key = "$\{API_KEY\}"
base_url = "http://localhost:8080/v1"

With embeddings enabled, memory_search combines BM25 keyword scores with cosine similarity from vector embeddings, producing better results for semantic queries like "how do we handle auth" (which would match "JWT validation process" even without shared keywords).

Cost Tracking

The CostStore records token usage and dollar costs:

CREATE TABLE costs (
    id INTEGER PRIMARY KEY,
    session_id TEXT NOT NULL,
    run_id TEXT,
    model TEXT NOT NULL,
    input_tokens INTEGER,
    output_tokens INTEGER,
    cost_cents REAL,
    timestamp TEXT NOT NULL
);

Cost data powers:

• Per-run budget limits (budget.per_run_limit_cents)
• Monthly budget enforcement (budget.monthly_limit_cents)
• The Web UI cost dashboard
• BudgetWarning and BudgetExceeded events

Session Metadata

The SessionMetaStore tracks metadata for each session:

• Session title (auto-generated from first message)
• Creation timestamp
• Last activity timestamp
• CLI session ID (for --resume matching)
• Message count

Database Location

:::tip SQLite WAL mode allows concurrent reads during writes. The database is crash-safe — if Ryvos is killed mid-write, the WAL file ensures no data corruption on restart. :::

Workspace Files

These files in your workspace directory (or ~/.ryvos/) customize the agent:

Next Steps

• Viking Memory — Hierarchical L0/L1/L2 memory with the viking:// protocol
• Context Management — How memory feeds into the context stack
• Configuration — Memory and embedding config options