Bumblebiber/hmem-using-hmem

Using hmem Skills

The Rule

Before searching, looking up, or exploring anything — dispatch via hmem-dispatch. Before responding to the user about something you had to find — dispatch first, synthesize after.

This is not optional. A 3-line grep dispatched is better than a slow main-context search that pollutes the conversation.

Skill Decision Table

| When you want to... | Use | |---------------------|-----| | Find a file, function, or code pattern | hmem-dispatch | | Check if a plan, spec, or doc exists | hmem-dispatch | | Answer "does X exist?" or "find Y" | hmem-dispatch | | Search hmem for past decisions/lessons | hmem-recall | | Run 2+ independent tasks at once | hmem-dispatch (multiple agents) | | Store a new insight, lesson, or decision | hmem-write | | Load project context at session start | hmem-session-start | | Load context for a specific topic | hmem-context | | Create a new project (P-entry) in hmem | hmem-new-project | | Start curation / cleanup of memory | hmem-curate | | Migrate O-entries to new format | hmem-migrate-o |

Targeted vs. Exploratory

Not all Bash calls need dispatching. The key distinction:

| Type | Characteristics | Action | |------|----------------|--------| | Targeted | Known path/pattern, single command, result ≤3 lines | Run directly | | Exploratory | Open-ended, multiple locations, result unknown | Dispatch |

Targeted (OK to run directly): find /home/username -name "settings.json" -path "*claude*" — one known location, one expected result.

Exploratory (must dispatch): grep -r "functionName" ~/projects/ across repos, or "where is X defined?" without knowing which file.

When in doubt: if you'd be surprised by the output → dispatch it.

Red Flags

These thoughts mean STOP — dispatch instead:

| Thought | Reality | |---------|---------| | "I'll just grep this quickly" | Is it exploratory? Dispatch. Is it one targeted command with predictable output? Run it. | | "Let me run find real fast" | Known path + expected result → OK. Unknown territory → dispatch. | | "It's only one Bash call" | Targeted (≤3 lines expected) → fine. Exploratory → dispatch. | | "This is too small to dispatch" | Dispatching 2-line tasks is fine and fast. | | "I need to check the codebase first" | Dispatch the check. | | "Let me read this file to see what's there" | Dispatch it. You only need the result. | | "I'll search memory quickly myself" | Use hmem-recall instead. | | "I remember how this works" | Skills evolve. Invoke the skill. | | "I'll write the P-entry manually with write_memory" | Use hmem-new-project. It handles schema, O-entry linking, and section setup. |

MANDATORY — DO NOT

Hard stops, not guidelines:

| DO NOT | Instead | |--------|---------| | Read ~/.hmem/*.hmem directly | Use read_memory(), search_memory(), or /hmem-read | | Create O-entries manually | O-entries are auto-managed by Haiku — use /hmem-session-start (R0022) | | Write to memory during an active task | Finish the task first, then write | | Call search_memory twice in one turn | Batch into one call, or use hmem-recall | | Create P-entries with write_memory | Use hmem-new-project — schema + O-entry linking auto-handled | | Call load_project mid-session without routing | Always use /hmem-activate — it handles exchange misrouting |

Mandatory Habits

1. Search = Dispatch — unless targeted. Exploratory searches ("find", "where is X", "what does file Y contain") → hmem-dispatch. Single targeted command with a predictable result (≤3 lines) → run directly.
2. Memory = Tools. Write insights via write_memory. Never rely on conversation history alone.
3. Skills override instinct. If a skill exists for the task, use it — even if you think you remember how it works.
4. New project = hmem-new-project. Never create P-entries manually — the skill handles schema, sections, and O-entry linking.
5. Code navigation = Codebase node first. Before editing or tracing any function: check read_memory(id="P00XX.2") for documented signatures. If not found, dispatch an Explore agent — never explore the filesystem directly in main context. Update the Codebase node with what you find.