前言¶

给 agent 加记忆，常见做法是把历史对话塞进上下文，或者挂一个 RAG 检索。前者受窗口限制，聊长了早期的约定和偏好就被挤出；后者能捞回原文，但捞回来的是「说过什么」，不是「agent 该记住什么」。Agent 还会反复写下同一件事、把过期偏好当成现状用，记忆库里的噪声随时间累积。

下面介绍的这个 Skill 处理的是后一个问题：它不是一套检索插件，而是把开源记忆系统 Hindsight 的方法论整理成一份可直接落地的心智模型和行为指令集，让 agent 在写代码或跑任务时自己决定记什么、何时存、何时取、何时合并、何时作废。

这是什么¶

Hindsight Agent Memory 是一个基于通用 SKILL.md 格式的 Skill，坐标 @user_1a99cb00/hindsight-agent-memory，版本 1.0.0，来源为 community，分类 ai-agent，标签为 requires_api_key=false。它面向的运行时是 Marvis（此信息来自 Skill 简介；SkillHub 页面在本次写作时无法访问，未能二次核对）。

它背后的 Hindsight 是 vectorize-io 开源的 agent 记忆系统，MIT 协议，仓库在 github.com/vectorize-io/hindsight。官方 README 称其在 LongMemEval 基准上达到了 SOTA；Skill 简介额外给出的表述是「BEAM 10M-token 级和 LongMemEval 基准上均为 SOTA」「19k+ stars」，这两点我只在 Skill 简介中见到，未在可访问的官方页面上核对到（Hindsight 官方文档站点头部显示的是 56.1k）。

Skill 解决的是：把 Hindsight 的记忆方法论从「系统能力」翻译成「agent 的行为约束」，让 agent 在执行任务时主动调用记忆相关动作，而不是等用户问起才去翻历史。

三层结构¶

Skill 的内容分成三层，自下而上是方法论、行为指令、MCP 桥接。

方法论层¶

这一层定义了 agent 脑子里的记忆长什么样、怎么读写。

记忆分四类：world facts（世界事实）、experiences（经验）、entity summaries（实体摘要）、beliefs（信念）。区别在于抽象层级——事实是单条可验证的陈述，经验是做过的事，实体摘要是对某个对象的归并，信念是 agent 持有但未必有证据支撑的判断。

核心操作有三个：

Retain：从当前交互中提取事实并存入。
Recall：检索已有记忆，Skill 中使用 TEMPR 混合召回。
Reflect：跨多条记忆做综合推理，得到单一答案。

记忆有生命周期：observation → validation → consolidation → invalidation。新观察到的内容先作为 observation 存在，经过验证后纳入正式记忆，累积到一定程度固化为更概括的知识，与现实冲突时被作废。这条链路的作用是给「什么时候清理记忆」一个明确依据，而不是让记忆无限增长。

行为指令层¶

这一层是 agent 在任务中可以直接使用的宏指令，据 Skill 简介：

@RETAIN：单条事实存入。
@RECALL：记忆检索。
@REFLECT：跨记忆综合。
@CONSOLIDATE：知识固化。
@SCAN：记忆健康度巡检。

@SCAN 对应上面的生命周期——定期检查记忆库里有没有过期项、重复项、互相矛盾的项，然后决定合并或作废。

MCP 桥接层¶

这一层解决 agent 怎么真正调用 Hindsight。Skill 提供 Docker 部署指南，以及用 Marvis 的 invoke_mcp_tool 对接 Hindsight MCP Server 的方式；Hindsight 的 MCP Server 提供 30 个工具。

部署 Hindsight 服务端¶

Skill 只承担方法论和行为指令，记忆的存储和推理由 Hindsight 服务端负责。所以先起服务，再让 agent 连上去。官方推荐 Docker：

export OPENAI_API_KEY=sk-xxx

docker run -it --pull always --name hindsight --restart unless-stopped -p 8888:8888 -p 9999:9999 \
  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
  -v hindsight-data:/home/hindsight/.pg0 \
  ghcr.io/vectorize-io/hindsight:latest

这一步在本地起 Hindsight，8888 是 API 端口，9999 是 UI 端口，数据落在名为 hindsight-data 的卷里。LLM 供应商通过 HINDSIGHT_API_LLM_PROVIDER 指定，官方支持 25 种以上，包括 openai、anthropic、gemini、groq、bedrock、vertexai、deepseek，以及本地的 ollama、lmstudio、llamacpp，和不需要额外 API key 的 openai-codex、claude-code、cursor、github-copilot 等订阅方式。

也有别的部署路径，按需选：

# 裸机
pip install hindsight-api
export HINDSIGHT_API_LLM_API_KEY=sk-xxx
hindsight-api

# Kubernetes
helm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight \
  --set api.llm.provider=openai \
  --set api.llm.apiKey=sk-xxx \
  --set postgresql.enabled=true

此外官方还提供 Docker + 外部 PostgreSQL、Oracle AI Database（企业部署）和 Hindsight Cloud（托管，客户端直接指向 https://api.hindsight.vectorize.io）。

让 agent 通过 MCP 接上¶

Hindsight 的 MCP Server 默认启用，挂在 API 服务的 /mcp 上，每个 memory bank 有自己的端点：

http://localhost:8888/mcp/{bank_id}/

例如连到 bank alice，就是 http://localhost:8888/mcp/alice/。bank 的优先级是：URL 路径最高，其次 X-Bank-Id 请求头，最后是环境变量 HINDSIGHT_MCP_BANK_ID（默认 default）。

下面是 Claude Code 的接法（Marvis 侧的 invoke_mcp_tool 对接逻辑见 Skill 内文档，本次未能核对到原文）：

claude mcp add --transport http hindsight http://localhost:8888/mcp \
  --header "Authorization: Bearer your-secret-key" \
  --header "X-Bank-Id: my-bank"

Claude Desktop 写进 ~/.claude_desktop_config.json：

{
  "mcpServers": {
    "hindsight": {
      "url": "http://localhost:8888/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-key",
        "X-Bank-Id": "my-bank"
      }
    }
  }
}

默认情况下 MCP 端点是开放访问的。要加鉴权，启用 API key tenant 扩展：

export HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension
export HINDSIGHT_API_TENANT_API_KEY=your-secret-key

关闭 MCP 用 export HINDSIGHT_API_MCP_ENABLED=false。想让客户端在工具描述里看到部署侧规则（比如该打什么 tag），设置 HINDSIGHT_API_MCP_INSTRUCTIONS。

工具数量与两种模式¶

Hindsight 的 MCP 工具数量取决于连的是哪个 URL，官方文档写得很明确：

单 bank 模式（/mcp/{bank_id}/）：27 个工具，覆盖 memory、mental models、directives、documents、operations、tags、bank 管理。bank 由 URL 隐式确定，工具签名里不再有 bank_id 参数。这是官方推荐模式，因为它把每次调用隔离在一个 bank 内。
多 bank 模式（/mcp）：30 个工具，额外提供 list_banks、create_bank、get_bank_stats，每个工具带可选的 bank_id 参数。

Skill 简介里说的「30 个工具」对应的是多 bank 模式。

工具的只读/破坏性标记是：recall、reflect、list_*、get_* 标 readOnlyHint: true；删除、清空、作废类操作标 destructiveHint: true；内置工具 openWorldHint 为 false，因为它们操作的是本地记忆库而不是公网。

典型用法¶

直接调 Python 客户端，三步对应 Retain / Recall / Reflect：

from hindsight_client import Hindsight

client = Hindsight(base_url="http://localhost:8888")

# Retain：存入信息
client.retain(bank_id="my-bank", content="Alice works at Google as a software engineer")

# Recall：检索记忆
client.recall(bank_id="my-bank", query="What does Alice do?")

# Reflect：综合生成带倾向性的回答
client.reflect(bank_id="my-bank", query="Tell me about Alice")

客户端装法：pip install hindsight-client -U（Python）、npm install @vectorize-io/hindsight-client（Node.js/TypeScript）、go get github.com/vectorize-io/hindsight/hindsight-clients/go（Go），还有官方 CLI。

通过 MCP 走 retain，参数如下（这是官方文档的示例）：

{
  "name": "retain",
  "arguments": {
    "content": "User prefers Python over JavaScript for backend development",
    "context": "programming_preferences",
    "tags": ["user:alice", "preferences"]
  }
}

content 必填，context、timestamp（ISO 8601）、tags、metadata、document_id 可选。官方列出的适用场景是：用户说出个人事实、偏好、兴趣；提到重要事件或里程碑；陈述决策、观点、目标；讨论工作上下文或项目细节。还有 sync_retain，与异步的 retain 区别是它会阻塞到写入完成，适合写完立刻要读的场景。

在 Marvis 里，Skill 期望的调用方式是让 agent 用 @RETAIN、@RECALL、@REFLECT、@CONSOLIDATE、@SCAN 这些宏指令驱动上述 MCP 工具——也就是由 agent 判断此刻该走哪个动作，再落到对应的工具调用上。这一部分的行为细节我无法从可访问的页面核对，只据 Skill 简介描述。

适用场景与注意¶

适合的场景：需要跨多次会话维持用户画像、项目约定、决策理由的长期任务型 agent；以及希望 agent 主动整理记忆而不是被动检索的场景。@SCAN 和 consolidation 链路在这类场景里价值最高，因为记忆会随时间膨胀。

几个需要注意的地方：

要自己起服务。Skill 不含存储和推理能力，Hindsight 服务端（Docker、pip 或 Cloud）是硬依赖。requires_api_key=false 指的是 Skill 本身，LLM 侧的 key 仍然需要按部署方式配置。
先想清楚 bank 划分。单 bank 模式下端点与 bank 绑定，隔离性最好；多 bank 模式才提供 bank 管理工具。划分方案一旦定了再改，历史记忆要迁移。
默认无鉴权。MCP 端点在未配置 tenant 扩展时是开放的，内网以外暴露前要启用 API key。
需要 LLM 参与写入。Retain 和 Reflect 依赖配置的模型，选用本地模型时留意召回质量。
工具数量要看模式。排查「为什么少了三个工具」时，先确认连的是 /mcp 还是 /mcp/{bank_id}/。

结尾¶

这个 Skill 的价值不在检索精度，而在把记忆的决策权交给 agent：记什么、何时合并、何时作废，都有对应的动作和生命周期阶段可依。配合 Hindsight 的四类记忆和三个核心操作，agent 的记忆从「对话日志」变成可维护的知识结构。

官方地址：https://api.skillhub.cn/user_1a99cb00/hindsight-agent-memory

补充说明：SkillHub 页面与 API 在本次写作时均抓取失败，上文中关于 Skill 的坐标、版本、评分、下载量、宏指令集与三层结构的描述来自预先抓取的资料，评分 100000、下载 2487、安装 0；Hindsight 本身的部署命令、MCP 工具清单和 benchmark 表述来自其 GitHub README 与官方文档站点。

Hindsight Agent Memory：把 agent 记忆从「记住对话」变成「学会」

前言¶

这是什么¶

三层结构¶

方法论层¶

行为指令层¶

MCP 桥接层¶

部署 Hindsight 服务端¶

让 agent 通过 MCP 接上¶

工具数量与两种模式¶

典型用法¶

适用场景与注意¶

结尾¶

精选优惠券

Hindsight Agent Memory：把 agent 记忆从「记住对话」变成「学会」

前言¶

这是什么¶

三层结构¶

方法论层¶

行为指令层¶

MCP 桥接层¶

部署 Hindsight 服务端¶

让 agent 通过 MCP 接上¶

工具数量与两种模式¶

典型用法¶

适用场景与注意¶

结尾¶

精选优惠券

相關文章