Architecture

Understanding how Raven Protocol works under the hood.

Overview

Raven is a multi-tenant persistent memory layer for LLM/AI agents backed by Walrus (blob storage) and Sui (control plane). The architecture is designed for security, scalability, and complete data isolation between tenants.

Core Principles

Multi-tenancy:Developers (tenants) integrate the API; their end-users get isolated memory storage.
Encryption-first:All blobs encrypted with AES-256-GCM before storage with tenant-scoped keys.
Decentralized storage:Walrus stores large blobs; Sui stores metadata/policies.
API key authentication:Server-issued keys with scope-based access control.

Data Hierarchy

Raven organizes data in a strict hierarchy that ensures complete isolation:

Tenant (Developer)
├── API Keys (authentication)
├── Settings (retention, rate limits, customization)
└── Users (end-users of the developer's application)
    └── Conversations (chat sessions with isolated memory)
        └── Memory Blobs (encrypted on Walrus)

Storage Architecture

Raven uses a tiered storage approach for optimal performance and cost:

Redis (Tier 2)

Fast key-value storage
API key validation
Session buffers
Metadata caching

Walrus (Tier 3/4)

Encrypted blob storage
Episodic memory
Semantic summaries
Embedding vectors

Sui Blockchain

Blob registry
Ownership proofs
Retention policies
Verification hashes

Context Window

Ephemeral only
Model context
No persistence
Real-time processing

Memory Tiers

Memory is organized into conceptual tiers based on access patterns and retention:

Tier	Type	Storage	Description
Tier 1	Context Window	Ephemeral	Model's active context (not persisted)
Tier 2	Core Memory	Redis	User profile, session state, quick access
Tier 3	Episodic Memory	Walrus	Conversation history chunks
Tier 4	Semantic Memory	Walrus	Extracted patterns and embeddings

Data Flow

Here's how data flows through the system during ingestion and retrieval:

Ingestion Flow

Agent Request (with API Key)
      ↓
Auth Middleware → Validate tenant
      ↓
Memory Ingestion Service
      ↓
Serialize MemoryBlob → JSON
      ↓
Hash (SHA-256) ← for integrity verification
      ↓
Encrypt (AES-256-GCM) ← tenant-scoped key
      ↓
Store to Walrus (encrypted bytes)
      ↓
Register metadata on Sui (blob_id, content_hash)

Retrieval Flow

Query from Agent (with API Key)
      ↓
Auth Middleware → Validate tenant
      ↓
Memory Retrieval Service
      ↓
Fetch blob_id from Tier2 (tenant-scoped)
      ↓
Retrieve encrypted bytes from Walrus
      ↓
Decrypt (AES-256-GCM) ← tenant-scoped key
      ↓
Parse MemoryBlob ← JSON
      ↓
Return conversation context

Service Components

API Server

apps/api

Express HTTP API with multi-tenant auth, rate limiting, and tenant management endpoints.

Ingest Worker

apps/worker-ingest

Background worker that processes buffered interactions and stores them to Walrus.

Analyze Worker

apps/worker-analyze

Periodic analysis worker for pattern extraction and semantic summarization.

Memory Core

packages/memory-core

Core service interfaces for ingestion, retrieval, and analysis.

Encryption Service

packages/encryption

AES-256-GCM encryption with tenant key management.

Learn More

→Multi-Tenancy Deep Dive →Encryption Architecture →Data Model Reference →API Authentication