/ham

name: ham
ham_version: "2026.02.28"
description: Set up Hierarchical Agent Memory (HAM) — scoped CLAUDE.md files per directory that reduce token spend. Trigger on "go ham", "set up HAM", "ham commands", "ham help", "ham route", "ham remove", "ham update", "ham status", "ham benchmark", "ham baseline start", "ham baseline stop", "ham metrics clear", "HAM savings", "HAM stats", "HAM dashboard", "HAM sandwich", "HAM insights", "HAM carbon", or "ham sync".

Pro Guard — run FIRST

Before ANY command, check for Pro signals: `.ham/config.json` with `"pro": true`, `enabledImporters` with more than `"claude"`, or any `**/AGENTS.md` files.

• **If Pro detected:** allow `go ham` (Pro-aware mode) and `ham remove` (has own Pro logic). All other commands → print `HAM Pro detected — this project is managed by HAM Pro. Manage at goham.dev` and STOP.
• **Pro rules:** NEVER create/modify/delete AGENTS.md files. CLAUDE.md = HAM-owned. AGENTS.md = Pro-owned.

Commands

**Trigger:** "ham commands" or "ham help" — list all commands:

| Command | What it does | |---|---| | `go ham` | Set up HAM (auto-detects stack and structure) | | `ham remove` | Remove HAM safely (preserves Pro files) | | `ham update` | Run `bash <skill-dir>/scripts/update.sh`, update `.ham/version` | | `ham status` | Show version, update status, memory file count, last setup date | | `ham route` | Add/update Context Routing in root CLAUDE.md | | `ham dashboard` | Launch web dashboard at :7777 via `node <skill-dir>/dashboard/launch.js --port 7777` | | `ham savings` | Show token and cost savings report | | `ham carbon` | Run `node <skill-dir>/dashboard/carbon-cli.js [--last] [--days 30]` | | `ham insights` | Generate insights → write actionable items to `.memory/inbox.md` | | `ham benchmark` | Run `node <skill-dir>/dashboard/benchmark-cli.js [--days 30] [--model name] [--json]` | | `ham baseline start` | Begin 10-task baseline capture | | `ham baseline stop` | End baseline early, keep partial data | | `ham metrics clear` | Delete all benchmark data (confirm first) | | `ham audit` | Check memory system health | | `ham sync` | Sync Claude Code sessions → `.ham/metrics/sessions.jsonl`. Run `node <skill-dir>/dashboard/sync-cli.js [--force] [--json]` |

go ham — Setup

0. **Update check** — compare `.ham/version` against `ham_version` in frontmatter. If outdated, print update notice. Never block. 1. **Detect platform** — scan for: `*.xcodeproj`/`Package.swift` (iOS), `build.gradle*` (Android), `pubspec.yaml` (Flutter), `package.json` + framework (Web/RN), `pyproject.toml`/`requirements.txt` (Python), `Cargo.toml` (Rust), `go.mod` (Go). 2. **Detect maturity** — count subdirs with code: 0-2 = greenfield, 3+ = brownfield. 3. **Monorepo guard** — if >20 code dirs: present sorted list, pre-select top 15, let user adjust. Hard cap: never create >20 subdirectory CLAUDE.md files. 4. **Generate files** silently, then confirm.

**Pro-aware mode:** if Pro detected, skip directories with existing CLAUDE.md (Pro-created). Fill gaps only. Never touch AGENTS.md.

Generated Structure

project/
├── CLAUDE.md              # Root (~200 tokens)
├── .ham/
│   ├── version
│   └── metrics/state.json # {mode, tasks_completed, tasks_target, started_at, memory_reads, total_prompts}
├── .memory/
│   ├── decisions.md       # ADRs
│   ├── patterns.md        # Reusable patterns
│   ├── inbox.md           # Inferred items (brownfield only)
│   └── audit-log.md       # Audit history (last 5 entries)
└── [src dirs]/CLAUDE.md   # Per-directory (brownfield only)

Greenfield: root + .memory/ + .ham/ only. Brownfield: also subdirectory CLAUDE.md files.

.gitignore

Append (idempotent — check for `# HAM` marker first):

# HAM — AI agent scaffolding (local, do not commit)
.ham/
.memory/
**/CLAUDE.md
!CLAUDE.md
# end HAM

Capture Baseline

Before creating files, save `.memory/baseline.json`:

{"captured_at":"YYYY-MM-DD","existing_claude_md":{"found":true,"chars":4820,"tokens":1205},"notes":"Migrated from monolithic CLAUDE.md"}

If no existing CLAUDE.md: `{"captured_at":"...","existing_claude_md":{"found":false},"estimated_baseline_tokens":7500}`.

Initialize Benchmarking

Create `.ham/metrics/state.json`: `{"mode":"baseline","tasks_completed":0,"tasks_target":10,"started_at":"ISO-8601","memory_reads":0,"total_prompts":0}`. Next 10 tasks log to `baseline.jsonl` without HAM memory loading. Auto-transitions to active after 10.

Confirm Setup

Report files created. If root CLAUDE.md >3,000 tokens: warn, list sections that may belong in subdirectory files, offer interactive migration (present each candidate one at a time, move only on user confirmation).

Operating Instructions

Embed in every root CLAUDE.md:

## Agent Memory System

### Before Working
- Read this file for global context, then read the target directory's CLAUDE.md before changes
- If this file has a ## Context Routing section, use it to find the right subdirectory CLAUDE.md
- Check .memory/decisions.md before architectural changes
- Check .memory/patterns.md before implementing common functionality
- Check if audit is due: if 14+ days or 10+ sessions since last audit in .memory/audit-log.md, suggest running one

### During Work
- Create CLAUDE.md in any new directory you create

### After Work
- Update relevant CLAUDE.md if conventions changed
- Log decisions to .memory/decisions.md (ADR format)
- Log patterns to .memory/patterns.md
- Uncertain inferences → .memory/inbox.md (never canonical files)

### Safety
- Never record secrets, API keys, or user data
- Never overwrite decisions — mark as [superseded]
- Never promote from inbox without user confirmation

Task Metrics Logging

Each non-trivial task logs two JSONL entries to `.ham/metrics/tasks.jsonl` (or `baseline.jsonl` in baseline mode):

{"id":"task-<hex8>","type":"task_start","timestamp":"ISO-8601","description":"...","ham_active":true,"model":"claude-opus-4-6","files_read":0,"