hmem-mcp 2.0.3 → 2.2.0

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

@@ -0,0 +1,113 @@
+---
+name: hmem-self-curate
+description: Curate your own memory. Systematically review entries — mark obsolete, irrelevant, or favorite. Run periodically to keep memory clean.
+---
+
+# Self-Curation: Review Your Own Memory
+
+You are curating **your own** memory — not another agent's. You know best which entries are still relevant. Use your regular tools: `read_memory`, `update_memory`, `write_memory`.
+
+---
+
+## Step 1 — Load overview
+
+```
+read_memory(titles_only=true)
+```
+
+This gives you every entry as a compact line: `ID date [flags] title`. Scan the full list before acting.
+
+---
+
+## Step 2 — Identify candidates
+
+Work through the list prefix by prefix. For each entry, decide:
+
+| 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 Step 3) |
+| Just noise — not wrong, but irrelevant | `update_memory(id="X", content="...", irrelevant=true)` |
+| L1 wording 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)` |
+
+**Drill into entries** before judging: `read_memory(id="L0042")` to see L2 children. An entry with a weak L1 may have valuable detail underneath.
+
+---
+
+## Step 3 — Marking obsolete
+
+Obsolete requires a correction reference. Two patterns:
+
+**Pattern A: Replacement exists already**
+Find the existing entry that supersedes it, then mark:
+```
+update_memory(id="E0023", content="Wrong approach — see [✓E0076]", obsolete=true)
+```
+
+**Pattern B: No replacement exists yet**
+Write the correction first, then mark:
+```
+write_memory(prefix="L", content="Correct approach is XYZ\n\tDetails...")  # -> L0090
+update_memory(id="L0042", content="Superseded — see [✓L0090]", obsolete=true)
+```
+
+**Pattern C: Just stale, no correction needed**
+If the entry is simply outdated with no replacement (e.g., a task that's done, a project note about a past state), mark it irrelevant instead:
+```
+update_memory(id="T0005", content="...", irrelevant=true)
+```
+
+---
+
+## Step 4 — Consolidate duplicates
+
+Look for entries that cover the same topic (common with P entries). Merge them:
+
+1. Pick the **keeper** (the more complete one)
+2. Copy unique info from the duplicate into the keeper:
+   ```
+   append_memory(id="P0029", content="Session from duplicate entry\n\tDetail carried over")
+   ```
+3. Mark the duplicate irrelevant:
+   ```
+   update_memory(id="P0031", content="Merged into P0029", irrelevant=true)
+   ```
+
+You cannot delete entries yourself (only the curator can). Marking irrelevant hides them from bulk reads, which is the same practical effect.
+
+---
+
+## Step 5 — Favorite audit
+
+Check your current favorites: look for `[♥]` markers in the title listing.
+
+- **Too many favorites?** If more than ~10% of entries are favorites, they lose their purpose. Demote the less important ones: `update_memory(id="X", content="...", favorite=false)`
+- **Missing favorites?** Reference entries you always need (API endpoints, key architecture decisions, frequently-used patterns) should be favorited.
+- **Sub-node favorites:** If a specific L2/L3 detail is the real reference (not the whole entry), favorite the sub-node: `update_memory(id="L0042.2", content="...", favorite=true)`
+
+---
+
+## Guidelines
+
+- **Work in batches.** Don't try to curate 100+ entries in one session. Focus on one or two prefixes per run.
+- **Read before marking.** Always `read_memory(id=X)` to see L2 children before marking obsolete/irrelevant. The L1 might be weak but the detail valuable.
+- **Preserve learning value.** Error entries (E) and lessons (L) that describe *why* something failed are valuable even if the bug is fixed. Only mark obsolete if the root cause analysis is wrong.
+- **When in doubt, skip.** You can always curate again later. False irrelevant/obsolete is harder to undo than leaving an entry alone.
+- **Update stale L1 text.** If an entry's summary doesn't match its content anymore, rewrite it. A clear L1 is the most impactful improvement you can make.
+
+---
+
+## Quick reference
+
+| Tool | When |
+|------|------|
+| `read_memory(titles_only=true)` | Get full overview |
+| `read_memory(titles_only=true, prefix="L")` | Focus on one category |
+| `read_memory(id="L0042")` | Drill into entry before judging |
+| `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 from duplicate |
+| `read_memory(show_obsolete=true)` | Review already-obsolete entries |

package/skills/hmem-setup/SKILL.md

@@ -138,10 +138,11 @@ Place `hmem.config.json` in your `HMEM_PROJECT_DIR` to customize behavior. All k
   "maxLnChars": 50000,
   "maxDepth": 5,
   "defaultReadLimit": 100,
-  "recentDepthTiers": [
-    { "count": 10, "depth": 2 },
-    { "count": 3,  "depth": 3 }
-  ]
+  "bulkReadV2": {
+    "topAccessCount": 3,
+    "topNewestCount": 5,
+    "topObsoleteCount": 3
+  }
 }
 ```
 
@@ -149,18 +150,7 @@ Place `hmem.config.json` in your `HMEM_PROJECT_DIR` to customize behavior. All k
 - `"maxL1Chars"` + `"maxLnChars"`: set endpoints only, intermediate levels interpolated linearly
 - `"maxCharsPerLevel"`: explicit array `[L1, L2, L3, L4, L5]`
 
-**Recency gradient** (`recentDepthTiers`): controls how deeply children are inlined for recent entries in a default `read_memory()` call.
-
-Each tier is `{ "count": N, "depth": D }` — the N most recent entries get children inlined up to depth D. The highest applicable depth wins.
-
-Default behavior:
-| Entry position | What you see |
-|---|---|
-| 0–2 (most recent) | L1 + L2 + L3 |
-| 3–9 | L1 + L2 |
-| 10+ | L1 only |
-
-Set to `[]` to disable (L1-only for all entries).
+**Bulk-read tuning** (`bulkReadV2`): controls which entries get expanded (all L2 children shown) in a default `read_memory()` call. Per prefix category: top N newest + top M most-accessed are expanded. Favorites are always expanded.
 
 ---
 

package/skills/hmem-write/SKILL.md

@@ -19,10 +19,14 @@ If the tool `write_memory` is not available:
 ```
 write_memory(
   prefix: "E",
-  content: "L1 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)\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)"
 )
 ```
 
+**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.
+
+**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.
+
 **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.
 **IDs and timestamps** are assigned automatically — never write them yourself.
@@ -109,12 +113,27 @@ write_memory(
 
 ---
 
-## L1 Quality Rule
+## Title + L1 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)
 
-- **One complete, informative sentence** — ~15–20 tokens
+**L1:** One complete, informative sentence — ~15–20 tokens.
 - Must be understandable without any context
 - Not "Fixed a bug" — instead "SQLite connection failed due to wrong path in .mcp.json"
 
+**With explicit title (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")
+```
+
+**Without explicit title (auto-extracted):**
+```
+write_memory(prefix="E", content="SQLite connection failed due to wrong path in .mcp.json\n\tFix: use absolute path in env var")
+```
+Title auto-extracted: `"SQLite connection failed due to wrong path in .mc"`
+
 ---
 
 ## Company Knowledge (requires AL+ role)
@@ -194,9 +213,9 @@ Use when: you have new context to add without replacing what's there.
 
 ---
 
-## Access Count (Automatic)
+## Access Count (Automatic + Time-Weighted)
 
-Access counts are managed automatically — every `read_memory` and `append_memory` call bumps the accessed entries. Entries with high access counts get [★] markers and expanded treatment in bulk reads. To explicitly mark an entry as important, use `favorite: true` on `write_memory` or `update_memory`.
+Access counts are managed automatically — every `read_memory` and `append_memory` call bumps the accessed entries. The ranking uses **time-weighted scoring** (`access_count / log2(age_in_days + 2)`) so newer entries with fewer accesses can outrank stale old ones. Entries with the highest weighted scores get `[★]` markers and expanded treatment in bulk reads. To explicitly mark an entry as important, use `favorite: true` on `write_memory` or `update_memory`.
 
 ---
 

package/skills/hmem-save/SKILL.md

@@ -1,128 +0,0 @@
----
-name: save
-description: >
-  End-of-session save routine. Use when the user types /hmem-save or /save or asks to
-  "save", "save session", or "save progress".
-  Saves session learnings to memory via write_memory, commits git changes,
-  then compacts the conversation context.
----
-
-# Save Session
-
-Execute these steps in order. Report results after all complete.
-
-## Step 0 — First-time setup check
-
-Before saving, verify that hmem is ready.
-
-**Check 1: Is write_memory available?**
-
-Try calling `write_memory` (or check if the tool exists in your tool list).
-
-If `write_memory` is NOT available:
-- Tell the user: "The hmem MCP server is not connected. Run `npx hmem-mcp init` in your terminal to set it up, then restart your AI tool."
-- **STOP. Do not continue.**
-
-**Check 2: Does a memory file exist?**
-
-Call `read_memory()`. If it returns entries → memory exists, skip to Step 1.
-
-If `read_memory()` returns an **empty memory** (no entries at all) for the first time, this is likely a fresh setup. Ask the user:
-
-> "No memory found yet. Where should hmem store your memories?
-> 1) Global — works in any directory (`~/.hmem/`)
-> 2) Project-local — only in this directory (current folder)
->
-> Recommendation: Global for personal assistants. Project-local for team projects."
-
-After the user chooses, walk them through the config setup:
-
-> "Let me set up your `hmem.config.json`. I'll explain each setting — press Enter to accept the recommendation or type a new value."
-
-Go through these parameters one by one:
-
-| Parameter | Recommendation | Question to ask |
-|-----------|---------------|-----------------|
-| `maxL1Chars` | 120 | "How long should memory summaries be? (60–200 characters — shorter loads faster at startup)" |
-| `maxDepth` | 5 | "How many detail levels do you want? (2–5 — 5 gives the most flexibility)" |
-| `recentDepthTiers` | [{count:10,depth:2},{count:3,depth:3}] | "Auto-expand recent entries? This shows extra detail for your newest memories without extra tool calls. Recommended: yes" |
-| `prefixes` | default | "Do you want custom memory categories beyond the defaults (P/L/E/D/M/S/T/N/H/R)? If yes, name them (e.g. R=Research, B=Bookmark). Otherwise press Enter." |
-
-Write the resulting `hmem.config.json` to the chosen directory.
-Tell the user: "Config saved to `<path>/hmem.config.json`. You can adjust settings anytime with `/hmem-config`."
-
-## Step 1 — Write Memory
-
-**IMPORTANT:** You MUST use the `write_memory` MCP tool. NEVER write directly to `.hmem` files via sqlite3 or shell commands — this bypasses WAL journaling, integrity checks, and tree logic, causing corruption or data loss.
-
-Your L1 memory summaries are already in your context (injected at session start).
-**Check them first** — do not re-write anything that already exists.
-
-Only write what is **new since the last `/save` or session start**:
-
-| Prefix | When to use |
-|--------|-------------|
-| `P` | (P)roject progress — work done this session |
-| `L` | (L)essons learned applicable beyond this session |
-| `E` | (E)rror patterns — root cause + fix |
-| `D` | (D)ecisions — architectural or design decisions |
-
-Quality over quantity. Skip trivial things and anything already captured.
-
-### P entries: append to existing, don't duplicate
-
-Before creating a new P entry, check if an existing P entry covers the **same project or topic**.
-
-- Scan your L1 summaries (already in context) for a matching P entry.
-- If one exists: use `append_memory` to add this session as a new L2 node.
-  - Keep the new L2 text concise (what was done this session, ~15–20 tokens).
-  - Add L3 nodes for details.
-- If none exists: use `write_memory` to create a new P entry.
-
-**Goal: one P entry per project, growing over time — not one P entry per session.**
-
-```
-# Existing entry found → append this session
-append_memory(id="P0038", content="Session 02-24: update_memory + append_memory tools (v1.5.0)
-	update_memory: update text of single node without touching children
-	append_memory: add child nodes to existing entry, relative indentation
-	access_count auto-promotion: top-5 most accessed entries get L2 in bulk reads")
-
-# No existing entry → create new
-write_memory(prefix="P", content="New project: authentication service
-	Implemented JWT flow with refresh token rotation
-	Session 02-24: initial setup + basic login endpoint")
-```
-
-### L / E / D entries: always create new
-
-For lessons, errors, and decisions — always create a new entry. These are indexed insights, not project logs.
-
-```
-write_memory(prefix="L", content="Always restart MCP server after recompiling TypeScript
-	Running process holds the old dist — tool calls return stale results otherwise")
-
-write_memory(prefix="E", content="write_memory returned HMEM_PROJECT_DIR not set
-	Cause: relative path in .mcp.json env — must be absolute
-	Fix: replace with full absolute path, restart AI tool")
-```
-
-## Step 2 — Commit & Push
-
-**IMPORTANT:** Step 1 (write_memory) MUST complete before this step. The `.hmem` file is modified by write_memory — if you push before writing, the memory changes won't be included in the commit.
-
-If in a git repository:
-
-```bash
-git add -A
-git commit -m "concise imperative summary of this session's changes"
-git push
-```
-
-Skip if there are no changes or no git repo.
-
-## Step 3 — Compact (Claude only)
-
-If you are running on **Claude** (Claude Code, claude.ai): run `/compact` to compress the conversation context. The next interaction starts fresh with your updated memories already loaded.
-
-If you are running on **Gemini CLI, OpenCode, or another tool**: skip this step — `/compact` is a Claude-specific command.