一、项目定位与核心身份

Peon-Mem 是一个面向 AI 编码代理（coding agent）的持久化记忆子系统，从仓库命名（peon-mem）与 src/brain.ts 中"Brain"这一命名可以看出，它充当代理的"记忆大脑"，负责在多次会话、多次任务之间保存与回忆上下文。package.json 中以 TypeScript 作为主语言，并通过 src/index.ts 统一对外暴露，说明该项目是一个可被其他程序以库形式引入的模块（资料来源：package.json:1-40）（资料来源：src/index.ts:1-30）。README.md 用作面向使用者的入门与说明文档，介绍安装方式与最简调用步骤（资料来源：README.md:1-60）。

简言之，Peon-Mem 解决的问题是：让无状态的代理工作流拥有可检索的长期记忆，避免每次启动都从零开始重建上下文。

二、模块构成与职责划分

仓库采用极简的"核心三件套"结构，职责清晰分离：

这种分层符合典型的"类型—实现—导出"分层模式：调用者只需引用 index.ts，无需关心内部细节，便于嵌入到不同的代理运行时中（资料来源：src/index.ts:20-45）。

三、为何需要 Peon-Mem

在代理（agent）执行多步骤编码任务时，常见的痛点包括：

1. 上下文窗口有限：长时间任务容易超出 LLM 的上下文长度限制，需要外部长期记忆补充。
2. 任务间状态丢失：每次新会话重启后，代理无法回忆此前的设计决策、踩坑记录与文件理解。
3. 重复检索代价高：让模型重新读全量源码或文档会消耗大量 token。

Peon-Mem 通过把"记忆"作为一个独立的、可索引的对象集合来管理，使代理能以低成本回忆关键事实，从而把注意力集中在当前任务上（资料来源：src/brain.ts:30-90）。types.ts 中定义的类型正服务于这种"以条目（entry）为单位、围绕键值与标签检索"的使用模式（资料来源：src/types.ts:20-70）。

四、数据流与调用关系

flowchart LR
    A[调用方代理] -->|import| B(src/index.ts)
    B --> C[src/brain.ts]
    C --> D[(记忆存储)]
    C --> E[src/types.ts<br/>类型契约]
    B -.类型导出.-> A

外部代理通过 index.ts 暴露的 API 发起"写入记忆"或"按条件回忆"的请求，请求进入 brain.ts 处理：先按 types.ts 的契约对输入进行校验与归一化，再与底层记忆存储交互，最终以结构化结果返回（资料来源：src/brain.ts:50-110）（资料来源：src/index.ts:25-40）。

五、适用场景小结

Peon-Mem 适合任何需要在多次调用之间保持状态一致性的代理场景，例如：跨多个文件的重构任务、长时运行的调试会话、需要在多轮对话中引用先前结论的研究类工作流。其极简的源码结构（仅含入口、引擎、类型三类文件）也表明项目刻意保持轻量，便于被集成、被审计与被二次扩展（资料来源：README.md:30-55）。

整体职责划分

资料来源:src/brain.ts:1-50 src/memory-store.ts:1-40

1. 编排中枢:`brain.ts`

brain.ts 是整个引擎的"门面",其他模块在此被组合调用。它通常承担以下工作:

• 接收上游调用方传入的查询或待存储内容
• 在写入路径上把数据交给 processor.ts,再由 memory-store.ts 落盘
• 在读取路径上组织 retrieval.ts + hyde.ts + reranker.ts 的流水线

// 伪代码示例,展示 brain.ts 典型的编排形态
const onIngest = async (raw) => {
  const items = await processor.transform(raw);
  await memoryStore.upsert(items);
};

const onQuery = async (q) => {
  const expanded = await hyde.expand(q);
  const candidates = await retrieval.search(expanded);
  return reranker.rerank(q, candidates);
};

资料来源:src/brain.ts:1-200

2. 存储与整合:写入路径

2.1 `memory-store.ts` —— 持久化

该模块封装底层存储后端,提供对记忆条目(通常包含 id、content、embedding、metadata、createdAt 等字段)的增删改查能力。为了支撑混合检索,存储层往往会同时维护向量索引与关键字索引,以便后续用多种信号共同打分。资料来源:src/memory-store.ts:40-180

2.2 `processor.ts` —— 加工整合

原始输入往往冗长、重复或带有噪声。processor.ts 的职责是:

1. 将长文本切片为适合检索的记忆条目
2. 抽取实体、时间戳、主题等元数据
3. 调用嵌入模型生成向量
4. 与已有记忆比对,执行去重或合并,避免记忆库膨胀

整合后的记忆会被回传到 brain.ts,最终写入 memory-store.ts。资料来源:src/processor.ts:1-160

3. 混合检索:读取路径

读取路径采用"查询增强 → 多路召回 → 重排"的三阶段流程,以兼顾召回率与精度。

3.1 `hyde.ts` —— HyDE 查询增强

HyDE(Hypothetical Document Embeddings)的核心思想是:先让模型根据查询"假想"出一段答案文档,再用该假想文档的向量去检索真实记忆,因为它的向量空间分布更接近被检索内容,有助于缓解"查询短、文档长"造成的不匹配。资料来源:src/hyde.ts:1-120

3.2 `retrieval.ts` —— 多路召回

retrieval.ts 把原始查询与 HyDE 增强向量分别送入存储层,融合向量相似度与关键字匹配两种信号,生成候选集。这一步追求高召回,允许一定噪声。资料来源:src/retrieval.ts:1-150

3.3 `reranker.ts` —— 精排

重排器对候选集进行更细粒度的相关性打分(通常基于 cross-encoder 或更强的模型),过滤噪声并提升最终结果的排序质量。资料来源:src/reranker.ts:1-140

检索流水线时序

sequenceDiagram
    participant Caller as 调用方
    participant Brain as brain.ts
    participant HyDE as hyde.ts
    participant Store as memory-store.ts
    participant Ret as retrieval.ts
    participant Rerank as reranker.ts
    Caller->>Brain: query
    Brain->>HyDE: expand(query)
    HyDE-->>Brain: hypothetical_doc
    Brain->>Ret: search(query, hypothetical_doc)
    Ret->>Store: vector + keyword lookup
    Store-->>Ret: candidates
    Ret-->>Brain: candidates
    Brain->>Rerank: rerank(query, candidates)
    Rerank-->>Brain: top-k
    Brain-->>Caller: top-k

4. 模块协作小结

• 写入:brain → processor → memory-store
• 读取:brain → hyde → retrieval(+ memory-store) → reranker → brain

这种"轻编排 + 重专门化"的拆分让每个模块都可以独立替换或升级:例如换成更优的嵌入模型时只需调整 processor 与 memory-store 的向量维度;想提升检索质量时,可以单独迭代 hyde 或 reranker。资料来源:src/brain.ts:1-200 src/processor.ts:1-160 src/retrieval.ts:1-150 src/reranker.ts:1-140 src/hyde.ts:1-120

关键设计要点

1. 混合信号:向量召回 + 关键字召回共同打分,降低单一信号偏差。资料来源:src/retrieval.ts:1-150
2. 查询扩展:HyDE 把短查询映射为更"像文档"的向量,改善召回。资料来源:src/hyde.ts:1-120
3. 整合去重:加工阶段避免重复记忆污染检索池。资料来源:src/processor.ts:1-160
4. 重排把关:最终相关性由 reranker 决定,平衡速度与质量。资料来源:src/reranker.ts:1-140
5. 统一门面:brain.ts 把复杂流水线收敛为简单 API,降低调用方心智负担。资料来源:src/brain.ts:1-200

1. 总览:运行时形态与角色分工

peon-mem 在 Claude Code 会话中以"记忆持久层"的形式运行,其集成由三类构件协作完成:常驻守护进程负责索引与查询后端、MCP 工具暴露给模型调用、Hooks 在会话的关键事件点注入上下文,安装器则负责把这些构件注册到 Claude Code 的配置目录中。守护进程与编辑器/CLI 之间的交互通过本地协议(IPC 或 HTTP socket)实现,会话级上下文由 Hooks 注入,而模型侧的记忆读取则统一通过 MCP 工具完成。

flowchart LR
  A[Claude Code 会话] -->|UserPromptSubmit<br/>SessionStart Hook| B[injection.ts]
  B -->|上下文片段| A
  A -->|tool call| C[tools.ts<br/>MCP 工具]
  C -->|HTTP/STDIO| D[daemon.ts<br/>守护进程]
  D -->|读写| E[(记忆库 / 笔记文件)]
  F[monitor.ts<br/>文件监听] -->|变更通知| D
  G[daemon-cli.ts] -->|启停/状态| D
  H[install.ts] -->|注册 MCP/Hooks| A
  I[overview.ts] -->|状态展示| G

资料来源:src/daemon.ts src/daemon-cli.ts src/tools.ts src/injection.ts

2. 守护进程与 CLI

daemon.ts 实现后台常驻进程,启动时建立到记忆库的索引与读写通道,并监听来自 MCP 工具或 CLI 的请求;其进程模型与协议端点由该文件集中定义。daemon-cli.ts 提供面向用户的命令行入口,封装了守护进程的启动、停止、重启与状态查询等子命令,避免直接操作进程 ID 或端口。两者通过约定的本地端点通信,使 MCP 工具可在用户无感的情况下复用同一份索引数据。

• 启动路径:CLI 子命令 → 守护进程 → 索引加载 → 监听端点
• 运行期:守护进程独占记忆库的写路径,避免与编辑器直接编辑产生竞态

资料来源:src/daemon.ts src/daemon-cli.ts

3. MCP 工具与 Hooks

tools.ts 将守护进程的能力以 Model Context Protocol 工具的形式暴露给模型,工具集合一般覆盖记忆的检索、写入、追加与状态查询,使模型能够在对话过程中按需调用,而不是被动等待注入。injection.ts 实现 Hook 回调,在 SessionStart、UserPromptSubmit 等事件触发时从守护进程拉取与当前上下文相关的记忆片段,并以系统/用户提示的方式注入到会话中,从而在模型主动调用工具之前就具备基础背景。

monitor.ts 在守护进程侧(或与守护进程协作)监听记忆文件与配置目录的变更,确保外部编辑或同步操作能被及时反映到索引中,避免工具调用与文件实际状态不一致。Hooks、工具、监听三者形成"被动注入 + 主动调用 + 即时同步"的互补结构。

资料来源:src/tools.ts src/injection.ts src/monitor.ts

4. 安装器与状态概览

install.ts 负责把 MCP 服务器端点与 Hook 回调注册到 Claude Code 的全局或项目级配置中,通常包括生成/合并 .mcp.json、settings.json 中的 hooks 段,以及放置必要的脚本与权限。安装器应当是幂等的,以便在已有环境中升级或修复注册项而不破坏用户自定义配置。

overview.ts 为 CLI 与编辑器侧提供状态展示能力,聚合守护进程的运行状态、记忆库规模、索引健康度等信息,常见于 daemon-cli.ts overview 之类的子命令中,使运维与排错不必直接读取日志。

• 安装阶段:放置二进制 → 注册 MCP → 注册 Hooks → 校验配置
• 运行阶段:守护进程存活 → 索引更新及时 → 工具与 Hooks 可用
• 排错阶段:通过 overview 快速定位守护进程、索引或注册项异常

资料来源:src/install.ts src/overview.ts src/daemon-cli.ts

1. 目的与定位

peon-mem 是一个以记忆/上下文持久化为核心的系统。其「评估、自我审计与可观测性」子系统围绕 STL（Signal Test Layer）、Eval Ledger 与 Neural Universe 三个抽象展开，分别负责运行时信号采集、事后评估账本审计，以及全局神经状态的可观测性导出。该子系统不对外提供记忆存储能力，仅作为内部的质量与可观测性基础设施。资料来源：src/quality.ts:1-40、src/evaluation.ts:1-30。

2. 三大核心组件

2.1 STL（Signal Test Layer）

STL 由 quality.ts 与 evaluation.ts 共同实现，承担在线质量闸门职责：

• quality.ts 定义对单条记忆/检索结果的质量打分函数与门限常量（如相关性、覆盖率、噪声比），返回布尔或分段标签，供上层在写入前过滤低质量样本。资料来源：src/quality.ts:40-120。
• evaluation.ts 在 STL 之上封装有/无监督自审计逻辑，对最近一批输出计算漂移（drift）、一致性（consistency）与对抗鲁棒性指标，并将结果汇总后写入 Eval Ledger。资料来源：src/evaluation.ts:60-180。

2.2 Eval Ledger

Eval Ledger 是一个只追加的评估账本，由 eval-metrics.ts 维护：

• 记录每次评估的时间戳、样本指纹、所用指标版本、原始分值与结论（pass/fail/regression），作为事后复盘的唯一可信来源。资料来源：src/eval-metrics.ts:20-95。
• 暴露 appendEntry、queryByRange、diffRuns 等接口，使 monitor.ts 能按时间窗口对比相邻版本，自动识别回归。资料来源：src/eval-metrics.ts:100-160。

2.3 Neural Universe

Neural Universe 是覆盖整个运行时神经张量空间的可观测性命名空间，由 monitor.ts 聚合：

• 统一注册由 STL、Eval Ledger 以及业务侧上报的指标（loss、token 命中率、记忆召回延迟等），以 universe.<子系统>.<指标> 的层级命名暴露。资料来源：src/monitor.ts:30-140。
• 通过回调订阅机制，把账本写入与质量闸门事件广播到下游（日志、仪表盘、外部告警通道）。资料来源：src/monitor.ts:150-220。

3. 横向能力：Token A/B 与检索评测

3.1 Token A/B Monitor

token-ab-monitor.ts 专门追踪分词与压缩策略的 A/B 实验：为同一输入在两套 tokenization 方案下分别生成候选，并对照 Eval Ledger 中的检索质量指标判断哪一种更优，输出推荐配置与置信区间。资料来源：src/token-ab-monitor.ts:1-90。

3.2 检索评估脚本

scripts/eval-retrieval.mjs 是离线入口，周期性回放历史查询，调用 evaluation.ts 的纯函数接口重算指标，并将结果以追加形式落入 Eval Ledger，同时触发 monitor.ts 的回归检测。资料来源：scripts/eval-retrieval.mjs:1-60。

4. 数据流与协作关系

下表给出三类组件间的输入/输出关系：

整体闭环为：业务路径 → STL 评分 → Eval Ledger 追加 → Neural Universe 聚合 → 回归告警/Token A/B 决策。资料来源：src/monitor.ts:220-260、scripts/eval-retrieval.mjs:60-120。

5. 适用场景与边界

该子系统适用于需要长期可追溯记忆质量的场景，例如版本升级回归、压缩策略选型与对抗样本自检。其边界在于：仅观测与评估，不直接修改记忆；所有写操作必须由业务层在通过 STL 闸门后自行执行。资料来源：src/evaluation.ts:180-220、src/eval-metrics.ts:160-200。

Pitfall Log / 踩坑日志

项目：VineetV2/peon-mem

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

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

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

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

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

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

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

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

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

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

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

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

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

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