Back to Details

hierarchical-agent-memory

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Hierarchical Agent Memory (HAM)

分层Agent内存系统（HAM）

Scoped memory system that gives AI coding agents a cheat sheet for each directory instead of re-reading your entire project every prompt. Root CLAUDE.md holds global context (~200 tokens), subdirectory CLAUDE.md files hold scoped context (~250 tokens each), and a 
.memory/
layer stores decisions, patterns, and an inbox for unconfirmed inferences.
这是一个作用域内存系统，可为AI编码Agent提供每个目录的“备忘单”，无需在每次提示时重新读取整个项目。根目录下的CLAUDE.md存储全局上下文（约200个Token），子目录的CLAUDE.md文件存储作用域上下文（每个约250个Token），而
.memory/
层则用于存储决策、模式以及待确认推论的收件箱。

When to Use This Skill

何时使用该技能

  • Use when you want to reduce input token costs across Claude Code sessions
  • Use when your project has 3+ directories and the agent keeps re-reading the same files
  • Use when you want directory-scoped context instead of one monolithic CLAUDE.md
  • Use when you want a dashboard to visualize token savings, session history, and context health
  • Use when setting up a new project and want structured agent memory from day one
  • 当你希望在Claude Code会话中降低输入Token成本时使用
  • 当你的项目包含3个以上目录，且Agent持续重复读取相同文件时使用
  • 当你需要目录级作用域上下文，而非单一整体的CLAUDE.md时使用
  • 当你需要通过仪表盘可视化Token节省量、会话历史及上下文健康状况时使用
  • 当你启动新项目，希望从第一天起就拥有结构化Agent内存时使用

How It Works

工作原理

Step 1: Setup ("go ham")

步骤1：设置（执行"go ham"命令）

Auto-detects your project platform and maturity, then generates the memory structure:
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
自动检测你的项目平台和成熟度，然后生成内存结构：
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

Step 2: Context Routing

步骤2：上下文路由

The root CLAUDE.md includes a routing section that tells the agent exactly which sub-context to load:
markdown
undefined
根目录的CLAUDE.md包含一个路由部分，明确告知Agent应加载哪个子上下文：
markdown
undefined

Context Routing

Context Routing

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

The agent reads root, then immediately loads the relevant subdirectory context — no guessing.
→ api: src/api/CLAUDE.md → components: src/components/CLAUDE.md → lib: src/lib/CLAUDE.md

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

Step 3: Dashboard ("ham dashboard")

步骤3：仪表盘（执行"ham dashboard"命令）

Launches a web dashboard at localhost:7777 that visualizes:
  • Token savings (HAM-on vs HAM-off sessions)
  • Daily token and cost trends
  • Per-directory session breakdown
  • Context file health (missing/stale/inherited CLAUDE.md coverage)
  • Routing compliance (how often the agent follows the routing map)
  • Carbon/energy estimates
在localhost:7777启动一个Web仪表盘，可视化展示以下内容：
  • Token节省量（启用HAM与未启用HAM的会话对比）
  • 每日Token消耗及成本趋势
  • 按目录划分的会话明细
  • 上下文文件健康状况（缺失/过期/继承的CLAUDE.md覆盖情况）
  • 路由合规性（Agent遵循路由映射的频率）
  • 碳排放/能耗估算

Commands

命令列表

TriggerWhat it does
go ham
Set up HAM — auto-detect platform, generate CLAUDE.md files
ham savings
Show token and cost savings report
ham dashboard
Launch the interactive web dashboard
ham audit
Health check on memory files
ham insights
Generate actionable insights from session data
ham route
Add/update Context Routing section in root CLAUDE.md
ham carbon
Show energy and carbon efficiency data
触发命令功能说明
go ham
搭建HAM系统——自动检测平台，生成CLAUDE.md文件
ham savings
展示Token及成本节省报告
ham dashboard
启动交互式Web仪表盘
ham audit
对内存文件进行健康检查
ham insights
从会话数据生成可执行的洞察信息
ham route
在根目录CLAUDE.md中添加/更新Context Routing部分
ham carbon
展示能耗及碳排放效率数据

Examples

使用示例

Example 1: First-time setup

示例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.
用户: go ham

Agent: HAM搭建完成。已创建8个文件。
  - CLAUDE.md (根目录)
  - .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

基准数据已保存至.memory/baseline.json
执行"HAM savings"查看你的Token及成本节省情况。

Example 2: Checking 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
用户: ham savings

Agent:
  启用HAM前: 约7,500 Token/次提示
  启用HAM后: 约450 Token/次提示
  节省量: 7,050 Token（94%）

  月度预估（1,500次提示）:
    Sonnet: 约节省$31.73
    Opus:   约节省$158.63

Best Practices

最佳实践

  • Keep root CLAUDE.md under 60 lines / 250 tokens
  • Keep subdirectory CLAUDE.md files under 75 lines each
  • Run 
    ham audit
    every 2 weeks to catch stale or missing context files
  • Use 
    ham route
    after adding new directories to keep routing current
  • Review 
    .memory/inbox.md
    periodically — confirm or reject inferred items
  • 根目录CLAUDE.md保持在60行/250个Token以内
  • 子目录CLAUDE.md文件每行不超过75行
  • 每2周执行一次
    ham audit
    ，排查过期或缺失的上下文文件
  • 添加新目录后使用
    ham route
    命令，保持路由信息最新
  • 定期查看
    .memory/inbox.md
    ——确认或拒绝推论项

Limitations

局限性

  • Token estimates use ~4 chars = 1 token approximation, not a real tokenizer
  • Baseline savings comparisons are estimates based on typical agent behavior
  • Dashboard requires Node.js 18+ and reads session data from 
    ~/.claude/projects/
  • Context routing detection relies on CLAUDE.md read order in session JSONL files
  • Does not auto-update subdirectory CLAUDE.md content — you maintain those manually or via 
    ham audit
  • Carbon estimates use regional grid averages, not real-time energy data
  • Token估算采用约4字符=1Token的近似值，而非真实的Token解析器
  • 基准节省量对比是基于典型Agent行为的估算值
  • 仪表盘需要Node.js 18+，并从
    ~/.claude/projects/
    读取会话数据
  • 上下文路由检测依赖会话JSONL文件中CLAUDE.md的读取顺序
  • 不会自动更新子目录CLAUDE.md的内容——你需要手动维护或通过
    ham audit
    更新
  • 碳排放估算采用区域电网平均值，而非实时能耗数据

Related Skills

相关技能

  • agent-memory-systems
    — general agent memory architecture patterns
  • agent-memory-mcp
    — MCP-based memory integration
  • agent-memory-systems
    —— 通用Agent内存架构模式
  • agent-memory-mcp
    —— 基于MCP的内存集成