o9k-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

Checkpoint and session parameters (v5+)

These control the automatic knowledge extraction pipeline:

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
      }
    }
  }
}

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:

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.

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

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 o9k-sync status

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

If installed (which o9k-sync): run npx o9k-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 o9k-sync enables zero-knowledge encrypted cross-device sync (AES-256-GCM, server sees only opaque blobs), and offer to install it:

npm install -g o9k-sync
npx o9k-sync connect

Sync troubleshooting

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/its-over-9k/dist/cli.js hook-startup",
            "shell": "powershell"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node C:/Users/<you>/AppData/Roaming/npm/node_modules/its-over-9k/dist/cli.js log-exchange",
            "shell": "powershell"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "node C:/Users/<you>/AppData/Roaming/npm/node_modules/its-over-9k/dist/cli.js context-inject",
            "shell": "powershell"
          }
        ]
      }
    ]
  },
  "statusLine": {
    "type": "command",
    "command": "node C:/Users/<you>/AppData/Roaming/npm/node_modules/its-over-9k/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:

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.

Hermes Agent Hook Configuration

For Hermes Agent (not Claude Code), hmem integration is configured via ~/.hermes/config.yaml hooks and the hermes-hooks/ scripts shipped in the its-over-9k repo.

Required hooks

hooks:
  pre_llm_call:
    - command: "~/.hermes/agent-hooks/o9k-startup.sh"
      timeout: 10
  post_llm_call:
    - command: "~/.hermes/agent-hooks/o9k-log-exchange.sh"
      timeout: 10
  on_session_end:
    - command: "/bin/bash -c 'exec hmem checkpoint'"
      timeout: 120
hooks_auto_accept: true

Hook scripts

Statusline (CC-Style in Hermes CLI)

To show hmem info in Hermes' status bar (like Claude Code's statusline):

1. Apply the CLI patch:

   cd ~/.hermes/hermes-agent
   git apply ~/projects/hmem/hermes-hooks/hermes-cli-hmem-statusline.patch

1. Restart Hermes. The status bar will show:

   Strato Server | P0048 its-over-9k → O0048.118 | 3/5 | ⚕ model | ...

The statusline requires hmem statusline to be installed and the o9k-startup.sh hook to be active (for session_id caching).

Deployment

On update or fresh install:

cp ~/projects/hmem/hermes-hooks/*.sh ~/.hermes/agent-hooks/
chmod +x ~/.hermes/agent-hooks/*.sh

Troubleshooting