用途
agents-memory 用于管理 AI 代理的指令文件，核心目标是让 Claude Code 与 Codex 在跨会话时获得稳定、有作用域的指令，同时避免把每一次提示都塞满。它把仓库记忆视为「活的例外文件」：凡是代理通过阅读代码、配置或 README 就能可靠推断的内容，都不应放入始终加载的层；只保留持久且无法推断的指导。
主要能力
- 定义并管理多层记忆：共享项目记忆（AGENTS.md）、Claude 项目记忆（CLAUDE.md）、Claude 作用域规则（.claude/rules/*.md）、个人指令（~/.codex/AGENTS.md，被 ~/.claude/CLAUDE.md 以 @ 导入）、Codex 目录覆盖（AGENTS.override.md）、Codex 运行时权限、Codex 自动记忆（~/.codex/memories/）、Claude 自动记忆（~/.claude/projects/<project>/memory/，由 MEMORY.md 索引加主题文件构成）。
- 指令预算控制：所有已加载层级共享同一指令池，每个始终加载的文件建议不超过 200 行。
- 提供分层记忆模型参考（references/memory-patterns.md），保持热记忆精简，把历史与可复用流程推到合适层级。
- 提供校验脚本，按作用域选择：单仓库 lint（scripts/lint_claude_memory.sh）、校验器回归测试（scripts/test_memory_scripts.sh）、单仓库审计（scripts/audit_repo.sh，含路径与幻觉诱饵检查）、多仓库组合审计（scripts/audit_portfolio.sh）、跨仓库对齐审查（scripts/compare_blocks.sh）。
- 提供作者面向指令：audit-path-prefix、audit-ignore、pre-code 等注释用于控制审计行为。
使用方式
- 添加或保留项目记忆中的每条内容前，先使用 AGENTS.md 收录清单。
- 从简短的根 AGENTS.md 或 CLAUDE.md 开始：项目用途、硬性约束、关键命令、必须不能破坏的规则。
- 优先写入精确命令、特殊设置步骤、部署怪癖、硬边界与验证规则，而非理念或概述性文字。
- 仅限 Claude 的细节应移入 .claude/rules/，避免膨胀共享文件。
- monorepo 中，在确实需要本地上下文的包或服务内添加嵌套 AGENTS.md。
- 技能目录庞大时，让 AGENTS.md 先指向紧凑的路由/发现映射，再指向完整目录。
- 在加入新层级前先定义冲突解决策略：当前任务指令优先于常驻记忆；更窄的仓库规则在其文档范围内优先于更广的个人指导；运行时权限策略对能力具有权威性。
常见命令
# 检查版本
claude --version
# 查看本次会话实际加载了哪些指令文件（Memory files 区段）
/context
# 浏览或编辑 CLAUDE.md、规则与自动记忆文件；切换自动记忆
/memory
# 直接查看自动记忆目录
ls ~/.claude/projects/"$(git rev-parse --show-toplevel | tr '/' '-')"/memory/
提交前记忆健康检查清单
- 运行
bash skills/universal/agents-memory/scripts/lint_claude_memory.sh .，要求 0 错误（无记忆文件的仓库会以非零退出，这是发现，不是通过）。 - 运行
bash skills/universal/agents-memory/scripts/audit_repo.sh .，要求无 HIGH 发现。 - 每个始终加载文件均少于 200 行（
wc -l CLAUDE.md AGENTS.md .claude/rules/*.md）。 - CLAUDE.md 中没有未解决的 {{placeholders}}（
rg "{{[^}]+}}" CLAUDE.md）。 - CLAUDE.md 与 AGENTS.md 不同时手工维护（使用符号链接或 @AGENTS.md 导入）。
- 手动编辑自动记忆 MEMORY.md 时，确保远低于运行时加载上限。
- 所有加载层级中的硬规则按一个池计数。
- 不包含消耗指令预算的性格类指令（如「像资深工程师一样思考」）。
- CLAUDE.md 中每条硬规则都能回答「这能防止什么错误？」。
- .claude/rules/ 中的作用域规则带有 paths: frontmatter 以做文件类型过滤。
- 生产构建产物中没有代理写入的记忆文件。
适用场景
- 希望 Codex 与 Claude Code 共享稳定仓库规则的团队。
- 需要把可移植项目规则放在 AGENTS.md、需要时镜像到 CLAUDE.md 的团队。
- monorepo 中需要按包/服务提供本地上下文的场景。
- 拥有大量技能或代理工作流、需要路由目录模式的仓库。
限制
- 对于用户、代理或知识的长期记忆系统（抽取、整合、时序事实、向量/图存储、记忆供应商），属于 ai-context-layer，不在本技能范围。
- 超出指令文件本身的上下文架构（冷热分层、编译知识库、上下文图、成熟度模型）属于 dev-context-engineering。
- 部分平台行为（如 Claude Code 是否原生读取 AGENTS.md）取决于版本、供应商及是否存在 CLAUDE.md 系文件，需先查阅文档确认。
- 错误标识符（Xcode scheme、函数名、构建标志）与跨文档一致性无法自动检查，仍需人工校验。
- 对外发布记忆建议前，需对照官方 Claude Code 与 Codex 文档重新核实平台行为。