hierarchical-agent-memory

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.
type	skill
created	2026-02-27T00:00:00.000Z
domain	productivity
category	developer-experience
risk	safe
source	https://github.com/kromahlusenii-ops/ham
tags	["skill","productivity","developer-experience","hierarchical","agent","memory"]

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