Bumblebiber/hmem-config

hmem-config — View and Change Settings

This skill guides you through reading, explaining, and updating hmem's configuration. The config controls how memory is stored, displayed, checkpointed, and synced across devices.

Locate and read the config

The config lives at hmem.config.json in the same directory as your .hmem file. Located at ~/.hmem/hmem.config.json (in the same directory as your .hmem file).

Read the file directly — don't ask the user where it is. If it doesn't exist, offer to create one (only non-default values need to be specified).

The config uses a unified format with a "memory" block and an optional "sync" block:

{
  "memory": { ... },
  "sync": { ... }
}

Show current settings

Present a table of current values vs. defaults. Only highlight values that differ from defaults — the user cares about what they've customized, not the full list.

Core parameters

| Parameter | Default | Purpose | |-----------|---------|---------| | maxCharsPerLevel | [200, 2500, 10000, 25000, 50000] | Character limits per tree level [L1–L5]. L1 is always loaded at startup, so keeping it short saves tokens across every session. L5 is raw data, rarely accessed. | | maxDepth | 5 | Tree depth (1–5). Most users need 5. Lower values save storage but lose granularity. | | defaultReadLimit | 100 | Max entries per bulk read. Lower = faster startup, higher = more complete overview. | | maxTitleChars | 50 | Auto-extracted title length. Only applies to entries without explicit body separation — entries with a blank-line body use the first line as title verbatim. Titles are navigation labels — too short truncates meaning, too long wastes space. | | accessCountTopN | 5 | Entries with highest access count get [★] and auto-expand in bulk reads. These are "organic favorites" — the things the agent keeps coming back to. |

Checkpoint and session parameters (v5+)

These control the automatic knowledge extraction pipeline:

| Parameter | Default | Purpose | |-----------|---------|---------| | checkpointMode | "remind" | "auto" spawns a Haiku subagent in the background every N exchanges — it reads the conversation, extracts lessons/errors/decisions, and writes them via MCP tools. The main agent is never interrupted. "remind" injects a prompt asking the main agent to save manually — simpler but interrupts flow. | | checkpointInterval | 20 | Exchanges between checkpoints. Counted in the active O-entry, not per session — so 10 messages on your laptop + 10 on your server = checkpoint fires at 20. Set to 0 to disable. | | recentOEntries | 10 | How many recent session logs to show when loading a project. All entries include full user/agent exchanges (L4/L5), not just titles. Higher = more context but more tokens at project load. | | contextTokenThreshold | 100000 | When cumulative hmem output exceeds this, the agent is told to flush context and /clear. Prevents runaway token usage in long sessions. Set to 0 to disable. |

Entry schemas (v6.3.0+)

Define per-prefix section schemas that control create_project structure and load_project rendering depth. When a schema is defined, it replaces the hardcoded R0009 sections and the loadProjectExpand settings.

{
  "memory": {
    "schemas": {
      "P": {
        "sections": [
          { "name": "Overview",    "loadDepth": 3, "defaultChildren": ["Current state", "Goals", "Environment"] },
          { "name": "Codebase",    "loadDepth": 1 },
          { "name": "Protocol",    "loadDepth": 0 },
          { "name": "Next Steps",  "loadDepth": 3 }
        ],
        "createLinkedO": true
      }
    }
  }
}

| Field | Type | Description | |-------|------|-------------| | sections[].name | string | L2 section title. Used for matching during auto-reconcile (case-insensitive). | | sections[].loadDepth | 0-4 | 0=skip, 1=title only, 2=+L3 titles, 3=+L3 body, 4=full subtree | | sections[].defaultChildren | string[] | L3 nodes created by create_project. Optional. | | createLinkedO | boolean | Auto-create matching O-entry on create_project. Default: false. |

Auto-reconcile: On every load_project, missing schema sections are automatically added as empty L2 nodes. Extra sections not in the schema are kept (loaded at depth 1).

No schema defined: Falls back to hardcoded R0009 behavior and loadProjectExpand settings.

load_project display (legacy, pre-v6.3.0)

Only used when no schemas entry exists for the prefix. Controls which P-entry sections are expanded:

| Parameter | Default | Purpose | |-----------|---------|---------| | loadProjectExpand.withBody | [1] | L2 section seq numbers where L3 children show title + body content. Default: .1 Overview — shows full architecture/state/goals detail. | | loadProjectExpand.withChildren | [6, 8] | L2 section seq numbers where all L3 children are listed as titles. Default: .6 Bugs, .8 Open Tasks — all items visible at a glance. |

Sections not in either list show L3 titles only in compact mode.

Bulk-read tuning

The bulk-read algorithm decides which entries get expanded (full L2 detail) vs. compressed (title only). Most users don't need to touch these — the defaults work well up to ~500 entries.

| Parameter | Default | Purpose | |-----------|---------|---------| | bulkReadV2.topNewestCount | 5 | Newest entries expanded. Increase if you want more recent context at startup. | | bulkReadV2.topAccessCount | 3 | Most-accessed entries expanded (time-weighted: access_count / log2(age_days + 2)). | | bulkReadV2.topObsoleteCount | 3 | Obsolete entries kept visible — "biggest mistakes" are still worth seeing. | | bulkReadV2.topSubnodeCount | 3 | Entries with most children expanded. These tend to be the most detailed/important. |

Prefixes

Default: P, L, T, E, D, M, S, N, H, R, O, I. Custom prefixes are merged with defaults — they don't replace them. Each prefix can have a custom description used as group header in bulk reads.

Help the user make changes

For each parameter the user wants to change:

1. Explain the tradeoff in plain language — what gets better, what gets worse
2. Show the recommended range (see below)
3. Validate before writing — numbers must be positive, arrays must be valid JSON

Recommended ranges

| Parameter | Range | Guidance | |-----------|-------|----------| | maxCharsPerLevel[0] (L1) | 60–300 | Below 60 is too terse for useful summaries. Above 300 wastes tokens on every bulk read — L1 is loaded at every session start. | | maxCharsPerLevel[4] (L5) | 1000–100000 | Raw data storage. Higher allows more verbatim content but L5 is rarely loaded. | | maxDepth | 2–5 | 3 suffices for simple setups. 5 for multi-agent or complex projects. | | checkpointMode | "auto" or "remind" | Recommend "auto" — it's non-disruptive and produces better results because Haiku has MCP access to check for duplicates. Auto-checkpoints also write rolling summaries ([CP] nodes) and tag skill-dialog exchanges for filtering. | | checkpointInterval | 0–100 | 20 is a good balance. Lower = more frequent saves (more Haiku cost). 0 = disabled. | | recentOEntries | 0–20 | 10 is the sweet spot. With checkpoint summaries, load_project shows summary + recent exchanges only — much more compact than raw exchange dumps. | | contextTokenThreshold | 0–500000 | 100k is recommended for most models. Increase for 1M-context models. |

Common recipes

"I want auto-checkpoints":

{ "memory": { "checkpointMode": "auto", "checkpointInterval": 20 } }

"Startup is too slow / uses too many tokens": Reduce recentOEntries (e.g., 5), bulkReadV2.topNewestCount (e.g., 3), or maxCharsPerLevel[0] (e.g., 150).

"I have 500+ entries and bulk reads are noisy": Increase bulkReadV2.topAccessCount and decrease topNewestCount — favor proven entries over new ones.

Write the updated config

Write hmem.config.json with only non-default values. The config uses a "memory" wrapper:

{
  "memory": {
    "checkpointMode": "auto"
  },
  "sync": { ... }
}

After writing, tell the user:

• Which values changed
• Changes take effect immediately — no restart needed
• maxCharsPerLevel only affects new entries (existing entries are not reformatted)

Check hmem-sync status

Run this check as part of every /hmem-config invocation.

If installed (which hmem-sync): run npx hmem-sync status and show server URL, user ID, last push/pull timestamps, and whether HMEM_SYNC_PASSPHRASE is set in .mcp.json (needed for auto-sync).

If not installed: explain that hmem-sync enables zero-knowledge encrypted cross-device sync (AES-256-GCM, server sees only opaque blobs), and offer to install it:

npm install -g hmem-sync
npx hmem-sync connect

Sync troubleshooting

| Problem | Fix | |---------|-----| | "Config not found" | Run npx hmem-sync connect | | 401 Token verification failed | Passphrase has special chars — set HMEM_SYNC_PASSPHRASE in .mcp.json env | | 0 entries after pull | HMEM_PATH filename must match between devices | | Update | npm update -g hmem-sync (always global, never inside a project) |

Hook configuration on Windows (REQUIRED)

On Windows, hook execution is fragile out of the box. Two issues bite every new user:

1. Git Bash routing — On systems with Git for Windows installed, Claude Code may route hook commands through Git Bash (bash.exe). Its MSYS2 runtime crashes transiently with add_item ("\??\C:\Program Files\Git", "/", ...) failed, errno 1 during cygheap init, killing the hook before the command is even parsed. Symptom: UserPromptSubmit hook error or Stop hook error with a bash.exe stacktrace.

2. Unix inline env-var syntax — Commands like HMEM_PATH=C:/... node ... work in bash but break in cmd.exe and PowerShell. Symptom: "HMEM_PATH" is not recognized as a command.

The fix for Windows users (apply to every hook + statusLine):

{
  "env": {
    "HMEM_PATH": "C:/Users/<you>/.hmem/Agents/<AGENT>/<AGENT>.hmem"
  },
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node C:/Users/<you>/AppData/Roaming/npm/node_modules/hmem-mcp/dist/cli.js hook-startup",
            "shell": "powershell"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node C:/Users/<you>/AppData/Roaming/npm/node_modules/hmem-mcp/dist/cli.js log-exchange",
            "shell": "powershell"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "node C:/Users/<you>/AppData/Roaming/npm/node_modules/hmem-mcp/dist/cli.js context-inject",
            "shell": "powershell"
          }
        ]
      }
    ]
  },
  "statusLine": {
    "type": "command",
    "command": "node C:/Users/<you>/AppData/Roaming/npm/node_modules/hmem-mcp/dist/cli.js statusline",
    "shell": "powershell"
  }
}

Two things to notice:

• "shell": "powershell" on every hook command and on statusLine — forces native PowerShell, bypasses Git Bash entirely.
• HMEM_PATH lives in the top-level env block, not inline in the command. Claude Code inherits the env block to every hook subprocess, regardless of shell.

Never use inline env-var syntax in hook commands on Windows. VAR=value command is bash-only syntax and will silently break under cmd.exe or PowerShell.

Troubleshooting matrix:

| Symptom | Cause | Fix | |---------|-------|-----| | UserPromptSubmit hook error (no stacktrace) | Inline VAR=value in command + cmd.exe parses it as a command name | Move env vars to env block, remove inline prefix | | bash.exe: *** fatal error - add_item ... errno 1 | Git Bash MSYS2 runtime crashing at startup | Add "shell": "powershell" to every hook command | | Hooks silently do nothing (no errors) | Wrong shell interpreting the command, or project not active for session logging | Verify "shell": "powershell", call load_project(id="P00XX") every session |

Note on load_project per-session: The active flag on a P-entry persists in the database, but the "currently active project for session logging" is a per-session attribute. After every Claude Code restart, the agent must call load_project(id="P00XX") again, or exchanges will be logged to O0000 (no-project fallback) instead of the project's O-entry. Consider adding this to your project briefing or session-start routine.