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-memoryai-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 []时行为与未配置完全一致默认全量采集。斜杠建议统一使用正斜杠/跨平台都适用。命中排除后会发生什么理解丢弃的力度很重要这直接决定规则是否可信✅文件类工具事件读、写、编辑等只要任一候选路径命中规则整个事件在本地直接丢弃——不进本地队列、不经过网络、不进服务器存储也不会出现在日志里。✅搜索/列目录类工具策略激活时会被保守地一并丢弃。✅路径缺失或无法解析的事件降级为仅元数据形态只保留有限的工具/路由元数据绝不包含路径、参数、输出或报错内容。❌它不是完整的 DLPShell 命令、自由文本补丁、提示词正文、助手回复都不做路径归属解析也不解析符号链接和 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 allowlistallowlist 模式下.ai-memory.toml的存在本身就是启用采集的声明没有标记文件的仓库不会发出任何生命周期事件。这适合个人开发机上工作目录才需要记忆其他一切保持安静的场景。结合项目首页可以直观看到各 workspace/project 的记忆页面分布确认采集范围符合预期常见问题FAQQignore_paths 会影响已有的记忆页面吗不会。它只拦截新采集的事件属于入口闸门。历史已入库的内容需要另行处理如purge-project等生命周期命令。Q多条规则冲突或写错了怎么办任何一条非法模式都会让整个策略进入 Invalid 状态而不是部分生效此时文件类事件降级为仅元数据——宁可少采、也不误采。用--check-capture可以确认策略是否处于 Active。QDocker 部署 / 远程脚本钩子支持吗旧版.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-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辅助生成（AIGC），仅供参考