跳转到主要内容

​
代码库指南

​
工作区布局

Memorose 是一个 Cargo 工作区（workspace），包含四个 crate 和一个 Next.js 仪表盘： 
Memorose/
  crates/
    memorose-common/    # 共享类型、配置、序列化
    memorose-core/      # 核心引擎 — 存储、LLM、worker、图谱
    memorose-server/    # Axum HTTP 服务器、Raft 共识、仪表盘认证
    memorose-gateway/   # 无状态网关、租户分片
  dashboard/            # Next.js 前端（TypeScript / React）
  scripts/              # 开发辅助脚本（start_cluster.sh、build_dashboard.sh）
  examples/             # SDK 示例和集成

​
Crate 依赖图

memorose-server ──┐
                  ├──→ memorose-core ──→ memorose-common
memorose-gateway ─┘
  • memorose-common 没有内部依赖——纯类型和配置。
  • memorose-core 依赖 memorose-common，包含所有业务逻辑。
  • memorose-server 和 memorose-gateway 都依赖 memorose-core 和 memorose-common。

​
Crate 职责

​
memorose-common

所有其他 crate 使用的共享基础：
  • Event、EventContent、Memory 领域类型
  • 配置加载——TOML 文件 + 环境变量覆盖
  • 序列化辅助工具（serde、chrono、uuid）
  • 错误类型（thiserror）

​
memorose-core

代码库的主体部分。关键模块：
模块路径职责
engine/src/engine/MemoroseEngine — 主编排器，包含约 17 个子模块用于记忆操作
storage/src/storage/多后端抽象（见下文）
worker.rssrc/worker.rs后台整合管线：L0 → L1 → L2、衰减、修剪、社区检测
llm/src/llm/LLM 提供商抽象 — Gemini、OpenAI 和 Mock 实现
graph/src/graph/知识图谱操作、社区检测（Louvain / LPA）
ingest/src/ingest/事件摄入管线（event ingestion pipeline）
raft/src/raft/通过 openraft 实现的分布式共识
fact_extraction.rssrc/fact_extraction.rs基于 LLM 的事实提取
arbitrator.rssrc/arbitrator.rs重叠记忆的冲突解决
reranker.rssrc/reranker.rs搜索结果重排序（reranking）

​
存储后端（Storage Backends）

均位于 memorose-core/src/storage/ 下：
文件后端用途
kv.rsRocksDBL0 原始事件的键值存储
index.rsLanceDB + TantivyL1 记忆的向量索引（LanceDB）+ 全文索引（Tantivy）
graph.rs自定义L2 洞察的知识图谱存储
blob.rs文件系统多模态内容的 Blob 存储
system_kv.rsRocksDB系统元数据和内部状态
tests.rs—全面的存储测试套件

​
memorose-server

HTTP 层：
  • main.rs — Axum 路由、Raft 节点引导、API 处理器
  • shard_manager.rs — 分片到节点的路由逻辑
  • types.rs — API 请求/响应类型
  • dashboard/ — 仪表盘认证和处理器端点

​
memorose-gateway

位于服务器节点前方的无状态 HTTP 代理：
  • 根据 user_id 将请求路由到正确的分片（shard）
  • 通过 URL 路径实现租户隔离（tenant isolation）
  • 自身不持有持久状态

​
仪表盘前端

dashboard/ 目录是一个标准的 Next.js 应用： 
dashboard/src/
  app/           # Next.js App Router 页面
  components/    # React 组件
  lib/
    api.ts       # API 客户端 — 所有调用通过 fetchAPI() 并携带 Bearer 认证
    hooks.ts     # 用于数据获取的 SWR hooks
    types.ts     # TypeScript 类型定义
应遵循的模式：
  • 所有 API 调用通过 lib/api.ts 中的 fetchAPI()
  • 数据获取使用 lib/hooks.ts 中定义的 SWR hooks
  • 类型定义在 lib/types.ts 中，与 Rust 服务端类型对应

​
关键模式

​
SQL 过滤器构建器

build_user_filter(user_id, app_id, extra) 为 LanceDB 查询构建 SQL WHERE 子句。在向量搜索操作中广泛使用。

​
KV 扫描

键值迭代使用 kv.scan(b"u:")，并通过键窗口过滤 :unit: 或 :event: 段。

​
仪表盘缓存

仪表盘 API 响应通过 state.dashboard_cache 缓存，TTL 为 5 分钟（基于 moka）。

​
双时态搜索（Bitemporal Search）

search_bitemporal() 支持有效时间（valid-time）和事务时间（transaction-time）查询，可选的 agent_id 过滤作为第 7 个参数。