企业官网建设流程全解析

Hindsight Cloud 记忆技能实战：为编码 Agent 配置团队共享记忆库

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight

本文围绕 Hindsight 项目的hindsight-cloud技能文档（skills/hindsight-cloud/SKILL.md），完整讲解如何为 Claude Code、Cursor、Copilot 等编码 Agent 接入Hindsight Cloud托管记忆服务：从首次配置hindsightCLI、理解服务端记忆管道，到使用memory retain/memory recall/memory reflect三个核心命令沉淀与检索团队知识。读完本文，你将掌握一套可落地的"何时存、存什么、何时取"的 Agent 记忆工作流，并理解其背后的源码实现原理。

一、Hindsight Cloud 技能是什么

hindsight-cloud技能是注入到编码 Agent（如 Claude Code、Cursor、Copilot CLI 等）系统提示中的一份操作手册，声明了 Agent 具备经由Hindsight Cloud提供的持久记忆能力。与本地版技能（见 skills/hindsight-local/SKILL.md，基于hindsight-embed）不同，Cloud 版的关键差异在于：

• 记忆存储在后端的Hindsight Cloud 服务（api.hindsight.vectorize.io），而非本地；
• 该记忆库是与团队共享的——任何人在这个代码库上工作时存入的知识，都能被团队其他成员、其他 Agent 会话检索到；
• Agent 的职责被明确为：主动存储团队知识、在任务开始前回忆上下文，从而提供更好的协助。

技能文档的核心观点是：Agent 不需要自己"总结"后再存，而是应该把完整的、富含上下文的原始内容直接交给服务端，由服务端负责提炼。

二、首次配置：连接 Hindsight Cloud

技能文档要求在首次使用记忆命令前，先验证 CLI 是否已配置：

cat ~/.hindsight/config

如果文件不存在或缺少凭据，按以下三步完成设置。

1. 安装 CLI

若hindsight命令不存在，通过官方安装脚本安装：

curl -fsSL https://hindsight.vectorize.io/get-cli | bash

提示：本仓库内也包含该 CLI 的完整 Rust 源码（hindsight-cli），核心入口在 hindsight-cli/src/main.rs，可通过 Cargo 自行构建。

2. 创建配置文件

向用户获取其API Key（在 Hindsight Cloud 控制台生成），然后写入配置文件：

mkdir -p ~/.hindsight cat > ~/.hindsight/config << 'EOF' api_url = "https://api.hindsight.vectorize.io" api_key = "<user's API key>" EOF chmod 600 ~/.hindsight/config

chmod 600用于收紧文件权限，防止 API Key 泄露。

3. 获取 Bank ID

向用户获取其团队的bank ID（例如team-myproject）。后续所有命令都要携带该 ID。

配置加载优先级（源码级验证）

从 CLI 源码看，配置并非只能写在~/.hindsight/config一个地方。在 hindsight-cli/src/config.rs 中，Config::load_with_profile实现了四级优先级：

1. 环境变量（HINDSIGHT_API_URL/HINDSIGHT_API_KEY）——优先级最高；
2. 命名 profile（-p参数或$HINDSIGHT_PROFILE指定，存放在~/.hindsight/cli-profiles/<name>.toml），可通过hindsight profile create <name> --api-url <url> [--api-key <key>]管理；
3. 本地配置文件~/.hindsight/config（即本文上述步骤写入的文件）；
4. 默认值http://localhost:8888（指向本地自托管服务）。

同时validate_and_create会校验api_url必须以http://或https://开头，否则报错。技能文档中的配置步骤正是第 3 级；若你的团队同时维护多个 Hindsight 环境（如 dev/prod），使用-pprofile 或环境变量会是更灵活的方式。

三、Hindsight 的工作原理：retain 之后发生了什么

技能文档明确指出：调用retain时，Hindsight不会原样存储字符串，服务端会运行一条内部管道：

1. 用 LLM 提取结构化事实（extracts structured facts）；
2. 识别实体（人、工具、概念）并关联相关事实；
3. 构建事实之间的时间与因果关系；
4. 生成嵌入向量用于语义检索。

因此，你应该传入丰富、完整的上下文内容——服务端比你更擅长从原文中抽取要点。你的职责是决定何时存储，而不是提取什么。

更深一层：事实类型与实体链接

在仓库文档 hindsight-docs/docs/developer/retain.md 中可以找到这条管道的更多细节：每个事实会被归类为experience（银行 Agent 自身的第一人称历史，如 "I recommended Python to Alice"）或world（关于外部世界的事实，如 "Alice works at Google"）。分类依据是"谁在说话"，而不是语法——用户对 Agent 说的 "I bought a Tesla" 是关于用户的world事实。技能文档中--context标志（如procedures、learnings、preferences）正是用于标注内容来源与归属，帮助服务端正确归类。

实体识别方面，retain 管道会自动识别人物、组织、地点、产品与概念，并通过模糊名称匹配与共现关系做实体消歧（"Alice" + "Alice Chen" → 同一人）。所有提到同一实体的事实会被链接在一起，形成知识图谱；recall 时可借此回答 "Tell me everything about Alice" 这类跨会话问题。

四、核心命令详解

技能文档要求将<bank-id>替换为实际的团队 bank ID（例如team-frontend）。以下命令均通过hindsightCLI 执行。

4.1 存储记忆：memory retain

用memory retain存储学到的内容，传入完整上下文——原始观察、会话笔记或详细描述：

hindsight memory retain <bank-id> "The project uses ESLint configured with the Airbnb rule set and Prettier for formatting. Auto-fix on save is enabled in the editor config." hindsight memory retain <bank-id> "Ran the test suite with NODE_ENV=test. Tests pass. Without NODE_ENV=test, the suite fails with a missing config error." --context procedures hindsight memory retain <bank-id> "Build failed on Node 18 with error 'ERR_UNSUPPORTED_ESM_URL_SCHEME'. Switched to Node 20 and build succeeded." --context learnings hindsight memory retain <bank-id> "Alice reviewed the PR and asked for verbose commit messages that explain the motivation, not just what changed." --context preferences

也可以直接传入带时间戳的原始对话记录（适合把一次排障过程整体沉淀下来）：

hindsight memory retain <bank-id> "[2026-03-16T10:12:03] User: The auth tests keep failing on CI but pass locally. Any idea? [2026-03-16T10:12:45] Assistant: Let me check the CI logs. Looks like the tests are running without the TEST_DATABASE_URL env var set — they fall back to the production DB URL and hit a connection timeout. [2026-03-16T10:13:20] User: Ah right, I never added that to the CI secrets. Adding it now. [2026-03-16T10:15:02] User: That fixed it. All green now." --context learnings

CLI 参数说明（依据 hindsight-cli/src/main.rs 中MemoryCommands::Retain的定义）：

在实现层（hindsight-cli/src/commands/memory.rs），retain将内容封装为MemoryItem并调用服务端retain接口；异步模式下会返回 "queued for background processing" 状态，后续可通过hindsight operation系列命令查询处理进度。

4.2 回忆记忆：memory recall

在开始任务之前使用memory recall获取相关上下文：

hindsight memory recall <bank-id> "project conventions and coding standards" hindsight memory recall <bank-id> "Alice preferences for this project" hindsight memory recall <bank-id> "what issues have we encountered before" hindsight memory recall <bank-id> "how does the auth module work"

recall是语义搜索，而非关键字匹配。根据 hindsight-docs/docs/developer/retrieval.md，recall 会并行运行多种检索策略（语义向量搜索、BM25 全文检索、知识图谱遍历、时间扩散等）。CLI 暴露的常用参数包括：

• -t, --fact-type：限定检索的事实类型（world、experience、observation，默认全部）；
• -b, --budget：思考预算low/mid/high，控制搜索深度（每种级别映射为一个 recall budget 数值，贯穿语义搜索LIMIT、图遍历节点数等管道阶段，默认mid）；
• --max-tokens：结果最大 token 数（默认 4096）；
• --trace：显示检索过程追踪信息，便于调试为何召回某些结果；
• --include-chunks：结果中附带原始内容分块（--chunk-max-tokens控制分块 token 上限，默认 8192）；
• --tags/--tags-match：按标签过滤，匹配模式支持any、all、any_strict、all_strict；
• --query-timestamp：参考时间点（ISO 8601），用于时间敏感查询；
• --prefer-observations：优先返回整合后的 observation 而非原始事实；
• --window-start/--window-end：限定搜索的时间窗口（注意：源码中两者必须成对提供，单独给一端会直接报错，且结束时间不得早于开始时间，见 hindsight-cli/src/commands/memory.rs 及对应单元测试）。

4.3 反思综合：memory reflect

用memory reflect让服务端基于已存记忆综合生成回答，适用于"基于过去经验我该如何做"这类需要推理的问题：

hindsight memory reflect <bank-id> "How should I approach this task based on past experience?"

reflect与recall的区别在于：recall返回相关记忆片段，reflect则调用 LLM 以该 bank 的"身份与倾向"（disposition）进行推理综合，产生一段可直接用于决策的答案。CLI 还支持-c, --context附加上下文、-s, --schema指定 JSON Schema 以输出结构化结果、--include-facts在回答中附带来源事实、--exclude-mental-models排除该 bank 的心理模型等选项。

4.4 配套管理命令

技能文档聚焦 retain/recall/reflect 三个命令，但完整 CLI 还提供记忆管理能力（见 hindsight-cli/src/main.rs 的MemoryCommands枚举）：

• hindsight memory list <bank-id>：分页列出记忆单元（-t按事实类型过滤、-q全文搜索、-l/-s分页）；
• hindsight memory get <bank-id> <memory-id>：查看单条记忆详情（含类型、实体、标签、时间范围）；
• hindsight memory delete <bank-id> <unit-id>：删除单条记忆；
• hindsight memory clear <bank-id> [-t world|experience|observation]：按类型或全部清空（交互式确认）；
• hindsight memory retain-files <bank-id> <path>：批量导入文件（pdf、docx、pptx、xlsx、图片 OCR、html、txt、md、csv、mp3 等格式，支持-r递归、每批 10 个文件、--async异步处理，详见 hindsight-cli/src/commands/memory.rs 的retain_files实现）。

五、何时存储记忆（团队视角）

技能文档强调这是共享团队库：只存对团队有价值的知识；个人偏好需标注人名归属。建议存储的五类内容：

项目/团队约定（共享）

• 编码规范（"Project uses 2-space indentation"）；
• 必需工具与版本（"Project requires Node 20+, PostgreSQL 15+"）；
• Lint 与格式化规则（"ESLint with Airbnb config"）；
• 测试约定（"Integration tests require Docker running"）；
• 分支命名与 PR 规范。

个人偏好（标注归属人）

• 个人编码风格（"Alice prefers explicit type annotations"）；
• 沟通偏好（"Bob prefers detailed PR descriptions"）；
• 工具偏好（"Carol uses vim keybindings"）。

过程结果

• 成功完成任务的步骤；
• 有效（或失败）的命令及原因；
• 发现的 workaround；
• 解决过问题的配置。

任务学习

• 遇到的 Bug 及解决方案；
• 有效的性能优化；
• 架构决策及理由；
• 依赖或版本要求。

团队知识

• 新成员 onboarding 信息；
• 常见坑与规避方法；
• 架构决策及其理由；
• 与外部系统的集成点；
• 领域知识与业务逻辑说明。

六、何时回忆记忆

技能文档明确要求：在以下场景务必先 recall：

• 开始任何非平凡任务之前；
• 做出实现相关决策之前；
• 建议工具、库或方案之前；
• 在新领域写代码之前；
• 回答关于代码库的问题时；
• 团队成员询问某个功能如何工作时。

这背后的思路是：Hindsight 的价值在于把过去的排障经验、项目约定、团队偏好"带进"新会话，让每个 Agent 会话都不必从零开始探索代码库。

七、最佳实践清单

技能文档给出了 8 条可操作的最佳实践，整理如下：

1. 立即存储：发现值得记的内容立刻存入，不要等任务结束；
2. 传入丰富上下文：传完整观察而非预总结字符串——服务端会自动抽取事实；
3. 包含结果：存"发生了什么 AND 为什么"，包括失败与 workaround；
4. 先回忆：开始工作前总是先检查相关上下文；
5. 团队优先：存对团队其他成员有帮助的知识；
6. 个人偏好标注归属：存 "Alice reviewed the PR and asked for X"，而不是笼统的 "User prefers X"；
7. 区分项目与个人：项目约定适用于所有人，个人偏好按人归属；
8. 用--context标注元数据：--context标志标记记忆类型（如procedures、learnings、preferences），它不是完整内容的替代品。

八、小结

Hindsight Cloud 技能的本质，是把"团队记忆"从个人笔记升级为 Agent 可自动读写的基础设施：服务端负责从原始内容中抽取事实、识别实体、构建时间与因果关联并生成语义向量；Agent 只需在正确的时机调用memory retain存入完整上下文，在任务开始前用memory recall/memory reflect取回相关知识。结合本仓库中 hindsight-cli 的源码（配置优先级、命令参数、异步处理）与 hindsight-docs/docs/developer/retain.md、hindsight-docs/docs/developer/retrieval.md 的管道说明，你可以清楚地看到从一条 CLI 命令到结构化知识图谱的完整链路，并据此设计出适合自己团队的 Agent 记忆工作流。

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight