拓冰网站定制 
Hindsight Obsidian 集成演进全览从插件首发到无头 CLI 同步引擎【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 的 Obsidian 插件npm 包vectorize-io/hindsight-obsidian为笔记库接入 AI Agent 记忆将 Obsidian vault 单向同步进 Hindsight memory bank并提供基于笔记给出引用答案的聊天面板。本文以官方 changelogskills/hindsight-docs/references/changelog/integrations/obsidian.md为骨架结合仓库源码与 README逐版本梳理从 0.1.0 到 0.2.1 的功能演进与关键修复并深入讲解同步引擎、隐式 scoping、CLI 工具与同步索引绑定等底层原理读完后你将掌握该插件的完整能力边界、配置方式与实现机制。版本演进总览Obsidian 集成从 0.1.0 首发至今共经历 5 个版本核心脉络清晰先解决插件能用0.1.0再打磨聊天体验0.1.1/0.1.2随后补上无头场景0.2.0最后加固多目标安全0.2.1。版本类型核心变化0.1.0首发引入插件本体编辑器内 Hindsight 聊天 笔记/记忆同步0.1.1功能聊天笔记查看改进grounded-note 引用、默认折叠、布局持久化、内联深度控制0.1.2修复修复聊天视图问题满足 Obsidian 社区商店community store审核要求0.2.0功能新增无头 CLI 工具hindsight-obsidian-sync无需运行 Obsidian 应用即可摄入/同步 vault0.2.1修复修复同步索引作用域使 Obsidian 同步/对账按 memory bank 与 API 目标隔离防止跨目标索引冲突v0.1.0插件首发双向能力落地0.1.0 是 Obsidian 集成的起点带来两大核心能力在编辑器内进行 Hindsight 聊天以及将 Obsidian 笔记/记忆同步到 Hindsight。这两个能力对应仓库中两个独立前端插件本体hindsight-integrations/obsidian/src/main.ts 等聊天面板chat-view.ts与同步逻辑sync.ts共享 HTTP 客户端hindsight-integrations/obsidian/src/client.ts封装了retain写入记忆、deleteDocument删除文档、reflect带引用问答三个核心 API 调用。插件的硬性设计原则Obsidian 永远是唯一事实源从 README 与sync.ts的注释可以看出该插件有一条不可违背的规则Hindsight 永远不是第二事实源。同步是单向的Obsidian → Hindsightvault 是权威来源每条聊天回答都会引用来源笔记方便你回到源头修改聊天记录默认不存储可在设置中开启编辑一条笔记后下次同步时 Hindsight 会重新收敛。增量同步引擎SyncEngine同步的核心实现在 hindsight-integrations/obsidian/src/sync.tsSyncEngine针对最小化的SyncVault/SyncFile接口编写因此可以脱离 Obsidian 运行时进行单元测试。同步模型对应如下操作映射note 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本地索引SyncIndex记录 note path → 内容哈希 mtime保证只有变更的笔记才会被重新摄入mtime 预过滤上次同步后 mtime 未变 → 直接跳过连文件都不读ingestFile中的 cheap pre-filter内容哈希mtime 变了但内容一致如仅 touch→ 只刷新索引中的 mtime不触发重新摄入SHA-256 前缀sha256:内容为空跳过正文为空frontmatter 剥离后无 body的笔记直接skippednothing to ground onupsert 语义对同一documentId重复retain即替换旧版本updateMode: replace对账reconcile全量遍历 vault 中应包含的笔记摄入漂移项后再按本地索引而非服务端文档列表清理孤儿文档——这样不会误删其他工具写入同 bank 的文档如conversation/…聊天记忆。隐式 scoping用户只在召回时思考范围这是 0.1.0 就确立的核心设计源码注释引用 DESIGN.md §4.6。每条笔记在摄入时被自动打上三类标签维度标签召回过滤示例Vaultvault:name只看 Work vault文件夹含祖先folder:Work、folder:Work/ClientsWork/下全部内容日期created:2026-03、updated:2026-06本月更新的笔记具体实现sync.ts的folderTags与dateTags文件夹标签对Work/Clients/acme.md生成[folder:Work, folder:Work/Clients]因此folder:Work能匹配Work/下所有内容日期标签按年 年月两级桶生成[created:2026, created:2026-03]因为 recall 没有硬性的日期范围过滤器日期范围被表达为桶的 OR 组合metadata 附注path字段让 API 消费者自动化能把一次召回命中映射回具体笔记vault字段用于多 vault 共库区分。你自己在 frontmatter 里写的tags/aliases也会被透传保留。frontmatter 解析逻辑见 hindsight-integrations/obsidian/src/frontmatter.ts——它刻意保持轻量、无依赖只识别 Obsidian 实际写入的简单键值/列表形式tags、aliases、created/date不做完整 YAML 解析。多 vault 可以共享同一个 bank靠vault:标签保持隔离且UI 与 API 看到的是同一份数据——Obsidian 聊天面板和外部自动化n8n、Hermes 等命中同一个 bank、同一批标签看到完全相同的 scoped 视图。配置项打开设置 → Hindsight即可配置设置项默认值说明API URLhttps://api.hindsight.vectorize.ioHindsight 服务地址自托管用http://localhost:8888API key—Hindsight Cloud API keyBank nameobsidian所有 vault 共享的 bank用vault:标签隔离Include / exclude folders—限制哪些笔记参与同步Sync on edit开启编辑时自动重新摄入笔记Default chat depthlow聊天回答的 reflect 预算Remember conversations关闭开启后聊天轮次会存进 Hindsight在 vault 之外产生记忆Prefix document IDs开启文档 ID 加 vault 前缀防止共享 bank 下多 vault 冲突单 vault 场景可关闭插件还提供三个命令Sync vault now全量对账摄入变更、清理删除、Ingest current note强制同步当前笔记、Open chat打开带引用的聊天面板。v0.1.1聊天笔记查看体验升级0.1.1 聚焦聊天面板的查看体验带来四项改进grounded-note 引用grounded-note citations答案明确列出命中的笔记可点击打开默认折叠collapsed-by-default引用与推理披露默认收起界面更清爽持久化布局persisted layout面板布局状态在会话间保留内联深度控制inline depth controls无需进入设置即可直接调整 reflect 预算。这些能力与 README 中描述的 grounded chat 特性一致侧边栏面板通过 Hindsight 的reflect在笔记上回答问题每条答案列出检索到的笔记点击打开与推理披露显示每一步查询了什么。用提问栏上方的vault / folder下拉框限定问题范围用New chat开启新线程打开Debug logging还能在控制台看到完整的reflect请求与检索结果。v0.1.2为社区商店审核而做的修复0.1.2 是一个合规性修复版本修复 Obsidian 聊天视图中的问题以满足Obsidian 社区商店community store评审要求。这一版本的意义在于流程层面——Hindsight Obsidian 插件此后具备了进入社区商店分发渠道的资质用户可以通过 BRAT 等途径安装体验。v0.2.0无头 CLI 工具 —— 同一引擎的第二个前端0.2.0 引入了hindsight-obsidian-sync无头 CLI 工具不运行 Obsidian 应用直接摄入/同步 vault 到 Hindsight。适合将 vault 放在常驻无头服务器上由 Obsidian Sync 保持磁盘内容最新的场景。从源码结构看hindsight-integrations/obsidian/src/node/CLI 是建立在与插件完全相同的SyncEngine之上的薄封装因此产生的文档 ID、scope 标签与 prune 归属与插件完全一致——一个 vault 可以在服务器上同步之后在别处交互式打开 Obsidian 使用两套前端不会互相打架或产生重复文档。两者的差异仅在三点见cli.ts顶部注释vault 来源文件系统FsVault vs Obsidian API传输层fetchfetch-transport.ts vs Obsidian 的requestUrlobsidian-transport.ts同步索引位置JSON 文件json-index.ts vs 插件的data.json。安装与基本用法npm install -g vectorize-io/hindsight-obsidian # one-shot reconcile适合 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。完整参数与cli.ts中USAGE一致参数说明--vault pathvault 根目录必填--bank id目标 Hindsight bank id必填--api-url urlAPI 基础 URL或HINDSIGHT_API_URL--api-token tokenAPI token或HINDSIGHT_API_TOKEN--include folder仅同步该文件夹可重复默认整个 vault--exclude folder跳过该文件夹可重复--vault-name name用于标签/ID 的 vault 名默认取 vault 目录名--prefix-doc-id文档 ID 加 vault 名前缀多 vault 共享 bank 用--index file同步索引 JSON 路径默认在~/.hindsight/obsidian/下按目标生成--watch常驻运行实时同步变更--help显示帮助CLI 只接受reconcile一个子命令也是默认命令用法错误输出到 stderr 并返回退出码 2--help输出到 stdout 返回 0parseCliArgs与runCli的实现。watch 模式基于 chokidar 的实时同步--watch模式下cli.ts的watchVaultCLI 先用一次初始reconcile建立基线再用 chokidar 监听 vault 目录忽略点目录.obsidian、.trash、.git等awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 }合并部分保存add/change事件 → 强制摄入对应笔记unlink事件 → 删除对应文档文件重命名在 chokidar 中体现为unlink(old) add(new)引擎天然按删除旧路径 创建新路径处理与插件专用重命名路径结果一致。v0.2.1同步索引作用域修复 —— 跨目标隔离与 fail-closed0.2.1 是本次 changelog 中最值得关注的安全修复将同步索引作用域按 memory bank 与 API 目标隔离防止跨目标索引冲突。修复的核心机制在 hindsight-integrations/obsidian/src/node/json-index.ts。默认索引路径刻意放在 vault 之外CLI 的同步索引相当于插件data.json默认是一个按目标隔离的文件~/.hindsight/obsidian/vault-bank-fingerprint.json它刻意放在 vault 之外这样 Obsidian Sync 永远不会把它传播到其他设备。文件名中的 fingerprint 是目标身份IndexIdentity的 12 位 SHA-256 摘要// IndexIdentity: apiOrigin bankId vaultPath vaultName prefixDocId任意绑定字段不同 → fingerprint 不同 → 即使两个 vault 同名也绝不共用索引文件。索引与目标的绑定fail-closed索引绑定了其建立时所针对的目标API origin、bank、vault 路径、文档 ID 命名空间。loadIndex在校验时发现持久化的目标身份与当前不一致就会抛出IndexIdentityErrorfail-closed——给出可操作的错误消息而不是静默跳过文件或把删除误归因到它从未写入过的 bank索引文件缺少 identity 元数据旧版遗留→ 拒绝复用提示删除后从零重同步或换新路径目标身份字段不一致 → 逐字段列出差异提示使用独立--index路径或删除后重同步索引损坏/不可读 → 仅警告后从空索引开始内容哈希会跳过未变更的笔记并说明孤儿清理需等索引重建。刻意不绑定的是 include/exclude 作用域同一目标下收窄范围本就应当修剪新排除的笔记因为该摄入器在目标上拥有这些文档而所有跨目标危害都源于目标变更这正是绑定所拒绝的。索引写入的原子性makePersist采用写临时文件 原子 rename策略保证永远不会留下半写状态的索引文件持久化时还会盖上version信封版本号与identity供下次加载校验。CLI 与插件混用的注意事项如果 CLI 和插件同时针对同一 bank vault请保持两者的 scope 配置一致--include/--exclude、--vault-name、--prefix-doc-id与插件设置匹配。它们各自维护自己的索引一次对账只会修剪自己索引跟踪的文档——两套前端 scope 不一致时一方可能修剪掉另一方拥有的文档。本地开发与手动安装插件的开发工作流hindsight-integrations/obsidian/package.jsonnpm install npm run lint # tsc --noEmit npm test # vitest npm run build # esbuild → main.js想在真实 vault 中试用把构建产物main.js、manifest.json、styles.css复制到vault/.obsidian/plugins/hindsight/并启用插件即可。插件为桌面端专用manifest.json中isDesktopOnly: true要求 Obsidian ≥ 1.7.2Node ≥ 20.15。测试方面仓库在 hindsight-integrations/obsidian/tests/ 提供了完整覆盖sync.spec.ts同步引擎、cli.spec.tsCLI 参数解析、reconcile-integration.spec.ts对账集成、watch.spec.tswatch 模式、json-index.spec.ts索引绑定等sync.ts刻意面向最小接口SyncVault/SyncFile设计正是为了能在无 Obsidian 运行时下单元测试。自托管快速上手不想依赖 Hindsight Cloud 时可以本地起一个服务端pip install hindsight-all export HINDSIGHT_API_LLM_API_KEYyour-openai-key hindsight-api随后在插件设置中把 API URL 指向http://localhost:8888并在 CLI 中使用--api-url http://localhost:8888即可。总结Obsidian 集成的版本演进勾勒出一条清晰的产品化路径0.1.0 确立单向同步 隐式 scoping grounded chat的核心架构与vault 是唯一事实源的设计原则0.1.1/0.1.2 打磨聊天查看体验并打通社区商店渠道0.2.0 通过共享同一SyncEngine的无头 CLI 把同一套同步语义扩展到服务器场景0.2.1 则以目标绑定的同步索引收紧了多 bank/多 API 场景下的数据安全边界。对于想要深度使用 Hindsight 记忆能力的 Obsidian 用户hindsight-integrations/obsidian/README.md 是配置入口hindsight-integrations/obsidian/src/sync.ts 与 hindsight-integrations/obsidian/src/node/json-index.ts 则是理解其底层机制的最佳起点。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hindsight Obsidian 集成演进全览：从插件首发到无头 CLI 同步引擎
Hindsight Obsidian 集成演进全览从插件首发到无头 CLI 同步引擎【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 的 Obsidian 插件npm 包vectorize-io/hindsight-obsidian为笔记库接入 AI Agent 记忆将 Obsidian vault 单向同步进 Hindsight memory bank并提供基于笔记给出引用答案的聊天面板。本文以官方 changelogskills/hindsight-docs/references/changelog/integrations/obsidian.md为骨架结合仓库源码与 README逐版本梳理从 0.1.0 到 0.2.1 的功能演进与关键修复并深入讲解同步引擎、隐式 scoping、CLI 工具与同步索引绑定等底层原理读完后你将掌握该插件的完整能力边界、配置方式与实现机制。版本演进总览Obsidian 集成从 0.1.0 首发至今共经历 5 个版本核心脉络清晰先解决插件能用0.1.0再打磨聊天体验0.1.1/0.1.2随后补上无头场景0.2.0最后加固多目标安全0.2.1。版本类型核心变化0.1.0首发引入插件本体编辑器内 Hindsight 聊天 笔记/记忆同步0.1.1功能聊天笔记查看改进grounded-note 引用、默认折叠、布局持久化、内联深度控制0.1.2修复修复聊天视图问题满足 Obsidian 社区商店community store审核要求0.2.0功能新增无头 CLI 工具hindsight-obsidian-sync无需运行 Obsidian 应用即可摄入/同步 vault0.2.1修复修复同步索引作用域使 Obsidian 同步/对账按 memory bank 与 API 目标隔离防止跨目标索引冲突v0.1.0插件首发双向能力落地0.1.0 是 Obsidian 集成的起点带来两大核心能力在编辑器内进行 Hindsight 聊天以及将 Obsidian 笔记/记忆同步到 Hindsight。这两个能力对应仓库中两个独立前端插件本体hindsight-integrations/obsidian/src/main.ts 等聊天面板chat-view.ts与同步逻辑sync.ts共享 HTTP 客户端hindsight-integrations/obsidian/src/client.ts封装了retain写入记忆、deleteDocument删除文档、reflect带引用问答三个核心 API 调用。插件的硬性设计原则Obsidian 永远是唯一事实源从 README 与sync.ts的注释可以看出该插件有一条不可违背的规则Hindsight 永远不是第二事实源。同步是单向的Obsidian → Hindsightvault 是权威来源每条聊天回答都会引用来源笔记方便你回到源头修改聊天记录默认不存储可在设置中开启编辑一条笔记后下次同步时 Hindsight 会重新收敛。增量同步引擎SyncEngine同步的核心实现在 hindsight-integrations/obsidian/src/sync.tsSyncEngine针对最小化的SyncVault/SyncFile接口编写因此可以脱离 Obsidian 运行时进行单元测试。同步模型对应如下操作映射note 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本地索引SyncIndex记录 note path → 内容哈希 mtime保证只有变更的笔记才会被重新摄入mtime 预过滤上次同步后 mtime 未变 → 直接跳过连文件都不读ingestFile中的 cheap pre-filter内容哈希mtime 变了但内容一致如仅 touch→ 只刷新索引中的 mtime不触发重新摄入SHA-256 前缀sha256:内容为空跳过正文为空frontmatter 剥离后无 body的笔记直接skippednothing to ground onupsert 语义对同一documentId重复retain即替换旧版本updateMode: replace对账reconcile全量遍历 vault 中应包含的笔记摄入漂移项后再按本地索引而非服务端文档列表清理孤儿文档——这样不会误删其他工具写入同 bank 的文档如conversation/…聊天记忆。隐式 scoping用户只在召回时思考范围这是 0.1.0 就确立的核心设计源码注释引用 DESIGN.md §4.6。每条笔记在摄入时被自动打上三类标签维度标签召回过滤示例Vaultvault:name只看 Work vault文件夹含祖先folder:Work、folder:Work/ClientsWork/下全部内容日期created:2026-03、updated:2026-06本月更新的笔记具体实现sync.ts的folderTags与dateTags文件夹标签对Work/Clients/acme.md生成[folder:Work, folder:Work/Clients]因此folder:Work能匹配Work/下所有内容日期标签按年 年月两级桶生成[created:2026, created:2026-03]因为 recall 没有硬性的日期范围过滤器日期范围被表达为桶的 OR 组合metadata 附注path字段让 API 消费者自动化能把一次召回命中映射回具体笔记vault字段用于多 vault 共库区分。你自己在 frontmatter 里写的tags/aliases也会被透传保留。frontmatter 解析逻辑见 hindsight-integrations/obsidian/src/frontmatter.ts——它刻意保持轻量、无依赖只识别 Obsidian 实际写入的简单键值/列表形式tags、aliases、created/date不做完整 YAML 解析。多 vault 可以共享同一个 bank靠vault:标签保持隔离且UI 与 API 看到的是同一份数据——Obsidian 聊天面板和外部自动化n8n、Hermes 等命中同一个 bank、同一批标签看到完全相同的 scoped 视图。配置项打开设置 → Hindsight即可配置设置项默认值说明API URLhttps://api.hindsight.vectorize.ioHindsight 服务地址自托管用http://localhost:8888API key—Hindsight Cloud API keyBank nameobsidian所有 vault 共享的 bank用vault:标签隔离Include / exclude folders—限制哪些笔记参与同步Sync on edit开启编辑时自动重新摄入笔记Default chat depthlow聊天回答的 reflect 预算Remember conversations关闭开启后聊天轮次会存进 Hindsight在 vault 之外产生记忆Prefix document IDs开启文档 ID 加 vault 前缀防止共享 bank 下多 vault 冲突单 vault 场景可关闭插件还提供三个命令Sync vault now全量对账摄入变更、清理删除、Ingest current note强制同步当前笔记、Open chat打开带引用的聊天面板。v0.1.1聊天笔记查看体验升级0.1.1 聚焦聊天面板的查看体验带来四项改进grounded-note 引用grounded-note citations答案明确列出命中的笔记可点击打开默认折叠collapsed-by-default引用与推理披露默认收起界面更清爽持久化布局persisted layout面板布局状态在会话间保留内联深度控制inline depth controls无需进入设置即可直接调整 reflect 预算。这些能力与 README 中描述的 grounded chat 特性一致侧边栏面板通过 Hindsight 的reflect在笔记上回答问题每条答案列出检索到的笔记点击打开与推理披露显示每一步查询了什么。用提问栏上方的vault / folder下拉框限定问题范围用New chat开启新线程打开Debug logging还能在控制台看到完整的reflect请求与检索结果。v0.1.2为社区商店审核而做的修复0.1.2 是一个合规性修复版本修复 Obsidian 聊天视图中的问题以满足Obsidian 社区商店community store评审要求。这一版本的意义在于流程层面——Hindsight Obsidian 插件此后具备了进入社区商店分发渠道的资质用户可以通过 BRAT 等途径安装体验。v0.2.0无头 CLI 工具 —— 同一引擎的第二个前端0.2.0 引入了hindsight-obsidian-sync无头 CLI 工具不运行 Obsidian 应用直接摄入/同步 vault 到 Hindsight。适合将 vault 放在常驻无头服务器上由 Obsidian Sync 保持磁盘内容最新的场景。从源码结构看hindsight-integrations/obsidian/src/node/CLI 是建立在与插件完全相同的SyncEngine之上的薄封装因此产生的文档 ID、scope 标签与 prune 归属与插件完全一致——一个 vault 可以在服务器上同步之后在别处交互式打开 Obsidian 使用两套前端不会互相打架或产生重复文档。两者的差异仅在三点见cli.ts顶部注释vault 来源文件系统FsVault vs Obsidian API传输层fetchfetch-transport.ts vs Obsidian 的requestUrlobsidian-transport.ts同步索引位置JSON 文件json-index.ts vs 插件的data.json。安装与基本用法npm install -g vectorize-io/hindsight-obsidian # one-shot reconcile适合 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。完整参数与cli.ts中USAGE一致参数说明--vault pathvault 根目录必填--bank id目标 Hindsight bank id必填--api-url urlAPI 基础 URL或HINDSIGHT_API_URL--api-token tokenAPI token或HINDSIGHT_API_TOKEN--include folder仅同步该文件夹可重复默认整个 vault--exclude folder跳过该文件夹可重复--vault-name name用于标签/ID 的 vault 名默认取 vault 目录名--prefix-doc-id文档 ID 加 vault 名前缀多 vault 共享 bank 用--index file同步索引 JSON 路径默认在~/.hindsight/obsidian/下按目标生成--watch常驻运行实时同步变更--help显示帮助CLI 只接受reconcile一个子命令也是默认命令用法错误输出到 stderr 并返回退出码 2--help输出到 stdout 返回 0parseCliArgs与runCli的实现。watch 模式基于 chokidar 的实时同步--watch模式下cli.ts的watchVaultCLI 先用一次初始reconcile建立基线再用 chokidar 监听 vault 目录忽略点目录.obsidian、.trash、.git等awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 }合并部分保存add/change事件 → 强制摄入对应笔记unlink事件 → 删除对应文档文件重命名在 chokidar 中体现为unlink(old) add(new)引擎天然按删除旧路径 创建新路径处理与插件专用重命名路径结果一致。v0.2.1同步索引作用域修复 —— 跨目标隔离与 fail-closed0.2.1 是本次 changelog 中最值得关注的安全修复将同步索引作用域按 memory bank 与 API 目标隔离防止跨目标索引冲突。修复的核心机制在 hindsight-integrations/obsidian/src/node/json-index.ts。默认索引路径刻意放在 vault 之外CLI 的同步索引相当于插件data.json默认是一个按目标隔离的文件~/.hindsight/obsidian/vault-bank-fingerprint.json它刻意放在 vault 之外这样 Obsidian Sync 永远不会把它传播到其他设备。文件名中的 fingerprint 是目标身份IndexIdentity的 12 位 SHA-256 摘要// IndexIdentity: apiOrigin bankId vaultPath vaultName prefixDocId任意绑定字段不同 → fingerprint 不同 → 即使两个 vault 同名也绝不共用索引文件。索引与目标的绑定fail-closed索引绑定了其建立时所针对的目标API origin、bank、vault 路径、文档 ID 命名空间。loadIndex在校验时发现持久化的目标身份与当前不一致就会抛出IndexIdentityErrorfail-closed——给出可操作的错误消息而不是静默跳过文件或把删除误归因到它从未写入过的 bank索引文件缺少 identity 元数据旧版遗留→ 拒绝复用提示删除后从零重同步或换新路径目标身份字段不一致 → 逐字段列出差异提示使用独立--index路径或删除后重同步索引损坏/不可读 → 仅警告后从空索引开始内容哈希会跳过未变更的笔记并说明孤儿清理需等索引重建。刻意不绑定的是 include/exclude 作用域同一目标下收窄范围本就应当修剪新排除的笔记因为该摄入器在目标上拥有这些文档而所有跨目标危害都源于目标变更这正是绑定所拒绝的。索引写入的原子性makePersist采用写临时文件 原子 rename策略保证永远不会留下半写状态的索引文件持久化时还会盖上version信封版本号与identity供下次加载校验。CLI 与插件混用的注意事项如果 CLI 和插件同时针对同一 bank vault请保持两者的 scope 配置一致--include/--exclude、--vault-name、--prefix-doc-id与插件设置匹配。它们各自维护自己的索引一次对账只会修剪自己索引跟踪的文档——两套前端 scope 不一致时一方可能修剪掉另一方拥有的文档。本地开发与手动安装插件的开发工作流hindsight-integrations/obsidian/package.jsonnpm install npm run lint # tsc --noEmit npm test # vitest npm run build # esbuild → main.js想在真实 vault 中试用把构建产物main.js、manifest.json、styles.css复制到vault/.obsidian/plugins/hindsight/并启用插件即可。插件为桌面端专用manifest.json中isDesktopOnly: true要求 Obsidian ≥ 1.7.2Node ≥ 20.15。测试方面仓库在 hindsight-integrations/obsidian/tests/ 提供了完整覆盖sync.spec.ts同步引擎、cli.spec.tsCLI 参数解析、reconcile-integration.spec.ts对账集成、watch.spec.tswatch 模式、json-index.spec.ts索引绑定等sync.ts刻意面向最小接口SyncVault/SyncFile设计正是为了能在无 Obsidian 运行时下单元测试。自托管快速上手不想依赖 Hindsight Cloud 时可以本地起一个服务端pip install hindsight-all export HINDSIGHT_API_LLM_API_KEYyour-openai-key hindsight-api随后在插件设置中把 API URL 指向http://localhost:8888并在 CLI 中使用--api-url http://localhost:8888即可。总结Obsidian 集成的版本演进勾勒出一条清晰的产品化路径0.1.0 确立单向同步 隐式 scoping grounded chat的核心架构与vault 是唯一事实源的设计原则0.1.1/0.1.2 打磨聊天查看体验并打通社区商店渠道0.2.0 通过共享同一SyncEngine的无头 CLI 把同一套同步语义扩展到服务器场景0.2.1 则以目标绑定的同步索引收紧了多 bank/多 API 场景下的数据安全边界。对于想要深度使用 Hindsight 记忆能力的 Obsidian 用户hindsight-integrations/obsidian/README.md 是配置入口hindsight-integrations/obsidian/src/sync.ts 与 hindsight-integrations/obsidian/src/node/json-index.ts 则是理解其底层机制的最佳起点。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考