Hindsight Memories API 实战指南列出、读取与策展记忆单元【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读在 Hindsight 中memory unit记忆单元是从文档中抽取并存储的最小原子事实也是整个记忆系统对外暴露的核心数据对象。本文基于仓库文档skills/hindsight-docs/references/developer/api/memories.md结合服务端实现hindsight-api-slim/hindsight_api/api/http.py 与 hindsight-api-slim/hindsight_api/engine/memories/pg/与 CLI 源码系统讲解记忆单元的读取、列表、观察历史与策展编辑、失效、恢复五类端点让你掌握何时该改 mission、何时该编辑、何时该失效的完整策展决策链并能直接用 REST、Node.js 或 CLI 对单个记忆单元做审计与修正。什么是 memory unitmemory unit是 Hindsight 抽取并存储的原子事实拥有三种fact_typeworld关于人、地点、事件、事物的一般性知识experience关于经历、对话、已执行操作与任务的经验类记忆observation由world/experience事实经 consolidation 综合得出的派生观察。每个记忆单元还携带statevalid|invalidated、元数据、实体、发生日期对于被用户编辑过的事实还会带一个edited_at时间戳控制平面中以Edited徽标呈现。记忆的摄入ingest与查询recall分别由 Retain 与 Recall 负责本文聚焦单个记忆单元层面的操作。端点总览MethodEndpoint用途GET/v1/default/banks/{bank}/memories/list列出/过滤某个 bank 中的记忆单元GET/v1/default/banks/{bank}/memories/{id}获取单个记忆单元GET/v1/default/banks/{bank}/memories/{id}/history派生观察observation的刷新历史PATCH/v1/default/banks/{bank}/memories/{id}策展编辑 / 失效 / 恢复DELETE/v1/default/banks/{bank}/memories/{id}/observations清空某记忆的派生观察这五个路由在 api/http.py 中均有对应实现api_listL5323、api_get_memoryL5530、api_get_observation_historyL5618、api_update_memoryL5562与api_clear_memory_observationsL8516operation_id 分别为list_memories、get_memory、get_observation_history、update_memory、clear_memory_observations。URL 前缀统一为v1/default/banks/{bank_id}其中default是命名空间实际路径与hindsight-all/hindsight/api_namespaces.py中的命名空间配置一致。列出记忆单元列表端点返回每个单元的fact_type、state、元数据、实体、发生日期以及被编辑事实的edited_at时间戳。已失效invalidated的行默认也被包含以保证策展操作可审计如需过滤请使用state参数。查询参数参数说明type按事实类型过滤world/experience/observationq对 text 与 context 做全文搜索statevalid/invalidated指定后不再默认混入归档行document_id过滤到单个来源文档entity_id精确反查返回与给定实体关联的记忆单元基于存储的实体链接不是文本或语义匹配。由于只有活跃单元存在实体链接entity_id与stateinvalidated组合会返回空consolidation_state对 source 记忆world/experience按 consolidation 状态过滤取值为failed/pending/donetags按标签过滤可传多个tags_match标签组合方式anyOR默认含未打标签项、allAND含未打标签项、any_strict/all_strict排除未打标签项、exact标签集合完全一致limit/offset分页limit默认 100结果按最近优先排序mentioned_at DESC其次created_at DESC见 http.py 的接口描述。entity_id的典型用法是直接列出某实体的证据例如用typeobservation拉取它的观察而不必扫描全部记忆——这正是精确反查实体链接比语义搜索更高效的原因。Python# 列出 bank 中的记忆单元默认包含 invalidated 行 resp client.list_memories(BANK_ID) for unit in resp[items]: print(f- [{unit[fact_type]}] {unit[text]}) # 只列出已失效的事实例如用于复查重复项 invalidated client.list_memories(BANK_ID, stateinvalidated) print(f{len(invalidated[items])} invalidated fact(s)) # 精确反查某实体的观察证据 obs client.list_memories(BANK_ID, entity_idENTITY_ID, typeobservation)仓库在 hindsight-clients/python 与 hindsight-clients/go 提供官方客户端hindsight-cli/src/api.rs 中的list_memories同样调用该端点。Node.js// 列出 bank 中的记忆单元。默认包含 invalidated 行。 const memories await client.listMemories(BANK_ID); for (const unit of memories.items) { console.log(- [${unit.fact_type}] ${unit.text}); } // 过滤出已失效的事实例如用于复查重复项。 const invalidated await client.listMemories(BANK_ID, { state: invalidated }); console.log(${invalidated.items.length} invalidated fact(s));CLI# 列出 bank 中的记忆单元默认包含 invalidated 行 hindsight memory list $BANK_ID # 过滤出已失效的事实 curl -s $HINDSIGHT_URL/v1/default/banks/$BANK_ID/memories/list?stateinvalidated # 组合过滤某文档下的 experience 事实且只取 50 条 curl -s $HINDSIGHT_URL/v1/default/banks/$BANK_ID/memories/list?typeexperiencedocument_id$DOC_IDlimit50Gomemories, err : client.ListMemories(ctx, BANK_ID, api.ListMemoriesParams{ State: api.Ptr(invalidated), }) for _, unit : range memories.Items { fmt.Printf(- [%s] %s\n, unit.FactType, unit.Text) }实现细节失效行来自归档表从源码看state过滤不是加一个谓词而是切换读取的表。在 memories/pg/curation.py 中# Invalidated facts live in a separate archive table; pick the source # table accordingly. is_archived state invalidated source_table fq_table(invalidated_memory_units) if is_archived else fq_table(memory_units)因此stateinvalidated时直接读invalidated_memory_units归档表并额外返回invalidation_reason与invalidated_at两条归档簿记字段活动表则返回NULL。get_memory_unit读取单个单元也遵循同一策略先查活动表memory_units未命中再回退到归档表因此即使一条事实已被失效你仍能通过 ID 读到它及其失效原因。获取单个记忆单元GET /v1/default/banks/{bank}/memories/{id}返回单个记忆单元的完整内容文本、元数据、实体、时间戳、标签与策展状态。若 ID 不存在返回404 Memory unit {id} not found见 http.py。// 获取单个记忆单元元数据、实体、日期、状态。 const memory await ( await fetch(${HINDSIGHT_URL}/v1/default/banks/${BANK_ID}/memories/${memoryId}) ).json(); console.log(Text: ${memory.text}); console.log(Type: ${memory.type} Entities: ${memory.entities});curl -s $HINDSIGHT_URL/v1/default/banks/$BANK_ID/memories/$MEMORY_ID | jq .顺带说明该端点的响应中history字段已废弃始终返回空列表请改用GET /memories/{id}/history见 http.py 的接口注释。查看派生观察的刷新历史GET /v1/default/banks/{bank}/memories/{id}/history仅对**派生观察observation**有意义它返回该观察随新源事实不断到达、被反复刷新的完整历史并把每次变化涉及的 source 事实解析为可读文本。curl -s $HINDSIGHT_URL/v1/default/banks/$BANK_ID/memories/$OBSERVATION_ID/history | jq .策展编辑、失效与清理记忆系统设计上是 append-only只追加但事实可能错误、过时或重复。策展让你在保留完整审计轨迹的前提下修正或退役单个记忆。被退役的事实会移出活跃集合recall 永远不会返回它但它仍可完整恢复。先想清楚该用哪把工具不是所有坏记忆都需要同一个手段先判断它为什么坏记忆的问题是…用为什么整库抽取系统性出错如主体始终抽错修 bank 的retain_mission/observations_mission然后reprocess该文档系统性问题最好在源头修复后重放见 Retain一次性抽取错误单个误抽取事实**编辑Edit**该记忆修正事实并重新生成其全部派生内容不再为真、且没有替代物服务器退役、工具已修复、角色已变更**失效Invalidate**该记忆管道中没有任何环节知道世界变了必须由你显式告知重复或被取代的事实**失效Invalidate**该记忆在保留审计轨迹的同时从 recall 中消除噪音被新事实取代、而你本来就会存新事实如喜欢 BMW→喜欢 Toyota直接 retain 新事实即可consolidation 已经会在流内把矛盾整合成单一观察经验法则Hindsight 自己可能知道的事交给 consolidation只有你知道的事才需要策展。原文if Hindsight could have known, let consolidation handle it; if only you know, curate it.哪些记忆可以被策展只有原始world与experience事实可以被策展。观察是派生数据——它们会从源事实重新生成因此你策展的是底层事实而非观察本身对一个 observation 发起PATCH会返回400。这一约束同时写在请求模型与路由描述中Only world/experience facts can be curated; observations are derived.见 http.py。编辑一个记忆修正 LLM 抽取出的错误。你可以改text、context、发生日期、fact_type与entities——任何抽取器可能搞错的字段。Hindsight 会重新为事实生成 embedding丢弃旧版本派生的观察与链接重新运行 consolidation让下游知识反映修正。编辑后的事实带edited_at时间戳控制平面显示Edited徽标。修正事实绝不会丢弃它参与的因果cause-and-effect关系——这些关系来自对原始来源的阅读编辑或一次失效/恢复往返会原样保留它们而不是丢掉无法重建的链接。你也不需要自己重建任何东西编辑会自动在后台重算知识图谱与链接。事实的实体关联会依据新的 text/entities 重新解析时间与语义链接重新派生consolidation 重新运行——全部由编辑触发。PATCH 在变更提交后立即返回图谱/观察的重建在其后异步进行。// 修正事实文本。会重新 embedding、丢弃派生观察/链接、 // 重新 consolidation并自动重算图谱。 await patchMemory(memoryId, { text: The user visited Paris in 2023., reason: wrong subject });curl -X PATCH $HINDSIGHT_URL/v1/default/banks/$BANK_ID/memories/$MEMORY_ID \ -H Content-Type: application/json \ -d {text: The user visited Paris in 2023., reason: wrong subject}日期、事实类型与实体可用同样的方式修正对context、occurred_start、occurred_end传空字符串清空该字段省略则保持不变对entities传入列表会整体替换事实的实体集合[]表示全部解除关联省略则保持不变。// 一次调用同时修正日期、事实类型与实体。 // 清空字段entities 整体替换[] 解除全部省略表示不变。 // resolve_entities: false 保证你写的实体名不会被匹配到已有相似实体上。 await patchMemory(memoryId, { occurred_start: 2023-06-01, fact_type: experience, entities: [Alice, Paris], resolve_entities: false, });curl -X PATCH $HINDSIGHT_URL/v1/default/banks/$BANK_ID/memories/$MEMORY_ID \ -H Content-Type: application/json \ -d {occurred_start: 2023-06-01, fact_type: experience, entities: [Alice, Paris], resolve_entities: false}从请求模型 UpdateMemoryRequest 可以看到完整字段校验逻辑请求至少需包含一个待更新字段text/context/occurred_start/occurred_end/fact_type/entities/statestate只能是valid或invalidatedfact_type只能是world或experience同时把occurred_start/occurred_end显式传null也会被转换为以表示清空见 http.py。实体名解析resolve_entitiesresolve_entities控制entities中的名字如何与 bank 内的实体匹配取值行为true默认与 retain 一致。每个名字都会对照 bank 内已有实体解析与你传入的其他名字共现强度越高、名字相似度越接近就越可能归并到已有实体false名字按字面处理。只有大小写不敏感完全匹配才复用已有实体其余名字一律新建实体同一请求内的名字彼此绝不合并手工修正事实时请传false。开启解析时一个与 bank 内已有实体相近的名字可能被匹配到那个邻居而不是你指定的实体——例如Dr. Waller被归到拼写错误的Dr WallAlice Smith被归到Alice——而由于编辑本身成功返回这种替换在响应中并不显眼。解析适合抽取产生的名字拼写多变、bank 已有实体通常就是本意当你已经明确知道想要哪个实体时它反而是错的。默认保持true以不影响既有调用方。同一标志也存在于 retain 端点的 entities 参数上。失效一个记忆可逆软退役一条事实。失效后该记忆从 recall、consolidation 与知识图谱中消失链接被剪除派生观察在不含它的前提下重新计算因果关系到别保存恢复时原样回来仍保留在 bank 中用于审计通过记忆视图与文档视图可见可以随时恢复。// 软退役从 recall/consolidation/graph 移除剪除链接 // 重算派生观察——但保留用于审计。 await patchMemory(memoryId, { state: invalidated, reason: server decommissioned 2026-06-01 });curl -X PATCH $HINDSIGHT_URL/v1/default/banks/$BANK_ID/memories/$MEMORY_ID \ -H Content-Type: application/json \ -d {state: invalidated, reason: server decommissioned 2026-06-01}恢复则把事实移回活跃集合、带回它参与的因果链并重新运行 consolidation// 恢复一条此前被失效的事实。 await patchMemory(memoryId, { state: valid });curl -X PATCH $HINDSIGHT_URL/v1/default/banks/$BANK_ID/memories/$MEMORY_ID \ -H Content-Type: application/json \ -d {state: valid}失效/恢复的底层实现移动而非打标文档明确invalidatingmovesthe row out of the activememory_unitstable into a separate archive, so recall and consolidation never need a skip invalidated filter — the rows simply arent there.源码印证了这一点。memories/pg/writes.py 的invalidate_memory分三步执行快照实体 ID在级联删除unit_entities之前把实体 ID 快照下来恢复时才能还原 postings快照因果链接因果链接是 retain 阶段抽取的输出级联外键一旦销毁就永久丢失无法重算因此先把它们的描述符以 JSONB 存进归档行对应 issue #2864插入归档、删除活动行INSERT INTO invalidated_memory_units (...) SELECT ... FROM memory_units随后DELETE FROM memory_units由外键级联自动清理unit_entities与memory_links。restore_memory同文件 L441 起则反向操作把归档行移回memory_units用当前后端重建search_vector避免事实在归档期间后端更换后留下过期/错误类型的向量对应 #2503embedding 由调用方重新生成。这也解释了前面列表端点的行为失效行默认被包含、stateinvalidated读归档表、entity_id与stateinvalidated组合返回空——因为归档表里没有实体链接。清空某记忆的派生观察DELETE /v1/default/banks/{bank}/memories/{id}/observations删除由某记忆派生出的全部观察并把它重置以便重新 consolidation。记忆本身不会被删除删除操作会自动触发一次 consolidation 作业使该记忆在下一次 consolidation 运行时产出全新观察见 http.py。curl -X DELETE $HINDSIGHT_URL/v1/default/banks/$BANK_ID/memories/$MEMORY_ID/observations # 响应{deleted_count: N}需要说明hindsight-cli/src/api.rs 目前不再支持删除单个记忆相关分支直接提示 Individual memory deletion is no longer supported. Use memory clear to clear all memories.整库清空请使用hindsight memory clear。文档是事实的源头 Documents are the source of truth记忆从文档中抽取而来。编辑或失效一个记忆不会改变它来源的文档——这是刻意设计文档作为准确的历史记录被保留。因此重新处理reprocess一个文档会重置它产出事实的策展状态抽取会基于原始文本重新执行。系统性问题请在 mission 层修复后 reprocess编辑/失效只用于处理残留问题。一个可落地的清理工作流要清理重复项、回收噪音推荐流程是从memories/list聚类重复项可按q全文搜索 stateinvalidated复查历史失效记录对确认重复的事实逐条PATCH失效附上reason说明recall 立即变干净同时审计轨迹完整保留如需反悔随时PATCH {state: valid}恢复。整套能力配合控制平面的记忆视图与图谱视图可形成抽取 → 审计 → 修正 → 恢复的完整闭环。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考