代码库指南

工作区布局

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

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

Crate 依赖图

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/ 应用主要包括：

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

​代码库指南

​工作区布局

​Crate 依赖图

​Crate 职责

​memorose-common

​memorose-core

​存储后端

​memorose-server

​memorose-gateway

​Dashboard 前端

​有用的模式

​Dashboard cache

​双时态和作用域检索

​真正的权威来源