Reduce AI coding agent token costs with scoped memory

Hierarchical Agent Memory (HAM) replaces one monolithic CLAUDE.md with a scoped memory system: a root CLAUDE.md holding global context at roughly 200 tokens, per-subdirectory CLAUDE.md files at roughly 250 tokens each, and a .memory/ layer holding architecture decision records (decisions.md), reusable patterns (patterns.md), an inbox of inferred items awaiting confirmation (inbox.md), and an audit log. Running go ham auto-detects the project's platform and maturity and generates this whole structure in one pass, capturing a token-usage baseline. The root CLAUDE.md includes a Context Routing section mapping named areas to their subdirectory file, for example → api: src/api/CLAUDE.md, so the agent reads root context, then loads exactly the relevant scoped file instead of guessing or re-reading the whole project. ham dashboard launches a local web dashboard at localhost:7777 visualizing token savings between HAM-on and HAM-off sessions, daily token and cost trends, per-directory session breakdowns, context-file health (missing, stale, or inherited coverage), how often the agent actually follows the routing map, and carbon and energy estimates. Other commands: ham savings, a token and cost savings report, for example dropping from roughly 7,500 to roughly 450 tokens per prompt, about 94%, with a monthly dollar projection for Sonnet versus Opus; ham audit, a health check on memory files; ham insights, actionable insights from session data; ham route, to add or refresh the routing section; and ham carbon, energy and carbon efficiency data.

Use it to cut input token costs across Claude Code sessions, once a project has 3+ directories and the agent keeps re-reading the same files, to get directory-scoped context instead of one giant CLAUDE.md, to get a dashboard visualizing token savings and context health, or to set up structured agent memory from day one on a new project. Its stated limitations matter for how much to trust the numbers: token estimates use a roughly 4-chars-per-token approximation rather than a real tokenizer, baseline savings comparisons are estimates based on typical agent behavior, carbon estimates use regional grid averages rather than real-time data, and it does not auto-update subdirectory CLAUDE.md content - you maintain those manually or via ham audit.

Input: the project's directory structure and, for savings or insights commands, prior session data. Output: a root and per-subdirectory CLAUDE.md set plus a .memory/ folder with decisions, patterns, inbox, and audit log, a captured token baseline, and, via the dashboard or CLI commands, savings reports, context-health audits, routing-compliance stats, and carbon estimates.

• Requires Node.js 18+ for the dashboard, which reads session data from the agent's local skill directory
• Context-routing detection relies on CLAUDE.md read order in session JSONL files
• Related skills: agent-memory-systems for general memory architecture, agent-memory-mcp for MCP-based memory integration

Teams running Claude Code on multi-directory projects who want to cut re-read token costs with scoped context files, and who want visibility into whether the agent actually follows the routing they set up.