hmem-mcp 6.3.0 → 6.3.2

package/skills/hmem-update/SKILL.md

@@ -55,11 +55,18 @@ Check for new skills that weren't there before — inform the user about new cap
 
 Hooks are critical — without them, O-entries are never logged and auto-checkpoints never fire.
 
-Check the current hook configuration:
+Check the current hook configuration. Use the platform-appropriate command:
+
 ```bash
+# Linux / macOS
 cat ~/.claude/settings.json | grep -A5 hooks
 ```
 
+```powershell
+# Windows (PowerShell)
+Get-Content "$env:USERPROFILE\.claude\settings.json" | Select-String -Pattern "hooks" -Context 0,5
+```
+
 **Required hooks (for `checkpointMode: "auto"`):**
 - **UserPromptSubmit** — memory load + checkpoint reminder
 - **Stop** — exchange logging (`hmem log-exchange`) + O-entry title generation
@@ -73,6 +80,46 @@ cat ~/.claude/settings.json | grep -A5 hooks
 - Check that hook scripts exist and are executable
 - Verify they reference the current hmem installation path
 
+### Windows-specific hook checks (CRITICAL)
+
+On Windows, two specific issues break hooks. Always run these checks when updating on Windows:
+
+**Check 1 — `shell: powershell` present on every hook command?**
+
+Each object in `hooks.*.hooks` and the `statusLine` object must contain `"shell": "powershell"`. Without it, Claude Code may route the command through Git Bash, whose MSYS2 runtime crashes transiently at startup (`bash.exe: *** fatal error - add_item ... errno 1`) before the command is even parsed. Every hook then fails with a generic error.
+
+**Check 2 — No inline env-var syntax in commands?**
+
+Commands must NOT contain `VAR=value` prefixes like `HMEM_PATH=C:/... node ...`. That's bash-only syntax; cmd.exe and PowerShell interpret `HMEM_PATH=...` as the command name and fail. All env vars must live in the top-level `env` block of settings.json.
+
+**The correct Windows shape:**
+
+```json
+{
+  "env": {
+    "HMEM_PATH": "C:/Users/<you>/.hmem/Agents/<AGENT>/<AGENT>.hmem"
+  },
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node C:/Users/<you>/AppData/Roaming/npm/node_modules/hmem-mcp/dist/cli.js log-exchange",
+            "shell": "powershell"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**If either check fails:** Offer to fix settings.json automatically. The fix is lossless on other platforms, so it's safe to apply even on shared configs synced across OSes. Point the user to the Windows hook section in `/hmem-config` for the full pattern (UserPromptSubmit, Stop, SessionStart, statusLine).
+
+**After fixing:** Claude Code must be restarted so the `env` block is re-loaded and hooks are re-registered with the new shell.
+
 ---
 
 ## Step 2c: Check load_project Display Config

package/skills/hmem-wipe/SKILL.md

@@ -76,15 +76,17 @@ Do NOT attempt to run /clear yourself — it is a built-in CLI command only the
 
 ## What happens after /clear
 
-The `SessionStart[clear]` hook automatically:
+Context is restored **automatically** by the `SessionStart[clear]` hook — no
+agent action needed after /clear. Do **NOT** call `load_project` or `read_memory`
+during or after this skill; the next session's first UserPromptSubmit hook will
+trigger the normal hmem-read flow with a verified active project ID.
+
+The hook:
 1. Resets the MCP session cache
 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 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

package/skills/hmem-write/SKILL.md

@@ -131,10 +131,20 @@ append_memory(id="P0048.6", content="Auto-sync fails with multiple .hmem in CWD
 ```
 Custom prefixes are merged with the defaults — they don't replace them. Without registering, the system will reject the prefix.
 
-### P-Entry Standard Schema (enforced by MCP server)
+### Schema-Enforced Entries (P and any prefix with a defined schema)
 
-Every project entry MUST follow this structure. The MCP server validates L2 nodes
-against the standard categories when `prefix="P"`.
+The MCP server enforces schemas for any prefix that has a `schemas` entry in `hmem.config.json`.
+For those prefixes, two rules apply:
+
+1. **`write_memory`**: L2 node names must match the defined section names (error otherwise).
+2. **`append_memory` to root entry (e.g. `P0029`, no dot)**: **blocked** — you cannot add new L2 sections.
+   You must append to a specific section: `append_memory(id="P0029.N", content="...")`.
+
+By default, `P` has a schema. If `L`, `D`, or other prefixes are configured with schemas, the same rules apply.
+
+### P-Entry Standard Schema
+
+Every project entry MUST follow this structure.
 
 **L1 Title:** `Name | Status | Tech Stack | GH: owner/repo | Short description`
 The GH field is optional — include it when a GitHub repo exists, omit otherwise.
@@ -327,7 +337,8 @@ read_memory(id="P0029")   # shows root + all L2 titles
 ```
 Do any L2 titles match the sub-topic?
 
-- **No match** → `append_memory(id="P0029", content="...")` adds a new L2
+- **No match (and no schema)** → `append_memory(id="P0029", content="...")` adds a new L2
+- **No match (schema-constrained entry like P)** → find the closest existing section and append there (L2 additions are blocked)
 - **Match found (e.g. .15)** → continue to Step 3
 
 **Step 3 — Drill into that L2**
@@ -411,12 +422,24 @@ Appends new child nodes under an existing root or node. Existing children are pr
 Content indentation is **relative to the parent** — 0 tabs = direct child of `id`.
 Body works the same as in `write_memory` — blank line separates title from body.
 
+> **Schema enforcement:** For entries with a defined schema (e.g., all P-entries), appending
+> to the root (e.g., `id="P0029"`) is **blocked** — that would create a new L2 section outside
+> the schema. You must target a specific section: `append_memory(id="P0029.3", content="...")`.
+> For entries without a schema (L, D, E, etc. by default), root appends are allowed.
+
 ```
 append_memory(
   id="L0003",
   content="New finding discovered later\n\nDetailed explanation of what was found and why it matters.\nThis can span multiple lines.\n\tSub-detail about it"
 )
 # → adds L0003.N (L2 with title + body) and L0003.N.1 (L3)
+# ↑ only works if L has no schema defined; use L0003.N for schema-constrained entries
+
+append_memory(
+  id="P0029.3",
+  content="New detail in the Usage section"
+)
+# → adds P0029.3.M (L3 under section .3) — correct way for schema-constrained entries
 
 append_memory(
   id="L0003.2",
@@ -434,7 +457,7 @@ Use when: you have new context to add without replacing what's there.
 | L1 wording is wrong/outdated | `update_memory` |
 | A sub-node has wrong detail | `update_memory` |
 | You have new info to add | `append_memory` |
-| Entry is completely wrong | curator: `delete_agent_memory` + `write_memory` |
+| Entry is completely wrong | mark obsolete with `[✓newId]`, then `write_memory` for the correction |
 
 ---
 

package/skills/hmem-self-curate/SKILL.md

@@ -1,194 +0,0 @@
----
-name: hmem-self-curate
-description: Curate your own memory. Systematically review entries — mark obsolete, irrelevant, or favorite. Run periodically to keep memory clean. Use when asked to "aufräumen", "clean up memory", "alte Einträge prüfen", "memory review", "Speicher bereinigen", "curate", "tidy up", or when memory_health() shows issues.
----
-
-# Self-Curation: Review Your Own Memory
-
-You are curating **your own** memory. You know best which entries are still relevant.
-
----
-
-## Step 0: Health Check First
-
-Before diving in, run an audit to get a prioritized list of issues:
-
-```
-memory_health()
-```
-
-This instantly shows:
-- **Broken links** — fix or remove them first (high impact, easy to miss manually)
-- **Orphaned entries** — root entries with no sub-nodes (likely draft stubs)
-- **Stale favorites/pinned** — favorites not accessed in >60 days (demote or verify)
-- **Broken obsolete chains** — `[✓ID]` pointing to deleted entries
-
-Also useful before starting:
-```
-memory_stats()          # overview: how many entries per prefix, stale count, etc.
-read_memory(stale_days=60)  # entries not touched in 60 days — prime curation candidates
-```
-
----
-
-## Workflow: Prefix by Prefix
-
-Work through one prefix at a time. Load all entries of a prefix with full depth:
-
-```
-read_memory(prefix="P", show_all=true)
-```
-
-This bypasses the bulk-read algorithm and session cache — every entry is expanded with L2+L3 children visible. Review each entry in the output directly — no need to drill into individual entries.
-
-**Order:** Start with the prefix that has the most entries (usually P), then move to L, E, D, O, etc.
-
-If context overflows mid-prefix, continue with the remaining entries — your memory survives compression.
-
----
-
-## O-Entries (Session Logs)
-
-O-entries accumulate automatically via the Stop hook — each session creates one per project. `load_project` injects the latest session's **checkpoint summary** (if available) plus the most recent raw exchanges.
-
-**Checkpoint summaries:** Auto-checkpoints write a `[CP]` prefixed summary node (tagged `#checkpoint-summary`) under the O-entry. These rolling summaries compress older exchanges so `load_project` stays compact. Older summaries are further compressed into 1-2 sentences by each new checkpoint.
-
-**Skill-dialog filtering:** Exchanges containing skill activations (brainstorming, TDD, debugging) are tagged `#skill-dialog` at the exchange-node level and automatically excluded from `load_project` / `/clear` output. The full content remains accessible via `read_memory(id="O0123")`.
-
-**Curation rules for O-entries:**
-- **Leave them alone.** Old O-entries don't cause harm — they're excluded from bulk reads and `load_project` only shows the most recent one.
-- **Don't mark them irrelevant or obsolete** — they serve as historical record and can be useful for checkpoint agents extracting L/D/E.
-- **Skip O-entries during curation.** Focus your time on L, E, D, P entries where curation has real impact.
-
----
-
-## Bulk Operations
-
-For large-scale curation across many entries, use the bulk tools instead of updating one by one:
-
-| Tool | Purpose |
-|------|---------|
-| `update_many(updates=[...])` | Batch-update multiple entries at once (content, flags, etc.) |
-| `tag_bulk(ids=[...], add_tags=[...], remove_tags=[...])` | Add or remove tags across many entries in one call |
-| `tag_rename(old_tag="...", new_tag="...")` | Rename a tag globally across all entries |
-
-These are especially useful when a curation pass reveals a pattern (e.g., 10 entries that all need the same tag added, or a batch of stale entries to mark irrelevant).
-
----
-
-## Title Quality Check
-
-Since v5.1, every node has a **title** (short navigation label, ~50 chars) and an optional **body** (detailed content shown on drill-down). During curation, check whether titles are good navigation labels:
-
-- **Vague title?** Update it: `update_memory(id="L0003", content="Better, specific title")`
-- **Title = full content?** Old entries without body separation have `title = autoExtract(content)`. If the content is valuable but the title is truncated gibberish, rewrite with explicit title + blank line + body.
-- **Long content in a leaf node?** Consider whether it would benefit from title/body separation: `update_memory(id, content="Clear title\n\nDetailed body text")`.
-
----
-
-## For Each Entry: Decide and Act
-
-| Decision | Action |
-|----------|--------|
-| Still valid and useful | Skip (no action needed) |
-| Important reference I need every session | `update_memory(id="X", content="...", favorite=true)` |
-| Outdated — a better entry exists | Mark obsolete (see below) |
-| Just noise — not wrong, but irrelevant | `update_memory(id="X", content="...", irrelevant=true)` |
-| Title is vague or misleading | `update_memory(id="X", content="Better wording")` |
-| Sub-node has valuable reference info | `update_memory(id="X.N", content="...", favorite=true)` |
-
----
-
-## Marking Obsolete
-
-Obsolete requires a correction reference. Three patterns:
-
-**A: Replacement exists already**
-```
-update_memory(id="E0023", content="Wrong approach — see [✓E0076]", obsolete=true)
-```
-
-**B: No replacement exists yet**
-```
-write_memory(prefix="L", content="Correct approach is XYZ\n\tDetails...")  # -> L0090
-update_memory(id="L0042", content="Superseded — see [✓L0090]", obsolete=true)
-```
-
-**C: Just stale, no correction needed**
-If the entry is simply outdated with no replacement (e.g., a finished task, a past state):
-```
-update_memory(id="T0005", content="...", irrelevant=true)
-```
-
----
-
-## Consolidate Duplicates
-
-Look for entries covering the same topic (common with P entries). Merge them:
-
-1. Pick the **keeper** (the more complete one)
-2. Copy unique info from the duplicate: `append_memory(id="P0029", content="Session from duplicate\n\tDetail carried over")`
-3. Mark the duplicate obsolete with a correction reference: `update_memory(id="P0031", content="Merged into [✓P0029]", obsolete=true)`
-
-**Note:** Only curators (ceo role) can delete entries via `delete_agent_memory`. As a worker agent, use `obsolete=true` with `[✓ID]` to point to the keeper. Obsolete entries are hidden from bulk reads and won't cause confusion.
-
----
-
-## Relocate Misplaced Nodes
-
-When a sub-node belongs under a different root or parent, use `move_memory` to cut and re-insert it. All IDs, links, and `[✓ID]` content references are updated automatically.
-
-```
-# Move P0029.15 to become a child of L0074
-move_memory(source_id="P0029.15", target_parent_id="L0074")
-# → P0029.15 (+ all children) become L0074.N (new seq under L0074)
-
-# Move within the same root: P0029.15 → under P0029.20
-move_memory(source_id="P0029.15", target_parent_id="P0029.20")
-# → becomes P0029.20.N with all children re-keyed
-```
-
-**Constraints:**
-- `source_id` must be a sub-node — cannot move root entries
-- Cannot move a node into its own subtree
-- Curator variant: `move_agent_memory(agent_name="THOR", source_id="...", target_parent_id="...")`
-
----
-
-## Favorite Audit
-
-Check `[♥]` markers in the output.
-
-- **Too many?** If >10% are favorites, demote less important ones: `update_memory(id="X", content="...", favorite=false)`
-- **Missing?** Reference entries you always need (API endpoints, key decisions, patterns) should be favorited.
-- **Sub-nodes:** If a specific L2/L3 is the real reference, favorite the sub-node instead.
-
----
-
-## Guidelines
-
-- **One prefix per batch.** Don't try all 200+ entries at once — focus on one prefix per `show_all` call.
-- **Preserve learning value.** Error entries (E) and lessons (L) about *why* something failed are valuable even if the bug is fixed. Only mark obsolete if the analysis is wrong.
-- **When in doubt, skip.** False irrelevant/obsolete is harder to undo than leaving an entry alone.
-- **Update stale L1 text.** A clear L1 is the most impactful improvement you can make.
-
----
-
-## Quick Reference
-
-| Tool | When |
-|------|------|
-| `memory_health()` | **Start here** — broken links, orphans, stale favorites |
-| `memory_stats()` | Overview before starting |
-| `read_memory(stale_days=60)` | Prime curation targets |
-| `read_memory(prefix="X", show_all=true)` | Load entire prefix for review |
-| `update_memory(id, content, favorite=true)` | Mark as always-show reference |
-| `update_memory(id, content, irrelevant=true)` | Hide from bulk reads (noise) |
-| `update_memory(id, content, obsolete=true)` | Mark as wrong (needs [✓ID]) |
-| `append_memory(id, content)` | Merge info into keeper |
-| `move_memory(source_id, target_parent_id)` | Relocate misplaced sub-node (updates all refs) |
-| `update_memory(id, content="Merged into [✓X]", obsolete=true)` | Mark duplicate as obsolete (point to keeper) |
-| `update_many(updates=[...])` | Batch-update multiple entries at once |
-| `tag_bulk(ids=[...], add_tags, remove_tags)` | Add/remove tags across many entries |
-| `tag_rename(old_tag, new_tag)` | Rename a tag globally |
-| `read_memory(show_obsolete=true, prefix="X")` | Review already-obsolete entries |