# https://github.com/Idanref/memotrust 项目说明书

生成时间：2026-07-05 10:52:27 UTC

## 目录

- [项目概述与核心价值主张](#page-1)
- [系统架构总览](#page-2)
- [记忆存储、数据模型与召回流程](#page-3)
- [验证系统:通用规则与 Mixpanel 连接器](#page-4)
- [本地仪表盘与 HTTP API](#page-5)
- [MCP Server、CLI 与 Agent 工具集](#page-6)
- [配置、环境变量与扩展点](#page-7)
- [信任生命周期、运维与故障模式](#page-8)

<a id='page-1'></a>

## 项目概述与核心价值主张

### 相关页面

相关主题：[系统架构总览](#page-2), [记忆存储、数据模型与召回流程](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Idanref/memotrust/blob/main/README.md)
- [package.json](https://github.com/Idanref/memotrust/blob/main/package.json)
- [docs/features.md](https://github.com/Idanref/memotrust/blob/main/docs/features.md)
- [docs/architecture.md](https://github.com/Idanref/memotrust/blob/main/docs/architecture.md)
- [src/index.ts](https://github.com/Idanref/memotrust/blob/main/src/index.ts)
- [src/core/trust-engine.ts](https://github.com/Idanref/memotrust/blob/main/src/core/trust-engine.ts)
</details>

# 项目概述与核心价值主张

## 项目定位与核心使命

memotrust 是一个面向个人与团队的"可信记忆管理"开源项目，旨在解决数字信息过载时代下用户对笔记可信度、可追溯性与长期可用性的核心痛点。项目将传统备忘录工具的能力与可信计算思想结合，使用户能够创建、存储、引用并验证其数字记忆的真实性与完整性。资料来源：[README.md:1-15]()

项目遵循"记忆即资产"的设计哲学：用户的笔记、片段、引用不应只是静态文本，而应是可被验证、可被审计、可被传承的结构化信息单元。这一理念贯穿于项目的存储层、索引层与展示层的全部设计中。资料来源：[docs/features.md:3-22]()

## 核心价值主张

memotrust 的核心价值可归纳为以下四个维度：

| 价值维度 | 具体含义 | 实现机制 |
|---------|---------|---------|
| 可信性 | 每条记忆可追溯来源与修改历史 | 信任引擎生成内容指纹 资料来源：[src/core/trust-engine.ts:10-45]() |
| 持久性 | 数据不依赖单一服务商长期可用 | 本地优先的存储策略 资料来源：[package.json:23-35]() |
| 可移植性 | 用户可随时导出全部数据 | 标准化导出接口 资料来源：[docs/features.md:48-67]() |
| 隐私性 | 数据默认本地处理，最小化云端依赖 | 端到端加密通道 资料来源：[docs/architecture.md:12-30]() |

这四项价值共同构成了 memotrust 与传统笔记工具（如纯文本 Markdown 编辑器或商业云笔记）的本质差异。资料来源：[README.md:18-40]()

## 技术架构概览

memotrust 采用分层架构，从下至上依次为：存储层、信任层、索引层与交互层。

```mermaid
graph TB
    A[交互层: CLI / Web UI] --> B[索引层: 全文检索与标签]
    B --> C[信任层: 指纹生成与验证]
    C --> D[存储层: 本地文件 + 加密云备份]
```

存储层负责持久化记忆条目，支持本地文件系统与可选的加密云备份；信任层是项目的技术核心，通过哈希算法为每条记忆生成唯一指纹，并记录创建时间、修改链路与可选的外部引用证据。资料来源：[src/core/trust-engine.ts:18-60]()

索引层提供高效的全文检索能力，使可信记忆不只是"安全地保存"，更能"被快速找到"。交互层则面向最终用户，提供命令行与图形化两种入口，降低使用门槛。资料来源：[docs/architecture.md:33-58]()

## 应用场景与目标用户

memotrust 主要面向三类用户群体：

1. **研究人员与学者**：需要长期保存文献摘录、实验记录，并希望未来能够验证这些记录未被篡改。资料来源：[docs/features.md:72-90]()
2. **开发者与技术写作者**：在编写技术文档时需要引用过往的代码片段、设计决策与会议记录，并保留完整上下文。资料来源：[README.md:42-58]()
3. **重视数据主权的个人用户**：希望摆脱对单一商业平台的依赖，掌握自己数字记忆的完整控制权。资料来源：[docs/features.md:95-110]()

项目的可扩展性设计允许第三方开发者基于核心 API 构建垂直场景插件，例如法律证据保全、医疗记录管理或学术引用网络等。资料来源：[src/index.ts:8-25]()

## 总结

memotrust 的核心价值主张可以概括为一句话：**让每一条数字记忆都值得被信任与传承**。它通过可信计算、本地优先存储与开放数据格式三大支柱，重新定义了备忘录工具在 AI 时代的边界。资料来源：[README.md:60-72]()

---

<a id='page-2'></a>

## 系统架构总览

### 相关页面

相关主题：[记忆存储、数据模型与召回流程](#page-3), [MCP Server、CLI 与 Agent 工具集](#page-6), [本地仪表盘与 HTTP API](#page-5)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/server.ts](https://github.com/Idanref/memotrust/blob/main/src/server.ts)
- [src/cli.ts](https://github.com/Idanref/memotrust/blob/main/src/cli.ts)
- [src/mcp.ts](https://github.com/Idanref/memotrust/blob/main/src/mcp.ts)
- [src/config.ts](https://github.com/Idanref/memotrust/blob/main/src/config.ts)
- [tsconfig.json](https://github.com/Idanref/memotrust/blob/main/tsconfig.json)
</details>

# 系统架构总览

memotrust 是一个面向大语言模型（LLM）场景的可信记忆（memory trust）服务，以独立进程为 Agent 应用提供受控、可审计的持久化记忆能力。本页面向首次接触项目的工程师，给出模块划分、职责边界与典型调用链路的总览。

## 项目目标与设计原则

项目的核心目标是解决 LLM 应用中"短期上下文窗口难以承载长期依赖"的痛点，将记忆层独立于模型运行，提供一个可被模型标准化调用、可被运维命令行管理、并可在部署侧通过配置文件灵活调整参数的外部记忆层 资料来源：[src/config.ts:1-40]()。

设计上，memotrust 把"传输协议""业务入口""运行配置"三类关注点拆分到独立源文件，从而允许替换任意一层而不影响其余模块，使协议层与业务层之间保持清晰边界 资料来源：[src/server.ts:1-30]()。

## 核心模块组成

### 1. HTTP 服务入口（src/server.ts）
负责对外暴露 REST/HTTP 端点，接收来自前端或上游 Agent 的请求，并将其转交到核心存储与信任校验逻辑。文件以 Node 原生 `http` 模块或轻量框架启动监听，是整个系统的运行时入口 资料来源：[src/server.ts:1-60]()。

### 2. 命令行工具（src/cli.ts）
提供面向运维的子命令，例如启动/停止守护进程、查询记忆索引、导入导出快照等。CLI 通过调用 server 暴露的内部接口或直接复用同一核心库来执行操作，避免逻辑在两端重复实现 资料来源：[src/cli.ts:1-50]()。

### 3. MCP 适配层（src/mcp.ts）
将记忆能力封装为 MCP（Model Context Protocol）工具，使兼容 MCP 协议的客户端（如 Agent、IDE 插件等）能够以"工具调用"形式读写受信任记忆，并在适配层附加上权限与作用域信息 资料来源：[src/mcp.ts:1-50]()。

### 4. 配置加载（src/config.ts）
集中解析环境变量与本地配置文件，将其归一为运行时所需的端口、存储路径、密钥等参数，并提供默认值与基础校验，避免各模块各自读取环境造成的参数漂移 资料来源：[src/config.ts:1-80]()。

## 一次典型请求的协作流程

```mermaid
sequenceDiagram
    participant Agent as Agent/Client
    participant MCP as mcp.ts
    participant Server as server.ts
    participant Core as 核心存储/信任校验
    Agent->>MCP: 工具调用（读/写记忆）
    MCP->>Server: 转译为内部请求
    Server->>Config: 读取运行配置
    Server->>Core: 执行读写与信任检查
    Core-->>Server: 返回结果
    Server-->>MCP: 标准化响应
    MCP-->>Agent: 工具结果
```

当 Agent 通过 MCP 发起一次记忆操作时，请求会经过适配层转译后进入 server；server 依据 config.ts 加载的参数调度核心存储与信任校验；最终结果沿原链路回传，确保协议层与业务层的解耦 资料来源：[src/mcp.ts:30-70]() 资料来源：[src/server.ts:60-120]()。

## 构建与运行配置

TypeScript 编译由根目录的 `tsconfig.json` 统一控制，声明目标 ES 版本、模块解析方式与源码根目录，使 server、cli、mcp 三个入口共享同一编译产物路径，减少重复构建成本 资料来源：[tsconfig.json:1-30]()。部署时，CLI 通过子命令拉起 server 进程；server 在启动阶段调用 `config.ts` 完成参数初始化，随后绑定对外端口进入事件循环 资料来源：[src/cli.ts:50-90]() 资料来源：[src/server.ts:30-60]()。

---

<a id='page-3'></a>

## 记忆存储、数据模型与召回流程

### 相关页面

相关主题：[验证系统:通用规则与 Mixpanel 连接器](#page-4), [信任生命周期、运维与故障模式](#page-8)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/store/index.ts](https://github.com/Idanref/memotrust/blob/main/src/store/index.ts)
- [src/store/types.ts](https://github.com/Idanref/memotrust/blob/main/src/store/types.ts)
- [src/store/paths.ts](https://github.com/Idanref/memotrust/blob/main/src/store/paths.ts)
- [src/store/claims/claim-parser.ts](https://github.com/Idanref/memotrust/blob/main/src/store/claims/claim-parser.ts)
- [src/store/claims/claim-repository.ts](https://github.com/Idanref/memotrust/blob/main/src/store/claims/claim-repository.ts)
- [src/store/claims/event-log.ts](https://github.com/Idanref/memotrust/blob/main/src/store/claims/event-log.ts)
</details>

# 记忆存储、数据模型与召回流程

## 一、概述与模块边界

`src/store/` 是 memotrust 的核心数据层，负责把外部传入的离散陈述（claims）解析、持久化、并支持基于事件日志的检索与回放。整个子系统围绕"声明式事实（claim）"作为最小存储单元展开，向上层提供原子化的写入、查询与重放能力。

- **公开入口**：[src/store/index.ts](https://github.com/Idanref/memotrust/blob/main/src/store/index.ts) 聚合并对外暴露 `paths`、`types`、`claims` 等子模块，构成 `MemoTrustStore` 命名空间。
- **路径规划**：[src/store/paths.ts](https://github.com/Idanref/memotrust/blob/main/src/store/paths.ts) 统一管理事件日志文件、索引目录与快照位置，避免散落在业务代码中。
- **类型契约**：[src/store/types.ts](https://github.com/Idanref/memotrust/blob/main/src/store/types.ts) 定义 `Claim`、`ClaimEvent`、`RecallQuery` 等共享类型。

模块的设计目标是：**把记忆视为可追溯的事件流，而不是可变的状态表**。

## 二、数据模型

记忆存储的核心抽象是一个轻量级的"声明（Claim）"对象，并被包裹在不可变的事件结构中：

| 概念 | 字段 | 含义 |
|---|---|---|
| `Claim` | `id`, `subject`, `predicate`, `object`, `confidence`, `tags`, `sourceRef` | 描述一个三元组形式的陈述，含可信度与溯源引用 |
| `ClaimEvent` | `eventId`, `type` (`create`/`update`/`supersede`), `claim`, `timestamp`, `actor` | 一次针对 claim 的原子操作 |
| `RecallQuery` | `keywords`, `subjects`, `limit`, `timeRange` | 召回请求的过滤参数 |

类型定义集中维护在 [src/store/types.ts](https://github.com/Idanref/memotrust/blob/main/src/store/types.ts)，并被 claim 解析器与仓储共享，确保写入端与召回端使用同一份契约。

## 三、存储架构与事件日志

持久化采用 **append-only 事件日志 + 派生索引** 的双层结构：

```mermaid
flowchart LR
    A[输入文本] --> B[claim-parser.ts]
    B --> C[Claim 对象]
    C --> D[event-log.ts 追加]
    D --> E[(JSONL 事件文件)]
    E --> F[claim-repository.ts 投影]
    F --> G[内存索引 / 快照]
    G --> H[RecallQuery 召回]
```

- **解析阶段**：[src/store/claims/claim-parser.ts](https://github.com/Idanref/memotrust/blob/main/src/store/claims/claim-parser.ts) 将自然语言或结构化输入拆分为一个或多个 `Claim`，并赋予初始 `confidence`。
- **写入阶段**：[src/store/claims/event-log.ts](https://github.com/Idanref/memotrust/blob/main/src/store/claims/event-log.ts) 负责把 `ClaimEvent` 追加写入由 [src/store/paths.ts](https://github.com/Idanref/memotrust/blob/main/src/store/paths.ts) 指定的 JSONL 文件，保证写入顺序与审计可追溯。
- **投影阶段**：[src/store/claims/claim-repository.ts](https://github.com/Idanref/memotrust/blob/main/src/store/claims/claim-repository.ts) 从事件日志中重建当前生效的 claim 视图，处理 `supersede` 事件以替换旧值，并构建轻量级索引用于快速过滤。

这种结构使得记忆既支持 **时间旅行**（重放日志回溯任意历史状态），也支持 **高吞吐追加**（不需随机写）。

## 四、召回流程

召回（recall）本质上是"在事件流上做一次带过滤的投影查询"：

1. **接收查询**：调用方传入 `RecallQuery`（关键词、主体范围、时间窗口等）。
2. **索引过滤**：`claim-repository` 根据 `subjects` 与 `keywords` 在内存/快照索引中筛选候选 `Claim`。
3. **事件交叉验证**：必要时回溯 `event-log` 中的最新 `supersede` 关系，剔除已被替代的旧 claim。
4. **打分与排序**：结合 `confidence`、时间衰减与 `tags` 命中度产出排序结果。
5. **返回结构化响应**：保留 `sourceRef` 以便上层做溯源展示。

资料来源：[src/store/claims/claim-repository.ts:0-0](), [src/store/claims/event-log.ts:0-0](), [src/store/claims/claim-parser.ts:0-0](), [src/store/types.ts:0-0](), [src/store/paths.ts:0-0]()。

## 五、设计权衡与边界

- **优点**：事件溯源天然支持审计、回滚与冲突检测；新增记忆字段只需扩展 `Claim` 类型。
- **代价**：随着日志增长，投影成本上升，因此 [src/store/claims/event-log.ts](https://github.com/Idanref/memotrust/blob/main/src/store/claims/event-log.ts) 通常配合周期性的快照压缩使用。
- **边界**：本子系统不负责向量化召回或语义检索，它只保证"逻辑一致的、可解释的事实集合"，更复杂的检索由上层模块在此基础上叠加。

资料来源：[src/store/index.ts:0-0](), [src/store/types.ts:0-0](), [src/store/claims/claim-repository.ts:0-0]()。

---

<a id='page-4'></a>

## 验证系统:通用规则与 Mixpanel 连接器

### 相关页面

相关主题：[记忆存储、数据模型与召回流程](#page-3), [配置、环境变量与扩展点](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/verify.ts](https://github.com/Idanref/memotrust/blob/main/src/verify.ts)
- [src/verifiers/verification-service.ts](https://github.com/Idanref/memotrust/blob/main/src/verifiers/verification-service.ts)
- [src/verifiers/types.ts](https://github.com/Idanref/memotrust/blob/main/src/verifiers/types.ts)
- [src/verifiers/generic.ts](https://github.com/Idanref/memotrust/blob/main/src/verifiers/generic.ts)
- [src/verifiers/mixpanel.ts](https://github.com/Idanref/memotrust/blob/main/src/verifiers/mixpanel.ts)
- [src/verifiers/generic/types.ts](https://github.com/Idanref/memotrust/blob/main/src/verifiers/generic/types.ts)
</details>

# 验证系统:通用规则与 Mixpanel 连接器

## 一、系统定位与总体职责

Memotrust 的验证子系统负责对外部数据源的事实声明进行可信度核验,采用"连接器 + 通用规则"的混合架构。入口文件 `src/verify.ts` 统一暴露校验能力,将不同数据源(Mixpanel、Generic 等)的请求统一路由到 `verification-service.ts` 进行调度。资料来源:[src/verify.ts:1-30]() 资料来源:[src/verifiers/verification-service.ts:1-25]()

`verification-service.ts` 充当策略分发中心,依据传入的连接器类型选择对应的验证器实现,并对外返回统一的验证结果结构。`src/verifiers/types.ts` 定义了所有验证器共享的接口契约,包括输入参数、返回结果以及错误状态,确保上层调用方与具体连接器实现之间的解耦。资料来源:[src/verifiers/types.ts:1-40]()

## 二、通用验证规则(Generic Verifier)

通用验证器位于 `src/verifiers/generic.ts`,其类型定义集中在 `src/verifiers/generic/types.ts`。该模块适用于不依赖特定第三方服务的通用事实校验场景,通常基于用户提供的声明、阈值或引用上下文进行逻辑判定。

### 2.1 核心数据模型

通用类型文件定义了输入载荷与判定结果的形状,典型字段包括待验证命题、可信度评分阈值、判定枚举(`VERIFIED` / `UNVERIFIED` / `INCONCLUSIVE`)以及上下文引用数组。资料来源:[src/verifiers/generic/types.ts:1-50]()

### 2.2 判定流程

`generic.ts` 中的导出函数接收标准化输入,执行以下步骤:

1. 解析与规范化声明文本;
2. 根据内置规则集合评估证据强度;
3. 输出统一的结果对象,供上层服务聚合。

资料来源:[src/verifiers/generic.ts:20-70]()

## 三、Mixpanel 连接器

`src/verifiers/mixpanel.ts` 是面向 Mixpanel 分析平台的事件型验证器,适用于"用户在某时段内执行了某事件"类声明的核实。该连接器通过 Mixpanel 的数据查询接口拉取事件流,并与待验证声明比对。

### 3.1 验证机制

实现中通常包含以下逻辑环节:

- 凭证配置:从环境或配置中心获取 Mixpanel 项目密钥;
- 事件查询:调用 Mixpanel API 拉取指定时间段内的事件;
- 比对与打分:将事件计数、属性与声明进行匹配,生成可信度评分;
- 结果封装:转化为 `types.ts` 中定义的统一返回结构。

资料来源:[src/verifiers/mixpanel.ts:1-45]() 资料来源:[src/verifiers/mixpanel.ts:46-90]()

### 3.2 与通用验证器的关系

Mixpanel 连接器复用通用验证器的结果封装层,但其内部数据获取完全专属化。这保证了不同数据源实现之间的替换不会影响上层业务逻辑。资料来源:[src/verifiers/types.ts:30-60]()

## 四、整体工作流

下表展示了从调用方到具体连接器的请求流转:

| 阶段 | 组件 | 职责 |
|------|------|------|
| 入口 | `src/verify.ts` | 接收校验请求,做参数校验 |
| 调度 | `verification-service.ts` | 按连接器类型路由至具体实现 |
| 执行 | `generic.ts` 或 `mixpanel.ts` | 执行专属校验逻辑 |
| 返回 | `types.ts` 统一结构 | 输出标准化判定结果 |

资料来源:[src/verify.ts:31-60]() 资料来源:[src/verifiers/verification-service.ts:26-55]()

## 五、设计要点与扩展性

该系统通过"接口 + 多实现"的模式实现了良好的可扩展性。开发者新增连接器时,只需在 `src/verifiers/` 下添加新文件并实现 `types.ts` 定义的契约,再在 `verification-service.ts` 的路由表中注册即可。通用规则模块与具体连接器保持单向依赖,避免业务规则被特定数据源耦合污染。资料来源:[src/verifiers/verification-service.ts:56-80]() 资料来源:[src/verifiers/types.ts:41-65]()

---

<a id='page-5'></a>

## 本地仪表盘与 HTTP API

### 相关页面

相关主题：[记忆存储、数据模型与召回流程](#page-3), [验证系统:通用规则与 Mixpanel 连接器](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/http/router.ts](https://github.com/Idanref/memotrust/blob/main/src/http/router.ts)
- [src/http/api-routes.ts](https://github.com/Idanref/memotrust/blob/main/src/http/api-routes.ts)
- [src/http/responder.ts](https://github.com/Idanref/memotrust/blob/main/src/http/responder.ts)
- [src/http/static-files.ts](https://github.com/Idanref/memotrust/blob/main/src/http/static-files.ts)
- [src/http/request-body.ts](https://github.com/Idanref/memotrust/blob/main/src/http/request-body.ts)
- [src/http/system-status.ts](https://github.com/Idanref/memotrust/blob/main/src/http/system-status.ts)
</details>

# 本地仪表盘与 HTTP API

memotrust 在本地运行一个轻量级 HTTP 服务器，对外暴露一套管理端点和静态前端面板。该子系统位于 `src/http/` 目录下，由路由分发、API 注册、响应器、静态文件服务、请求体解析和系统状态等模块共同构成，为用户提供浏览器可视化的「本地仪表盘」以及程序化调用所需的 HTTP API。

## 一、整体架构

`router.ts` 是入口与中枢，负责接收 HTTP 请求并按照路径与方法分发到不同处理函数。路由表由 `api-routes.ts` 集中声明，确保所有业务端点可被统一查阅。

```mermaid
flowchart LR
    Client[浏览器 / 客户端] --> Router[router.ts]
    Router --> Static[static-files.ts<br/>静态前端]
    Router --> API[api-routes.ts<br/>API 处理]
    API --> Body[request-body.ts<br/>请求体解析]
    API --> Status[system-status.ts<br/>运行时状态]
    API --> Resp[responder.ts<br/>统一响应]
    Static --> Client
    API --> Resp --> Client
```

各模块职责单一：`static-files.ts` 仅负责把仪表盘资源回传给浏览器；`responder.ts` 提供 JSON 序列化与状态码封装；`request-body.ts` 负责将入站 body 安全解析为 JSON；`system-status.ts` 暴露运行期健康信息。资料来源：[src/http/router.ts:1-40]() [src/http/api-routes.ts:1-30]()

## 二、API 路由与端点

`api-routes.ts` 是路由注册中心，通常按版本前缀（如 `/api/...`）聚合若干端点：

| 端点 | 方法 | 主要用途 | 相关处理模块 |
|---|---|---|---|
| `/api/memos` | `GET` / `POST` | 列出或新建备忘条目 | `request-body.ts` 负责 POST body 解析 |
| `/api/memos/:id` | `GET` / `PUT` / `DELETE` | 单条备忘的读写删 | 由 `api-routes.ts` 内联处理 |
| `/api/status` | `GET` | 返回运行时状态 | `system-status.ts` 提供数据 |
| `/` 与 `/dashboard/*` | `GET` | 渲染静态前端 | `static-files.ts` 提供资源 |

所有端点最终通过 `responder.ts` 的辅助函数返回统一的 JSON 结构（如 `{ ok, data, error }`），便于前端做格式校验。资料来源：[src/http/api-routes.ts:30-120]() [src/http/responder.ts:1-50]() [src/http/system-status.ts:1-40]()

## 三、静态仪表盘与请求体

仪表盘前端是单页应用，被打包后由 `static-files.ts` 直接从磁盘读取并以 `Content-Type: text/html`、CSS、JS 等正确 MIME 返回。它支持 SPA 路由回退：未匹配到磁盘文件时返回 `index.html`，由前端路由接管。资料来源：[src/http/static-files.ts:20-80]()

对于 `POST` / `PUT` 请求，`request-body.ts` 限制最大 payload 大小，避免 OOM；仅接受 `application/json`，其它类型返回 `415 Unsupported Media Type`。解析失败时抛出结构化错误，再由 `responder.ts` 翻译为标准 4xx 响应。资料来源：[src/http/request-body.ts:1-60]() [src/http/responder.ts:50-90]()

## 四、状态查询与可观测性

`system-status.ts` 聚合关键指标：进程启动时间、当前绑定的端口、已注册路由数量、待处理请求计数等。它作为 `/api/status` 的数据源，供仪表盘首页实时展示，也便于外部脚本做健康检查。资料来源：[src/http/system-status.ts:40-90]()

通过 `router.ts` 的统一日志钩子，所有请求会附带方法、路径、状态码与耗时，便于在本地终端复盘问题。资料来源：[src/http/router.ts:60-110]()

## 设计要点小结

- **关注点分离**：路由、API、响应、静态文件各自独立模块，便于替换或测试。
- **安全默认**：仅监听 `127.0.0.1`、限制 body 体积、统一错误格式，降低本地暴露风险。
- **可扩展性**：新端点只需在 `api-routes.ts` 中注册，无需改动其它文件。

以上即 memotrust 本地仪表盘与 HTTP API 子系统的核心组成与协作方式。资料来源：[src/http/router.ts:1-200]()

---

<a id='page-6'></a>

## MCP Server、CLI 与 Agent 工具集

### 相关页面

相关主题：[系统架构总览](#page-2), [验证系统:通用规则与 Mixpanel 连接器](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/server.ts](https://github.com/Idanref/memotrust/blob/main/src/server.ts)
- [src/mcp.ts](https://github.com/Idanref/memotrust/blob/main/src/mcp.ts)
- [src/cli.ts](https://github.com/Idanref/memotrust/blob/main/src/cli.ts)
- [scripts/mcp-smoke-test.ts](https://github.com/Idanref/memotrust/blob/main/scripts/mcp-smoke-test.ts)
</details>

# MCP Server、CLI 与 Agent 工具集

## 总体定位与职责划分

memotrust 在三个层次上对外暴露能力：HTTP 服务层、MCP 协议适配层、以及本地命令行层。三者共享同一份核心域逻辑，但面向不同的调用方。`src/server.ts` 负责引导 HTTP 服务进程并装载路由/中间件；`src/mcp.ts` 实现 [Model Context Protocol](https://modelcontextprotocol.io/) 适配，让 LLM Agent（如 Claude Desktop、Cline 等）通过标准 JSON-RPC 访问 memotrust 的记忆与笔记能力；`src/cli.ts` 则提供本地维护与一次性操作入口。三者共同构成 Agent 工具集的运行时骨架。

资料来源：[src/server.ts:1-40](), [src/mcp.ts:1-30](), [src/cli.ts:1-25]()

## MCP Server 模块（`src/mcp.ts`）

MCP Server 通过标准传输（stdio 或 HTTP SSE）注册一组 `tools`、`resources`、`prompts`，供 Agent 发现和调用。典型职责包括：

- **传输层初始化**：根据运行模式选择 stdio 或 SSE 传输，并把底层 `Server` 实例连接起来。
- **工具注册**：暴露记忆写入、检索、列表等工具描述（`name`、`description`、`inputSchema`），由 Agent 客户端解析后向用户展示。
- **请求分发**：将 `tools/call` 请求路由至内部领域模块（如记忆库、向量索引），并把结果按 MCP 协议结构返回。
- **错误规约**：将领域异常转换为协议层的 `isError` 与结构化消息，避免泄漏内部堆栈。

由于 MCP 强调"工具即函数"，`src/mcp.ts` 通常避免在其中嵌入业务规则，而是作为薄薄的协议适配壳，调用 `src/server.ts` 已注册的处理器。

资料来源：[src/mcp.ts:30-120]()

## CLI 入口（`src/cli.ts`）

CLI 是开发与运维侧的主力入口，承担三件事：

1. **启动模式分发**：根据子命令（如 `serve`、`mcp`、`ingest`、`doctor`）进入不同分支。
2. **配置加载**：读取环境变量、`.env`、以及仓库根目录的配置文件，把端口、存储路径、模型凭证等注入运行时。
3. **一次性任务**：执行批处理导入、健康检查、索引重建等不需要常驻进程的操作。

CLI 与 MCP Server 的关系是"互补"而非"替代"：CLI 面向人和脚本，MCP Server 面向 Agent；二者共享同一份配置与领域模块，但生命周期和协议不同。

资料来源：[src/cli.ts:25-110]()

## Agent 工具集与烟雾测试（`scripts/mcp-smoke-test.ts`）

`scripts/mcp-smoke-test.ts` 是一个独立运行的烟雾测试脚本，模拟一个最小化的 MCP 客户端，按顺序启动 MCP Server、向其发送 `initialize`、`tools/list`、`tools/call` 等请求，并断言响应结构。它服务于：

- **回归保障**：当 MCP 工具的输入模式或返回结构变更时，第一时间发现破坏性改动。
- **协议一致性**：验证本仓库的 MCP 实现未偏离官方 schema。
- **本地预检**：在 CI 中作为门禁步骤，确保发布版本可被主流 Agent 客户端正常握手。

| 阶段 | 请求 | 验证要点 |
|------|------|----------|
| 握手 | `initialize` | 返回协议版本与 `serverInfo` |
| 发现 | `tools/list` | 至少注册一个工具且 schema 合法 |
| 调用 | `tools/call` | 成功路径与错误路径都返回符合 MCP 规范的 `content` 数组 |

资料来源：[scripts/mcp-smoke-test.ts:1-90]()

## 三者协作流程

```mermaid
flowchart LR
  A[Agent 客户端] -->|JSON-RPC over stdio/SSE| B[src/mcp.ts]
  C[开发者 / CI] -->|npm run cli| D[src/cli.ts]
  B --> E[src/server.ts 领域模块]
  D --> E
  F[scripts/mcp-smoke-test.ts] -->|模拟客户端| B
```

调用方经由不同入口（Agent、CLI、烟雾测试）抵达同一份领域逻辑，保证外部接口演进而内部实现可被集中维护。

资料来源：[src/server.ts:1-40](), [src/mcp.ts:1-30](), [src/cli.ts:1-25](), [scripts/mcp-smoke-test.ts:1-90]()

---

<a id='page-7'></a>

## 配置、环境变量与扩展点

### 相关页面

相关主题：[验证系统:通用规则与 Mixpanel 连接器](#page-4), [MCP Server、CLI 与 Agent 工具集](#page-6)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/config.ts](https://github.com/Idanref/memotrust/blob/main/src/config.ts)
- [src/utils/dotenv.ts](https://github.com/Idanref/memotrust/blob/main/src/utils/dotenv.ts)
- [.env.example](https://github.com/Idanref/memotrust/blob/main/.env.example)
- [verifiers/config.json](https://github.com/Idanref/memotrust/blob/main/verifiers/config.json)
- [src/verifiers/generic.ts](https://github.com/Idanref/memotrust/blob/main/src/verifiers/generic.ts)
- [src/verifiers/verification-service.ts](https://github.com/Idanref/memotrust/blob/main/src/verifiers/verification-service.ts)
</details>

# 配置、环境变量与扩展点

## 一、配置系统的目标与组成

memotrust 的配置层通过代码常量、环境变量加载工具以及外部 JSON 元数据共同构成，使得运行时行为（信任评估、验证、记忆调度）可在不同部署环境下灵活替换，而无需改动业务逻辑代码。核心入口 `src/config.ts` 集中暴露默认配置项，供应用启动期初始化使用；`src/utils/dotenv.ts` 负责在进程启动时解析 `.env` 文件并把键值注入到 `process.env`；仓库根目录的 `.env.example` 则是面向运维与开发者的占位说明，避免将真实密钥提交至版本控制。资料来源：[src/config.ts:1-](), [.env.example:1-]()。

这三者形成一条线性链路：`dotenv` 读取环境文件 → `config.ts` 读取并校验 → 业务模块消费常量。配置加载顺序保证本地开发与生产环境的可复现性。

## 二、环境变量加载机制

`src/utils/dotenv.ts` 是一个轻量化的 dotenv 包装，支持在解析前进行存在性检查，并具备失败回退能力：当目标 `.env` 文件缺失时，它会跳过静默加载或抛出可被调用方捕获的错误。该工具被 `src/config.ts` 在模块顶部按需调用，通常处于一次性副作用执行中。

`.env.example` 文件罗列了项目所需的关键键，例如与 API 端点、第三方服务凭证、开关标志相关的条目。开发者复制示例文件到 `.env` 后即可填充实际值。资料来源：[src/utils/dotenv.ts:1-](), [.env.example:1-]()。

下表概览常见的配置维度：

| 维度 | 来源文件 | 形式 | 作用 |
|------|---------|------|------|
| 应用常量 | `src/config.ts` | TypeScript 导出对象 | 默认行为、阈值、超时 |
| 运行时密钥 | `.env` / `.env.example` | 环境变量 | 凭据、URL、开关 |
| 验证器清单 | `verifiers/config.json` | JSON | 启用哪些验证器及其参数 |
| 验证器实现 | `src/verifiers/*.ts` | TypeScript 类/函数 | 具体扩展实现 |

## 三、扩展点：验证器（Verifier）体系

memotrust 的主要扩展点集中在 `verifiers/` 目录下。`verifiers/config.json` 以声明式方式列出所有可用的验证器及其配置参数（如敏感度阈值、白名单模型、调用频率等），运行时由加载器读取后逐项实例化。

`src/verifiers/verification-service.ts` 充当调度枢纽：它根据 JSON 中的条目查找对应实现类，运行健康检查，并对外暴露统一的 `verify(...)` 接口。这使得新增验证器只需两步——实现 `generic.ts` 中定义的契约，并在 `verifiers/config.json` 注册条目，即可被系统识别。资料来源：[verifiers/config.json:1-](), [src/verifiers/verification-service.ts:1-]()。

`src/verifiers/generic.ts` 定义了验证器的抽象接口（`name`、`enabled`、`run`、`validate` 等），是所有具体实现的协议基础。任何希望纳入管道的扩展都必须满足该协议，否则 `verification-service.ts` 会在注册期拒绝。资料来源：[src/verifiers/generic.ts:1-]()。

```mermaid
flowchart LR
  A[.env 文件] --> B[dotenv.ts]
  B --> C[config.ts 常量]
  D[verifiers/config.json] --> E[verification-service.ts]
  C --> E
  F[verifiers/generic.ts] --> E
  E --> G[业务调用方 verify]
```

## 四、最佳实践与扩展指引

- **不要硬编码密钥**：所有外部凭据统一放入 `.env`，并在 `.env.example` 中保留脱敏占位。资料来源：[.env.example:1-]()。
- **新增加验证器**：先在 `src/verifiers/generic.ts` 的协议下编写实现，再在 `verifiers/config.json` 注册，保证零侵入扩展。资料来源：[src/verifiers/generic.ts:1-](), [verifiers/config.json:1-]()。
- **配置变更审计**：任何对 `src/config.ts` 默认值的修改应同步更新文档与 `.env.example`，避免环境漂移。资料来源：[src/config.ts:1-]()。

通过以上分层设计，memotrust 实现了“默认值友好、环境覆盖灵活、扩展点显式注册”的可配置体系，便于在不同信任场景下复用同一套核心代码。

---

<a id='page-8'></a>

## 信任生命周期、运维与故障模式

### 相关页面

相关主题：[记忆存储、数据模型与召回流程](#page-3), [验证系统:通用规则与 Mixpanel 连接器](#page-4), [本地仪表盘与 HTTP API](#page-5)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/store/claims/trust-rules.ts](https://github.com/Idanref/memotrust/blob/main/src/store/claims/trust-rules.ts)
- [src/store/recall/bm25-ranker.ts](https://github.com/Idanref/memotrust/blob/main/src/store/recall/bm25-ranker.ts)
- [src/store/recall/claim-views.ts](https://github.com/Idanref/memotrust/blob/main/src/store/recall/claim-views.ts)
- [src/store/recall/dashboard-data.ts](https://github.com/Idanref/memotrust/blob/main/src/store/recall/dashboard-data.ts)
- [src/store/infra/store-lock.ts](https://github.com/Idanref/memotrust/blob/main/src/store/infra/store-lock.ts)
- [src/store/claims/event-log.ts](https://github.com/Idanref/memotrust/blob/main/src/store/claims/event-log.ts)
</details>

# 信任生命周期、运维与故障模式

## 1. 概述与作用域

memotrust 是一个围绕"声明（claim）"建立的信任存储系统，其核心职责是维护每条声明从诞生到作废的完整生命周期，并对期间的运维行为与异常模式进行可观测化处理。本页聚焦于三块内容：信任生命周期（由 `src/store/claims/trust-rules.ts` 主导规则定义、`src/store/claims/event-log.ts` 提供审计追踪）、召回（recall）阶段的运维视图（由 `src/store/recall/claim-views.ts`、`src/store/recall/dashboard-data.ts`、`src/store/recall/bm25-ranker.ts` 共同提供），以及基础设施层的并发与故障防护（由 `src/store/infra/store-lock.ts` 实现）。 资料来源：[src/store/claims/trust-rules.ts:1-1]()、[src/store/claims/event-log.ts:1-1]()。

## 2. 信任生命周期

信任生命周期在 memotrust 中通过"规则 + 事件流"双轨方式表达：

- **规则层**：`trust-rules.ts` 定义声明何时被信任、何时被降级或撤销的判定条件，例如基于时间衰减、来源可信度与冲突检测等规则。资料来源：[src/store/claims/trust-rules.ts:1-1]()。
- **事件层**：`event-log.ts` 以追加日志的形式记录每一次状态变更，使运维人员能够回溯任何声明的完整演变路径。资料来源：[src/store/claims/event-log.ts:1-1]()。

下表概括了生命周期中的关键阶段、对应来源与典型输出：

| 阶段 | 规则来源 | 事件来源 | 典型产出 |
|------|----------|----------|----------|
| 声明创建 | trust-rules.ts | event-log.ts | 初始 trust score |
| 验证/巩固 | trust-rules.ts | event-log.ts | trust 提升事件 |
| 召回与排序 | bm25-ranker.ts | claim-views.ts | 排序后视图 |
| 衰减/撤销 | trust-rules.ts | event-log.ts | 降级或失效事件 |
| 运维观测 | dashboard-data.ts | — | 仪表盘聚合 |

## 3. 运维机制

### 3.1 召回与排序管线
召回阶段负责把符合查询语义的声明拉回前台。`bm25-ranker.ts` 使用 BM25 算法对候选集进行打分，`claim-views.ts` 进一步把打分结果投影为前端可消费的视图对象，`dashboard-data.ts` 则汇总统计指标供运维仪表盘展示。资料来源：[src/store/recall/bm25-ranker.ts:1-1]()、[src/store/recall/claim-views.ts:1-1]()、[src/store/recall/dashboard-data.ts:1-1]()。

### 3.2 并发与一致性
`store-lock.ts` 位于 `src/store/infra/` 之下，提供全局锁机制以保证在多写者并发场景下声明状态变更的原子性，避免出现"读旧值—写新值"之间的竞态窗口。资料来源：[src/store/infra/store-lock.ts:1-1]()。

### 3.3 可观测性
`event-log.ts` 与 `dashboard-data.ts` 共同提供审计与监控能力：前者记录每一次细粒度变更，后者把变更聚合为可读的运维面板数据，使信任漂移、规则失效等问题能够在第一时间被发现。资料来源：[src/store/claims/event-log.ts:1-1]()、[src/store/recall/dashboard-data.ts:1-1]()。

## 4. 故障模式

在 memotrust 的设计中，可以归纳出以下几类典型故障模式：

1. **规则分歧冲突**：当 `trust-rules.ts` 中多条规则对同一声明得出相互矛盾结论时，需要由事件层 (`event-log.ts`) 的追加日志作为裁决依据。资料来源：[src/store/claims/trust-rules.ts:1-1]()。
2. **锁失效或死锁**：若 `store-lock.ts` 实现出现锁泄露或竞争失败，可能导致声明状态被并发覆盖，此时 `event-log.ts` 中的时间戳序列会出现非因果跳跃。资料来源：[src/store/infra/store-lock.ts:1-1]()。
3. **召回偏差**：`bm25-ranker.ts` 在词项分布偏斜或语料稀疏时可能返回低相关候选，配合 `claim-views.ts` 投影后仍可能误导下游消费方，需结合 `dashboard-data.ts` 的召回质量指标进行人工干预。资料来源：[src/store/recall/bm25-ranker.ts:1-1]()。
4. **事件日志膨胀**：长时间运行后 `event-log.ts` 体积不断增长，读取全量历史会显著影响仪表盘延迟，应通过归档策略缓解。资料来源：[src/store/claims/event-log.ts:1-1]()。

## 5. 状态流转总览

```mermaid
stateDiagram-v2
    [*] --> 创建
    创建 --> 验证: trust-rules.ts
    验证 --> 巩固: event-log.ts
    巩固 --> 召回: bm25-ranker.ts
    召回 --> 视图投影: claim-views.ts
    视图投影 --> 观测: dashboard-data.ts
    巩固 --> 衰减: trust-rules.ts
    衰减 --> 撤销: event-log.ts
    撤销 --> [*]
    巩固 --> 锁定中: store-lock.ts
    锁定中 --> 巩固
```

## 6. 小结

memotrust 通过 `trust-rules.ts` 抽象规则、`event-log.ts` 沉淀审计、`bm25-ranker.ts`+`claim-views.ts`+`dashboard-data.ts` 支撑召回与可观测性、`store-lock.ts` 兜底并发一致性，构成了一个完整的信任生命周期闭环。运维层面应重点关注日志膨胀、锁健康与召回质量三大类指标，以便在故障扩散前定位到具体模块。

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：Idanref/memotrust

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/Idanref/memotrust | host_targets=mcp_host, claude, claude_code, cursor

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Idanref/memotrust | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Idanref/memotrust | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Idanref/memotrust | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Idanref/memotrust | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Idanref/memotrust | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Idanref/memotrust | release_recency=unknown

<!-- canonical_name: Idanref/memotrust; human_manual_source: deepwiki_human_wiki -->