Hindsight 如何用 hindsight fs mount 把银行的 Knowledge Pages 镜像为本地 Markdown 文件-育师

Hindsight 如何用 hindsight fs mount 把银行的 Knowledge Pages 镜像为本地 Markdown 文件

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight

Hindsight 银行的 Knowledge Pages 是一组会随记忆整理自动重写的 markdown 文档。当这些页面已经建好，但你不想每次都用 API 或knowledge-base子命令去读它们时，可以用 CLI 的hindsight fs mount把整个知识库镜像到本地磁盘：文件夹树变成真实目录，每个页面变成一个带 YAML frontmatter 的 markdown 文件，并由后台刷新循环持续保持最新。镜像之后，ls、cat、grep、rg、fzf和你的编辑器都能直接对真实文件工作，不需要 SDK 或 API 客户端。

前提是有一个可访问的 Hindsight 服务（本地或远程），且目标银行里已经存在 Knowledge Pages。

准备条件：安装 CLI 并配置访问

安装 CLI（该命令会下载并执行官方安装脚本来安装hindsight）：

curl -fsSL https://hindsight.vectorize.io/get-cli | bash

配置 API 地址与密钥，让 CLI 指向你的服务：

# 交互式配置 hindsight configure # 或直接指定 hindsight configure --api-url http://localhost:8888 --api-key your-api-key

也可以用环境变量配置，环境变量优先级最高：

export HINDSIGHT_API_URL=http://localhost:8888 export HINDSIGHT_API_KEY=your-api-key

配置优先级从高到低是：环境变量（HINDSIGHT_API_URL、HINDSIGHT_API_KEY）、命名 profile（-p <name>或$HINDSIGHT_PROFILE）、~/.hindsight/config共享配置、默认值http://localhost:8888。

先确认银行存在、并且里面已经有知识页面：

# 列出所有银行 hindsight bank list # 查看该银行的文件夹/页面树（落后的页面会标记 stale） hindsight knowledge-base tree my-bank

my-bank是文档示例用的银行 ID，请替换成hindsight bank list输出中的实际 ID。如果银行里还没有页面，可以先用hindsight knowledge-base create-page <bank_id> "页面名" "页面回答的问题"创建——内容在后台生成，通过返回的operation_id轮询可知道内容是否就绪，详见 Knowledge Pages API。

前台挂载：一条命令镜像知识库

hindsight fs mount --bank my-bank

这条命令是前台运行：先把银行的知识库同步进挂载目录，然后进入循环，每隔一个刷新间隔（默认 30 秒）再同步一次，直到按 Ctrl-C 停止。每轮同步都会输出一行日志（源码 fs/mod.rs 中的格式，数值以实际输出为准）：

[2026-09-14 01:30:00] synced 5 pages / 2 folders — 2 updated, 3 unchanged, 0 removed

常用选项：

选项	作用
位置参数`<dir>`（或环境变量`HINDSIGHT_FS_DIR`）	指定挂载目录，默认`./hindsight-fs`
`-b, --bank <bank_id>`	要镜像的银行（也可用环境变量`HINDSIGHT_BANK_ID`）
`-i, --interval <秒>`	刷新间隔，默认 30 秒
`--once`	只做一次同步就退出，等价于`fs sync`
`--writable`	让镜像文件可编辑；默认是只读文件。注意即使开了`--writable`镜像仍是单向的，本地改动会在下次刷新时被还原

后台挂载：让镜像长期保持最新

如果希望镜像在终端关闭后仍然更新，用--detach启动后台守护进程（等价于hindsight fs start）：

hindsight fs mount --bank my-bank --detach

启动成功会打印守护进程 PID 和日志路径，并提示停止方式。后台模式下常用的配套命令：

# 查看守护进程、最近一次同步与健康状态；不健康时以非零码退出 hindsight fs status ./hindsight-fs # 查看守护进程日志的末尾（最近 40 行） hindsight fs logs ./hindsight-fs # 手动触发一次刷新后退出 hindsight fs sync --bank my-bank # 停止该目录对应的后台守护进程 hindsight fs stop ./hindsight-fs

fs status会输出挂载目录、银行、API 地址、模式（read-only (edits blocked)或writable (one-way; edits reverted on refresh)）、守护进程状态、Last sync时间与Health: ok。它是否健康可以直接用退出码判断，适合放进脚本。--stale-after <秒>可调“多久没同步算过期”，默认是max(interval×3, 15)。

验证镜像结果

挂载完成后，验证方式就是普通文件操作：

ls -R ./hindsight-fs cat ./hindsight-fs/Operations/Deploying\ the\ API.md rg "deploy" ./hindsight-fs

文件夹树变成真实目录，每个页面是一个 markdown 文件，文件内容带 YAML frontmatter（id、type、title、description、tags、timestamp），随后是页面正文——与 API 的GET /knowledge-base/pages/{page_id}返回的markdown字段是同一种文档。

判断镜像是否健康：

前台模式：每轮同步打印synced N pages / M folders — ... updated, ... unchanged, ... removed；出错时打印sync failed: <原因>。
后台模式：hindsight fs status <dir>显示Health: ok且Last sync时间持续更新；状态异常时退出码非零。
银行里根本没有知识库时，hindsight fs list --bank my-bank会提示No knowledge base in bank "my-bank".——fs list只列出该银行的文件夹和页面，不写任何文件。

卸载与替代路径

卸载会删除本地文件，执行前确认挂载目录里只有镜像内容：

# 停止守护进程，并删除镜像文件与本地控制数据 hindsight fs unmount ./hindsight-fs

输出会说明删除了多少个镜像文件。镜像只是记忆的投影：删掉本地文件不损失任何银行内容，下次挂载会重新生成。

如果只是一次性导出、不想维持一个长期挂载，API 侧有等价路径：hindsight knowledge-base export <bank_id>把整个知识库导出为一组可移植的 markdown 文件（一个嵌套index.md、每个页面一个<page-id>.md，重建过的页面附带<page-id>.log.md刷新历史），适合提交到别的仓库或存档。

边界说明

镜像是单向的：银行侧的页面更新（consolidation 之后页面自动重写）会在下一轮刷新落到本地文件；本地文件默认只读，--writable也只在本地编辑方便意义上有用，改动会在下次刷新被还原。
--bank指定的银行若没有知识页面，挂载本身可以运行，但没有文件可写；先用hindsight knowledge-base tree确认。
页面内容背后是 mental model：默认只从该银行的 observations 增量刷新、不会读取其他页面，页面与 API 行为一致的细节见 Knowledge Pages 与 Knowledge Pages API。