---

name: hierarchical-agent-memory description: "分层 CLAUDE.md 记忆系统，减少上下文 token 消耗。创建目录级上下文文件，通过仪表板跟踪节省量，并将代理路由到正确的子上下文。" risk: safe source: "https://github.com/kromahlusenii-ops/ham" date_added: "2026-02-27"

分层代理记忆 (HAM)

分层记忆系统，为 AI 编码代理提供每个目录的速查表，而不是每次提示都重新读取整个项目。根 CLAUDE.md 保存全局上下文（约 200 token），子目录 CLAUDE.md 文件保存范围上下文（每个约 250 token），.memory/ 层存储决策、模式和未确认推断的收件箱。

适用场景

• 当你想减少 Claude Code 会话间的输入 token 成本时使用
• 当你的项目有 3 个以上目录且代理不断重新读取相同文件时使用
• 当你想要目录范围的上下文而非一个庞大的 CLAUDE.md 时使用
• 当你想要仪表板来可视化 token 节省、会话历史和上下文健康度时使用
• 当设置新项目并希望从第一天就有结构化代理记忆时使用

工作原理

步骤 1：设置（"go ham"）

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

project/
├── CLAUDE.md              # 根上下文（约 200 token）
├── .memory/
│   ├── decisions.md       # 架构决策记录
│   ├── patterns.md        # 可复用模式
│   ├── inbox.md           # 等待确认的推断项
│   └── audit-log.md       # 审计历史
└── src/
    ├── api/CLAUDE.md      # api/ 的范围上下文
    ├── components/CLAUDE.md
    └── lib/CLAUDE.md

步骤 2：上下文路由

根 CLAUDE.md 包含路由部分，告诉代理确切加载哪个子上下文：

## Context Routing

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

代理读取根文件，然后立即加载相关子目录上下文 - 无需猜测。

步骤 3：仪表板（"ham dashboard"）

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

• Token 节省（HAM 开启 vs HAM 关闭的会话）
• 每日 token 和成本趋势
• 每目录会话分解
• 上下文文件健康度（缺失/过期/继承的 CLAUDE.md 覆盖率）
• 路由合规性（代理遵循路由映射的频率）
• 碳排放/能源估算

命令

| 触发器 | 功能 | |---|---| | 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 的近似值，非真实分词器
• 基线节省比较是基于典型代理行为的估算
• 仪表板需要 Node.js 18+ 并从 ~/.claude/projects/ 读取会话数据
• 上下文路由检测依赖于会话 JSONL 文件中的 CLAUDE.md 读取顺序
• 不会自动更新子目录 CLAUDE.md 内容 - 你需要手动维护或通过 ham audit
• 碳估算使用区域电网平均值，非实时能源数据

相关技能

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