agentmemory filesystem-watcher 接入指南把目录变更变成可检索的持久化记忆【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory导读agentmemory是面向 AI 编码 Agent 的持久化记忆服务详见仓库根目录 README.md。而 integrations/filesystem-watcher/README.md 描述的agentmemory/fs-watcher则是它的一个文件系统数据源连接器它以常驻进程的方式监控一个或多个目录每当文件发生写入或删除就把变更作为一条post_tool_use观测observation推送给正在运行的 agentmemory 服务器。读完本文你将掌握它的安装方式、CLI 与环境变量用法、全部配置项与默认值、事件载荷结构以及底层脱敏、去抖与容错实现从而把“编辑文件”这一高频行为自动沉淀为 Agent 可检索的记忆。一、背景为什么需要文件系统连接器agentmemory 的核心能力是把 Agent 工作过程中的信号hook 事件、对话、工具调用等沉淀为可检索的观测。但这类观测通常来自 Agent 运行时本身如 Claude Code、Codex、Cursor 的钩子。而现实中的很多重要信息——笔记、文档、配置、代码草稿——是直接在编辑器中修改的并不会经过 Agent 的工具调用链路。agentmemory/fs-watcher正是为填补这一空白而设计的单向数据源连接器属于仓库中>npm install -g agentmemory/fs-watcher安装后即获得agentmemory-fs-watcher命令bin字段指向 bin.mjs。2.3 不安装直接运行npx agentmemory/fs-watcher ~/work/my-reponpx会临时拉取并执行该包适合快速试用。参数含义与全局安装完全一致后续 CLI 参数即为要监控的目录列表。三、用法与参数优先级3.1 用 CLI 参数指定监控目录# CLI args win over env. —— CLI 参数优先于环境变量 agentmemory-fs-watcher ~/work/my-repo ~/notes可以同时监控多个根目录空格分隔即可。从 bin.mjs 的源码可以看到解析逻辑const roots cliArgs.length 0 ? cliArgs : envCfg.roots;只要 CLI 传入了任意目录环境变量AGENTMEMORY_FS_WATCH_DIRS就会被忽略这正是文档中 CLI args win over env 的源码依据。3.2 用环境变量配置# 一次性设置 export AGENTMEMORY_FS_WATCH_DIRS~/work/my-repo,~/notes export AGENTMEMORY_URLhttp://localhost:3111 export AGENTMEMORY_SECRET... # 仅当服务器要求认证时 agentmemory-fs-watcher此时不传任何 CLI 参数进程会从环境读取配置。若既不传 CLI 参数、也未设置AGENTMEMORY_FS_WATCH_DIRSbin.mjs 会向 stderr 输出用法提示并以退出码 2 结束。3.3 完整配置项一览以下参数表完整继承自 integrations/filesystem-watcher/README.md变量默认值含义AGENTMEMORY_FS_WATCH_DIRS—逗号分隔的待监控目录列表AGENTMEMORY_FS_WATCH_IGNORE—逗号分隔的正则模式匹配相对路径则忽略AGENTMEMORY_FS_WATCH_ALLOW_BINARY0设为1时把二进制文件也纳入预览读取AGENTMEMORY_URLhttp://localhost:3111agentmemory 服务器地址AGENTMEMORY_SECRET—Bearer Token当服务器设置了AGENTMEMORY_SECRET时必须提供AGENTMEMORY_PROJECT—可选附加到每条观测的项目标签AGENTMEMORY_SESSION_ID—可选观测归属的会话 id结合 watcher.mjs 中的configFromEnv可以补充两点实现细节AGENTMEMORY_PROJECT_NAME是规范覆盖项代码注释与 test/project-scope-parity.test.ts 的测试均说明AGENTMEMORY_PROJECT_NAME优先级更高AGENTMEMORY_PROJECT仅作为向后兼容的别名保留且两者都会先trim()纯空白视为未设置。AGENTMEMORY_FS_WATCH_IGNORE是逐条编译为正则的每个逗号分隔的片段都会new RegExp(s)因此可以直接写foo$、^bar这类锚定表达式测试中configFromEnv用例对此有断言。四、事件语义一次文件变化 一条观测4.1 观测类型与载荷结构监控根目录内每次文件变化都会成为一条post_tool_use观测其data.changeKind为file_change文件被写入/修改file_delete文件被删除。观测载荷的完整形态见 watcher.mjs 的flush方法其 JSON 结构如下{ hookType: post_tool_use, sessionId: fs-watcher-ts-rand, project: 仓库名或目录名, cwd: 根目录绝对路径, timestamp: 2026-09-10T01:06:57.000Z, data: { source: filesystem-watcher, changeKind: file_change, files: [notes.md], content: notes.md (13 bytes)\n\nhello world\n, rootDir: /abs/path/to/root, absPath: /abs/path/to/root/notes.md, size: 13, truncated: false } }这一结构完全符合 agentmemory 的HookPayload契约。在 src/types.ts 中HookPayload要求hookType、sessionId、project、cwd、timestamp五个必填字符串字段watcher 发送的每条消息都完整携带。4.2 服务端如何消费这条观测理解载荷之后值得看一下它进入服务器后的处理链路这能让文件变更如何变成可检索记忆变得具体HTTP 入口src/triggers/api.ts 中api::observe注册在POST /agentmemory/observe会先校验hookType/sessionId/project/cwd/timestamp五个必填字段再转发给mem::observe缺失任一字段返回 400。若服务器配置了AGENTMEMORY_SECRET该路由还受middleware::api-auth中间件保护src/triggers/api.ts。观测入库src/functions/observe.ts 中的mem::observe把载荷包装成RawObservation见 src/types.ts。由于hookType属于post_tool_use其origin.channel被标记为tool同时尝试从data中提取toolName、toolInput、toolOutput。会话自动创建一个值得注意的细节是若sessionId对应的会话尚不存在只要载荷携带了合法的project与cwd服务端会自动创建会话记录src/functions/observe.ts 中else if分支。这正是 watcher 文档强调session id 和 project 是 observe 端点必需项的原因——有了它们即使 watcher 没有先调用/session/start记忆也能正确归入会话。压缩与索引默认走零 LLM 消耗的合成压缩buildSyntheticCompression随后写入 BM25 搜索索引与向量索引src/functions/observe.ts使文件内容片段可被后续recall/搜索命中。4.3 session id 与 project 的自动推导observe 端点要求会话与项目信息watcher 的处理策略是能自动则自动session id未显式设置AGENTMEMORY_SESSION_ID时生成形如fs-watcher-时间戳36进制-3字节随机hex的按进程会话 idwatcher.mjs 构造函数。也就是说一次常驻运行对应一个会话。project默认取第一个根目录的目录名但若该目录位于 Git 仓库内则优先使用仓库顶层目录名。这是因为 watcher.mjs 的deriveProjectName与 hooks 的resolveProject保持相同解析顺序先git rev-parse --show-toplevel取顶层名失败再退回目录名从而让监控子目录时记忆仍按仓库名归类。多根目录的按根归属构造器中还维护了projectByRootMap——多根场景下每条事件会打上产生该事件的根目录所对应的 project而不是统一用第一个根的项目仅当显式配置了AGENTMEMORY_PROJECT时才对所有根统一覆盖。五、预览内容与脱敏机制5.1 预览规则文本文件会读取前 4 KBMAX_PREVIEW_BYTES 4096作为data.content使得后续检索可以通过子串匹配命中更大的文件会置data.truncated: true。二进制文件默认不读取只产生一条不含内容的路径观测设置AGENTMEMORY_FS_WATCH_ALLOW_BINARY1可覆盖此行为。可读文本扩展名内置了一套白名单见 watcher.mjs 的TEXT_EXTENSIONS涵盖.ts/.tsx/.js/.jsx/.mjs/.cjs、.py/.rb/.go/.rs/.java/.kt/.swift、.c/.cc/.cpp/.h/.hpp、.md/.mdx/.txt/.rst、.json/.yaml/.yml/.toml/.ini/.env、.html/.css/.scss/.vue/.svelte、.sh/.bash/.zsh/.fish、.sql/.graphql/.proto等此外.env及其变体.env.*也被强制视为文本。未知扩展名的文件只记录路径不带内容。content的拼装格式formatContent为相对路径 (字节数[, truncated])\n\n预览内容删除事件则简化为deleted: 相对路径。5.2 敏感信息脱敏源码级细节这是该连接器最有价值的防护设计watcher.mjs 中有一整套redactSensitivePreview脱敏管线且每条规则都有对应的测试覆盖见 test/fs-watcher.test.ts敏感键值对匹配KEYvalue/KEY: value含引号与export前缀形式的赋值若键名去除符号后小写命中apikey/accesstoken/accesskey/authorization/bearer/clientsecret/password/passwd/privatekey/pwd/secret/token之一则值替换为[REDACTED]。注意.env中的OPENAI_API_KEY会被脱敏而PUBLIC_FLAG这类非敏感键保持原样测试断言PUBLIC_FLAGenabled仍可见。Bearer Token对Bearer token形式的明文令牌至少 8 个可见字符统一脱敏。PEM 私钥块-----BEGIN ... PRIVATE KEY-----与-----END ... PRIVATE KEY-----之间的全部内容折叠为[REDACTED]但保留 BEGIN/END 标记同一行内内联的 PEM如 JSON 单行值也能被正确识别服务账号 JSON 中的private_key即属此类场景。JWT长度 100 的三段式eyJ...JWT 字符串整体替换为[REDACTED]而较短的、或非三段式 base64 形态的词语不会被误伤测试用例专门验证了这一点。5.3 去抖Debounce编辑器保存文件往往会在短时间内产生多次写事件。watcher 对每个路径做了500 msDEBOUNCE_MS的去抖schedule会先取消该路径未决的定时器再重新计时因此编辑器连续保存最终合并为一条观测测试debounces rapid writes to a single observation断言连续 4 次写入后命中观测数不超过 2。六、默认忽略规则与自定义扩展文档明确列出的默认忽略清单如下无需任何配置即可生效.git/、node_modules/、dist/、build/、.next/、.turbo/、coverage/、.DS_Store、*.log、*.lock对应到 watcher.mjs 的DEFAULT_IGNORE它们是编译好的正则数组例如/(?:^|\/)node_modules(?:\/|$)/匹配路径中任意层级的node_modules目录/\.log$/匹配所有.log后缀文件。isIgnored会在两个环节生效事件回调中立即跳过不入队以及flush落库前的二次校验。需要扩展时通过AGENTMEMORY_FS_WATCH_IGNORE传入逗号分隔的正则表达式作用于相对路径例如export AGENTMEMORY_FS_WATCH_IGNOREtmp/,^\.cache/,\.swp$七、运行机制、容错与运维建议7.1 底层机制基于 Node 内置fs.watch的{ recursive: true, persistent: true }watcher.mjs 的startmacOS、Linux、Windows 10 原生可用无任何原生依赖。事件回调会把相对路径统一为/分隔后再做忽略判断与入队保证跨平台一致。观察到的文件变化会先确认目标仍是文件statSync且isFile()已被删除则走file_delete分支——这正是删除事件能被识别的方式。对外发送使用全局fetch提交到${AGENTMEMORY_URL}/agentmemory/observe带 5 秒超时失败只记录warn日志不影响进程继续监控。7.2 容错设计单个根目录 attach 失败权限、平台差异等时watcher 会记录错误并继续监控其余根目录。对根目录会先做显式statSync校验存在性 是否为目录。test/fs-watcher.test.ts 中有一条重要回归测试在 Linux Node 24 上fs.watch对不存在路径不再同步抛错若不自行校验缺失目录会被静默当作已监控而现在的实现会直接抛错could not watch any of the configured roots。若所有根目录都失败进程抛错退出并给出 Node 版本相关的升级提示Node 19.1.0/ 建议 Node 20 LTS。stop()会关闭全部 watcher 句柄并清空未决定时器保证优雅退出。7.3 常驻与进程管理watcher 进程必须保持运行才能持续捕获变化文档明确建议用进程管理器托管Use a process managerlaunchd、systemd、pm2to supervise it.例如 systemd 服务的ExecStart指向agentmemory-fs-watcher并带上目标目录即可。由于 bin.mjs 已对SIGINT/SIGTERM注册了优雅关闭调用watcher.stop()后退出无论前台 Ctrl-C 还是进程管理器发信号都能干净收尾。八、测试验证与仓库对照本连接器的行为在 test/fs-watcher.test.ts 中有系统性的集成测试覆盖通过 mockfetch捕获请求断言可作为理解其行为的权威参考测试场景验证点写入文件发出post_tool_use观测URL 为/agentmemory/observechangeKindfile_changecontent含文件内容删除文件changeKindfile_delete无效根目录抛could not watch any of the configured roots根目录是文件拒绝监控默认忽略node_modules/ignored.js不产生观测Bearer 认证配置 secret 后请求头携带Authorization: Bearer shhh.env脱敏OPENAI_API_KEY[REDACTED]PUBLIC_FLAGenabled保留JSON 敏感键api_key: [REDACTED]公开键保留明文 BearerAuthorization: Bearer [REDACTED]PEM 多行/内联私钥内容折叠为[REDACTED]保留 BEGIN/END 标记JWT 脱敏长 JWT 被替换短 base64 词不受影响去抖连续写入合并为少量观测九、典型应用场景小结笔记与文档记忆化把~/notes纳入监控随手写的想法、调研结论会自动进入 agentmemory后续会话可通过检索召回。配置与草稿追踪监控.env、.yaml、.md等变更让 Agent 知道项目配置与文档何时、在哪、改了什么。代码仓库的增量观察监控仓库根目录配合AGENTMEMORY_FS_WATCH_IGNORE排除构建产物为 Agent 补充基于文件系统信号的工作上下文。最后再强调两点边界一是该连接器单向——只写入观测、从不读取记忆库想给 Agent 注入记忆需依赖 agentmemory 的 recall/检索能力二是它把文件系统信号作为post_tool_use类观测入库与钩子事件同构因此能无缝复用压缩、索引、会话归并等全部下游能力。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考