pathnote

路径知识管理 CLI，面向 Agent 设计。为文件和目录附加语义元数据，支持继承与移动追踪。零侵入——所有数据存放在 ~/.pathnote/db.sqlite。

English version

为什么需要它

AI Agent 在不同项目间工作时，总是反复重新发现同样的东西：这个目录是什么？怎么跑测试？这个配置文件干什么用？ pathnote 在文件系统之上给 Agent 一层持久可查的记忆，不会往项目目录里塞任何 dotfile。

安装

go install（推荐）

go install github.com/caikiji/pathnote/cmd/pn@latest

需要 Go 1.22+。安装到 $GOPATH/bin（通常为 ~/go/bin/），确保该目录在 PATH 中。

编译安装

git clone https://github.com/caikiji/pathnote.git
cd pathnote
go build -o ~/bin/pn ./cmd/pn

快速上手

pn init

# 追加观察笔记（最常用操作）
pn /path/to/project/src "修改启动参数后需重启服务"
pn /path/to/project/data "大文件目录，用 head 不要 cat"
pn /path/to/project/config "生产环境配置" --source user

# 设置结构化元数据
pn set /path/to/project --tags +backend,+go --conv "后端服务主目录"
pn set /path/to/project/src --tags +api --conv "HTTP API 层"
pn set /path/to/project/src/main.go --tags +entrypoint --conv "应用入口" --note "启动参数顺序不可修改"

# Glob 规则：自动标注未注册的子项
pn set /path/to/project/src --glob "*.go:tags=go,conv=Go 源码"
pn set /path/to/project/docs --glob "*.md:+文档"  # 简写格式

# 查看视野（子项继承父级的 tags/conv，除非被覆盖）
pn view /path/to/project/src/main.go
pn view /path/to/project/src/main.go --status    # ok | changed | orphan | new
pn view --status                                  # 默认 cwd

# 确认知识仍正确（更新 verified_at）
pn verify /path/to/project/src/main.go

# 搜索（按继承后的 resolved tags 匹配）
pn find --tags go
pn find --tags +go,-test
pn find --conv "入口"
pn find --orphan
pn find --stale                                    # 找出不新鲜的知识

# 列出子项
pn ls /path/to/project
pn ls                                               # 默认 cwd
pn ls -r                                            # 递归

# JSON 输出（供程序调用）
pn view /path/to/project/src -j
pn find --tags go -j

# 清空字段
pn set /path/to/project --clear=tags,note

# 检测文件移动和孤儿条目
pn reindex /path/to/project
pn reindex --dry-run /path/to/project

# 删除条目
pn rm /path/to/project/old_file.go
pn rm /path/to/project/old_dir --cascade

# 全局状态
pn status

# MCP server
pn mcp                                              # 作为 stdio server 运行

核心概念

追加观察（最常用）

pn <path> <text> 是最短路径：追加一条 note，默认 source=agent。

与 pn set --note 的区别：note 是追加（换行分隔），set 是替换。source 默认也不同（agent vs user）。

继承

子路径从所有父目录继承元数据，自底向上合并：

/path/to          → tags: [python], conv: "ML 项目"
/path/to/src      → tags: [fastapi], conv: "API 层"
/path/to/src/api  → (无本地元数据)

pn view /path/to/src/api 解析为：

• Tags: [fastapi, python]（从两个父级继承，去重）
• Conv: "API 层"（被 /path/to/src 覆盖）

字段	继承行为	说明
tags	并集（祖先 + 本地，去重）	不要在子路径重复标注已有标签
conv	本地覆盖祖先	子路径有本地 conv 则使用本地值
note	本地覆盖祖先	与 conv 相同
globs	不继承	glob 规则只对定义它的目录的直接子项生效
source	不继承	每条记录独立标注来源
verified_at	不继承	每条记录独立追踪验证时间

来源 (Source)

每条路径知识标注其来源：

来源	值	可信度	何时设置
用户明确说的	user	高	pn set 默认值
Agent 观察推断的	agent	中	pn note 默认值

时效 (Staleness)

verified_at 记录知识最后确认正确的时间：

状态	条件
fresh	verified ≤ 7 天前
stale	verified 7–30 天前
old	verified > 30 天前

用 pn verify <path> 显式确认知识仍正确。

移动检测

文件移动后，pn reindex 通过内容哈希检测变更并自动迁移元数据。

孤儿条目（路径不存在且无哈希匹配）可通过 pn find --orphan 查看。

命令参考

命令	说明
init	初始化数据库（--force 备份并重建）
note <path> <text>	追加观察笔记（最短命令）
set <path>	设置/更新元数据
view [path]	查看合并后的元数据（默认 cwd）
verify <path>	确认知识仍正确
ls [path]	列出子项（默认 cwd）
find	按条件搜索（--orphan 替代 orphans）
reindex [path]	更新哈希，检测移动（默认 cwd）
rm <path>	删除条目
status	显示数据库统计
mcp	MCP stdio server
feedback	提交/列出反馈

MCP Server

MCP (Model Context Protocol) stdio server 集成。

配置 Claude Code

claude mcp add --transport stdio -s user pathnote -- pn mcp

可用工具（8）

工具	功能
view	查看路径元数据
note	追加观察笔记
set	设置元数据
verify	确认知识正确
find	搜索路径
ls	列出子项
reindex	检测移动
rm	删除条目

数据存储

所有元数据存放在 ~/.pathnote/db.sqlite——单个文件，零侵入。

可通过 PATHNOTE_DB 环境变量指定数据库路径。

许可证

MIT