Agent-Skills.md

Agent Skills: Hierarchical Agent Memory (HAM)

Scoped CLAUDE.md memory system that reduces context token spend. Creates directory-level context files, tracks savings via dashboard, and routes agents to the right sub-context.

UncategorizedID: sickn33/antigravity-awesome-skills/hierarchical-agent-memory

Repository

sickn33/antigravity-awesome-skills
sickn33License: MIT
27,0474,580

Install this agent skill to your local

pnpm dlx add-skill https://github.com/sickn33/antigravity-awesome-skills/tree/HEAD/skills/hierarchical-agent-memory

Skill Files

Browse the full folder contents for hierarchical-agent-memory.

Download Skill

Loading file tree…

skills/hierarchical-agent-memory/SKILL.md

Skill Metadata

Name
hierarchical-agent-memory
Description
"Scoped CLAUDE.md memory system that reduces context token spend. Creates directory-level context files, tracks savings via dashboard, and routes agents to the right sub-context."

Hierarchical Agent Memory (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.

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

How It Works

Step 1: Setup ("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

Step 2: Context Routing

The root CLAUDE.md includes a routing section that tells the agent exactly which sub-context to load:

## 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.

Step 3: Dashboard ("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

Commands

| Trigger | What 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 |

Examples

Example 1: First-time setup

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.

Example 2: Checking savings

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

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

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

Related Skills

  • agent-memory-systems — general agent memory architecture patterns
  • agent-memory-mcp — MCP-based memory integration