> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorose.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Architectural Overview

> Workspace shape, runtime pipeline, key concepts, and deployment model.

# Architecture Overview

Memorose is a memory runtime for agents. The system ingests raw events, consolidates them into durable memory, derives higher-order insights, tracks goal execution, and exposes all of that through a Rust server, a dashboard, and optional gateway plus Raft-backed deployment primitives.

## System Architecture

```mermaid theme={null}
graph TB
  subgraph Clients
    SDK["SDK / API Client"]
    Dashboard["Dashboard UI :3100"]
  end

  subgraph OptionalGateway["Optional Gateway"]
    GW["Gateway :8080<br/>Stateless Router"]
  end

  SDK --> API
  Dashboard --> API
  SDK -.->|"optional"| GW
  GW -.->|"optional shard routing"| API

  subgraph Node["Server Node :3000"]
    direction TB
    API["Axum API Layer"]

    subgraph Engine["MemoroseEngine"]
      direction LR
      Ingest["Ingest"]
      Retrieve["Hybrid Retrieval"]
      Forget["Forgetting"]
    end

    subgraph Worker["Background Worker"]
      direction LR
      Consolidation["L0→L1<br/>Consolidation"]
      Reflection["L1→L2<br/>Reflection"]
      Goals["L2→L3<br/>Goal Tracking"]
    end

    subgraph Storage
      direction LR
      RocksDB["RocksDB<br/>KV Store"]
      Lance["LanceDB<br/>Vector Index"]
      Tantivy["Tantivy<br/>Text Index"]
      Graph["Knowledge<br/>Graph"]
    end

    API --> Engine
    Engine --> Storage
    Worker --> Storage
    Worker -.->|"LLM"| LLM["Gemini / OpenAI"]
  end

  subgraph Cluster["Raft Cluster"]
    direction LR
    N1["Node 1"]
    N2["Node 2"]
    N3["Node 3"]
    N1 <-->|"Raft"| N2
    N2 <-->|"Raft"| N3
    N1 <-->|"Raft"| N3
  end

  style Clients fill:#f9fafb,stroke:#d1d5db,color:#111827
  style OptionalGateway fill:#f3f4f6,stroke:#9ca3af,color:#111827
  style Node fill:#f9fafb,stroke:#6b7280,color:#111827
  style Engine fill:#e5e7eb,stroke:#6b7280,color:#111827
  style Worker fill:#e5e7eb,stroke:#6b7280,color:#111827
  style Storage fill:#e5e7eb,stroke:#6b7280,color:#111827
  style Cluster fill:#f3f4f6,stroke:#9ca3af,color:#111827
```

## Data Flow

```mermaid theme={null}
graph LR
  E["Events"] -->|"ingest"| L0["L0<br/>Raw Events"]
  L0 -->|"consolidate"| L1["L1<br/>Stable Memory"]
  L1 -->|"reflect"| L2["L2<br/>Insights &<br/>Communities"]
  L2 -->|"plan"| L3["L3<br/>Goals & Tasks"]

  L0 -.->|"decay"| Forget["Forget /<br/>Prune"]
  L1 -.->|"decay"| Forget
  Forget -.->|"remove"| Gone["∅"]

  Q["Query"] -->|"retrieve"| Hybrid["Hybrid Search"]
  L1 --> Hybrid
  L2 --> Hybrid
  L3 --> Hybrid
  Hybrid --> R["Results"]

  style L0 fill:#f3f4f6,stroke:#9ca3af,color:#111827
  style L1 fill:#e5e7eb,stroke:#6b7280,color:#111827
  style L2 fill:#d1d5db,stroke:#6b7280,color:#111827
  style L3 fill:#9ca3af,stroke:#4b5563,color:#111827
  style Hybrid fill:#f3f4f6,stroke:#6b7280,color:#111827
  style Forget fill:#f9fafb,stroke:#d1d5db,color:#6b7280
  style Gone fill:#ffffff,stroke:#d1d5db,color:#9ca3af
```

## Workspace Shape

```text theme={null}
crates/
├── memorose-common    # shared config, core types, task and graph models
├── memorose-core      # engine, storage, retrieval, graph, organization knowledge
├── memorose-server    # Axum API, dashboard auth, management routes
└── memorose-gateway   # optional stateless shard router
```

## Runtime Pipeline

1. Events arrive on `/v1/users/:user_id/streams/:stream_id/events`
2. L0 raw events are stored and queued for consolidation
3. Consolidation produces L1 memory units
4. Reflection and graph/community analysis produce L2 insights
5. L3 goal and task memory coordinates future work and execution state
6. Retrieval merges vector, text, graph, and shared-knowledge signals
7. Forgetting prunes or compacts low-value memory over time

## Key Product Concepts

### L0-L3

Memorose uses an explicit memory hierarchy:

* `L0`: raw event stream
* `L1`: stable facts and procedural traces
* `L2`: themes, clusters, reflective summaries, and shared insights
* `L3`: goal structures, task trees, milestones, dependencies, and execution status

### Domains

The ownership and sharing model is:

* `agent`: how a specific agent learns to operate
* `user`: who the user is and what they prefer
* `organization`: reusable shared knowledge projected from authorized source memory

### Streams

Every ingest and retrieval request is scoped to a `stream_id`. Streams preserve session-local chronology while still feeding long-lived memory.

## Storage Model

Memorose combines several storage engines instead of pushing everything into one system:

* RocksDB for local durable state and key-value access
* Lance for embeddings and vector retrieval
* Tantivy for text retrieval
* Graph and organization-knowledge views built on top of those primitives

## Retrieval Model

Retrieval is hybrid by design. Queries can combine:

* semantic similarity
* text search
* graph depth expansion
* time filters
* organization knowledge
* optional multimodal embedding input

## Deployment Model

* Single-node mode for local development
* Raft-based clustering for replicated deployment
* Sharded topologies for larger installations
* Optional gateway routing layer for some deployments
* Separate dashboard UI on port `3100`

This is infrastructure software first. The docs should be read with that model in mind.