hmem-mcp 5.0.0 → 5.1.21

package/skills/hmem-update/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: hmem-update
+description: >
+  Post-update checklist for hmem-mcp and hmem-sync. Run after npm update or when
+  hmem detects a version change. Covers skill sync, entry migration, schema enforcement,
+  O-entry curation, and smoke tests. Use when the user says "update hmem", "hmem updaten",
+  or when the startup version-check detects a new version.
+---
+
+# /hmem-update — Post-Update Checklist
+
+Run this after updating hmem-mcp or hmem-sync. Every step is important — do not skip steps.
+
+---
+
+## Step 1: Version Check
+
+Determine what changed:
+
+```bash
+hmem --version                    # current installed version
+npm view hmem-mcp version         # latest on npm
+npm view hmem-mcp versions --json # all versions
+```
+
+Read the changelog for the version range:
+```bash
+cd ~/projects/hmem && git log --oneline <old-tag>..HEAD  # if local repo exists
+```
+
+Or check GitHub releases: `gh release list -R Bumblebiber/hmem --limit 5`
+
+**If already on latest:** Tell the user and skip to Step 7 (smoke test).
+
+---
+
+## Step 2: Update Skills
+
+```bash
+hmem update-skills
+```
+
+This syncs all skill files from the npm package to the local skills directory. Verify:
+
+```bash
+ls ~/.claude/skills/hmem-*/SKILL.md   # Claude Code
+ls ~/.config/gemini/skills/hmem-*/     # Gemini CLI (if applicable)
+```
+
+Check for new skills that weren't there before — inform the user about new capabilities.
+
+---
+
+## Step 2b: Verify Hooks
+
+Hooks are critical — without them, O-entries are never logged and auto-checkpoints never fire.
+
+Check the current hook configuration:
+```bash
+cat ~/.claude/settings.json | grep -A5 hooks
+```
+
+**Required hooks (for `checkpointMode: "auto"`):**
+- **UserPromptSubmit** — memory load + checkpoint reminder
+- **Stop** — exchange logging (`hmem log-exchange`) + O-entry title generation
+- **SessionStart[clear]** — context re-injection after `/clear`
+
+**If hooks are missing or empty (`hooks: {}`):**
+1. Inform the user: "Hooks are not configured — O-entries won't be logged and auto-checkpoints won't fire."
+2. Suggest: "Run `/hmem-config` to set up hooks, or run `hmem init` to re-initialize."
+
+**If hooks exist but reference old paths or scripts:**
+- Check that hook scripts exist and are executable
+- Verify they reference the current hmem installation path
+
+---
+
+## Step 2c: Check load_project Display Config
+
+Since v5.1.8, `load_project` supports configurable section expansion:
+- `loadProjectExpand.withBody`: sections showing L3 title + body (default: `[1]` = Overview)
+- `loadProjectExpand.withChildren`: sections listing all L3 children as titles (default: `[6, 8]` = Bugs, Open Tasks)
+
+Check if the user has customized this in `hmem.config.json`. If not, inform them about the option:
+```json
+{ "memory": { "loadProjectExpand": { "withBody": [1], "withChildren": [6, 8] } } }
+```
+
+---
+
+## Step 3: Entry Migration
+
+Some versions introduce new data formats. Check if migration is needed:
+
+**v5.1.0+ Title/Body Separation:**
+- Entries now support `>` body lines (title shown in listings, body on drill-down)
+- Check if old entries need title/body split:
+  ```
+  read_memory(titles_only=true)
+  ```
+- Look for entries where the title is truncated mid-word or contains too much detail
+- Fix with: `update_memory(id="L0042", content="Clear title\n> Detailed body text")`
+
+**v5.1.2+ Checkpoint Summaries:**
+- O-entries with >10 exchanges should have `[CP]` checkpoint summaries
+- Check recent O-entries: `read_memory(prefix="O")`
+- If summaries are missing, write them:
+  ```
+  append_memory(id="O00XX", content="\t[CP] Factual 3-8 sentence summary of the session")
+  ```
+
+**v5.1.2+ Skill-Dialog Tags:**
+- Exchanges containing skill activations should be tagged `#skill-dialog`
+- These are auto-tagged by the checkpoint process going forward
+- For old exchanges: the checkpoint auto-tagger picks them up on the next run
+
+**General migration pattern:**
+1. Read a sample of entries to assess the current state
+2. Identify entries that don't match the new format
+3. Fix in batches — don't try to fix everything at once
+4. Prioritize: favorites and pinned entries first, then high-access, then the rest
+
+---
+
+## Step 4: P-Entry Schema Enforcement (R0009)
+
+All P-entries (projects) must follow the standard L2 structure:
+
+```
+.1 Overview
+.2 Codebase
+.3 Usage
+.4 Context
+.5 Deployment
+.6 Bugs
+.7 Protocol
+.8 Open tasks
+.9 Ideas
+```
+
+For each active P-entry:
+1. `read_memory(id="P00XX", depth=2)` — check L2 structure
+2. Compare against the schema above
+3. Add missing sections: `append_memory(id="P00XX", content="\tOverview\n\t\tCurrent state: ...")`
+4. L1 body should be: `Name | Status | Stack | Description`
+
+**Do not restructure entries that already follow the schema.** Only fix what's missing or wrong.
+
+---
+
+## Step 5: O-Entry Curation
+
+Check recent O-entries for quality:
+
+```
+read_memory(prefix="O")
+```
+
+**Titles:**
+- Replace "unassigned" or generic titles (e.g., "hmem-mcp") with descriptive ones
+- Good: "Title/Body Separation design + v5.1.0 release"
+- Fix: `update_memory(id="O00XX", content="Descriptive session title")`
+
+**Tags:**
+- Every O-entry should have at least `#session`
+- Add topic tags where obvious: `#release`, `#bugfix`, `#refactor`, `#brainstorming`
+- Fix: `update_memory(id="O00XX", tags=["#session", "#release"])`
+
+**Checkpoint Summaries:**
+- O-entries with >10 exchanges and no `[CP]` summary need one
+- Write summary: `append_memory(id="O00XX", content="\t[CP] Summary...")`
+- The auto-tagger will tag it `#checkpoint-summary` on the next checkpoint run
+
+**Cleanup:**
+- Look for duplicate O-entries (same title, same date, 1-2 exchanges) — these are likely subagent artifacts
+- Mark as irrelevant or delete if clearly junk
+
+---
+
+## Step 6: hmem-sync Update (if installed)
+
+Check if hmem-sync is installed and needs updating:
+
+```bash
+which hmem-sync && hmem-sync --version  # check if installed
+npm view hmem-sync version              # latest on npm
+```
+
+If outdated:
+```bash
+npm update -g hmem-sync
+```
+
+Verify sync still works:
+```bash
+hmem-sync status    # check connection to sync server
+hmem-sync push      # test push
+hmem-sync pull      # test pull
+```
+
+**If hmem-sync is not installed:** Skip this step. Mention to the user that hmem-sync is available for cross-device sync.
+
+---
+
+## Step 7: Smoke Test
+
+Verify everything works after the update:
+
+```
+read_memory()                           # bulk read works
+read_memory(id="P00XX")                 # drill-down works
+load_project(id="P00XX")               # project loading works
+write_memory(prefix="T", content="Update smoke test — delete me", tags=["#test"])
+                                        # write works → note the ID
+update_memory(id="T00XX", content="Update smoke test — verified", irrelevant=true)
+                                        # update works + mark for cleanup
+```
+
+If any step fails: report the error to the user. Do not proceed with normal work until the issue is resolved.
+
+---
+
+## Step 8: Report
+
+Tell the user what was done:
+
+```
+hmem-mcp updated: v5.1.2 → v5.1.4
+
+Changes applied:
+- Skills synced (2 new, 3 updated)
+- 5 P-entries checked against R0009 schema (2 fixed)
+- 12 O-entries curated (4 titles fixed, 3 summaries added)
+- Smoke test passed
+
+New features in this version:
+- Rolling checkpoint summaries
+- Skill-dialog exchange filtering
+- hmem --version reads from package.json
+```
+
+---
+
+## Auto-Detection (for hook integration)
+
+This skill can be triggered automatically. At session startup, if the hmem MCP server detects that the installed version differs from the last-seen version stored in the config, it appends a notice to the first `read_memory()` response:
+
+```
+⚠ hmem-mcp updated: v5.1.2 → v5.1.4. Run /hmem-update to apply post-update steps.
+```
+
+The agent should then invoke this skill automatically or ask the user if they want to run it.
+
+**Last-seen version** is stored in `hmem.config.json` under `lastSeenVersion`. Updated automatically after a successful `/hmem-update` run.

package/skills/hmem-wipe/SKILL.md

@@ -1,49 +1,75 @@
 ---
 name: hmem-wipe
 description: >
-  Flush conversation context to hmem and prepare for /clear. Use when:
+  Prepare for /clear by optionally saving high-value knowledge. Use when:
   - User types /wipe
   - Context threshold warning appears (100k tokens)
   - User says "context aufräumen", "clear machen", "wipe"
-  Saves the current session, then instructs user to /clear for re-injection.
+  Handles pre-clear cleanup, then instructs user to /clear for automatic context restoration.
 ---
 
-# Wipe — Save & Clear Context
+# Wipe — Prepare & Clear Context
 
-You MUST follow these steps in order:
+Follow these steps in order.
 
-## Step 1: Save pending knowledge
+## Step 1: Optionally save high-value knowledge
 
-Save any unsaved insights from this session:
-- New lessons learned → `write_memory(prefix="L", ...)`
-- Project progress → `append_memory(id="P00XX.7", ...)` (Protocol node)
-- Decisions made → `write_memory(prefix="D", ...)`
-- Errors encountered → `write_memory(prefix="E", ...)`
+Check `checkpointMode` in hmem.config.json to decide what to do:
 
-Skip if you already saved recently (last checkpoint < 5 messages ago).
+### checkpointMode: "auto"
 
-## Step 2: Title O-entries
+The Haiku subagent already extracts L/D/E entries every 20 exchanges automatically.
+Skip manual writes unless you have **specific high-value knowledge** that:
+- Was discovered in the last few exchanges (too recent for the last auto-checkpoint)
+- Is critical enough that losing it would cost significant rework
+- Is NOT already covered by a recent auto-checkpoint
 
-Run the title script in the background — it spawns Haiku to title untitled O-entries:
+If nothing qualifies, proceed directly to Step 2.
 
-```bash
-/home/bbbee/.claude/hooks/hmem-title-o-entries.sh &
-```
+### checkpointMode: "remind"
 
-## Step 3: Tell the user
+Manually save unsaved insights from this project context:
+- New lessons learned: `write_memory(prefix="L", ...)`
+- Project progress: `append_memory(id="P00XX.7", ...)` (Protocol node)
+- Decisions made: `write_memory(prefix="D", ...)`
+- Errors encountered: `write_memory(prefix="E", ...)`
+
+Skip if the last checkpoint was fewer than 5 messages ago.
+
+### Why gate on checkpointMode?
+
+Redundant writes waste tokens and create duplicates that clutter memory.
+Auto-checkpoints already call `read_memory` to deduplicate before writing —
+manual writes during wipe bypass that check and risk creating noise.
+
+## Step 2: Tell the user to /clear
+
+O-entries are auto-logged by the Stop hook — every exchange is already saved
+to the active project's O-entry. No need to manually create O-entries or call
+`flush_context` for conversation history.
 
 Reply with exactly:
 
-> Wissen gesichert, O-Titles werden im Hintergrund erstellt. Tippe jetzt `/clear` — der Hook injiziert automatisch den komprimierten Kontext.
+> Context ready for clear. Type `/clear` — the SessionStart hook will automatically restore your project context.
 
-Do NOT attempt to run /clear yourself — it's a built-in CLI command only the user can execute.
+Do NOT attempt to run /clear yourself — it is a built-in CLI command only the user can execute.
 
 ## What happens after /clear
 
 The `SessionStart[clear]` hook automatically:
 1. Resets the MCP session cache
-2. Injects the last 20 conversation messages from the transcript
+2. Injects recent conversation exchanges from the project's O-entry transcript
 3. Injects the active project briefing (overview expanded)
 4. Injects recent O-entry titles + rules
 
-The agent then has full context to continue working.
+The agent then calls `load_project` and has full context to continue working.
+No manual restoration needed.
+
+## Why this flow works
+
+- **O-entries are covered.** The Stop hook logs every exchange to the active
+  project's O-entry. Wipe does not need to handle conversation history.
+- **Checkpoints are covered (auto mode).** The Haiku subagent extracts knowledge
+  every 20 exchanges. Wipe only needs to catch the tail end, if anything.
+- **Context restoration is covered.** The SessionStart[clear] hook handles
+  re-injection automatically. The agent just needs the user to type /clear.

package/skills/hmem-write/SKILL.md

@@ -19,13 +19,30 @@ If the tool `write_memory` is not available:
 ```
 write_memory(
   prefix: "E",
-  content: "Short Title (~50 chars)\nL1 sentence — concise, understandable without context\n\tL2 detail (1 tab)\n\t\tL3 detail (2 tabs)\n\t\t\tL4 raw data (3 tabs — rarely needed)"
+  content: "Short Title (~50 chars)\n> L1 body — detailed explanation, can span multiple lines\n> second body line with more context\n\tL2 node title\n\t> L2 body text (supports newlines)\n\t> more L2 body\n\t\tL3 detail (2 tabs)\n\t\t\tL4 raw data (3 tabs — rarely needed)"
 )
 ```
 
-**Title convention:** The first non-indented line is the **title** (~50 chars, configurable via `maxTitleChars` in `hmem.config.json`) — a short label for navigation, like a chapter title. The second non-indented line is the L1 summary (full sentence). If only one non-indented line is provided, the title is auto-extracted from the first `maxTitleChars` characters.
+**Title + Body convention:** Every node has a **title** (short navigation label) and an optional **body** (detailed content loaded on drill-down).
 
-**Child node titles** are always auto-extracted from the first `maxTitleChars` characters of their content (or text before ` — ` if shorter). No explicit title needed for children.
+- **Title:** The first non-indented line (L1) or first line at a given indent level (L2+). ~50 chars, like a chapter title.
+- **Body:** Lines starting with `> ` at the same indent level. Joined with newlines. Shown only when the node is drilled into, not in listings.
+- **Backward-compatible:** Without `> ` lines, the full text is stored as `content` and the title is auto-extracted from the first `maxTitleChars` characters (existing behavior).
+
+**L1 example with body:**
+```
+Short Error Title
+> SQLite connection failed because .mcp.json used a relative path.
+> The fix was to use an absolute path in the HMEM_PROJECT_DIR env var.
+	Details about reproduction
+	> Steps: 1. Set HMEM_PROJECT_DIR=./hmem  2. Run hmem serve  3. Observe SQLITE_CANTOPEN
+```
+
+**L1 example without body (old format, still works):**
+```
+SQLite connection failed due to wrong path in .mcp.json
+	Fix: use absolute path in env var
+```
 
 **Indentation:** 1 tab = 1 level. Alternatively: 2 or 4 spaces per level (auto-detected).
 **Warning:** A tab at the start of any line always means "go one level deeper" — it is structural, not content. If you need to store code or text that contains leading tabs, use spaces instead.
@@ -167,13 +184,13 @@ The MCP server validates that L2 nodes start with one of these names. Minimum fo
 ```
 write_memory(
   prefix="P",
-  content="WeatherBot | New | Python/Discord.py | GH: user/weatherbot | Discord bot for weather forecasts\n\tOverview\n\t\tCurrent state — scaffolding done, no commands yet\n\t\tGoals — daily/hourly forecasts via slash commands, multi-city\n\t\tArchitecture — Discord slash command → OpenWeatherMap API → formatted embed\n\t\tEnvironment — /home/user/weatherbot, python bot.py, needs DISCORD_TOKEN + WEATHER_API_KEY\n\tCodebase\n\t\tEntry point — bot.py, start: python bot.py\n\t\tCore modules\n\t\t\tweather_cog.py — WeatherCog(Cog); fetch_forecast(city: str) → discord.Embed\n\t\t\tformatter.py — format_embed(data: dict) → discord.Embed\n\t\tHelpers / Utilities\n\t\t\tapi_client.py — get_weather(city: str) → dict; wraps HTTP to OpenWeatherMap\n\t\tConfig / Constants — .env: DISCORD_TOKEN, WEATHER_API_KEY, DEFAULT_CITY\n\t\tTests — pytest, test_weather_cog.py (3 tests)\n\tUsage\n\t\tInstallation / Setup — pip install -r requirements.txt, cp .env.example .env\n\t\tCLI / API — /weather <city>, /forecast <city> (planned)\n\tContext\n\t\tInitiator — personal project, Mar 2026\n\t\tTarget audience — personal Discord server\n\t\tDependencies — discord.py, OpenWeatherMap API, aiohttp\n\tOpen tasks\n\t\tImplement /forecast command for multi-day view\n\t\tAdd city autocomplete",
+  content="WeatherBot | New | Python/Discord.py | GH: user/weatherbot\n> Discord bot for weather forecasts — slash commands for current weather and multi-day forecasts\n\tOverview\n\t\tCurrent state\n\t\t> Scaffolding done, no commands yet. Bot connects to Discord but has no slash commands registered.\n\t\tGoals\n\t\t> Daily/hourly forecasts via slash commands, multi-city support, embed formatting\n\t\tArchitecture\n\t\t> Discord slash command → OpenWeatherMap API → formatted embed. Single-file cog pattern.\n\t\tEnvironment\n\t\t> /home/user/weatherbot, python bot.py, needs DISCORD_TOKEN + WEATHER_API_KEY in .env\n\tCodebase\n\t\tEntry point — bot.py, start: python bot.py\n\t\tCore modules\n\t\t\tweather_cog.py — WeatherCog(Cog); fetch_forecast(city: str) → discord.Embed\n\t\t\tformatter.py — format_embed(data: dict) → discord.Embed\n\t\tHelpers / Utilities\n\t\t\tapi_client.py — get_weather(city: str) → dict; wraps HTTP to OpenWeatherMap\n\t\tConfig / Constants — .env: DISCORD_TOKEN, WEATHER_API_KEY, DEFAULT_CITY\n\t\tTests — pytest, test_weather_cog.py (3 tests)\n\tUsage\n\t\tInstallation / Setup — pip install -r requirements.txt, cp .env.example .env\n\t\tCLI / API — /weather <city>, /forecast <city> (planned)\n\tContext\n\t\tInitiator — personal project, Mar 2026\n\t\tTarget audience — personal Discord server\n\t\tDependencies — discord.py, OpenWeatherMap API, aiohttp\n\tOpen tasks\n\t\tImplement /forecast command\n\t\t> Multi-day view with daily highs/lows and weather icons per day\n\t\tAdd city autocomplete",
   tags=["#discord", "#python", "#weather", "#bot"],
   links=[]
 )
 ```
 
-Note: L2 nodes use 1 tab, L3 uses 2 tabs, L4 uses 3 tabs. Each module under "Core modules" is an L4 node with signature + purpose. Skip empty sections — no need for placeholder text.
+Note: L2 nodes use 1 tab, L3 uses 2 tabs, L4 uses 3 tabs. Use `> ` for body text that should be hidden in listings but shown on drill-down. Skip empty sections — no need for placeholder text.
 
 ### Marking entries as favorites
 
@@ -234,22 +251,22 @@ write_memory(
 
 ---
 
-## Title + L1 Quality Rules
+## Title + Body Quality Rules
 
 **Title:** Short navigation label, ~50 chars (configurable via `maxTitleChars`). Think "chapter title in a book".
 - Good: `"hmem.py Performance: Bulk-Queries statt N+1"`, `"Ghost Wakeup Bug in msg-router.ts"`
 - Bad: `"Fixed a bug"`, `"Important lesson"` (too vague)
 
-**L1:** One complete, informative sentence — ~15–20 tokens.
+**Body (via `>` lines):** Detailed explanation — full sentences, multiline OK. Shown on drill-down, hidden in listings.
 - Must be understandable without any context
-- Not "Fixed a bug" — instead "SQLite connection failed due to wrong path in .mcp.json"
+- Not "Fixed a bug" — instead explain root cause, fix, and impact
 
-**With explicit title (recommended):**
+**With title + body (recommended):**
 ```
-write_memory(prefix="L", content="hmem.py Performance\nAlle Nodes in 2 Bulk-Queries laden, nicht pro Entry einzeln\n\tload_nodes() pro Entry = N+1 SQLite-Connections")
+write_memory(prefix="L", content="hmem.py Performance: Bulk-Queries statt N+1\n> Alle Nodes in 2 Bulk-Queries laden, nicht pro Entry einzeln.\n> Vorher: load_nodes() pro Entry = N+1 SQLite-Connections.\n\tImplementation detail\n\t> Changed read() to batch-fetch all nodes for visible entries in one query")
 ```
 
-**Without explicit title (auto-extracted):**
+**Without body (simple entries, backward-compatible):**
 ```
 write_memory(prefix="E", content="SQLite connection failed due to wrong path in .mcp.json\n\tFix: use absolute path in env var")
 ```
@@ -330,7 +347,13 @@ Only use `write_memory` when:
 
 ## When to save?
 
-**Mandatory before terminating.** Only save what is still valuable in 6 months.
+**Checkpoint mode matters.** Check `checkpointMode` in hmem.config.json:
+
+- **`"auto"` (recommended):** A background Haiku subagent handles checkpoints automatically every N exchanges. It reads recent O-entry exchanges, calls `read_memory` to avoid duplicates, and writes L/D/E entries + handoff via MCP tools. It also writes a rolling checkpoint summary (`[CP]` node tagged `#checkpoint-summary`) that compresses older exchanges for `load_project`. Skill-dialog exchanges are auto-tagged `#skill-dialog` and filtered from context injection. **You do NOT need to write entries yourself** unless the user explicitly asks you to save something specific.
+
+- **`"remind"`:** You will receive a CHECKPOINT reminder every N messages. When you see it, save key learnings yourself using `write_memory` / `append_memory`.
+
+**In both modes:** Only save what is still valuable in 6 months.
 
 | Save | Don't save |
 |------|-----------|
@@ -364,13 +387,14 @@ Use when: the wording is wrong, outdated, or needs clarification.
 Appends new child nodes under an existing root or node. Existing children are preserved.
 
 Content indentation is **relative to the parent** — 0 tabs = direct child of `id`.
+Body lines (`> `) work the same as in `write_memory`.
 
 ```
 append_memory(
   id="L0003",
-  content="New finding discovered later\n\tSub-detail about it"
+  content="New finding discovered later\n> Detailed explanation of what was found and why it matters.\n> This can span multiple lines.\n\tSub-detail about it"
 )
-# → adds L0003.N (L2) and L0003.N.1 (L3)
+# → adds L0003.N (L2 with title + body) and L0003.N.1 (L3)
 
 append_memory(
   id="L0003.2",