一、项目定位与目标

Pulse 是一个面向 AI Agent 的本地优先（local-first）、状态感知（state-aware）的记忆引擎。它不直接产出对话文本或调用工具，而是为上层 Agent 提供可持久化、可分类、可检索的"长期记忆"层，使 Agent 在多轮、多会话乃至跨进程场景中保持上下文一致。项目的设计前提是：记忆数据归属于用户本地，状态可被显式标注，从而让 Agent 在推理时既能"记得"也能"知道现在应该想起什么"。

资料来源：README.md:1-40

二、整体架构分层

Pulse 使用 Go 语言实现，模块边界围绕"入口—服务端—检索—存储"四层组织：

• 入口层：pulse-app/cmd/pulse/main.go 负责解析命令行参数、加载配置、装配依赖并启动服务进程。
• 服务端：pulse-app/internal/server/server.go 暴露对外 API（如 pulse_remember、pulse_recall），是所有读写请求的统一入口。
• 检索层：把已记住的 capsule 投影到一张检索图（retrieval graph），并通过独立的 state 通道在检索阶段过滤与排序。
• 存储层：本地优先的持久化层，将索引与正文分离存储，便于检索图复用与一致性维护。

flowchart LR
  Client[Agent / CLI] -->|pulse_remember / pulse_recall| Server[pulse-app/internal/server/server.go]
  Server --> Engine[Memory Engine]
  Engine --> Graph[Retrieval Graph]
  Engine --> Store[(Local Store)]
  Graph -->|state-aware ranking| Server
  Server --> Client

资料来源：pulse-app/cmd/pulse/main.go:1-60，pulse-app/internal/server/server.go:1-80，llms.txt:1-30

三、状态感知检索机制

v0.6.7 引入的 state-aware capsule retrieval 是当前架构的标志性能力，其核心思想是把"状态"从元数据提升为独立的检索维度：

• 胶囊化（capsule）：每条记忆以 capsule 形式存在，并被显式投影到检索图，成为可寻址的节点而非纯文本片段。
• state 通道：当 capsule 携带 state:<flag> 标签，且调用方传入 user_state.context_flags[flag] 为真时，该胶囊所在分区在排序时被整体抬升，从而凌驾于"普通"记忆之上。
• 同分区 tie-break：被抬升的分区内部以词法顺序（lexical tie-break）二次排序，避免引入额外语义开销。
• 无 flag 兜底：若没有任何 state flag 激活，则回退到主题连贯性（thematic coherence）+ state:calm 等默认偏好，保证结果稳定可复现。
• 官方公布的评测显示 15/15 命中率，表明在带状态的查询路径上，state 通道不会被普通记忆淹没。

资料来源：CHANGELOG.md:1-50

四、安全护栏与版本演进

项目把"安全护栏"作为一等公民，与功能演进并行推进：

• Unicode-aware 标签：v0.6.5 修复了非 ASCII 标签（如西里尔字母）首次写入需重试的问题，消除了 pulse_remember 路径上多秒级别的隐式延迟。
• 三组守卫：secret / path / transcript 三个方向的负向烟雾测试持续拒绝 15 种危险负载，覆盖凭据泄露、路径穿越、对话回灌等典型攻击面。
• 可审计变更：所有能力边界与回归修复都通过 CHANGELOG.md 显式记录，方便 Agent 作者判断升级风险。

资料来源：CHANGELOG.md:1-80，AGENTS.md:1-40

五、协作与扩展边界

• AGENTS.md 规定了 AI Agent 协作流程：新增能力需同步更新变更说明与用例，确保记忆语义对所有调用方保持一致。
• llms.txt 为 LLM 消费方提供精简接入说明，使 Pulse 可以作为更大 Agent 栈中的一块"记忆后端"被嵌入。
• 后续演进方向集中于：在保持本地优先与状态可解释性的前提下，进一步提升检索图在跨进程、跨设备场景下的一致性表现。

资料来源：AGENTS.md:1-50，llms.txt:1-40

概述

Pulse 是一个面向 AI 代理的本地优先（local-first）、具备状态感知的记忆引擎。其核心子系统之一 状态感知胶囊检索（State-aware Capsule Retrieval） 随 v0.6.7 引入，负责在检索阶段决定"哪条记忆胜出"。该子系统通过将记忆胶囊（memory capsule）投影到检索图（retrieval graph）并维护一条独立的 状态通道（state channel），使得当用户进入特定情境（如 calm、alert）时，带有 state:<flag> 标签的记忆会优先召回。资料来源：v0.6.7 发布说明。

围绕该通道的还有 连续性包（continuity pack）：一组配套的提升器（booster）文件，覆盖情绪角色（emotion role）、v3 提升逻辑和状态标签提升，使检索不仅"找得到"，还能"找得连贯"。资料来源：pulse-app/internal/retrieve/state.go。

状态通道与标签提升机制

状态通道以 user_state.context_flags 为入口，由 state.go 读取当前生效的上下文标志，并将其传递给 graph_retrieve.go 的排序管线。记忆胶囊若被打上 state:<flag> 标签，便会进入"状态分区"，位于普通记忆之上；当对应 context_flags[flag] 未激活时，这些项目回落到常规排序路径。资料来源：pulse-app/internal/retrieve/state.go、pulse-app/internal/retrieve/graph_retrieve.go。

具体打分动作发生在 state_tag_boost.go：模块按当前 flag 对候选胶囊计算提升值，保证同分区内部仍以词典序（lexical tie-break）作为最终决定。当 context_flags 全部为空时，系统回退到 state:calm + 主题一致性兜底策略，保证始终有一条可解释的胜出路径。资料来源：pulse-app/internal/retrieve/state_tag_boost.go。

胶囊数据结构与图投影

胶囊由 memory_capsule.go 定义，是检索图中的最小节点。每个胶囊持有内容、标签集与时间戳；标签集中允许出现 state:<flag>，该前缀在写入路径已被验证通过 Unicode 字符（v0.6.5 修复非 ASCII 标签首次校验失败的问题）。资料来源：pulse-app/internal/store/memory_capsule.go、v0.6.5 发布说明。

graph_retrieve.go 在构建检索图时将这些胶囊节点连同其标签一并注入，状态通道读取 state:<flag> 标签后，在排序阶段建立状态分区。下列简图描述一次典型召回的数据流：

flowchart LR
  A[memory_capsule.go<br/>胶囊节点] --> B[graph_retrieve.go<br/>检索图投影]
  C[state.go<br/>读取 context_flags] --> D[state_tag_boost.go<br/>标签提升]
  B --> E{状态 flag 激活?}
  D --> E
  E -- 是 --> F[状态分区优先<br/>词典序兜底]
  E -- 否 --> G[常规排序<br/>calm + 主题一致性]

连续性包：v3 提升与情绪角色

连续性包由 v3boosts.go 与 emotion_role.go 共同构成，承担"找得连贯"的职责。v3boosts.go 在 v3 评分模型上叠加主题、时间、近因性等连续性信号；emotion_role.go 进一步将情绪角色（如安抚、提醒）映射为加权因子，使状态通道胜出的胶囊在情绪一致性上更稳定。资料来源：pulse-app/internal/retrieve/v3boosts.go、pulse-app/internal/retrieve/emotion_role.go。

社区证据显示，状态感知胶囊检索在实测中达到 15/15 通过率，说明状态分区与连续性包协同稳定，且保留了原有 secret/path/transcript 守卫（v0.6.5 引入负向烟雾测试拒绝 15 类危险载荷）。资料来源：v0.6.7 发布说明、v0.6.5 发布说明。

总结

状态感知胶囊检索与连续性包是 Pulse 的核心召回管线，由 state.go、state_tag_boost.go、graph_retrieve.go 共同实现状态分区，再由 v3boosts.go、emotion_role.go 保障召回在主题与情绪层面的连续性。该设计让记忆召回既对 context_flags 敏感，又在无 flag 时拥有 state:calm 兜底，是 v0.6.7 的关键能力。资料来源：v0.6.7 发布说明。

Pulse 的存储子系统是整个本地优先（local-first）、状态感知（state-aware）记忆引擎的物理底盘。pulse-app/internal/store 目录下聚合了所有持久化原语——负责把"被记住"的事实、断言、上下文状态、标签与对应的检索图谱落到磁盘上，并在版本升级时平滑演进 schema。本页聚焦于三个紧密耦合的概念：存储层总体职责、Schema 演进机制、以及Material Graph（物化检索图）。

存储层总体职责与分层

存储层对外屏蔽底层 KV/嵌入式数据库的实现细节，对内向上层服务（如 pulse_remember、capsule 检索通路）提供原子写入、状态查询、图谱构建三类能力。store.go 充当门面（facade），把不同子模块聚合起来：

• Memory Capsule 落盘：memory_capsule.go 将每条被记住的记忆压缩为 capsule 结构，写入时同步投影到检索图谱中。
• Material Graph 投影：material_graph.go 维护一张"已落盘即入图"的图结构，使记忆条目在写入瞬间即可被检索通路访问，避免异步索引带来的"写入可见性窗口"问题。
• Schema 版本门控：schema.go 在 Store.Open 路径上检查并按需执行迁移，保证旧版本数据在升级后仍可读取。

flowchart LR
  A[pulse_remember / 写入路径] --> B[store.go<br/>门面]
  B --> C[memory_capsule.go<br/>条目序列化]
  B --> D[material_graph.go<br/>检索图谱]
  B --> E[schema.go<br/>迁移与版本]
  B --> F[claim_resolver.go<br/>冲突/Claim 解析]
  B --> G[assertions.go<br/>不变式断言]
  D --> H[(本地持久化层)]
  E --> H
  C --> H

资料来源：pulse-app/internal/store/store.go:1-120、pulse-app/internal/store/memory_capsule.go:1-80。

Schema 演进与断言门控

随着 Pulse 从 0.6.5 → 0.6.7 的演进，schema 必须容纳 Unicode 标签、state:<flag> 通道等新增字段。schema.go 内部通过版本号 + 迁移函数列表的方式实现轻量演进：每次 Open 时读取持久化层的 schema version，与代码内置版本对比，按差集顺序执行迁移步骤。

要点：

资料来源：pulse-app/internal/store/schema.go:30-95`。

资料来源：pulse-app/internal/store/schema.go:97-140。

资料来源：pulse-app/internal/store/assertions.go:1-60。

1. 版本比对与幂等迁移：迁移函数被设计为幂等，重复执行不会引入重复记录。`
2. Unicode-aware 标签校验：schema.go 在 tag 字段上接受非 ASCII 字符（包含西里尔字母），这正是 v0.6.5 修复"沉默重试"问题的落点——校验逻辑放在 schema 解析早期，避免写入路径重新跑一遍序列化。
3. 断言护栏：assertions.go 在迁移前后注入不变式断言（例如"所有 capsule 必须带有唯一 ID"、"标签集合非空则必须 UTF-8 合法"），失败则中止启动。

社区反馈显示，Unicode 校验回归在 0.6.5 之前曾带来多秒延迟，因此 schema 层现在通过 validate_once 风格设计避免重复校验。

Material Graph：写入即投影的检索图谱

material_graph.go 实现了"material（物化）"语义：胶囊一经写入即被投影到图谱中，使得 pulse_recall 任何时刻查询都能看到最新集合，无需等待后台索引器。

资料来源：pulse-app/internal/store/material_graph.go:50-130。

资料来源：pulse-app/internal/store/material_graph.go:132-180。

• 节点（Node）：每条 capsule 是一个节点，边由标签共现、状态字段共享构造。
• 状态通道（state:<flag>）：v0.6.7 起，凡带 state:<flag> 标签的节点在活跃标志下被提升到单独分区，词法分数仅在分区内作为 tie-break。
• 主题一致性回退：当 user_state.context_flags 中没有激活标志时，节点回到主题（thematic）通道，依靠向量/词的连贯度排序。

Claim 解析与一致性收尾

claim_resolver.go 处理多源声称同一事实时的冲突解决，是 Material Graph 写入流程的最后一步。常见的输入包括：被记忆值与既有 capsule 之间的字段级差异、并发写入留下的 tombstone、以及状态字段切换带来的隐含上下文变更。Claim resolver 在解析后通知 material graph 更新边权重，并返回给上层 pulse_remember 一个明确的响应报文。

资料来源：pulse-app/internal/store/claim_resolver.go:1-110、pulse-app/internal/store/store.go:120-180。

综上所述，存储层把 schema 演进、断言护栏、物化图与 claim 解析四件工作耦合在同一事务边界内落地，使得 Pulse 在保持 local-first 简洁性的同时，仍能支持 Unicode 标签、状态分通道等增量能力——这是 0.6.5 与 0.6.7 两个发布版本共同验证的设计主线。

概述

Pulse 是一个面向 AI 代理的、本地优先（local-first）、状态感知的记忆引擎。当前发布线为 v0.6.7（状态感知胶囊检索）。本页聚焦安装、平台兼容与四类运维入口——doctor 健康自检、demo 演示种子、wipe 数据擦除与 MCP 协议接入——以便用户在选型、部署与排障时建立一致的预期。CLI 由 pulse-app/cli/src/cli.js 暴露，底层 Go 服务在 pulse-app/internal/ 下承载擦除与健康逻辑。资料来源：README.md

安装路径

Pulse 提供三种互不互斥的安装形态，可按使用场景单独或组合部署。

• 本地 CLI 独立安装：直接通过 CLI 二进制使用 pulse_remember 等命令，适合本地原型与脚本化场景。CLI 入口与命令路由位于 pulse-app/cli/src/cli.js。资料来源：pulse-app/cli/src/cli.js
• Agent 嵌入安装：作为 AI 代理的依赖或工具集集成，遵循 docs/INSTALL_WITH_AGENT.md 中描述的代理侧接入步骤。资料来源：docs/INSTALL_WITH_AGENT.md
• 带安全检查的安装：在上述任一路径之外，需按 docs/SECURITY_INSTALL_CHECKLIST.md 完成秘密/路径/转录三类安全守卫（secret/path/transcript guards）的核对；v0.6.5 的负向烟雾测试覆盖了 15 种危险载荷并应全部被拒。资料来源：docs/SECURITY_INSTALL_CHECKLIST.md

兼容性矩阵

下表汇总了 Pulse 当前文档与代码可验证的兼容性边界，仅列出可由仓库文件直接支持的项；空白格表示该组合未在仓库中明示。

运维命令（doctor/demo/wipe/MCP）

doctor — 健康自检

doctor 由 pulse-app/internal/health/fixture.go 提供健康探针实现，供 CLI 调用以校验本地环境与依赖就绪状态。建议在首次安装、升级后或排障前运行。资料来源：pulse-app/internal/health/fixture.go

demo — 演示种子

demo 命令用于在隔离环境中注入演示胶囊，使用户在不污染生产记忆的前提下观察状态感知检索行为；其与 v0.6.7 引入的 state:<flag> 分区机制配合，可演示 state:calm 等典型场景。资料来源：README.md

wipe — 数据擦除

wipe 通过 pulse-app/internal/erase/erase.go 实现本地记忆胶囊与状态上下文的不可逆清理；由于 Pulse 为本地优先设计，擦除操作无需远端协调即可完成，但应与 docs/SECURITY_INSTALL_CHECKLIST.md 一并审计以避免残留。资料来源：pulse-app/internal/erase/erase.go 资料来源：docs/SECURITY_INSTALL_CHECKLIST.md

MCP — 模型上下文协议接入

MCP 命令将 Pulse 的记忆能力以模型上下文协议的形式暴露给上游代理，使代理在调用 pulse_remember 等操作时复用统一的安全守卫与状态通道。该入口在 CLI 中由 pulse-app/cli/src/cli.js 注册。资料来源：pulse-app/cli/src/cli.js

运维流程

flowchart LR
  A[安装] --> B[doctor 自检]
  B --> C{通过?}
  C -- 否 --> X[按 SECURITY_INSTALL_CHECKLIST 修复]
  C -- 是 --> D[demo 验证]
  D --> E[投入运行 / MCP 接入]
  E --> F[wipe 数据擦除]

常见排障要点

• 若 pulse_remember 在非 ASCII 标签上出现多秒级延迟，请确认版本不低于 v0.6.5；旧版本的重试逻辑是已知根因之一。资料来源：README.md
• 检索结果未按预期偏置到 state:<flag> 分组时，应检查 user_state.context_flags 是否正确激活对应 flag。资料来源：README.md
• 任何危险载荷（秘密/路径/转录）若被 doctor 或守卫放行，应立即视为安全回归并对照 15 项负向烟雾测试复测。资料来源：docs/SECURITY_INSTALL_CHECKLIST.md

Pitfall Log / 踩坑日志

项目：zbs-gg/pulse

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

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

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

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

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

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

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

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

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

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

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

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

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

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