AI coding agents are stateless. Every new session, they re-scan your entire codebase to figure out where they are. That burns thousands of tokens before writing a single line of code. I hit this building my own products. So I built HAM. HAM gives agents scoped memory files at every directory level. Instead of re-reading everything, the agent reads a small file that says what's here, what decisions were made, and what happened last session.

Based on my observations, creating a directory with relevant claude.md files tends to increase file count, and claude --resume already stores code-related data. Given this, I'm wondering if it might be worth considering an alternative approach — summarizing the entire code and its actions instead. From what I understand, Claude handles this through a planning process, where we define a to-do list before starting a project or idea, iterate on it until we're satisfied, and then ask it to build accordingly. With this approach in place, I'm curious whether HAM is still necessary — just wanted to share this thought for consideration, not to dismiss anything.

Good question and appreciate the thoughtful framing.

--resume and planning mode solve different problems than HAM. --resume carries forward one session's state. Planning mode structures one task. Neither gives the agent persistent knowledge about the codebase across sessions, across tasks, or across developers.

If you start a fresh session tomorrow in src/api/, --resume doesn't help unless you're literally continuing yesterday's session. HAM means every new session in that directory starts with the right context — conventions, patterns, decisions — regardless of what came before.

They're complementary. I use all three together.

The file count concern is fair though. Not every directory needs a CLAUDE.md. v0.2 adds a routing section in the root file that maps which directories actually need context files. So instead of scattering them everywhere, you're explicit about which folders the agent frequently works in and only those get context files. Fewer files, higher quality.

The stateless problem compounds when you're running multiple agents, not just one. Each agent re-scanning means N × full-codebase-reads per session.

I took a different angle than directory-scoped files. Every agent action gets logged to an append-only NDJSON ledger — what was done, why, what it affected. New sessions load a compressed summary from the ledger instead of re-scanning source. After 6 months and 1100+ entries, cold-start context dropped from ~40k tokens to under 3k.

The key insight was separating "what's here" (which changes slowly) from "what happened" (which changes constantly). Directory-level memory handles the first well but can drift on the second. A receipt-based approach lets you reconstruct both, plus you get an audit trail for free.

One thing I'd add: governance matters as much as memory. Without constraints on what agents can read/write per session, memory files become a dumping ground. I use a 3-hook pipeline that scopes each agent's context window before it even starts

Curious how HAM handles conflict when two agents modify overlapping directory scopes.

This is a really sharp breakdown.

The "what's here" vs "what happened" framing is exactly right. HAM's CLAUDE.md files handle the first — conventions, stack decisions, patterns. We have a .memory/ layer (decisions.md, session logs) for the second, but your ledger approach sounds like it handles "what happened" more cleanly than what we're doing. 40k down to 3k cold-start is a serious number. Would love to hear more about your NDJSON setup if you're open to sharing.

The governance point is the one that sticks with me most. Right now HAM is permissive — the agent reads context files but nothing constrains what it can scan beyond that. Your 3-hook pipeline that scopes the context window before the agent starts is a stronger guarantee. Curious what the three hooks are and how you handle edge cases where the agent needs context outside its scoped window mid-task.

On multi-agent conflict — context files are read-only during sessions. The agent never writes to them. Conflicts happen when two developers update the same CLAUDE.md, which resolves at the git/PR layer.

Our approaches seem complementary more than competing. The ledger and directory-scoped files could work together well. Down to compare notes if you're interested.