name: ham description: Set up and maintain Hierarchical Agent Memory (HAM) for Codex using scoped local memory files. 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 audit".

HAM

Use this skill to apply the file-based HAM workflow from this repo in Codex. Work through CLAUDE.md, scoped CLAUDE.md files, .memory/*, and .ham/*. Do not introduce MCP-based behavior into this skill.

Current HAM skill version: 2026.02.28

Pro Guard

Before any HAM command, check for Pro signals:

• .ham/config.json with "pro": true
• enabledImporters with more than "claude"
• any **/AGENTS.md files

If Pro is detected:

• allow go ham in Pro-aware mode
• allow ham remove because it has its own removal logic
• for all other HAM commands, print HAM Pro detected — this project is managed by HAM Pro. Manage at goham.dev and stop

Never create, modify, or delete AGENTS.md files from this skill.

Commands

ham commands / ham help

List the supported HAM workflows and what each one does:

• go ham: set up HAM and detect project structure
• ham remove: remove HAM safely while preserving Pro-owned files
• ham update: run bash <skill-dir>/scripts/update.sh and update .ham/version
• ham status: show version, update status, memory file count, and last setup signal
• ham route: add or update ## Context Routing in root CLAUDE.md
• ham dashboard: launch the dashboard on port 7777
• HAM savings: show token and cost savings
• ham carbon: run the carbon report
• ham insights: generate actionable inbox items from session data
• ham benchmark: compare baseline and HAM performance
• ham baseline start: begin baseline capture
• ham baseline stop: stop baseline capture early
• ham metrics clear: clear benchmark data after confirmation
• ham audit: check memory system health

go ham

1. Compare .ham/version to 2026.02.28. If outdated, print an update notice. Never block setup.
2. Detect platform signals:
   • *.xcodeproj or Package.swift: iOS
   • build.gradle*: Android
   • pubspec.yaml: Flutter
   • package.json with framework hints: Web or React Native
   • pyproject.toml or requirements.txt: Python
   • Cargo.toml: Rust
   • go.mod: Go
3. Detect maturity:
   • 0-2 code directories: greenfield
   • 3+ code directories: brownfield
4. For large repos, apply a monorepo guard:
   • if there are more than 20 candidate code directories, present a sorted list
   • pre-select the top 15 most likely directories
   • let the user adjust when needed
   • never create more than 20 scoped CLAUDE.md files
5. Generate files silently, then confirm what was created.

Pro-aware mode:

• if Pro is detected, skip directories that already have CLAUDE.md
• fill gaps only
• never touch AGENTS.md

Generated structure:

project/
├── CLAUDE.md
├── .ham/
│   ├── version
│   └── metrics/state.json
├── .memory/
│   ├── decisions.md
│   ├── patterns.md
│   ├── inbox.md
│   └── audit-log.md
└── [major code dirs]/CLAUDE.md

Greenfield: create root files only. Brownfield: also create scoped CLAUDE.md files in major code areas.

Append the HAM block to .gitignore if missing:

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

Before creating files, capture .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 root CLAUDE.md exists:

{"captured_at":"YYYY-MM-DD","existing_claude_md":{"found":false},"estimated_baseline_tokens":7500}

Create .ham/metrics/state.json with baseline mode enabled:

{"mode":"baseline","tasks_completed":0,"tasks_target":10,"started_at":"ISO-8601","memory_reads":0,"total_prompts":0}

The next 10 non-trivial tasks should log to baseline mode without HAM memory loading. Auto-transition to active after 10 completed tasks.

If root CLAUDE.md is over 3,000 tokens, warn that it is oversized, list sections that should probably move into scoped CLAUDE.md files, and offer migration guidance one section at a time.

Operating Instructions

Embed these ideas in the generated root CLAUDE.md:

• read root CLAUDE.md before work
• read the target directory CLAUDE.md before changes
• if root CLAUDE.md has ## Context Routing, use it to find the right scoped file
• check .memory/decisions.md before architectural changes
• check .memory/patterns.md before implementing common functionality
• check if audit is due: if 14 or more days or 10 or more sessions have passed since the last audit in .memory/audit-log.md, suggest running one
• create CLAUDE.md in new directories when they need distinct guidance
• update relevant memory files after work
• keep uncertain inferences in .memory/inbox.md
• never record secrets or user data
• never overwrite historical decisions; mark them superseded

ham route

1. Find all scoped CLAUDE.md files excluding the root file.
2. Build a ## Context Routing section in root CLAUDE.md.
3. Add or update entries without deleting unrelated user-written content.

ham status

Report:

• installed version from .ham/version if present
• whether root HAM files exist
• scoped memory file count
• last setup signal if discoverable
• whether baseline tracking is active
• whether an update appears available

ham audit

Check:

• root CLAUDE.md size
• oversized scoped CLAUDE.md files
• missing scoped memory in major code directories
• .memory/ entry counts
• unreviewed inbox items

Append a short result to .memory/audit-log.md.

HAM savings / HAM stats

Read .memory/baseline.json, estimate token load from all CLAUDE.md and .memory/*.md files, and compare baseline versus current HAM setup. If no baseline exists, show raw counts and tell the user savings percentage requires a real baseline.

Use this calculation model:

root_tokens = count_tokens(read("CLAUDE.md"))
subdir_files = glob("**/CLAUDE.md", exclude="root")
avg_subdir = sum(count_tokens(read(f)) for f in subdir_files) / len(subdir_files) if subdir_files else 0

memory_tokens = sum(count_tokens(read(f)) for f in glob(".memory/*.md"))
state = read_json(".ham/metrics/state.json")
memory_weight = state["memory_reads"] / state["total_prompts"] if state.get("total_prompts", 0) >= 10 else 0.30
ham_tokens = root_tokens + avg_subdir + (memory_tokens * memory_weight)

if exists(".memory/baseline.json"):
    baseline_mid = baseline_data["old_claude_md_tokens"] + max(500, len(subdir_files) * 300)
    baseline_is_measured = True
else:
    code_dirs = count_dirs_with_code()
    baseline_mid = max(1000, ham_tokens * 1.5) if code_dirs <= 2 else max(3000, ham_tokens * 2.5) if code_dirs <= 10 else max(5000, ham_tokens * 3.5)
    baseline_is_measured = False

Display rules:

• if baseline is estimated, show raw token counts only
• do not show savings percentage or monthly projections without a real baseline
• label .memory/ weighting as estimated until at least 10 prompts are tracked

ham baseline start / ham baseline stop

• start: write .ham/metrics/state.json with mode: "baseline"
• stop: set mode: "active" and report captured tasks

Task Metrics Logging

Each non-trivial task should log two JSONL entries to .ham/metrics/tasks.jsonl, or baseline.jsonl while baseline mode is active:

{"id":"task-<hex8>","type":"task_start","timestamp":"ISO-8601","description":"...","ham_active":true,"model":"codex","files_read":0,"memory_files_loaded":0,"estimated_tokens":0}
{"id":"task-<hex8>","type":"task_end","timestamp":"ISO-8601","status":"completed"}

Skip trivial queries such as HAM commands, yes or no answers, and clarifications.

Baseline mode rules:

1. If mode = "baseline", write to baseline.jsonl, set ham_active: false, skip scoped CLAUDE.md and .memory/ reads, and increment tasks_completed only for completed tasks.
2. If mode = "active", or the state file is missing or unparseable, write to tasks.jsonl, set ham_active: true, and use HAM memory normally.
3. If the state file is corrupt, warn once and treat the repo as active mode.

ham benchmark

Run node <skill-dir>/dashboard/benchmark-cli.js [--days 30] [--model name] [--json].

ham dashboard / HAM sandwich

Run node <skill-dir>/dashboard/launch.js --port 7777 from the project root and tell the user to open http://localhost:7777.

ham carbon

Run node <skill-dir>/dashboard/carbon-cli.js [--last] [--days 30].

ham insights

Run node <skill-dir>/dashboard/insights-cli.js --days 30, extract actionable items, deduplicate against .memory/inbox.md, append new items, and log the audit event.

ham update

Run bash <skill-dir>/scripts/update.sh, then update .ham/version.

ham metrics clear

Require confirmation before deleting benchmark data.

ham remove

1. Detect Pro state.
2. Inventory HAM-owned versus Pro-owned files.
3. Show a dry run.
4. Confirm with the user.
5. Remove only HAM-owned files and sections:
   • .memory/*
   • .ham/* except Pro-owned config
   • scoped CLAUDE.md files created by HAM
   • HAM sections from root CLAUDE.md
   • HAM block from .gitignore
6. Preserve user content and Pro files.

Templates

See references/templates.md for starter file shapes and references/platforms.md for platform-specific source roots and brownfield analysis cues.

Writing Rules

• Write memory into the narrowest scope that will still be useful.
• Keep root CLAUDE.md short and global.
• Use scoped CLAUDE.md files for purpose, conventions, integrations, patterns, and gotchas that only apply in one subtree.
• Never overwrite existing memory blindly; read first and merge carefully.
• Never store secrets, API keys, tokens, or user data.
• Never promote uncertain findings from .memory/inbox.md into canonical memory without user confirmation.

Session Discipline

• For non-trivial work, read memory before coding and write back durable learnings after coding.
• Skip memory churn for trivial one-shot asks.
• Record accepted architecture changes in .memory/decisions.md.
• Record reusable implementation rules in .memory/patterns.md.
• Keep speculation, cleanup ideas, and uncertain inferences in .memory/inbox.md.

Read references/setup-and-scopes.md when deciding where scoped CLAUDE.md files belong.