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

# 代码库指南

> 介绍当前 Memorose 工作区布局、crate 职责和关键模块。

# 代码库指南

## 工作区布局

Memorose 是一个 Cargo workspace，包含四个 crate 和一个 Next.js dashboard：

```text theme={null}
Memorose/
  crates/
    memorose-common/    # 共享类型和配置加载
    memorose-core/      # 核心引擎、检索、存储、图谱、worker 逻辑
    memorose-server/    # Axum HTTP 服务和 dashboard 相关 API
    memorose-gateway/   # 无状态分片路由网关
  dashboard/            # Next.js 前端
  scripts/              # 本地开发辅助脚本
  examples/             # 示例客户端和集成
```

## Crate 依赖图

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

## Crate 职责

### memorose-common

给整个工作区共享的基础定义：

* `Event`、`EventContent`、`MemoryUnit`、`GraphEdge`、`L3Task` 等核心类型
* `src/config.rs` 中的运行时配置加载
* 序列化辅助和共享枚举

### memorose-core

业务逻辑和存储编排层：

| 模块              | 路径                  | 作用                              |
| --------------- | ------------------- | ------------------------------- |
| `engine/`       | `src/engine/`       | `MemoroseEngine` 编排和领域工作流       |
| `storage/`      | `src/storage/`      | RocksDB、向量、文本、blob、系统元数据存储      |
| `worker.rs`     | `src/worker.rs`     | 后台整合、遗忘、insight 等周期任务           |
| `llm/`          | `src/llm/`          | Gemini 和 OpenAI provider client |
| `graph/`        | `src/graph/`        | 图谱存储、遍历、缓存和查询辅助                 |
| `ingest/`       | `src/ingest/`       | 多模态 ingest 辅助                   |
| `raft/`         | `src/raft/`         | openraft 集成                     |
| `arbitrator.rs` | `src/arbitrator.rs` | 记忆冲突与纠错计划                       |
| `reranker.rs`   | `src/reranker.rs`   | 内置或外部 reranking                 |

### 存储后端

位于 `memorose-core/src/storage/`：

| 文件             | 后端                | 用途              |
| -------------- | ----------------- | --------------- |
| `kv.rs`        | RocksDB           | 事件和记忆单元的持久化键值存储 |
| `index.rs`     | LanceDB + Tantivy | 向量索引和文本索引       |
| `graph.rs`     | 自定义               | 图边持久化           |
| `blob.rs`      | 文件系统              | 资产存储            |
| `system_kv.rs` | RocksDB           | 内部元数据、任务和控制状态   |

### memorose-server

HTTP 层：

* `main.rs`：路由定义和服务启动
* `types.rs`：请求/响应 payload 类型
* `shard_manager.rs`：分片路由和集群协调辅助
* `dashboard/`：dashboard 所需的认证和 handler 模块

### memorose-gateway

某些部署场景下的无状态路由层：

* 根据 shard 把请求转发到后端节点
* 读取 `SHARD_COUNT` 等 gateway 专用环境变量
* 自身不持有持久状态

## Dashboard 前端

当前 `dashboard/` 应用主要包括：

```text theme={null}
dashboard/src/
  app/           # Next.js app router 页面
  components/    # UI 组件
  lib/
    api.ts       # API helpers
    auth.ts      # 认证辅助
    hooks.ts     # SWR hooks
    types.ts     # TypeScript API 类型
```

## 有用的模式

### Dashboard cache

Dashboard API 响应通过 `state.dashboard_cache` 做缓存。

### 双时态和作用域检索

检索请求支持 valid-time、transaction-time、`org_id` 和 `agent_id` 等输入。

### 真正的权威来源

如果文档和代码有冲突，优先看：

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