hierarchical-agent-memory

分层 Agent 记忆（HAM）

为 AI 编码 Agent 提供按目录划分的备忘单，而不是每次提示都重新读取整个项目。根目录的 CLAUDE.md 保存全局上下文（约 200 个 token），子目录中的 CLAUDE.md 文件保存各自范围内的上下文（每个约 250 个 token），而 .memory/ 层则用于存储决策、模式，以及存放未经确认的推断的收件箱。

何时使用此技能

• 如果你想在 Claude Code 会话中降低输入 token 成本，请使用此技能
• 如果你的项目有 3 个或更多目录，而且 Agent 不断重复读取相同文件，请使用此技能
• 如果你想要按目录划分的上下文，而不是一个庞大的 CLAUDE.md，请使用此技能
• 如果你想要通过仪表板可视化 token 节省量、会话历史和上下文健康状况，请使用此技能
• 如果你要设置新项目，并希望从第一天起就拥有结构化的 Agent 记忆，请使用此技能

可用性与证据

此目录仅包含指南；不包含 HAM CLI、仪表板或 tokenizer。go ham 和 ham ... 是上游工作流约定；在调用它们或声称相关文件、仪表板或节省效果存在之前，请先确认实际安装了经过审查的实现。添加上下文时应保留现有项目指令，将推断项保持为未确认状态，并在读取私人会话历史前取得授权。报告实测 token 用量时，应与建模估算的节省量、成本和碳排示例分开；不要将不同任务进行比较并声称已证明有所改进。

工作原理

步骤 1：设置（“go ham”）

自动检测项目平台和成熟度，然后生成记忆结构：

project/
├── CLAUDE.md              # Root context (~200 tokens)
├── .memory/
│   ├── decisions.md       # Architecture Decision Records
│   ├── patterns.md        # Reusable patterns
│   ├── inbox.md           # Inferred items awaiting confirmation
│   └── audit-log.md       # Audit history
└── src/
    ├── api/CLAUDE.md      # Scoped context for api/
    ├── components/CLAUDE.md
    └── lib/CLAUDE.md

步骤 2：上下文路由

根目录的 CLAUDE.md 中包含一个路由部分，明确告知 Agent 应加载哪些子上下文：

## Context Routing

→ api: src/api/CLAUDE.md
→ components: src/components/CLAUDE.md
→ lib: src/lib/CLAUDE.md

Agent 先读取根目录，然后立即加载相关子目录的上下文，无需猜测。

步骤 3：仪表板（“ham dashboard”）

在 localhost:7777 启动 Web 仪表板，用于可视化：

• token 节省量（启用 HAM 与未启用 HAM 的会话）
• 每日 token 和成本趋势
• 按目录划分的会话明细
• 上下文文件健康状况（CLAUDE.md 覆盖情况：缺失、过时或继承）
• 路由合规情况（Agent 遵循路由图的频率）
• 碳排放／能源估算

命令

触发方式	功能
go ham	设置 HAM——自动检测平台并生成 CLAUDE.md 文件
ham savings	显示 token 和成本节省报告
ham dashboard	启动交互式 Web 仪表板
ham audit	检查记忆文件的健康状况
ham insights	根据会话数据生成可执行的见解
ham route	在根目录的 CLAUDE.md 中添加／更新上下文路由部分
ham carbon	显示能源和碳效益数据

示例

示例 1：首次设置

User: go ham

Agent: HAM setup complete. Created 8 files.
  - CLAUDE.md (root)
  - .memory/decisions.md
  - .memory/patterns.md
  - .memory/inbox.md
  - src/api/CLAUDE.md
  - src/components/CLAUDE.md
  - src/lib/CLAUDE.md
  - src/utils/CLAUDE.md

Baseline captured in .memory/baseline.json
Run "HAM savings" to see your token and cost savings.

示例 2：检查节省量

User: ham savings

Agent:
  Before HAM: ~7,500 tokens/prompt
  After HAM:    ~450 tokens/prompt
  Savings:    7,050 tokens (94%)

  Monthly projection (1,500 prompts):
    Sonnet: ~$31.73 saved
    Opus:   ~$158.63 saved

最佳实践

• 将根目录的 CLAUDE.md 控制在 60 行／250 个 token 以内
• 将子目录中的 CLAUDE.md 文件控制在每个 75 行以内
• 每 2 周运行一次 ham audit，以发现过时或缺失的上下文文件
• 添加新目录后运行 ham route，以保持路由信息为最新
• 定期检查 .memory/inbox.md，确认或拒绝推断项

限制

• token 估算采用约 4 个字符 = 1 个 token 的近似值，并非使用真实 tokenizer
• 基线节省量比较是基于 Agent 典型行为的估算
• 仪表板需要 Node.js 18+，并从 ~/.claude/projects/ 读取会话数据
• 上下文路由检测依赖会话 JSONL 文件中 CLAUDE.md 的读取顺序
• 不会自动更新子目录中 CLAUDE.md 的内容——你需要手动维护，或通过 ham audit 维护
• 碳排估算采用区域电网平均值，而非实时能源数据

相关技能

• agent-memory-systems — 通用 Agent 记忆架构模式
• agent-memory-mcp — 基于 MCP 的记忆集成