
关于
分层 CLAUDE.md 记忆系统,减少上下文 Token 消耗。创建目录级上下文文件,通过仪表盘追踪节省量,并将代理路由到正确的子上下文。
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 的记忆集成
兼容工具
Claude CodeCursor
标签
AI与机器学习