Documentation

Hierarchical Agent Memory for every AI tool in your repo.

HAM is a hierarchical memory system for AI coding agents. Two tiers: Free (Claude Code skill, .ham/ files managed natively) and Pro (MCP server with 7 tools, web dashboard, team analytics).

Hierarchical Scoping

Context files at every directory level. Agents load only the scoped context for their working directory — root rules plus local overrides.

Tool-Agnostic

One .ham/ directory works with Claude, Cursor, Windsurf, Copilot, Gemini, and any MCP-compatible agent. No vendor lock-in.

Zero Lock-In

.ham/ files are plain markdown. One command to eject completely. Your repo works exactly the same without HAM.

HAM Free

Quick Start

Install the Claude Code skill, run ham init, and .ham/ files appear across your directory tree.

Terminal

# Install the HAM skill for Claude Code
claude install-skill /path/to/ham/SKILL.md

# Initialize HAM in your project (creates .ham/ files)
# Say "go ham" to Claude, or run:
ham init --scan

# Optional: scaffold hierarchical memory files (via PR)
ham init --scaffold

Result: .ham/ directory structure

my-project/
├── .ham/
│   ├── context.md         # Project context (YAML frontmatter + markdown)
│   ├── decisions.md       # Architecture Decision Records
│   ├── patterns.md        # Reusable patterns & conventions
│   ├── inbox.md           # Uncertain observations (append-only)
│   └── config.json        # HAM configuration
├── src/
│   ├── .ham/
│   │   └── context.md     # Source code conventions
│   └── api/
│       └── .ham/
│           └── context.md # API-specific rules
└── CLAUDE.md              # Tool-specific file (also created)

HAM Free works entirely through Claude Code's skill system. Claude reads SKILL.md, internalizes the .ham/ protocol, and manages your memory files natively. No CLI server, no MCP — just files.

HAM Free

.ham/ File Format

Each .ham/ directory can contain these five files. All are plain markdown — no special tooling required to read or edit.

File	Purpose
context.md	Project context with optional YAML frontmatter for metadata (tags, owner). Stack, rules, conventions.
decisions.md	Architecture Decision Records. Each ### heading is a dedup key — deeper scopes override shallower.
patterns.md	Reusable patterns and conventions. Each ### heading is a dedup key — deeper scopes override.
inbox.md	Append-only scratchpad for uncertain observations. Never promoted to canonical files without user confirmation.
session-log.md	Append-only log of work sessions with scope, summary, files touched, decisions made.

.ham/context.md

---
tags: [api, auth]
owner: backend-team
---

# API Layer Context

## Stack
- Node.js, Express, TypeScript

## Rules
- Validate inputs at the boundary

.ham/decisions.md

### Use Prisma over raw SQL
- **Status**: accepted
- **Date**: 2025-01-15
- **Context**: Need consistent ORM
- **Decision**: Prisma for all DB ops
- **Consequences**: Better DX, slight overhead

.ham/patterns.md

### Error Handling
- **When**: Any async operation
- **Do**: try/catch with typed errors
- **Don't**: Swallow errors silently

.ham/inbox.md

- [2025-01-20] Auth middleware duplicated in 3 routes
- [2025-01-21] Config loading seems slow

.ham/session-log.md

### Session 2025-01-20T14:30:00Z
- **Scope**: src/api
- **Summary**: Fixed auth race condition
- **Files touched**: auth.ts, users.ts

HAM Free

Skill Protocol

The HAM skill teaches Claude a three-phase protocol for managing .ham/ files during every coding session.

On Session Start

1.Read root .ham/context.md
2.Walk ancestor chain to working directory
3.Read decisions.md and patterns.md at each scope
4.Deeper scopes override shallower (same heading)

During Session

•Append decisions to .ham/decisions.md
•Append patterns to .ham/patterns.md
•Uncertain observations → .ham/inbox.md
•Never promote inbox without user confirmation

On Session Close

•Append summary to .ham/session-log.md
•Include: scope, summary, files touched
•Reference decisions and patterns made

HAM Pro

MCP Server

HAM Pro runs as an MCP server, exposing 7 tools to any MCP-compatible agent. Connect a repo in the dashboard for zero-config setup, or run locally for offline use.

Dashboard-Hosted (Recommended)

No local server required. Connect your repo, generate an API key, and paste the config into your editor.

Claude Code — .mcp.json

{
  "ham-memory": {
    "type": "streamable-http",
    "url": "https://goham.dev/api/mcp/{repoId}",
    "headers": { "Authorization": "Bearer ham_..." }
  }
}

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "ham-memory": {
      "url": "https://goham.dev/api/mcp/{repoId}?token=ham_..."
    }
  }
}

Local Server (Offline)

For offline use or when you prefer keeping data on your machine.

Terminal

# Start the MCP server locally
ham serve --transport stdio --repo_root . --role writer

Agent	Config File	MCP Support
Claude Code	CLAUDE.md	Yes
Cursor	.cursorrules	Yes
Windsurf	.windsurfrules	Yes
GitHub Copilot	.github/copilot-instructions.md	Via compiler
Gemini CLI	GEMINI.md, .gemini/	Yes
Aider	.aider.conf.yml	Via compiler
Llama	LLAMA.md, .llama/	Yes
Manus	MANUS.md, .manus/	Yes

HAM Pro

Tools Reference

Seven tools exposed via the MCP server. Each operates on .ham/ files within the repo sandbox.

ham.read_context

Read merged .ham/ context for a target directory. Walks root → target, deduplicates decisions/patterns by heading, returns sections with provenance and token estimates.

Param	Type	Required	Description
path	string	Yes	Target directory path (relative to repo root)
sections	string[]	No	Filter to specific sections (context, decisions, patterns, inbox, sessions)
max_sessions	number	No	Max session entries per scope (default: 3)

Returns: { sections, provenance, token_estimates, rendered_text, composite_revision }

ham.write_context

Write to a .ham/ section file. Supports append and replace modes with optimistic concurrency via revision hashing.

Param	Type	Required	Description
path	string	Yes	Target directory path
section	string	Yes	Section file: context, decisions, patterns, inbox, session-log
content	string	Yes	Content to write
mode	string	No	Write mode: append (default) or replace
expected_revision	string	No	SHA-256 revision for optimistic concurrency

Returns: { path, revision, bytes_written }

ham.route_task

Determine the best scope for a task using deterministic heuristics: ownership policies, keyword matching, directory name matching, nearest common ancestor.

Param	Type	Required	Description
task_description	string	Yes	Description of the task to route
candidate_paths	string[]	No	Limit routing to specific paths

Returns: { target_scope, rationale[], context_payload, budget }

ham.log_session

Append a session summary to .ham/session-log.md. Idempotent via idempotency_key stored in .meta.json.

Param	Type	Required	Description
path	string	Yes	Scope directory for the session log
summary	string	Yes	Session summary text
files_touched	string[]	No	List of files modified
idempotency_key	string	No	Unique key to prevent duplicate entries

Returns: { path, entry_count, idempotency_key }

ham.list_scopes

Walk the directory tree and find all .ham/ directories. Returns a tree structure with optional token stats per scope.

Param	Type	Required	Description
include_stats	boolean	No	Include token counts and file stats (default: false)

Returns: { scopes: [{ path, depth, sections[], token_count? }] }

ham.search_context

BM25 keyword search across all .ham/ content. Ranked by term frequency, section weight, and scope proximity.

Param	Type	Required	Description
query	string	Yes	Search query
scope	string	No	Limit search to a specific scope path
sections	string[]	No	Filter to specific sections
top_k	number	No	Max results (default: 10)

Returns: { results: [{ path, section, snippet, score }] }

ham.get_stats

Per-scope metrics from .meta.json and file stats. Token counts, last updated, last writer, file revisions, write counts.

Param	Type	Required	Description
path	string	No	Scope path (default: root)
recursive	boolean	No	Include child scopes (default: false)

Returns: { scopes: [{ path, token_count, last_updated, last_writer, sections }] }

ham.disconnect

Disconnect from HAM Pro — sets pro: false in .ham/config.json, transferring ownership to the Free skill. Admin-only.

Param	Type	Required	Description

Returns: { disconnected, config_path }

HAM Pro

CLI Reference

ham serve

Start the MCP server (stdio by default). Exposes 7 tools to any MCP-compatible agent. Use --transport stdio, --repo_root ., --role writer, --port 3847.

ham init --scan

Scan your repo for AI tool configs and create .ham/config.json. Produces a report of everything found. No files are modified.

ham compile --path <file> --target <tool>

Compile a context bundle for a specific file. Targets: cursor, claude, gemini, aider, copilot, universal. Use --budget <n> to set a token limit.

ham report --last

View the most recent compile report: what was included, what conflicted, and how it was resolved.

ham export --target <tool>

Write the compiled bundle into your tool file using HAM:BEGIN/HAM:END markers. Only the content between markers is managed by HAM.

ham eject [--full]

Remove HAM markers from tool files. With --full, also removes the .ham/ directory (asks for confirmation).

ham pro login

Authenticate with your HAM Pro license key. Stores credentials locally.

ham pro status

Show current license status, seat count, and expiration.

HAM Pro

Dashboard

Web dashboard for team-wide analytics, cost tracking, and scope visualization.

Token Analytics

Multi-model token usage tracking across all agents. See per-file, per-directory, and per-engineer breakdowns. Track costs over time with interactive charts.

CO2 Estimation

Estimate the carbon footprint of your AI usage based on the CodeCarbon methodology. Track energy efficiency improvements from scoped context.

Team Management

Invite team members, manage seats, compare per-engineer usage. Role-based access control for who can read, write, or administer HAM memory.

Scope Visualization

Interactive directory tree showing .ham/ coverage across your repo. See which directories have context, decisions, and patterns — and where gaps exist.

Settings

Configuration

All settings live in .ham/config.json, created when you run ham init.

.ham/config.json

{
  "ham_version": "1.0",
  "enabled_importers": [
    "ham", "cursor", "claude",
    "gemini", "aider", "copilot"
  ],
  "precedence_preset": "target-first",
  "default_budget": 2000,
  "ignored_paths": ["legacy/", "vendor/"]
}

Field	Description
enabled_importers	Which tool formats HAM reads during compilation
precedence_preset	How conflicts are resolved (see Precedence Presets below)
default_budget	Token limit for compiled bundles
ignored_paths	Directories HAM skips during scanning

Precedence Presets

Preset	What It Does
target-first	The tool you're compiling for gets priority. Recommended for most teams.
ham-first	HAM context takes priority over all tool-specific files. Use when HAM is your single source of truth.
advisory	All sources treated equally. Conflicts are surfaced but nothing automatically wins. Good for auditing.

Security

Security & Privacy

HAM operates within a strict security boundary. All file operations are sandboxed to the repo root. Role-based access controls who can read or write. Telemetry is configurable.

Sandbox

All paths are normalized and resolved against repo_root. Symlinks outside the repo are rejected. Only .ham/ directories are operated on. No file outside your project is ever read or written.

RBAC Roles

Role	Allowed Tools
Reader	read_context, list_scopes, search_context, get_stats
Writer	All Reader + write_context, log_session, route_task
Admin	All Writer (admin-only tools in v2)

Telemetry Levels

Level	What Is Collected
off	Zero events emitted. Fully private.
metadata	Paths, token counts, model, timestamps, agent ID. No content. Default.
full	All metadata + task text, summaries, .ham/ snippets. Opt-in only.

Principles

Trust & Safety

HAM is built on a simple promise: your repo, your rules, your control.

Deterministic

Same inputs, same output, every time. HAM's compilation is deterministic and cacheable. Context merging uses stable sort by path depth then alphabetical — no randomness.

Read-only by default

Scanning and compiling never modify your repo. Write operations (write_context, log_session) require Writer role. Scaffolding always goes through a pull request.

Nothing hidden

Every conflict is surfaced. Provenance tracking shows exactly which file contributed each section. The report shows what happened and why.

Clean eject

One command to remove HAM completely. Your repo is exactly how it was before. .ham/ files are plain markdown you can keep using manually.

Plans

Pricing

Start free. Upgrade when your team needs shared analytics and MCP tooling.

Free

$0

forever

For individual developers and open-source projects.

✓Claude Code skill (SKILL.md)
✓.ham/ file protocol
✓Hierarchical scoping
✓CLI tooling (init, compile, report, export, eject)
✓Token analytics
✓Community support

Pro

$29

per seat / month

For teams using any AI coding agent.

✓Everything in Free
✓MCP server (7 tools, stdio transport)
✓Any-agent support (Cursor, Windsurf, Copilot, etc.)
✓Web dashboard with team analytics
✓CO2 estimation
✓Role-based access control
✓Telemetry pipeline
✓Priority support