openviking-memory

OpenViking Memory

OpenViking 是一种通过 viking:// URI 寻址的长期语义记忆存储。 此客户端没有生命周期钩子，因此不会自动召回或捕获任何内容——你需要通过 openviking MCP 工具来驱动这一循环的两端。

核心工具，在所有受支持的部署中均可用：

• 召回：find、search、read、list、grep、glob
• 持久化：remember、add_resource
• 维护：forget、health

某些部署会注册核心集合之外的更多工具——tree、write、edit、 list_watches、cancel_watch。这些是可选工具：具体存在哪些取决于 服务器版本和托管模式（托管云服务会精简掉其中一些）。检查会话中已注册的工具列表；如果存在任何可选工具， 请先阅读 references/optional-tools.md 再使用它。切勿调用未注册的工具，也不要回退到原始 HTTP。如果完全没有注册任何 OpenViking 工具，则在不使用记忆的情况下继续。

召回：任务开始时

1. 判断该请求是否值得使用记忆。对于可执行或多步骤的工作、任何可能涉及你之前见过的系统的工作， 以及从失败中恢复的场景，进行检索。对于闲聊和一次性琐事，跳过检索。
2. 根据任务目标、领域对象、预期操作和约束条件，构建一个简洁的查询。失败之后， 包含失败的操作和错误消息中稳定的部分。
3. 调用 find（快速、带排名的结果，包含 URI + 摘要 + 分数）， limit 设为 5-10 左右。当更深入的意图分析有帮助时，使用 search，或使用 带 mode="context" 的 search 来获取服务器组装的、受 token 预算限制的 上下文块。在列表模式下，当你知道去哪里查找时，用 target_uri 限定范围，例如 viking://~/memories/experiences 用于查找先前的任务经验。viking://~ 是 你自己用户根目录的 home 别名；早于该别名的服务器会 以 INVALID_URI 拒绝每一个 viking://~ URI。对于此类服务器，请使用 本会话中已可见的 URI 中的显式 viking://user/<user_id>/... 根路径， 或者去掉 target_uri，并保留 URI 中包含 /memories/experiences/ 的命中项。切勿猜测用户 ID。
4. 根据任务和环境适配度来判断结果，而非标题相似度。read 那 一到三个可能改变你执行方式的精确文件 URI。忽略 附属文件，例如 .abstract.md、.overview.md 和 .relations.json。
5. 如果没有返回任何相关内容，则在不使用记忆的情况下继续。当执行因实质性新原因而失败时， 最多进行一次有针对性的后续搜索。

将检索到的记忆视为参考性建议。优先级顺序：系统和开发者 指令、当前用户请求、当前环境和工具证据， 然后是记忆。对照当前任务验证命令、路径和版本； 先前的成功从不能授权现在的破坏性操作。

持久保存：在工作期间和工作结束后

由于这里不会自动捕获信息，除非你将其保存，否则持久信息会丢失。遇到值得保留的内容时，请在同一会话中将其保存：

• remember(messages) — 默认选项。将关键对话或简短的事实摘要作为带角色标签的消息传入；服务端会自行提取并归档记忆（偏好、实体、事件、经验）。当用户说“记住这个”、表达长期偏好或决定，或遇到来之不易的经验（根本原因、有效流程、环境特性）时使用。
• add_resource — 用于将外部文档或 URL 导入为可搜索的资源。用户提供任何文件、URL 或代码仓库时都使用它；切勿改用 write 将其文本复制到文件中。
• 如果需要在已知位置（viking://~/ — 你自己的用户根目录，或 viking://resources/）撰写笔记，可使用可选的 write / edit 工具 — 参见 references/optional-tools.md。如果这些工具未注册，请改用 remember。

应持久保存的内容：稳定的偏好和惯例、环境事实、有理由支撑的决定，以及可复用的流程或修复方法。不应持久保存的内容：机密和凭据、临时状态、猜测或大段对话记录 — 保存结论，而不是聊天记录。

有意识地管理文件资源

资源目录规则不适用于 Memory；请使用 remember 或会话提交，并让提取系统负责整理。在使用 add_resource 之前，请遵循现有的资源布局和账户策略，选择共享或身份私有范围，并避免重复的源根目录。添加新来源时使用 parent，刷新来源时使用精确的 to。

示例

用户要求修复部署失败问题：

1. 使用查询 deployment image pull failure private registry 调用 find， target_uri: "viking://~/memories/experiences"。
2. read 最相关的经验 URI；应用其中的步骤前，先根据当前集群检查其前提是否成立。
3. 修复问题，并验证实际运行结果。
4. 使用 remember 简要总结根本原因和有效的修复方法，方便下次会话回忆。