{"id":"c35d4de5-cff8-4458-abf9-a9cab8dd0b1e","shortId":"zwsQxv","kind":"skill","title":"hierarchical-agent-memory","tagline":"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.","description":"# Hierarchical Agent Memory (HAM)\n\nScoped 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.\n\n## When to Use This Skill\n\n- Use when you want to reduce input token costs across Claude Code sessions\n- Use when your project has 3+ directories and the agent keeps re-reading the same files\n- Use when you want directory-scoped context instead of one monolithic CLAUDE.md\n- Use when you want a dashboard to visualize token savings, session history, and context health\n- Use when setting up a new project and want structured agent memory from day one\n\n## How It Works\n\n### Step 1: Setup (\"go ham\")\n\nAuto-detects your project platform and maturity, then generates the memory structure:\n\n```\nproject/\n├── CLAUDE.md              # Root context (~200 tokens)\n├── .memory/\n│   ├── decisions.md       # Architecture Decision Records\n│   ├── patterns.md        # Reusable patterns\n│   ├── inbox.md           # Inferred items awaiting confirmation\n│   └── audit-log.md       # Audit history\n└── src/\n    ├── api/CLAUDE.md      # Scoped context for api/\n    ├── components/CLAUDE.md\n    └── lib/CLAUDE.md\n```\n\n### Step 2: Context Routing\n\nThe root CLAUDE.md includes a routing section that tells the agent exactly which sub-context to load:\n\n```markdown\n## Context Routing\n\n→ api: src/api/CLAUDE.md\n→ components: src/components/CLAUDE.md\n→ lib: src/lib/CLAUDE.md\n```\n\nThe agent reads root, then immediately loads the relevant subdirectory context — no guessing.\n\n### Step 3: Dashboard (\"ham dashboard\")\n\nLaunches a web dashboard at localhost:7777 that visualizes:\n- Token savings (HAM-on vs HAM-off sessions)\n- Daily token and cost trends\n- Per-directory session breakdown\n- Context file health (missing/stale/inherited CLAUDE.md coverage)\n- Routing compliance (how often the agent follows the routing map)\n- Carbon/energy estimates\n\n## Commands\n\n| Trigger | What it does |\n|---|---|\n| `go ham` | Set up HAM — auto-detect platform, generate CLAUDE.md files |\n| `ham savings` | Show token and cost savings report |\n| `ham dashboard` | Launch the interactive web dashboard |\n| `ham audit` | Health check on memory files |\n| `ham insights` | Generate actionable insights from session data |\n| `ham route` | Add/update Context Routing section in root CLAUDE.md |\n| `ham carbon` | Show energy and carbon efficiency data |\n\n## Examples\n\n### Example 1: First-time setup\n\n```\nUser: go ham\n\nAgent: HAM setup complete. Created 8 files.\n  - CLAUDE.md (root)\n  - .memory/decisions.md\n  - .memory/patterns.md\n  - .memory/inbox.md\n  - src/api/CLAUDE.md\n  - src/components/CLAUDE.md\n  - src/lib/CLAUDE.md\n  - src/utils/CLAUDE.md\n\nBaseline captured in .memory/baseline.json\nRun \"HAM savings\" to see your token and cost savings.\n```\n\n### Example 2: Checking savings\n\n```\nUser: ham savings\n\nAgent:\n  Before HAM: ~7,500 tokens/prompt\n  After HAM:    ~450 tokens/prompt\n  Savings:    7,050 tokens (94%)\n\n  Monthly projection (1,500 prompts):\n    Sonnet: ~$31.73 saved\n    Opus:   ~$158.63 saved\n```\n\n## Best Practices\n\n- Keep root CLAUDE.md under 60 lines / 250 tokens\n- Keep subdirectory CLAUDE.md files under 75 lines each\n- Run `ham audit` every 2 weeks to catch stale or missing context files\n- Use `ham route` after adding new directories to keep routing current\n- Review `.memory/inbox.md` periodically — confirm or reject inferred items\n\n## Limitations\n\n- Token estimates use ~4 chars = 1 token approximation, not a real tokenizer\n- Baseline savings comparisons are estimates based on typical agent behavior\n- Dashboard requires Node.js 18+ and reads session data from `~/.claude/projects/`\n- Context routing detection relies on CLAUDE.md read order in session JSONL files\n- Does not auto-update subdirectory CLAUDE.md content — you maintain those manually or via `ham audit`\n- Carbon estimates use regional grid averages, not real-time energy data\n\n## Related Skills\n\n- `agent-memory-systems` — general agent memory architecture patterns\n- `agent-memory-mcp` — MCP-based memory integration","tags":["hierarchical","agent","memory","antigravity","awesome","skills","sickn33","agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding"],"capabilities":["skill","source-sickn33","skill-hierarchical-agent-memory","topic-agent-skills","topic-agentic-skills","topic-ai-agent-skills","topic-ai-agents","topic-ai-coding","topic-ai-workflows","topic-antigravity","topic-antigravity-skills","topic-claude-code","topic-claude-code-skills","topic-codex-cli","topic-codex-skills"],"categories":["antigravity-awesome-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/hierarchical-agent-memory","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add sickn33/antigravity-awesome-skills","source_repo":"https://github.com/sickn33/antigravity-awesome-skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 34768 github stars · SKILL.md body (4,254 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-23T18:51:26.515Z","embedding":null,"createdAt":"2026-04-18T21:38:24.656Z","updatedAt":"2026-04-23T18:51:26.515Z","lastSeenAt":"2026-04-23T18:51:26.515Z","tsv":"'/.claude/projects':534 '050':438 '1':172,381,443,508 '158.63':450 '18':528 '2':220,420,474 '200':66,193 '250':74,460 '3':113,264 '31.73':447 '4':506 '450':434 '500':430,444 '60':458 '7':429,437 '75':467 '7777':274 '8':394 '94':440 'across':104 'action':357 'ad':487 'add/update':364 'agent':3,26,34,44,117,163,233,251,308,389,426,523,578,582,587 'agent-memory-mcp':586 'agent-memory-system':577 'ai':42 'api':216,244 'api/claude.md':212 'approxim':510 'architectur':197,584 'audit':209,348,472,562 'audit-log.md':208 'auto':177,326,550 'auto-detect':176,325 'auto-upd':549 'averag':568 'await':206 'base':520,592 'baselin':405,515 'behavior':524 'best':452 'breakdown':296 'captur':406 'carbon':372,376,563 'carbon/energy':313 'catch':477 'char':507 'cheat':46 'check':350,421 'claud':105 'claude.md':6,62,69,137,190,225,301,330,370,396,456,464,540,553 'code':43,106 'command':315 'comparison':517 'complet':392 'complianc':304 'compon':246 'components/claude.md':217 'confirm':207,497 'content':554 'context':11,18,32,65,73,132,151,192,214,221,238,242,260,297,365,481,535 'cost':103,290,337,417 'coverag':302 'creat':14,393 'current':493 'daili':287 'dashboard':23,143,265,267,271,341,346,525 'data':361,378,532,574 'day':166 'decis':82,198 'decisions.md':196 'detect':178,327,537 'directori':16,50,114,130,294,489 'directory-level':15 'directory-scop':129 'effici':377 'energi':374,573 'entir':57 'estim':314,504,519,564 'everi':59,473 'exact':234 'exampl':379,380,419 'file':19,70,124,298,331,353,395,465,482,546 'first':383 'first-tim':382 'follow':309 'general':581 'generat':185,329,356 'give':41 'global':64 'go':174,320,387 'grid':567 'guess':262 'ham':36,175,266,280,284,321,324,332,340,347,354,362,371,388,390,410,424,428,433,471,484,561 'ham-off':283 'ham-on':279 'health':152,299,349 'hierarch':2,33 'hierarchical-agent-memori':1 'histori':149,210 'hold':63,71 'immedi':255 'inbox':86 'inbox.md':203 'includ':226 'infer':89,204,500 'input':101 'insight':355,358 'instead':51,133 'integr':594 'interact':344 'item':205,501 'jsonl':545 'keep':118,454,462,491 'launch':268,342 'layer':80 'level':17 'lib':248 'lib/claude.md':218 'limit':502 'line':459,468 'load':240,256 'localhost':273 'maintain':556 'manual':558 'map':312 'markdown':241 'matur':183 'mcp':589,591 'mcp-base':590 'memori':4,7,35,38,79,164,187,195,352,579,583,588,593 'memory/baseline.json':408 'memory/decisions.md':398 'memory/inbox.md':400,495 'memory/patterns.md':399 'miss':480 'missing/stale/inherited':300 'monolith':136 'month':441 'new':158,488 'node.js':527 'often':306 'one':135,167 'opus':449 'order':542 'pattern':83,202,585 'patterns.md':200 'per':293 'per-directori':292 'period':496 'platform':181,328 'practic':453 'project':58,111,159,180,189,442 'prompt':60,445 're':54,120 're-read':53,119 'read':55,121,252,530,541 'real':513,571 'real-tim':570 'record':199 'reduc':10,100 'region':566 'reject':499 'relat':575 'relev':258 'reli':538 'report':339 'requir':526 'reusabl':201 'review':494 'right':29 'root':61,191,224,253,369,397,455 'rout':25,222,228,243,303,311,363,366,485,492,536 'run':409,470 'save':21,147,278,333,338,411,418,422,425,436,448,451,516 'scope':5,37,72,131,213 'section':229,367 'see':413 'session':107,148,286,295,360,531,544 'set':155,322 'setup':173,385,391 'sheet':47 'show':334,373 'skill':94,576 'skill-hierarchical-agent-memory' 'sonnet':446 'source-sickn33' 'spend':13 'src':211 'src/api/claude.md':245,401 'src/components/claude.md':247,402 'src/lib/claude.md':249,403 'src/utils/claude.md':404 'stale':478 'step':171,219,263 'store':81 'structur':162,188 'sub':31,237 'sub-context':30,236 'subdirectori':68,259,463,552 'system':8,39,580 'tell':231 'time':384,572 'token':12,67,75,102,146,194,277,288,335,415,439,461,503,509,514 'tokens/prompt':431,435 'topic-agent-skills' 'topic-agentic-skills' 'topic-ai-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-ai-workflows' 'topic-antigravity' 'topic-antigravity-skills' 'topic-claude-code' 'topic-claude-code-skills' 'topic-codex-cli' 'topic-codex-skills' 'track':20 'trend':291 'trigger':316 'typic':522 'unconfirm':88 'updat':551 'use':92,95,108,125,138,153,483,505,565 'user':386,423 'via':22,560 'visual':145,276 'vs':282 'want':98,128,141,161 'web':270,345 'week':475 'work':170","prices":[{"id":"e7dd7293-3c3d-465d-97fc-65319d6a8ae4","listingId":"c35d4de5-cff8-4458-abf9-a9cab8dd0b1e","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"sickn33","category":"antigravity-awesome-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T21:38:24.656Z"}],"sources":[{"listingId":"c35d4de5-cff8-4458-abf9-a9cab8dd0b1e","source":"github","sourceId":"sickn33/antigravity-awesome-skills/hierarchical-agent-memory","sourceUrl":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/hierarchical-agent-memory","isPrimary":false,"firstSeenAt":"2026-04-18T21:38:24.656Z","lastSeenAt":"2026-04-23T18:51:26.515Z"}],"details":{"listingId":"c35d4de5-cff8-4458-abf9-a9cab8dd0b1e","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sickn33","slug":"hierarchical-agent-memory","github":{"repo":"sickn33/antigravity-awesome-skills","stars":34768,"topics":["agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows","antigravity","antigravity-skills","claude-code","claude-code-skills","codex-cli","codex-skills","cursor","cursor-skills","developer-tools","gemini-cli","gemini-skills","kiro","mcp","skill-library"],"license":"mit","html_url":"https://github.com/sickn33/antigravity-awesome-skills","pushed_at":"2026-04-23T06:41:03Z","description":"Installable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.","skill_md_sha":"1eb2fb296e5f0d9eb825c702aec2a705c20fabdf","skill_md_path":"skills/hierarchical-agent-memory/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/hierarchical-agent-memory"},"layout":"multi","source":"github","category":"antigravity-awesome-skills","frontmatter":{"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."},"skills_sh_url":"https://skills.sh/sickn33/antigravity-awesome-skills/hierarchical-agent-memory"},"updatedAt":"2026-04-23T18:51:26.515Z"}}