Hindsight Obsidian 记忆接入实战：把 Vault 同步为可检索、可引用的 Agent 记忆库

Hindsight Obsidian 记忆接入实战把 Vault 同步为可检索、可引用的 Agent 记忆库【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本篇指南讲解如何通过 Hindsight 官方 Obsidian 插件将你的 Obsidian Vault 单向同步进 Hindsight 记忆银行bank并借助内置聊天面板让 Agent 基于你的笔记回答问题——每个答案都附带来源笔记引用方便你回到原文修正。读完本文你将掌握插件安装、后端连接配置、增量同步机制、标签作用域scoping过滤以及一套可复现的验证流程。为什么把 Obsidian 笔记变成 Hindsight 记忆Obsidian 的知识天然存在于本地 Vault 中而 Hindsight 插件的作用是让这些笔记可被 Agent 理解与推理而不是停留在纯文本搜索层面。插件通过两个触点工作同步Vault → Hindsight每篇 Markdown 笔记成为 Hindsight 中的一个文档document。编辑即 upsert删除即移除内容哈希保证未变化的笔记被跳过。本地维护笔记路径 → 内容哈希索引因此只有真正变化的笔记才会被重新摄入。接地聊天Grounded chat侧边聊天面板通过 Hindsight 的 Reflect 能力基于笔记作答提供可折叠的引用列表点击可打开源笔记和推理过程披露reasoning disclosure展示每一步实际查询了什么。同步是单向的Obsidian → Hindsight因此 Vault 始终是事实来源source of truthHindsight 绝不会成为第二份真相。每条答案都引用其来源笔记聊天记录默认不存储——改完笔记下次同步时 Hindsight 自动收敛reconverge。前置条件开始前请确认已安装 Obsidian 且有一个正在使用的 Vault可用的 BRAT 插件用于安装 beta 插件一个可达的 Hindsight 后端Hindsight Cloud或自托管服务器Step 1安装插件Beta 期走 BRAT插件处于 beta 阶段官方推荐通过 BRAT 安装。在 BRAT 中添加专属插件仓库vectorize-io/hindsight-obsidianBRAT 从该仓库的最新 Release 读取插件然后在Settings → Community plugins中启用。如果想自托管 Hindsight 而非使用 Cloud可先在本地起一个服务pip install hindsight-all export HINDSIGHT_API_LLM_API_KEYyour-openai-key hindsight-api启动后服务默认监听http://localhost:8888。Step 2把插件指向 Hindsight 后端打开Settings → Hindsight逐项配置连接参数。下表完整列出了插件提供的设置项默认值来自 settings.ts 中的DEFAULT_SETTINGS设置项默认值说明API URLhttps://api.hindsight.vectorize.ioHindsight 服务地址自托管填http://localhost:8888API key—Hindsight Cloud API KeyBank nameobsidian所有 Vault 共享的银行通过vault:标签隔离Include / exclude folders—限定哪些笔记参与同步Sync on edit开编辑笔记时自动重新摄入Default chat depthlow聊天回答的 Reflect 预算low/mid/highRemember conversations关开启后聊天轮次会存入 Hindsight会在 Vault 之外产生记忆Prefix document IDs with vault name开文档 ID 加 Vault 前缀避免共享银行下多 Vault 冲突仅单 Vault 场景可关闭Debug logging关在控制台输出每次 reflect 请求含作用域过滤条件与引用来源使用 Hindsight Cloud 时保持 API URL 默认粘贴 API Key 即可自托管则将 API URL 改为http://localhost:8888。设置页还提供一个Test connection按钮底层调用 client.ts 中的health()方法探测/health端点返回connected ✓即说明连通。从源码看连接的核心是 HindsightClient它把请求封装为POST /v1/default/banks/{bankId}/memoriesretain、DELETE .../documents/{document_id}删除、POST .../reflect查询并通过可注入的 Transport 解耦 Obsidian 运行时的requestUrl与 CLI 的fetch保证两个前端请求语义永不漂移。Step 3同步 Vault运行Sync vault now命令做一次完整对账reconcile——摄入已变化的笔记并剪除已删除的笔记。插件共暴露三个命令Sync vault now— 完整对账摄入变更、剪除删除Ingest current note— 强制同步当前活动笔记Open chat— 打开接地聊天面板保持Sync on edit开启时笔记编辑会自动触发重新摄入一般无需手动同步。状态栏会常驻显示同步状态例如Hindsight ✓ 412 notes · 2m ago旁边有刷新按钮点击即触发一次同步同步过程中图标旋转不会静默进行。同步引擎的底层行为同步逻辑集中在 sync.ts 的SyncEngine中值得关注几个关键点文档 IDdocId()在开启prefixDocId时返回{vaultName}/{path}否则直接用笔记路径。文档 ID 与笔记路径对应是后续引用和删除映射的基础。增量判定先比较 mtime 做廉价预过滤再对内容做sha256哈希mtime 变了但内容一致时只刷新索引、不重新摄入。摄入调用ingestFile()对每篇笔记调用client.retain(bankId, docId, body, { tags, metadata, timestamp, updateMode: replace })即以replace模式 upsert新版本整体替换旧版本。重命名handleRename()先删除旧路径文档再在新路径下强制摄入。删除handleDelete()只删除本地索引中确实同步过的文档。对账剪除reconcile()依据本地索引而非服务端文档列表来剪除孤儿文档——这样不会误删其他工具如开启记忆后的conversation/…文档写入同一银行的内容。代价是本地索引丢失如重装期间产生的孤儿不会自动剪除删除一次该笔记即可修复。并发控制摄入通过mapLimit(files, 3, ...)限制并发数为 3。插件如何使用记忆两条链路插件的核心链路如下参见 obsidian READMEnote created / edited ──▶ retain(documentId note path) (upsert; replaces prior version) note renamed ──▶ deleteDocument(old) retain(new) note deleted ──▶ deleteDocument(path) Sync vault now ──▶ reconcile: ingest drifted notes, prune orphans chat turn ──▶ reflect(question) over the whole bank └─ answer citations (→ source notes) reasoning摄入端笔记正文在 frontmatter.ts 的normalizeNote()中被轻量规范化——剥离 YAML frontmatter、提取tags/aliases兼容行内流式列表与块列表、读取created/date字段作为时间戳。该解析有意不引入 YAML 依赖只处理 Obsidian 实际写入的简单键值/列表形式。查询端每次聊天轮次调用reflect见 chat.ts 的runChatTurn()默认rememberConversations false只调用reflect读而从不调用retain写因此不会产生任何不追溯回 Vault 笔记的知识——测试对此有显式断言。reflect 请求携带budget、includeCitations: true和可选的tagGroups作用域过滤。开启记忆时用户/助手轮次会以conversation/{ISO时间}-{role}为文档 ID 存入银行仅在用户显式开启时发生。引用还原答案的引用列表不是简单罗列检索结果。reflect-util.ts 的groundedNotes()将based_on.memories中引用的事实 ID 与 trace 中 recall/expand 工具输出的document_id做关联还原出这条答案真正基于哪些笔记并保持引用顺序、去重、附带事实片段预览——这比展示 Agent 的全部草稿scratchpad更精确、更相关。隐式作用域Implicit Scoping按 Vault / 文件夹 / 日期过滤每篇笔记在摄入时会被自动打上Vault、文件夹含各级祖先文件夹、创建/更新日期标签见 sync.ts 的scopeTags构造因此你不需要在同步阶段操心作用域——直到 recall 时才用tag_groups按任意组合过滤维度标签示例 recall 过滤Vaultvault:name只看 Work Vault文件夹含祖先folder:Work、folder:Work/ClientsWork/下全部内容日期created:2026-03、updated:2026-06本月更新过的笔记标签的具体生成逻辑folderTags()为一篇Work/Clients/acme.md生成[folder:Work, folder:Work/Clients]dateTags()按 UTC 生成年 年月两级桶标签如[created:2026, created:2026-03]这是因为 recall 没有硬性的日期范围过滤日期作用域表达为对多个桶的 OR。你自己的 frontmattertags和aliases也会原样透传。因为聊天面板和你的外部自动化n8n、Hermes 等命中同一个银行、同一套标签它们看到的作用域视图完全一致。多个 Vault 默认共享一个银行靠vault:标签保持可分离。验证记忆确实生效推荐按以下顺序验证运行Sync vault now确保笔记已被摄入打开聊天面板提出一个答案明确存在于某篇具体笔记中的问题检查回答是否基于笔记给出并列出其使用的笔记点击引用确认打开的是正确的源笔记例如询问某条记录在你某篇笔记中的决策或约定确认被引用的笔记确实是承载该内容的那篇。若回答给出了事实且引用了正确笔记说明整套链路已打通。常见错误期望双向同步同步是单向的Obsidian → Hindsight。Vault 才是规范来源需要修正时请编辑笔记本身而不是在 Hindsight 里改。聊天前没有同步聊天面板只基于已摄入的内容作答。请先运行Sync vault now或保持Sync on edit开启让银行反映当前笔记状态。以为聊天记录默认会被保存Remember conversations默认关闭。只有当你希望聊天轮次存入 Hindsight这会在 Vault 之外产生记忆时才应打开。以为每个 Vault 是独立银行多个 Vault 默认共享一个银行靠vault:标签分离。只想看单个 Vault 时用vault:name过滤即可。FAQ我必须用 Hindsight Cloud 吗不必。自托管同样可行——pip install hindsight-all运行hindsight-api把插件 API URL 指向本地地址如http://localhost:8888。Hindsight 会成为我笔记的第二份拷贝吗不会。同步是单向的Vault 始终是事实来源每条答案都引用其笔记便于你在源头修正且下次同步时 Hindsight 自动收敛。我的 Vault 是如何被作用域划分的每篇笔记被自动打上 Vault、文件夹含祖先和创建/更新日期标签可按任意组合过滤 recall 与 reflect。我的聊天对话会被存储吗默认不会。除非你打开Remember conversations。进阶无桌面端的 CLI 摄入如果你的 Vault 运行在常开无头服务器上由 Obsidian Sync 保持磁盘最新插件包还附带hindsight-obsidian-syncCLI驱动与插件同一套同步引擎因此生成的文档 ID、作用域标签和剪除归属完全一致——Vault 可以在服务器上同步之后再在别处交互式打开两个摄入端不会互相打架或产生重复文档npm install -g vectorize-io/hindsight-obsidian # 一次性对账适合 cron hindsight-obsidian-sync reconcile \ --vault ~/Vaults/Brain --bank my-vault \ --api-url https://api.hindsight.vectorize.io --api-token hsk_... # 或常驻监听、实时同步变更 hindsight-obsidian-sync reconcile --vault ~/Vaults/Brain --bank my-vault --watch--api-url/--api-token会回退到环境变量HINDSIGHT_API_URL/HINDSIGHT_API_TOKEN。其余参数--include folder/--exclude folder可重复、--vault-name name默认取 Vault 目录名、--prefix-doc-id多 Vault 共享银行时为文档 ID 加 Vault 前缀、--index file、--help。CLI 的同步索引默认存放在~/.hindsight/obsidian/下的vault-bank-fingerprint.json刻意放在 Vault 之外避免被 Obsidian Sync 传播索引绑定其构建目标API 来源、银行、Vault 路径与文档 ID 命名空间把既有索引指向不同银行/API 时会**安全失败fail closed**并给出可操作提示而不会静默漏文件或把删除错误归属到它从未写入过的银行。若同时用 CLI 和插件操作同一银行 Vault务必保持两者的作用域配置一致--include/--exclude、--vault-name、--prefix-doc-id与插件设置对齐因为各自维护自己的索引对账只剪除自己索引追踪的文档。进一步探索插件完整源码与测试hindsight-integrations/obsidian——同步引擎测试见 tests/sync.spec.ts聊天轮次测试见 tests/chat.spec.tsHindsight 的 recall 与 retain API 是理解底层行为的入口recall 对应reflect查询链路retain 对应memories写入链路自托管部署参考仓库内 docker/docker-compose 目录下的各类编排示例external-pg、local-llm、pg_search 等以及 hindsight-all 的安装说明【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考