Hindsight 心理模型标签实战新列表视图、服务器端标签建议与更安全的刷新/反射过滤【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本文围绕 Hindsight 控制平面Control Plane的一次重要更新展开心理模型Mental Models在新列表视图中作为“真正的操作文档”被管理标签建议改为从心理模型自身的标签源获取同时标签直接参与刷新输入过滤与反射Reflect可见性控制。读完后您将掌握如何用sourcemental_models标签端点做精确过滤、如何用“任意/全部”匹配模式调试过滤结果并理解心理模型标签在刷新与反射流程中的真实语义避免“模型存在但内容为空”这类标签范围陷阱。快速答案这次更新改变了什么在深入细节之前先给出三条核心结论心理模型现在在默认列表视图中打开旧的卡片仪表板Dashboard仍作为辅助视图可用只是不再是第一眼看到的东西。标签建议tag suggestions现在来自新的心理模型标签源sourcemental_models过滤基于模型实际使用的标签而不是让您凭记忆输入标签。心理模型标签影响刷新输入和反射可见性因此过滤绝不仅仅是装饰性的。为什么列表视图成为默认列表视图成为更好的默认值原因在于心理模型本质上是长期的操作文档long-lived operating documents而不是仪表板上的卡片。在新视图中您可以在一个窗格中扫描每个模型的名称、源查询source query和刷新状态在另一个窗格中检查模型的具体内容。这修复了一个真实的工作流问题当您的库bank中维护着多个心理模型时卡片网格适合浏览而列表适合日常维护。本次更新两者都保留只是把维护视图变成您首先落地的第一件事。从控制平面组件结构看列表视图位于 mental-models-view.tsx其加载逻辑直接调用客户端的listAllMentalModels拉取全量模型后再在本地渲染。值得注意的是该组件中的一行注释// Tag filtering happens server-side; only the search text is applied locally.即标签过滤发生在服务器端只有文本搜索是本地应用的。这意味着 UI 上的标签芯片tag chip会直接转换为GET /v1/default/banks/{bank_id}/mental-models?tags...tags_match...请求参数而不是在前端对全量数据做内存过滤。使用真实建议按标签过滤sourcemental_models新的标签建议路径之所以重要是因为它直接查询心理模型标签源。在实践中UI 可以建议“来自心理模型”的标签而不是“来自一般记忆”的标签。当库中有许多普通内存标签、但只有一小部分标签真正附加到心理模型时这正是您想要的区别。基础端点形状如下curl $BASE_URL/v1/default/banks/$BANK_ID/tags?sourcemental_models端点的完整参数对照 API 源码 api/http.py 中的list_tags路由实现该端点的完整参数集为参数类型默认值说明qstringNone通配符过滤模式*为通配符大小写不敏感。例如user:*匹配user:alice、user:bob*-admin匹配role-admin、super-adminsourcememories \| mental_modelsmemories标签读取来源memories读memory_units表默认mental_models读mental_models表limitint100最多返回的标签数 0offsetint0分页偏移 0响应体为ListTagsResponse包含items每个元素为{tag, count}的使用计数对、total、limit、offset。控制平面的 API 客户端在 api.ts 中对该端点做了薄封装/** * List unique tags in a bank with usage counts. Supports wildcard * in q. * Pass source: mental_models to read tags from mental_models instead of memory_units. */ async listTags( bankId: string, q?: string, limit?: number, source?: memories | mental_models ) { ... }引擎层实现为什么两个源走的是同一条直方图逻辑在引擎层memory_engine.py 中list_mental_model_tags的实现揭示了底层原理async def list_mental_model_tags(self, bank_id, *, patternNone, limit100, offset0, ...): List all unique tags used on mental models in a bank with usage counts. Same wildcard semantics as list_tags. Useful to populate tag autocompletion for UIs filtering mental models by tag. ... return await self._list_tags_from_table( tablemental_models, bank_idbank_id, patternpattern, limitlimit, offsetoffset, )可以看到它复用与list_tags相同的_list_tags_from_table私有方法只是把表从memory_units切换为mental_models。源码注释说明了设计意图“标签与记忆共存因此存储层拥有直方图并应用通配符过滤、排序count 降序、tag 升序和分页——在 SQL 存储上这是单条分页查询而不是把整个直方图拉过网络。”这也解释了为什么该端点支持limit/offset分页而不是返回全量。此外该操作被纳入操作校验体系操作类型LIST_MENTAL_MODEL_TAGS定义于 operation_validator.py意味着租户扩展extension可以对“读取心理模型标签”这一读操作做独立的权限校验与LIST_TAGS分开授权。心理模型标签真正做什么不只是浏览标签这是最容易被误解的部分。心理模型标签不仅仅是浏览标签它们有两层运行时语义缩小刷新输入标签决定了模型在刷新refresh期间可以读取哪些记忆。如果您用user:alice标记一个心理模型刷新时将只读取也带有该必需标签的记忆。当您想要给模型划范围scoping时这是理想行为但代价是如果基础记忆从未被反向填充这些标签过度标记会使模型看起来空或陈旧。影响反射可见性在 Reflect 调用期间哪些心理模型对 LLM 可见也由标签决定。反射调用携带的标签与模型自身标签不重叠时该模型会被“隐藏”。控制平面中这两层语义都体现在心理模型的trigger配置上。从 api.ts 中listMentalModels的类型定义可以看到 trigger 的完整字段集trigger: { mode?: full | delta; refresh_after_consolidation: boolean; refresh_cron?: string | null; min_refresh_interval_seconds?: number | null; fact_types?: Arrayworld | experience | observation; exclude_mental_models?: boolean; exclude_mental_model_ids?: string[]; tags_match?: TagsMatch; // 标签匹配模式 tag_groups?: TagGroup[]; // 组合标签组 include_chunks?: boolean; recall_max_tokens?: number; recall_chunks_max_tokens?: number; response_schema?: Recordstring, unknown; keep_trace?: boolean; };其中tags_match支持any/all/any_strict/all_strict四种模式——非严格any/all匹配会把无标签行untagged rowsOR 进来严格*_strict模式则不会。API 层 http.py 中 mental-models 列表端点同样暴露了这一参数tags_match: str Query( defaultany, descriptionHow to match tags (any, all, any_strict, all_strict) )有意使用“任意”与“全部”匹配控制平面的列表视图现在支持带匹配模式match mode的标签过滤。组件中tagsMatch状态默认值为any见 mental-models-view.tsx 中useStateany | all(any)。这给您两个实用的使用习惯浏览和快速查找相关心理模型时使用any任意只要命中所选标签集合中的任意一个就展示调试精确范围、想只看匹配整个标签集的模型时使用all全部所选标签必须全部命中。当过滤列表突然看起来太小时排查顺序是第一个要做的从全部切回任意第二件事检查心理模型本身是否具有比您期望读取的记忆更严格的标签即模型 trigger 上的标签范围比您以为的更窄导致刷新读到的输入很少。排除空白或误导结果的三种常见模式文档总结了三个高频排查模式逐一对照标签机制解释根因模型存在但内容为空。通常是因为心理模型的标签比可用记忆更严格——刷新阶段按trigger.tags_match过滤输入若命中的记忆集为空生成的内容自然趋近空白。您想要的标签芯片从不出现。通常是因为没有任何心理模型携带该标签即使普通记忆大量使用该标签。这正是需要sourcemental_models独立源的原因两个源回答的是不同的浏览问题。反射似乎缺少某个模型。通常是反射调用使用的标签与模型自身标签不重叠反射可见性同样受标签过滤影响不匹配即隐藏。如果有疑问请回到心理模型 API 文档和观察Observations指南核对标签范围。大多数“心理模型混乱”实际上都是标签范围混淆tag scope confusion。常见问题仪表板视图消失了吗没有。仪表板仍然存在。本次更新只是让列表视图成为默认值因为它对日常维护更好。为什么心理模型标签建议需要单独的源因为内存标签和心理模型标签解决不同的浏览问题。当建议来自您实际过滤的心理模型表mental_models时建议才有用——否则会建议您一堆只存在于memory_units上、对心理模型过滤毫无意义的标签。标签可以使心理模型从反射中消失吗可以。反射可见性也由标签过滤因此请求标签和模型标签之间的不匹配可以隐藏模型。配套客户端行为列表视图如何拉取全量模型列表视图为了在一个窗格内展示全部模型的名称、源查询与刷新状态需要绕过单页上限。客户端封装 listAllMentalModels 说明了这一点/** * List every mental model for a bank, paging until total is reached. * The endpoint caps a response at 1000 models, so anything that needs the * whole set (the list view, the freshness card) has to page. */ async listAllMentalModels(bankId: string, options) { const PAGE_SIZE 1000; // 以 1000 为页宽循环翻页直到 items.length total }即服务端单次响应最多 1000 个模型列表视图与“新鲜度卡片”freshness card都需要循环分页取全量。同时listMentalModels支持detail参数metadata/content/full裁剪负载——端点默认返回metadatasource_query、content、max_tokens、trigger为 null需要这些字段时必须显式传detail。列表中展示的is_stale字段标记“该模型自身范围内是否有记忆自上次读取后写入”这正是列表视图里“刷新状态”列的数据来源。小结心理模型列表视图是默认维护入口一窗格扫名称/源查询/刷新状态另一窗格看内容卡片仪表板保留为辅助视图。标签建议用GET /v1/default/banks/{bank_id}/tags?sourcemental_models获取支持q通配符与limit/offset分页引擎层复用与内存标签相同的直方图查询只是换读mental_models表。心理模型标签的运行时语义有两层限定刷新可读取的记忆范围、决定反射期间的模型可见性。标签不匹配会导致内容为空或模型在反射中“消失”排查时优先在 any/all 之间切换再检查模型 trigger 标签是否比预期更严格。关键参考文件api/http.pytags 端点、memory_engine.pylist_mental_model_tags、mental-models-view.tsx列表视图与 any/all 过滤、api.tsmental-models 客户端封装。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考