项目定位与核心使命

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

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

核心价值主张

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

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

技术架构概览

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

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

项目目标与设计原则

项目的核心目标是解决 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。

一次典型请求的协作流程

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。

一、概述与模块边界

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

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

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

二、数据模型

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

类型定义集中维护在 src/store/types.ts，并被 claim 解析器与仓储共享，确保写入端与召回端使用同一份契约。

三、存储架构与事件日志

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

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 将自然语言或结构化输入拆分为一个或多个 Claim，并赋予初始 confidence。
• 写入阶段：src/store/claims/event-log.ts 负责把 ClaimEvent 追加写入由 src/store/paths.ts 指定的 JSONL 文件，保证写入顺序与审计可追溯。
• 投影阶段：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 通常配合周期性的快照压缩使用。
• 边界：本子系统不负责向量化召回或语义检索，它只保证"逻辑一致的、可解释的事实集合"，更复杂的检索由上层模块在此基础上叠加。

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

一、系统定位与总体职责

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: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

一、整体架构

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

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/...）聚合若干端点：

所有端点最终通过 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

总体定位与职责划分

memotrust 在三个层次上对外暴露能力：HTTP 服务层、MCP 协议适配层、以及本地命令行层。三者共享同一份核心域逻辑，但面向不同的调用方。src/server.ts 负责引导 HTTP 服务进程并装载路由/中间件；src/mcp.ts 实现 Model Context Protocol 适配，让 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 客户端正常握手。

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

三者协作流程

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

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

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-。

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

三、扩展点：验证器（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-。

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 实现了“默认值友好、环境覆盖灵活、扩展点显式注册”的可配置体系，便于在不同信任场景下复用同一套核心代码。

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。

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

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. 状态流转总览

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 兜底并发一致性，构成了一个完整的信任生命周期闭环。运维层面应重点关注日志膨胀、锁健康与召回质量三大类指标，以便在故障扩散前定位到具体模块。

Pitfall Log / 踩坑日志

项目：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