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

# Codebase Guide

> A walkthrough of the current Memorose workspace layout, crate responsibilities, and key modules.

# Codebase Guide

## Workspace layout

Memorose is a Cargo workspace with four crates plus a Next.js dashboard:

```text theme={null}
Memorose/
  crates/
    memorose-common/    # Shared types and config loading
    memorose-core/      # Core engine, retrieval, storage, graph, worker logic
    memorose-server/    # Axum HTTP server and dashboard-backed API surface
    memorose-gateway/   # Stateless gateway for shard routing
  dashboard/            # Next.js frontend
  scripts/              # Local dev helpers
  examples/             # Example clients and integrations
```

## Crate dependency graph

```text theme={null}
memorose-server ──┐
                  ├──→ memorose-core ──→ memorose-common
memorose-gateway ─┘
```

## Crate responsibilities

### memorose-common

Shared foundations used by the rest of the workspace:

* core types such as `Event`, `EventContent`, `MemoryUnit`, `GraphEdge`, and `L3Task`
* runtime config loading in `src/config.rs`
* serialization helpers and shared enums

### memorose-core

Business logic and storage orchestration:

| Module          | Path                | Role                                                               |
| --------------- | ------------------- | ------------------------------------------------------------------ |
| `engine/`       | `src/engine/`       | `MemoroseEngine` orchestration and domain workflows                |
| `storage/`      | `src/storage/`      | RocksDB, vector, text, blob, and system metadata backends          |
| `worker.rs`     | `src/worker.rs`     | background consolidation, forgetting, insights, and related cycles |
| `llm/`          | `src/llm/`          | Gemini and OpenAI provider clients                                 |
| `graph/`        | `src/graph/`        | graph storage, traversal, cache, and query helpers                 |
| `ingest/`       | `src/ingest/`       | multimodal ingest helpers                                          |
| `raft/`         | `src/raft/`         | openraft integration                                               |
| `arbitrator.rs` | `src/arbitrator.rs` | memory conflict and correction planning                            |
| `reranker.rs`   | `src/reranker.rs`   | weighted or external reranking                                     |

### Storage backends

All under `memorose-core/src/storage/`:

| File           | Backend           | Purpose                                               |
| -------------- | ----------------- | ----------------------------------------------------- |
| `kv.rs`        | RocksDB           | durable key-value storage for events and memory units |
| `index.rs`     | LanceDB + Tantivy | vector and text indexing                              |
| `graph.rs`     | custom            | graph edge persistence                                |
| `blob.rs`      | file system       | asset storage                                         |
| `system_kv.rs` | RocksDB           | internal metadata, jobs, and control state            |

### memorose-server

The HTTP layer:

* `main.rs`: route definitions and server bootstrap
* `types.rs`: request / response payload types
* `shard_manager.rs`: shard routing and cluster coordination helpers
* `dashboard/`: auth and handler modules backing dashboard and management endpoints

### memorose-gateway

The stateless routing layer used in some deployments:

* maps requests to backend nodes by shard
* reads gateway-specific env vars such as `SHARD_COUNT`
* does not own persistent state

## Dashboard frontend

The `dashboard/` app currently contains:

```text theme={null}
dashboard/src/
  app/           # Next.js app router pages
  components/    # UI components
  lib/
    api.ts       # API helpers
    auth.ts      # auth helpers
    hooks.ts     # SWR hooks
    types.ts     # TypeScript API types
```

## Useful patterns

### Dashboard cache

Dashboard API responses are cached with `state.dashboard_cache`.

### Bitemporal and scoped retrieval

Retrieval supports valid-time, transaction-time, `org_id`, and `agent_id` inputs through the server request payloads.

### Route truth

When in doubt, treat these as the primary references:

* `crates/memorose-server/src/main.rs`
* `crates/memorose-server/src/types.rs`
* `crates/memorose-common/src/config.rs`