hmem Setup

Recommended: hmem init

Install hmem globally, then run the interactive installer:

npm install -g its-over-9k
hmem init

hmem init performs all setup steps automatically:

1. Detects installed AI tools (Claude Code, Gemini CLI, OpenCode, Cursor, Windsurf, Cline)
2. Asks for installation scope (system-wide or project-local)
3. Creates the memory directory and optional example database
4. Writes .mcp.json with the correct paths for each detected tool
5. Adds session-start instructions to the tool's config file (CLAUDE.md, GEMINI.md, etc.)
6. Creates hmem.config.json with sensible defaults
7. Installs all 4 auto-memory hooks (Claude Code only — see Hook Reference below)
8. Copies skill files (slash commands) to the tool's skill directory

After hmem init, install the slash-command skills:

npx hmem update-skills

Restart your AI tool and call read_memory() to verify.

Non-interactive mode (CI / scripting):

hmem init --global --tools claude-code --dir ~/.hmem --no-example

Hook Reference (Claude Code)

hmem init registers 4 hooks in ~/.claude/settings.json. Each hook is a bash script in ~/.claude/hooks/.

1. UserPromptSubmit — memory load + checkpoint reminder

Script: ~/.claude/hooks/o9k-startup.sh

• First message: injects additionalContext telling the agent to call read_memory() silently. Also injects H-entries (ID + title; pinned H-entries include their L2 children inline so canonical identity/preference info is visible without extra reads — since v1.3.3), active device apps, infrastructure favorites, recent projects, checkpoint status, and an --- hmem-sync --- block showing link state (✓ linked / ⚠ partial / ✗ not linked / ✗ not configured). Block is always emitted since v1.2.9.
• Every Nth message (N = checkpointInterval, default 20): injects a checkpoint reminder.
• checkpointMode: "remind" — adds an additionalContext nudge; the agent decides what to save.
• checkpointMode: "auto" — checkpoint is handled by the Stop hook instead (no reminder injected).
• Subagents (messages with parentUuid) are skipped.
• Uses a per-session counter file at /tmp/claude-o9k-counter-{SESSION_ID}.

2. Stop (async) — exchange logging + checkpoint

Script: ~/.claude/hooks/o9k-log-exchange.sh

• Runs asynchronously after every agent response (timeout: 10s).
• Pipes the Stop hook JSON (containing transcript_path and last_assistant_message) to hmem log-exchange.
• hmem log-exchange reads the last user message from the JSONL transcript, combines it with the agent response, and appends both to the currently active O-entry (session history).
• If no active O-entry exists, one is created automatically.
• Every N exchanges (configurable via checkpointInterval, default 20), triggers a checkpoint:
• auto mode: Spawns hmem checkpoint in background — Haiku subagent with MCP tools that:
• Titles each exchange with a descriptive summary (max 50 chars)
• Writes L/D/E entries for non-obvious insights
• Updates P-entry (protocol, bugs, open tasks, overview, codebase)
• Writes a checkpoint summary for context re-injection
• Verifies project relevance and fixes links
• remind mode: Injects a reminder for the main agent to save knowledge manually
• Checks transcript file size and writes a warning flag when context exceeds contextTokenThreshold (default 100k tokens).

3. SessionStart[clear] — context re-injection + deactivation

Fires only after /clear (matcher: "clear"). Two hooks run in sequence:

a) `hmem context-inject` — outputs additionalContext containing:

• 5 most recently edited P-entries (one line each, active marked with [*])
• Hint to call read_memory({prefix:"P", titles_only:true}) for the full list
• All R-entries (rules, one line each)
• Footer with load_project call for the active project (if any)
• Keeps the agent oriented after a context reset without a full read_memory() call.

b) `hmem deactivate` — resets the active project for the new session:

• Writes a session marker with projectId: null, deactivated: true for the new session_id
• Deletes the per-process active-project file (/tmp/o9k-active-<pid>.txt)
• Clears statusline cache files
• Result: statusline shows no project after /clear until load_project is called

Configuration Reference

Place hmem.config.json in your memory directory (the path you chose during hmem init). All keys are optional — defaults are applied for anything missing.

{
  "memory": {
    "maxCharsPerLevel": [200, 2500, 10000, 25000, 50000],
    "maxDepth": 5,
    "defaultReadLimit": 100,
    "maxTitleChars": 50,
    "checkpointInterval": 20,
    "checkpointMode": "remind",
    "recentOEntries": 10,
    "contextTokenThreshold": 100000,
    "bulkReadV2": {
      "topAccessCount": 3,
      "topNewestCount": 5,
      "topObsoleteCount": 3,
      "topSubnodeCount": 3,
      "newestPercent": 20,
      "newestMin": 5,
      "newestMax": 15,
      "accessPercent": 10,
      "accessMin": 3,
      "accessMax": 8
    }
  }
}

Bulk-read tuning (bulkReadV2): controls which entries get expanded (all L2 children shown) in a default read_memory() call. Per prefix category, the top N newest + top M most-accessed entries are expanded. Favorites are always expanded.

Manual Setup (Fallback)

Use these steps only if hmem init is not available (e.g., local clone without global install).

Step 0 — Prerequisites

node --version    # must be >= 18
npm --version     # any recent version

better-sqlite3 requires native build tools:

Step 1 — Clone and Build

git clone https://github.com/Bumblebiber/its-over-9k.git
cd its-over-9k
npm install
npm run build

Verify: dist/mcp-server.js must exist after build.

Step 2 — Create Memory Directory

mkdir -p ~/.hmem

The SQLite .hmem file is created automatically on first write.

Step 3 — Configure MCP

Add hmem to your .mcp.json (create it at your project root if it does not exist). All paths must be absolute.

{
  "mcpServers": {
    "hmem": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/hmem/dist/mcp-server.js"],
      "env": {
        "HMEM_PATH": "/absolute/path/to/your/memory.hmem",
        "HMEM_AGENT_ROLE": "worker"
      }
    }
  }
}

Step 4 — Install Skill Files

Copy skill files to the global skills directory for your tool:

Claude Code:

mkdir -p ~/.claude/skills/o9k-read ~/.claude/skills/o9k-write ~/.claude/skills/save ~/.claude/skills/memory-curate
cp /path/to/hmem/skills/o9k-read/SKILL.md ~/.claude/skills/o9k-read/SKILL.md
cp /path/to/hmem/skills/o9k-write/SKILL.md ~/.claude/skills/o9k-write/SKILL.md
cp /path/to/hmem/skills/save/SKILL.md ~/.claude/skills/save/SKILL.md
cp /path/to/hmem/skills/memory-curate/SKILL.md ~/.claude/skills/memory-curate/SKILL.md

Gemini CLI:

mkdir -p ~/.gemini/skills/o9k-read ~/.gemini/skills/o9k-write ~/.gemini/skills/save ~/.gemini/skills/memory-curate
cp /path/to/hmem/skills/*/SKILL.md to corresponding ~/.gemini/skills/*/SKILL.md

Step 5 — Verify

Fully restart your AI tool (exit and reopen — /clear is not enough). Then call:

read_memory()

Expected: Memory is empty (or your existing memories).

Troubleshooting

Quick Reference — After Setup

read_memory()                          # see all L1 memories
read_memory(id="L0001")               # drill into one entry
write_memory(prefix="L", content="Short title\n\nDetailed body text\n\tL2 sub-node")
search_memory(query="error node.js")  # search across all memories

Separate title from body with a blank line (hidden in listings, shown on drill-down). See o9k-write skill for details.

See skills/o9k-read/SKILL.md and skills/o9k-write/SKILL.md for full usage.