hmem-mcp 6.3.0 → 6.3.2

package/opencode-plugin/hmem.js

@@ -0,0 +1,105 @@
+/**
+ * hmem OpenCode plugin
+ *
+ * Bridges OpenCode's plugin event system into hmem's CLI hook commands.
+ * Drop this file into ~/.config/opencode/plugins/ (global) or
+ * .opencode/plugins/ (project-local) and OpenCode will auto-load it.
+ *
+ * Mapping:
+ *   chat.message                       → capture user prompt + write session marker
+ *   event: message.part.updated        → accumulate assistant text per session
+ *   event: session.idle                → spawn `hmem log-exchange` + `hmem checkpoint`
+ *   experimental.session.compacting    → inject hmem context into compaction prompt
+ *
+ * Requires `hmem` CLI on PATH and HMEM_PATH env var (auto-detected if unset).
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+
+function spawnHmem(args, stdinJson) {
+  try {
+    const child = spawn("hmem", args, {
+      detached: true,
+      stdio: ["pipe", "ignore", "ignore"],
+      env: process.env,
+    });
+    if (stdinJson) {
+      child.stdin.end(stdinJson);
+    } else {
+      child.stdin.end();
+    }
+    child.unref();
+  } catch {
+    // hmem not installed or not on PATH — silently no-op
+  }
+}
+
+function partsToText(parts) {
+  if (!Array.isArray(parts)) return "";
+  return parts
+    .filter(p => p && p.type === "text" && typeof p.text === "string")
+    .map(p => p.text)
+    .join("\n")
+    .trim();
+}
+
+export default {
+  id: "hmem",
+  server: async () => {
+    const userMessages = new Map();
+    const assistantBuffers = new Map();
+
+    return {
+      "chat.message": async ({ sessionID }, { parts }) => {
+        const text = partsToText(parts);
+        if (text) userMessages.set(sessionID, text);
+        assistantBuffers.set(sessionID, "");
+        spawnHmem(["hook-startup"], JSON.stringify({ session_id: sessionID }));
+      },
+
+      event: async ({ event }) => {
+        if (!event || typeof event !== "object") return;
+
+        if (event.type === "message.part.updated") {
+          const part = event.properties?.part;
+          if (!part || part.type !== "text" || typeof part.text !== "string") return;
+          const sid = part.sessionID;
+          if (!sid) return;
+          assistantBuffers.set(sid, part.text);
+          return;
+        }
+
+        if (event.type === "session.idle") {
+          const sid = event.properties?.sessionID;
+          if (!sid) return;
+          const userMessage = userMessages.get(sid);
+          const assistantMessage = assistantBuffers.get(sid);
+          if (!userMessage || !assistantMessage) return;
+          userMessages.delete(sid);
+          assistantBuffers.delete(sid);
+          spawnHmem(["log-exchange"], JSON.stringify({
+            session_id: sid,
+            last_user_message: userMessage,
+            last_assistant_message: assistantMessage,
+          }));
+          spawnHmem(["checkpoint"], JSON.stringify({ session_id: sid }));
+        }
+      },
+
+      "experimental.session.compacting": async ({ sessionID }, output) => {
+        try {
+          const result = spawnSync("hmem", ["context-inject"], {
+            input: JSON.stringify({ session_id: sessionID }),
+            encoding: "utf8",
+            timeout: 5000,
+            env: process.env,
+          });
+          const text = (result.stdout || "").trim();
+          if (text) output.context.push(text);
+        } catch {
+          // hmem not available — skip
+        }
+      },
+    };
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hmem-mcp",
-  "version": "6.3.0",
+  "version": "6.3.2",
   "description": "Humanlike memory for AI agents — MCP server with 5-level lazy-loaded SQLite memory",
   "author": "Bumblebiber",
   "license": "MIT",
@@ -32,6 +32,7 @@
     "dist",
     "skills",
     "scripts",
+    "opencode-plugin",
     "prebuilds",
     "server.json",
     "README.md",

package/skills/hmem-config/SKILL.md

@@ -183,3 +183,80 @@ 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):**
+
+```json
+{
+  "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.

package/skills/hmem-curate/SKILL.md

@@ -1,206 +1,213 @@
 ---
 name: hmem-curate
-description: >
-  Memory curation workflow. Use when asked to curate, audit, or clean up agent memories.
-  Processes one agent at a time — read, fix, mark audited, summarize, terminate.
-  Requires role: ceo.
+description: Curate hmem memory — your own or a foreign .hmem file. Systematically review entries, mark obsolete/irrelevant/favorite, fix titles, consolidate duplicates. Use when asked to "aufräumen", "clean up memory", "curate", "Speicher bereinigen", "tidy up", or when memory_health() shows issues.
 ---
 
-# /hmem-curate — hmem Curation Workflow
+# hmem Curation
 
-You are the memory curator. Process **one agent per run**, then terminate.
+Curate hmem memory — mark obsolete/irrelevant/favorite, fix titles, consolidate duplicates, fix broken links.
+
+**Two modes:**
+- **Self-curation** (default): you curate your own memory. No extra params.
+- **Foreign-file curation**: pass `hmem_path=/absolute/path/to/file.hmem` to `read_memory`, `update_memory`, `memory_health`, `find_related`. Sync and session cache are disabled. All updates land in that file.
 
 ---
 
-## Step-by-Step
+## Step 0: Health Check First
 
 ```
-1. get_audit_queue()
-   → Empty → write a short summary to LAST_CURATION.md and terminate
-   → Not empty → take the FIRST agent from the list
+memory_health()                  # own store
+memory_health(hmem_path="...")   # foreign file
+```
+
+Shows:
+- **Broken links** — entries with refs to deleted IDs
+- **Orphaned entries** — roots with no sub-nodes (likely draft stubs)
+- **Stale favorites/pinned** — not accessed in >60 days (demote or verify)
+- **Broken obsolete chains** — `[✓ID]` pointing to deleted entries
 
-2. read_agent_memory(agent_name, depth=5)
-   → Study all entries carefully
+Useful before starting:
+```
+memory_stats()
+read_memory(stale_days=60)                   # stale entries in own store
+read_memory(stale_days=60, hmem_path="...")  # same, foreign file
+```
 
-3. Fix every issue found (see criteria below)
+---
 
-4. mark_audited(agent_name)
+## Workflow: Prefix by Prefix
 
-5. Append one line to LAST_CURATION.md:
-   "- **AGENTNAME**: N entries — [OK | fixed L0003 | marked E0002 obsolete (dup) | consolidated P0004+P0007→P0004]"
+Work one prefix at a time. Load all entries of a prefix with full depth:
 
-6. Terminate.
 ```
+read_memory(prefix="P", show_all=true)
+read_memory(prefix="P", show_all=true, hmem_path="...")
+```
+
+`show_all=true` bypasses the bulk-read algorithm and session cache — every entry is expanded with L2+L3 children visible. Review the output directly.
+
+**Order:** Start with the prefix with the most entries (usually P), then L, E, D, etc.
+
+If context overflows mid-prefix, continue with the remaining entries — memory survives compression.
 
 ---
 
-## Quality Criteria
+## For Each Entry: Decide and Act
 
-### L1 Quality
-| Check | Rule |
-|-------|------|
-| Too long | Single concise sentence, ~15–20 tokens. Fix with `fix_agent_memory(agent_name, id, content="shorter")` |
-| Too vague | "Fixed a bug" → mark obsolete. "SQLite failed due to wrong path in .mcp.json" → keep |
-| Factually wrong | Fix content or mark obsolete. |
-| Duplicate of another entry | Merge the best content from both into the keeper (see merge workflow below), then mark the weaker entry obsolete. |
+| Decision | Action |
+|----------|--------|
+| Still valid and useful | Skip |
+| Important reference (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 vague or misleading | `update_memory(id="X", content="Better wording")` |
+| Sub-node has valuable reference info | `update_memory(id="X.N", content="...", favorite=true)` |
 
-### Compound Node IDs
-Memory content lives in `memory_nodes` — not in flat `level_2/3` fields.
-To fix an L2 or deeper node, use the compound ID: `fix_agent_memory(agent_name, "L0003.2", content="corrected text")`.
-To navigate the tree: `read_memory` shows node IDs like `L0003.2`, `L0003.2.1` — use those directly.
+Add `hmem_path="..."` to every call when curating a foreign file.
 
-### Obsolete entries
-Entries marked `[!]` (or `[OBSOLETE]` in curator view) are already hidden from bulk reads — they do not need to be deleted.
-Leave them in place. The curator's job is to *mark* entries obsolete, not remove them.
+---
+
+## Marking Obsolete
+
+Obsolete requires a correction reference. Three patterns:
 
-**Curator bypass:** As curator, you can mark entries obsolete **without** the `[✓ID]` correction reference that agents are required to include. Use this for stale entries where no correction exists (e.g., entries about deleted features, abandoned approaches).
+**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)
 ```
-# Curator can bypass [✓ID] enforcement:
-fix_agent_memory(agent_name, id, obsolete=true)
 
-# But prefer including a correction reference when one exists:
-fix_agent_memory(agent_name, id, content="Outdated — see [✓E0076]", obsolete=true)
+**C: Just stale, no correction needed**
+```
+update_memory(id="T0005", content="...", irrelevant=true)
 ```
 
-### Merging entries (duplicates and fragmented P entries)
+Foreign file: curator may mark obsolete without `[✓ID]` for stale entries where no correction exists.
 
-**Merge workflow:**
-1. Read both entries fully (`read_memory(id=X)` for each)
-2. Pick the **keeper** (usually the older/more informative one)
-3. Fix the keeper's L1 if needed: `fix_agent_memory(agent_name, keeper_id, content="Broader title")`
-4. Carry over the best content from the entry to be deleted:
-   - Existing nodes with better wording → `fix_agent_memory(agent_name, "KEEPER.2", content="improved text")`
-   - Content that only exists in the entry to be deleted → `append_agent_memory(agent_name, keeper_id, content="carried-over detail\n\tsub-detail")`
-5. `fix_agent_memory(agent_name, fragment_id, obsolete=true)` once content is carried over
+---
 
-**For fragmented P entries** (same project, multiple entries):
-- Same workflow. Pick oldest as keeper.
-- Goal: one P entry per project, growing over time.
+## Consolidate Duplicates
 
-*Note: only carry over content with lasting value. Low-value session notes can be dropped.*
+1. Pick the **keeper** (more complete, usually older)
+2. Copy unique info: `append_memory(id="P0029", content="Carry-over\n\tDetail")`
+3. Mark duplicate obsolete: `update_memory(id="P0031", content="Merged into [✓P0029]", obsolete=true)`
 
-### Links — cross-references
+**Fragmented P-entries (same project, multiple entries):** same workflow. One P per project.
+
+---
 
-When two entries have a clear causal or contextual relationship (e.g. a P entry and the L/E entries that resulted from it, or an E entry and the D entry that documents the fix decision), add links at **both** entries so they resolve each other on drill-down:
+## Links — Cross-References
+
+When two entries have a clear causal/contextual relationship (e.g. a P and the L/E entries that resulted from it), add links at **both** so drill-down resolves them:
 
 ```
-fix_agent_memory(agent_name, "P0001", links=["L0023", "E0009"])
-fix_agent_memory(agent_name, "L0023", links=["P0001"])
-fix_agent_memory(agent_name, "E0009", links=["P0001"])
+update_memory(id="P0001", content="...", links=["L0023", "E0009"])
+update_memory(id="L0023", content="...", links=["P0001"])
 ```
 
-`read_memory(id=X)` auto-resolves linked entries — the agent sees both sides when drilling into either one.
+Don't over-link — only where navigation benefits.
 
-Don't over-link: only add links where the connection adds real navigational value, not just topical similarity.
+---
 
-### Title/Body Quality (v5.1+)
+## Title/Body Quality
 
-Entries support explicit title/body separation via a blank line (like git commits). During curation:
+Every node has a **title** (short, ~50 chars) and optional **body** (blank line separator). During curation:
 
 **Root entries (L1):**
-- Check if the auto-extracted title is meaningful. If it's truncated or vague, rewrite with explicit title + body:
+- Auto-title truncated/meaningless? Rewrite with explicit title + body:
   ```
-  fix_agent_memory(agent_name, id, content="Clear navigation title\n\nOriginal detailed L1 text that was too long for a title")
+  update_memory(id="L0042", content="Clear title\n\nDetailed L1 body that was too long for a title")
   ```
-- Old entries without body separation still work — the title is auto-extracted from `level_1`. Only rewrite if the auto-title is genuinely bad.
 
 **Child nodes (L2+):**
-- Same principle: if a node has dense content, split into title + body:
+- Dense content? Split into title + body:
   ```
-  fix_agent_memory(agent_name, "L0003.2", content="Short node title\n\nDetailed explanation\nspanning multiple lines")
+  update_memory(id="L0003.2", content="Short node title\n\nDetailed explanation")
   ```
-- Nodes with short, clear content don't need body separation — leave them as-is.
 
-**When to rewrite old entries:**
-- Auto-title is truncated mid-word or meaningless
-- Node has >200 chars of content crammed into one line
-- Content is valuable but hard to scan in listings (title = full text)
+**Rewrite when:** auto-title is truncated mid-word, node has >200 chars crammed in one line, content is valuable but unscannable.
+**Don't rewrite when:** title is already clear, or entry has low access count and marginal value.
 
-**When NOT to rewrite:**
-- Title is already clear and navigable
-- Entry has low access count and marginal value (not worth the effort)
+---
 
-### P-Entry Standard-Schema (R0009)
+## P-Entry Standard-Schema (R0009)
 
-All P-entries must follow the standard L2 structure (see R0009):
+P-entries follow the standard L2 structure:
 `.1 Overview`, `.2 Codebase`, `.3 Usage`, `.4 Context`, `.5 Deployment`, `.6 Bugs`, `.7 Protocol`, `.8 Open tasks`, `.9 Ideas`
 
-During curation, check P-entries against this schema:
-- **Missing sections:** Add them using `append_agent_memory(agent_name, "P00XX", content="\tOverview\n\t\tCurrent state: ...")`
-- **Wrong order:** Flag and restructure — order is fixed per R0009
-- **Empty sections:** OK to omit, but if content exists it must be in the right section
-- **L1 body:** Should be a one-line project summary in format `Name | Status | Stack | Description`
-
-### O-entry curation (v5.1.2+)
-
-O-entries may need curation for titles, tags, and summaries:
+Check P-entries during curation:
+- **Missing section:** `append_memory(id="P00XX", content="\tOverview\n\t\tCurrent state: ...")`
+- **Wrong order:** Restructure — order is fixed per R0009
+- **Empty section:** OK to omit, but content must be in the right section if present
+- **L1 body:** One-line project summary: `Name | Status | Stack | Description`
 
-**Titles:**
-- Old O-entries may have title "unassigned" or generic titles like "hmem-mcp". Fix with `fix_agent_memory(agent_name, id, content="Descriptive session title")`.
-- Good title: "Title/Body Separation design + v5.1.0 release". Bad: "hmem-mcp".
+---
 
-**Tags:**
-- O-entries should have a `#session` tag and optionally topic tags (e.g. `#npm`, `#release`, `#refactor`).
-- Add missing tags: `fix_agent_memory(agent_name, id, tags=["#session", "#release"])`
+## O-Entries (Session Logs)
 
-**Checkpoint summaries:**
-- O-entries with many exchanges (>10) should have a `[CP]` checkpoint summary. If missing, write one:
-  `append_agent_memory(agent_name, "O00XX", content="\t[CP] Factual 3-8 sentence summary of the session")`
-  Then tag it: the auto-tagger picks up `[CP]` prefixed nodes on the next checkpoint run.
+O-entries accumulate via the Stop hook. They're excluded from bulk reads by default — **leave them alone**. Focus curation time on L, E, D, P.
 
 **Special tagged nodes — do not modify:**
-- **`#checkpoint-summary`** nodes: Auto-generated `[CP]` summaries. Leave as-is.
-- **`#skill-dialog`** exchange nodes: Skill activations filtered from `load_project`. Leave as-is.
+- `#checkpoint-summary` — auto-generated `[CP]` summaries
+- `#skill-dialog` — skill activation exchanges
 
-### Stale entries — auto-mark obsolete
+**Exception — old O-entries with bad titles/missing tags:**
+- `update_memory(id="O0042", content="Descriptive session title")`
+- `update_memory(id="O0042", content="...", tags=["#session", "#release"])`
 
-Entries older than 1 month with `access_count = 0` (no `(Nx accessed)` suffix in curator read) should be marked obsolete automatically.
+---
 
-```
-fix_agent_memory(agent_name, id, obsolete=true)
-```
+## Bulk Operations
 
-Exception: unique lessons or error patterns with no equivalent elsewhere — keep even if never accessed.
+For large-scale changes across many entries:
 
-**Note:** The V2 algorithm uses **time-weighted scoring** (`access_count / log2(age_in_days + 2)`) for "most accessed" ranking. This means genuinely stale entries (old + low access) naturally sink — but an old entry that's still frequently accessed stays visible.
+| Tool | Purpose |
+|------|---------|
+| `update_many(updates=[...])` | Batch flag updates across multiple IDs |
+| `tag_bulk(ids=[...], add_tags=[...], remove_tags=[...])` | Add/remove tags across many entries |
+| `tag_rename(old_tag, new_tag)` | Rename a tag globally |
 
-### N entries — flag stale code pointers
-Navigator entries go stale when code moves. Check: does the file/line referenced still exist?
-If stale and the agent hasn't updated it: mark obsolete via `fix_agent_memory(agent_name, id, obsolete=true)`.
-Do NOT fix stale N entries yourself — the agent who wrote them must verify and update.
+(These operate on your own store only — for foreign files, iterate manually with `update_memory(hmem_path=...)`.)
 
 ---
 
-### Quick audit with titles_only
+## Relocate Misplaced Nodes
 
-Use `read_memory(titles_only=true)` for a compact overview of an agent's memory before drilling in. Shows V2-selected entries as one line each with `(N)` child counts — useful for spotting duplicates, poor titles, or category imbalances at a glance.
+`move_memory` cuts and re-inserts a sub-node under a new parent, rewriting all IDs + links + `[✓ID]` refs.
+
+```
+move_memory(source_id="P0029.15", target_parent_id="L0074")
+move_memory(source_id="P0029.15", target_parent_id="P0029.20")
+```
+
+**Constraints:** source must be a sub-node (not root); cannot move into own subtree. Operates on own store only.
 
 ---
 
-## V2 Bulk-Read Output
+## Favorite Audit
 
-The default `read_memory()` now returns **grouped output** by prefix category:
+- **Too many?** >10% favorites → demote less important: `update_memory(id="X", content="...", favorite=false)`
+- **Missing?** Reference entries (API endpoints, key decisions, patterns) should be favorites.
+- **Sub-node better than root?** Favorite the sub-node instead.
 
-```
-## Project experiences and summaries (5 entries)
+---
 
-P0001 02-14  Das Althing — Node.js/TS Multi-Agent-Orchestrator
-  2.1  Architecture: Node.js polling daemon with file-based IPC
-  2.2  Key decisions: SQLite for hmem, MCP for tool protocol
-  [+7 more → P0001]
-  Links: L0045, D0003
+## Stale Entries
 
-## Lessons learned and best practices (78 entries)
-...
+Entries older than 1 month with `access_count = 0`: mark obsolete.
 
---- 5 obsolete entries hidden (E0023, D0007, ...) — top 3 shown above ---
+```
+update_memory(id="L0042", obsolete=true)
 ```
 
-**Expanded entries** (newest, most-accessed, favorites) show all L2 children + links.
-**Non-expanded entries** show latest child + `[+N more → ID]` hint.
+**Exception:** unique lessons or error patterns with no equivalent — keep even if never accessed.
 
-Use `read_memory(show_obsolete=true)` to see all obsolete entries.
+The V2 algorithm uses time-weighted scoring (`access_count / log2(age_in_days + 2)`) — old+low-access entries naturally sink; old+high-access stay visible.
 
 ---
 
@@ -208,22 +215,39 @@ Use `read_memory(show_obsolete=true)` to see all obsolete entries.
 
 | Store | Max entries | Action when over |
 |-------|-------------|-----------------|
-| Personal | 300 | Triage: duplicates → low-access old entries → generic lessons |
+| Personal | 300 | Triage: duplicates → low-access old → generic lessons |
 | Company | 200 | Same |
 
-**Triage order (over limit):**
-1. Mark exact duplicates obsolete (after merging content into keeper)
-2. Mark stale entries obsolete (access_count = 0, >1 month old)
-3. Consolidate fragmented P entries
-4. Mark borderline entries obsolete
+**Triage order:** exact duplicates → stale (access=0, >1 month) → fragmented P entries → borderline.
+
+---
+
+## 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 |
+| `update_memory(id, content, favorite=true)` | Always-show reference |
+| `update_memory(id, content, irrelevant=true)` | Hide from bulk reads |
+| `update_memory(id, content, obsolete=true)` | Mark wrong (needs [✓ID]) |
+| `append_memory(id, content)` | Merge info into keeper |
+| `move_memory(source_id, target_parent_id)` | Relocate misplaced sub-node |
+| `update_many(updates=[...])` | Batch flag updates |
+| `tag_bulk / tag_rename` | Tag maintenance |
+| `read_memory(show_obsolete=true)` | Review already-obsolete |
+| `find_related(id)` | Discover connections / spot duplicates |
+
+All four read/update/health/find tools accept `hmem_path="..."` for foreign-file curation.
 
 ---
 
 ## Rules
 
 - Never invent or fabricate memories.
-- Never add new content — only fix, consolidate, or mark obsolete. Never delete.
-- Obsolete entries are hidden from bulk reads — they don't need to be removed.
-- Skip yourself (the curator agent) if you appear in the queue.
-- One agent per run — be called again for the next agent.
-- Always write to LAST_CURATION.md, even for clean runs ("OK — nothing to fix").
+- Prefer fix/consolidate/mark-obsolete over deletion. Obsolete entries are hidden from bulk reads anyway.
+- **When in doubt, skip.** False obsolete/irrelevant is harder to undo than leaving an entry alone.
+- **Preserve learning value.** E (errors) and L (lessons) about *why* something failed stay valuable even after the bug is fixed — only mark obsolete if the analysis is wrong.
+- **One prefix per batch.** Don't try all 200+ entries at once.

package/skills/hmem-migrate-o/SKILL.md

@@ -136,7 +136,7 @@ The migration tags old O-entries as `#legacy`. These still use the old flat form
 
 1. **Keep for now** — they don't hurt anything, just take space
 2. **Mark irrelevant** — `update_memory(id="O0042", irrelevant=true)` for entries you don't need
-3. **Delete later** — run `/hmem-self-curate` to review and clean up `#legacy` entries
+3. **Delete later** — run `/hmem-curate` to review and clean up `#legacy` entries
 4. **Auto-purge** — irrelevant entries older than 30 days are automatically deleted
 
 Recommendation: keep them for a week to make sure everything works, then curate.

package/skills/hmem-read/SKILL.md

@@ -382,7 +382,7 @@ After any `read_memory()` call, scan for:
 - Don't curate during time-critical tasks (the user is waiting for a bug fix, not curation)
 - Don't mark entries irrelevant if you're unsure — ask the user first
 
-For a thorough deep-clean, use the `/hmem-self-curate` skill.
+For a thorough deep-clean, use the `/hmem-curate` skill.
 
 ---
 

package/skills/hmem-release/SKILL.md

@@ -47,8 +47,7 @@ Every code change can affect skill documentation. Check each skill against the c
 | **hmem-read** | read_memory output format, load_project display, O-entry format | Changes to `formatBulkRead`, `formatRecentOEntries`, `load_project` rendering |
 | **hmem-config** | New config parameters, changed defaults, removed options | Changes to `HmemConfig` interface, `DEFAULT_CONFIG`, `loadHmemConfig` |
 | **hmem-update** | New migration steps, new post-update checks | Any schema change, new features that need post-update setup |
-| **hmem-curate** | Curation rules, new node types, new tags | New tagged node types (#checkpoint-summary, #skill-dialog), schema changes |
-| **hmem-self-curate** | Same as curate but for agent self-curation | Same triggers as hmem-curate |
+| **hmem-curate** | Curation rules (self + foreign-file), hmem_path param, new node types, new tags | New tagged node types (#checkpoint-summary, #skill-dialog), schema changes, hmem_path-capable tool changes |
 | **hmem-new-project** | P-entry schema (R0009), write_memory format | Changes to P-entry structure or write format |
 | **hmem-setup** | Hook scripts, init flow, MCP config format | Changes to hooks, CLI commands, environment variables |
 | **hmem-wipe** | Checkpoint references, context threshold | Changes to checkpointMode, contextTokenThreshold |
@@ -131,7 +130,7 @@ git push
 | Code area | Skills to check |
 |-----------|----------------|
 | hmem-store.ts (write/read) | hmem-write, hmem-read, hmem-curate |
-| hmem-store.ts (O-entries) | hmem-read, hmem-self-curate, hmem-curate |
+| hmem-store.ts (O-entries) | hmem-read, hmem-curate |
 | hmem-config.ts | hmem-config, hmem-update, hmem-setup |
 | mcp-server.ts (tools) | hmem-write, hmem-read (tool params) |
 | mcp-server.ts (load_project) | hmem-read, hmem-new-project |