ai-memory采集排除ignore_paths：别让敏感文件进入你的记忆库-育师

ai-memory采集排除ignore_paths：别让敏感文件进入你的记忆库

【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memory

ai-memory 是为编码 Agent CLI 提供的长期记忆系统，会自动采集你与 Agent 的会话并沉淀为可检索的记忆页。但密钥、私人笔记这类敏感文件，真的不该被存进记忆库。本文介绍如何用[capture] ignore_paths配置采集排除规则，在事件离开本机之前就把敏感文件挡在 ai-memory 记忆库之外。

为什么需要 ai-memory 采集排除

ai-memory 的生命周期钩子（lifecycle hooks）会捕获 Agent 的文件读写事件，编译成会话记忆，最终落到 Wiki 页面里——就像下面这个 Web 界面中展示的"项目记忆库"：

这套机制的好处是"零配置、自动学习"，但副作用也很直接：Agent 每读一个文件，其路径和内容摘录都可能被记录。如果你在工作目录里同时放着.env、个人笔记目录或客户资料，它们就会被一并采集。ai-memory 提供的[capture] ignore_paths就是为了解决这个问题——一条"采集排除"规则，让敏感文件根本不进入记忆库。

💡 核心结论：排除发生在客户端本地，命中规则的事件在入队、发送、落库之前就被丢弃，敏感内容不会到达服务器，也不会进入全文检索、会话页或交接（handoff）流程。

三步配置 ignore_paths 排除敏感路径

第 1 步：在仓库根目录创建标记文件

在项目根目录（即 Agent 的工作目录或其上级目录）创建.ai-memory.toml，这是 ai-memory 的仓库级配置文件。

第 2 步：写入 [capture] 排除规则

在标记文件中加入[capture]段和ignore_paths列表：

[capture] ignore_paths = ["private/**", "~/.env", "secrets/*.pem"]

规则含义：

相对路径（如private/**）以标记文件所在目录为根
~/前缀会自动展开为用户主目录，比如~/personal-notes/**可以排除家目录里的私人笔记
**表示目录及其全部子路径，*、?用于普通通配

第 3 步：重新安装钩子使规则生效

排除策略由原生ai-memory hook命令在本地强制执行。如果你用的是旧版.sh/.ps1脚本钩子，需要重新安装钩子（或重新生成 OpenCode / OMP / Pi / OpenClaw 插件）才能启用。本地安装默认写入原生钩子，升级后刷新一次即可。

ignore_paths 匹配规则与边界限制

为了避免误伤，ai-memory 对排除规则做了严格的语法约束（见 docs/marker-file.md 的"Capture exclusions"一节）：

项目	规则
匹配方式	匹配整条规范化路径，不是子串匹配
通配符	仅支持``、`?`、`*`，不支持`{}`、`[]`、`!`等扩展语法
规模上限	最多 128 条模式、单条最长 1024 字符
大小写	POSIX 下区分大小写；Windows 盘符/UNC 路径不区分 ASCII 大小写
失效策略	未知键、非法通配符或超过 64 KiB 的文件会整体使策略失效，而不是部分生效

几个容易踩的坑：

只有最近的标记文件生效——标记文件之间不合并。如果子目录有更近的.ai-memory.toml，它的[capture]才是权威配置。
不写[capture]段或ignore_paths = []时，行为与未配置完全一致（默认全量采集）。
斜杠建议统一使用正斜杠/，跨平台都适用。

命中排除后会发生什么

理解"丢弃"的力度很重要，这直接决定规则是否可信：

✅文件类工具事件（读、写、编辑等）：只要任一候选路径命中规则，整个事件在本地直接丢弃——不进本地队列、不经过网络、不进服务器存储，也不会出现在日志里。
✅搜索/列目录类工具：策略激活时会被保守地一并丢弃。
✅路径缺失或无法解析的事件：降级为"仅元数据"形态，只保留有限的工具/路由元数据，绝不包含路径、参数、输出或报错内容。
❌它不是完整的 DLP：Shell 命令、自由文本补丁、提示词正文、助手回复都不做路径归属解析；也不解析符号链接和 Windows 8.3 短名。请为每个可见别名显式添加一条规则。

这套"本地优先丢弃"的边界设计可以在 crates/ai-memory-hooks/src/capture_policy.rs 中找到实现，它也是 crates/ai-memory-hooks/ 钩子 crate 的核心安全逻辑之一。

用 --check-capture 本地验证采集决策

配置完之后，不必等一次真实的会话来验证。ai-memory hook --check-capture会读取一份 JSON 事件载荷，只打印有界的决策元数据（策略状态、处置结果、路径数量等），不做任何入队、网络或交接操作：

printf '%s\n' '{"session_id":"demo","cwd":"/example/workspace","tool_name":"Edit","tool_input":{"path":"secrets/key.pem"}}' \ | ai-memory hook --event post-tool-use --agent claude-code \ --server-url http://127.0.0.1:49374 --check-capture

如果命中排除，输出会显示事件被丢弃（drop）；未命中则显示保留（keep）。整个过程不会泄露路径或载荷内容，可以安全地反复调试规则。

进阶：allowlist 模式，让"未标记即不采集"

默认情况下，没有.ai-memory.toml的仓库也会被采集——忘记放标记文件就等于"泄漏"。ai-memory 提供了反过来的失败模式：

ai-memory install-hooks --apply --capture-mode allowlist

allowlist 模式下，.ai-memory.toml的存在本身就是"启用采集"的声明：没有标记文件的仓库不会发出任何生命周期事件。这适合个人开发机上"工作目录才需要记忆，其他一切保持安静"的场景。

结合项目首页可以直观看到各 workspace/project 的记忆页面分布，确认采集范围符合预期：

常见问题（FAQ）

Q：ignore_paths 会影响已有的记忆页面吗？不会。它只拦截新采集的事件，属于"入口闸门"。历史已入库的内容需要另行处理（如purge-project等生命周期命令）。

Q：多条规则冲突或写错了怎么办？任何一条非法模式都会让整个策略进入 Invalid 状态而不是部分生效，此时文件类事件降级为"仅元数据"——宁可少采、也不误采。用--check-capture可以确认策略是否处于 Active。

Q：Docker 部署 / 远程脚本钩子支持吗？旧版.sh/.ps1脚本和 Docker 纯远程脚本包不强制执行该策略；请使用install-hooks --apply写入的原生钩子或重新生成的 TypeScript 集成。

Q：它能把密钥从提示词里也过滤掉吗？不能。忽略路径是词法层面的采集边界，只处理可证明路径归属的文件工具事件，不是全文内容过滤器。不要把希望寄托于它拦截所有敏感内容。

小结

需求	做法
排除仓库内敏感目录	`ignore_paths = ["secrets/**", ".env"]`
排除家目录个人笔记	`ignore_paths = ["~/personal-notes/**"]`
未标记仓库一律不采集	`install-hooks --capture-mode allowlist`
本地验证规则效果	`ai-memory hook --check-capture`

一句话记住：敏感文件不进记忆库，最好的时机是在它离开你的电脑之前。用[capture] ignore_paths配一条规则、重新安装钩子、跑一次--check-capture，三分钟内就能让 ai-memory 的采集排除生效。更多标记文件字段（workspace、project、briefing 等）参考 docs/marker-file.md，日常使用场景见 docs/usage.md。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考