hmem-mcp 5.0.0 → 5.1.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +161 -214
  2. package/dist/cli-checkpoint.js +102 -40
  3. package/dist/cli-checkpoint.js.map +1 -1
  4. package/dist/cli-context-inject.d.ts +7 -6
  5. package/dist/cli-context-inject.js +27 -130
  6. package/dist/cli-context-inject.js.map +1 -1
  7. package/dist/cli-env.d.ts +16 -0
  8. package/dist/cli-env.js +40 -0
  9. package/dist/cli-env.js.map +1 -0
  10. package/dist/cli-hook-startup.d.ts +20 -0
  11. package/dist/cli-hook-startup.js +101 -0
  12. package/dist/cli-hook-startup.js.map +1 -0
  13. package/dist/cli-init.js +97 -188
  14. package/dist/cli-init.js.map +1 -1
  15. package/dist/cli-log-exchange.js +63 -3
  16. package/dist/cli-log-exchange.js.map +1 -1
  17. package/dist/cli-statusline.d.ts +14 -0
  18. package/dist/cli-statusline.js +172 -0
  19. package/dist/cli-statusline.js.map +1 -0
  20. package/dist/cli.js +18 -2
  21. package/dist/cli.js.map +1 -1
  22. package/dist/hmem-config.d.ts +10 -0
  23. package/dist/hmem-config.js +63 -13
  24. package/dist/hmem-config.js.map +1 -1
  25. package/dist/hmem-store.d.ts +30 -1
  26. package/dist/hmem-store.js +219 -48
  27. package/dist/hmem-store.js.map +1 -1
  28. package/dist/mcp-server.js +202 -75
  29. package/dist/mcp-server.js.map +1 -1
  30. package/package.json +1 -1
  31. package/scripts/autoresearch-nightly.sh +84 -0
  32. package/scripts/hmem-statusline.sh +4 -0
  33. package/skills/hmem-config/SKILL.md +112 -147
  34. package/skills/hmem-curate/SKILL.md +56 -6
  35. package/skills/hmem-new-project/SKILL.md +164 -0
  36. package/skills/hmem-read/SKILL.md +174 -146
  37. package/skills/hmem-release/SKILL.md +141 -0
  38. package/skills/hmem-self-curate/SKILL.md +49 -7
  39. package/skills/hmem-setup/SKILL.md +169 -87
  40. package/skills/hmem-sync-setup/SKILL.md +16 -3
  41. package/skills/hmem-update/SKILL.md +254 -0
  42. package/skills/hmem-wipe/SKILL.md +47 -21
  43. package/skills/hmem-write/SKILL.md +38 -14
@@ -2,21 +2,25 @@
2
2
  name: hmem-read
3
3
  description: >
4
4
  Load long-term memory from hmem. Use when:
5
- - User types /hmem-read or says "load memory", "check your memory", "was weißt du über..."
5
+ - User types /hmem-read or says "load memory", "check your memory", "what do you remember",
6
+ "show me the project", "continue where we left off", "was weißt du über..."
6
7
  - Starting work and you have no L1 summaries in context yet
7
8
  - After /compact or context reset, to reload knowledge
8
9
  - Before any significant work to anchor yourself with prior context
9
10
  - User asks about a specific project, error, or topic visible in L1 summaries
10
- Calls read_memory() immediately. Also covers all read_memory query patterns:
11
- search, prefix filter, context_for, stale detection, find_related, memory_stats, memory_health.
11
+ - User says "pick up where we left off", "what were we working on", "resume",
12
+ "Woran haben wir gearbeitet", "Was war der letzte Stand"
13
+ Calls read_memory() or load_project() immediately. Also covers all read_memory query
14
+ patterns: search, prefix filter, context_for, stale detection, find_related,
15
+ memory_stats, memory_health.
12
16
  ---
13
17
 
14
18
  # Load Memory — Choose Your Path
15
19
 
16
- When this skill is invoked, pick the right path based on your situation.
17
- Do NOT just read this document — execute a tool call immediately.
20
+ When this skill is invoked, pick the right path and execute a tool call immediately.
21
+ Do NOT just read this document — act.
18
22
 
19
- If the tool `read_memory` is not available, tell the user:
23
+ If `read_memory` is not available, tell the user:
20
24
  "read_memory tool not found. Run `hmem init` to configure the MCP server."
21
25
 
22
26
  **Announcements:** If `read_memory` or `hmem-sync pull` shows urgent announcements
@@ -26,43 +30,55 @@ server migrations, or breaking updates that must be handled first.
26
30
 
27
31
  ---
28
32
 
29
- ## Path A: Fresh Session Start (no context yet)
33
+ ## Path A: Start Working on a Project (primary workflow)
30
34
 
31
- Start by seeing what projects exist, then focus:
35
+ Use `load_project` as the single entry point. It activates the project, returns the full
36
+ briefing (L2 content + L3 titles), and shows recent O-entries with full L4/L5 user/agent
37
+ exchanges — so you see exactly what happened in previous sessions, not just titles.
32
38
 
33
- ```
34
- # Step 1: Quick project overview (~200 tokens)
35
- read_memory(titles_only=true, prefix="P")
36
- ```
37
-
38
- This shows all projects as one-liners. Then:
39
+ - **User mentioned a project** → load it directly:
40
+ ```
41
+ load_project(id="P0037")
42
+ ```
43
+ This replaces the old pattern of `update_memory(active=true)` + `read_memory()`.
44
+ One call gives you everything: project structure, open tasks, and recent session history.
39
45
 
40
- - **If the user mentioned a project** → activate it and load full context:
46
+ - **Unclear which project** → list projects first, then load:
41
47
  ```
42
- update_memory(id="P0037", active=true) # mark project as active
43
- read_memory() # bulk read, filtered by active project
48
+ read_memory(titles_only=true, prefix="P") # ~200 tokens overview
44
49
  ```
50
+ Then ask the user or pick the most relevant one, and call `load_project(id="P00XX")`.
45
51
 
46
- - **If working on a new project** → create it first, then read:
52
+ - **New project** → create it first, then load:
47
53
  ```
48
- write_memory(prefix="P", content="New project: ...", tags=["#project-name"])
49
- update_memory(id="P00XX", active=true)
50
- read_memory()
54
+ write_memory(prefix="P", content="New project: ...") # → P00XX
55
+ load_project(id="P00XX")
51
56
  ```
52
57
 
53
- - **If unclear what to work on** → load everything:
58
+ - **No specific project** → load everything:
54
59
  ```
55
- read_memory() # full bulk read, all projects
60
+ read_memory() # full bulk read, all projects
56
61
  ```
57
62
 
58
- The bulk read returns memories **grouped by category** with smart expansion:
59
- - **Expanded entries** (newest, most-accessed, favorites): show L2 children + links
60
- - **Non-expanded entries**: latest child + `[+N more → ID]` hint
61
- - **Active-prefix filtering**: entries in active projects get full expansion, others title-only
63
+ ### What load_project returns
64
+
65
+ The response includes:
66
+ - **L2 content + L3 titles** the complete project briefing (~700 tokens)
67
+ - **Recent O-entries with full exchanges** — configurable via `recentOEntries` in config
68
+ (default: 10). Each O-entry contains the actual L4/L5 user/agent messages, not just
69
+ summaries. This is your continuity — read them to understand where the last session
70
+ left off.
71
+
72
+ ### Why load_project over read_memory
73
+
74
+ `read_memory()` shows a cross-project overview optimized for breadth. `load_project`
75
+ goes deep on one project — it activates it, filters related entries, and includes session
76
+ history. Use `load_project` when you know which project to work on; use `read_memory`
77
+ when you need orientation across all projects.
62
78
 
63
79
  ## Path B: After Context Compression (/compact)
64
80
 
65
- You still have the recent conversation in memory — you don't need the newest entries again.
81
+ You still have the recent conversation — you do not need the newest entries again.
66
82
  Load the long-term knowledge that was lost during compression:
67
83
 
68
84
  ```
@@ -72,116 +88,96 @@ read_memory(mode="essentials")
72
88
  Essentials mode prioritizes favorites, most-accessed, and pinned entries over newest.
73
89
  This is your "recover what matters" call — rules, decisions, error patterns, key references.
74
90
 
75
- If you need a specific project's full context:
91
+ For a specific project's full context:
76
92
  ```
77
93
  read_memory(context_for="P0029")
78
94
  ```
79
95
 
80
96
  ## Path C: User Asks About a Specific Topic
81
97
 
82
- When the user asks about something you can see in your L1 summaries:
98
+ When the user asks about something visible in your L1 summaries:
83
99
 
84
100
  ```
85
- # User: "Was weißt du über das hmem Projekt?"
101
+ # "Was weißt du über das hmem Projekt?"
86
102
  read_memory(context_for="P0029")
87
103
 
88
- # User: "Tell me about that Heimdall error"
104
+ # "Tell me about that Heimdall error"
89
105
  read_memory(context_for="E0090")
90
106
  ```
91
107
 
92
- `context_for` loads the entry expanded + all related entries (via links and weighted tag scoring)
93
- in a single call. The `min_tag_score` parameter controls strictness (default: 5). Raise for fewer results:
108
+ `context_for` loads the entry expanded + all related entries (via links and weighted tag
109
+ scoring) in a single call. Raise `min_tag_score` for fewer results:
94
110
 
95
111
  ```
96
- read_memory(context_for="P0029", min_tag_score=7) # stricter — only strong matches
112
+ read_memory(context_for="P0029", min_tag_score=7) # stricter — only strong matches
97
113
  ```
98
114
 
99
115
  ---
100
116
 
101
- ## Adapt Communication to User Skill Level
102
-
103
- After loading memory, check H-prefix entries for **User Skill Assessments** (e.g. H0010 "User Skill: IT").
104
- These contain 1-10 scores per subtopic — adapt your language accordingly:
105
-
106
- - **1-4**: Explain concepts, avoid jargon, use analogies
107
- - **5-6**: Brief explanations, some jargon OK
108
- - **7-8**: Direct technical language, skip basics
109
- - **9-10**: Peer-level discussion, challenge assumptions
117
+ ## Bulk Read Design
110
118
 
111
- If no skill assessment exists yet, create one based on the user's vocabulary and questions
112
- (see hmem-write skill for the H-prefix convention).
119
+ `read_memory()` shows **current context** newest entries, most-accessed favorites, open
120
+ tasks. It is not a full dump. Older entries with low access_count are intentionally omitted.
113
121
 
114
- ---
122
+ **Expanded entries** (newest, most-accessed, favorites): show L2 children + links.
123
+ **Non-expanded entries**: latest child + `[+N more → ID]` hint.
124
+ **Active-prefix filtering**: entries in active projects get full expansion, others title-only.
115
125
 
116
- ## After loading proactive cleanup
126
+ **For older or broader knowledge:**
117
127
 
118
- Only on the **first read of a session** (not after every read). Scan L1 summaries and flag:
128
+ ```
129
+ read_memory(titles_only=true, prefix="L") # all lesson titles as table of contents
130
+ read_memory(search="SQLite corruption") # semantic search
131
+ read_memory(tag="#sqlite") # hashtag filter
132
+ ```
119
133
 
120
- - **Wrong** write correction first, then `update_memory(id="E0023", content="Wrong see [✓E0076]", obsolete=true)`
121
- - **Noise** → `update_memory(id="T0005", irrelevant=true)` or `update_many(ids=["T0005", "T0012"], irrelevant=true)`
122
- - **Important** → `update_memory(id="S0001", favorite=true)`
134
+ **Tags are hidden by default** use `read_memory(curator=true)` to see hashtags on entries.
123
135
 
124
- For a thorough review, use the `/hmem-self-curate` skill.
136
+ Repeated bulk reads without a goal yield little new information after 3-4 iterations — use
137
+ targeted search or a prefix overview instead.
125
138
 
126
139
  ---
127
140
 
128
- ## Bulk Read Design Intent
129
-
130
- `read_memory()` shows **current context** — newest entries, most-accessed favorites, open tasks. It is not a full dump. Older entries with low access_count are intentionally omitted.
141
+ ## Title vs. Body (v5.1+)
131
142
 
132
- **For older or broader knowledge:**
133
-
134
- ```
135
- # All lesson titles as table of contents (one line per entry)
136
- read_memory(titles_only=true, prefix="L")
137
-
138
- # Semantic search
139
- read_memory(search="SQLite corruption")
140
-
141
- # Hashtag filter
142
- read_memory(tag="#sqlite")
143
- ```
143
+ Every node has a **title** (short navigation label) and an optional **body** (detail shown on drill-down). This affects what you see in different read modes:
144
144
 
145
- **Tags are hidden by default** — hashtags are only shown when `curator=true` is set. This saves tokens in normal reads. Use `read_memory(curator=true)` when you need to see or verify tags on entries.
145
+ | Mode | Shows |
146
+ |------|-------|
147
+ | `titles_only=true` | Title only — compact table of contents |
148
+ | Default (by ID) | Title + body for requested node, children as title-only |
149
+ | `expand=true` | Title + body recursively for all nodes |
150
+ | Bulk reads | Title only for L1, expanded entries show L2 titles |
146
151
 
147
- Repeated bulk reads without a goal yield little new information after 3–4 iterationsuse targeted search or a prefix overview instead.
152
+ Entries written with the `>` body format have explicit title/body separation. Older entries without `>` show auto-extracted titles (~50 chars) the full text is still accessible on drill-down.
148
153
 
149
154
  ---
150
155
 
151
- ## Lazy Loading Protocol (for subsequent reads)
156
+ ## Lazy Loading Protocol (subsequent reads)
152
157
 
153
- After the initial `read_memory()`, use these patterns to drill deeper:
158
+ After the initial load, drill deeper with these patterns:
154
159
 
155
160
  ```
156
- # Filter by category
157
- read_memory(prefix="E") # only errors
158
- read_memory(store="company") # shared company knowledge
159
-
160
- # Expand a root entry → shows L2 children
161
- read_memory(id="E0042")
162
-
163
- # Expand an L2 node → shows L3 children
164
- read_memory(id="E0042.2")
165
-
166
- # Expand further (rarely needed)
167
- read_memory(id="E0042.2.1")
161
+ read_memory(prefix="E") # only errors
162
+ read_memory(store="company") # shared company knowledge
163
+ read_memory(id="E0042") # expand root → shows L2 children
164
+ read_memory(id="E0042.2") # expand L2 → shows L3 children
165
+ read_memory(id="E0042.2.1") # expand further (rarely needed)
168
166
  ```
169
167
 
170
168
  **Compact table of contents:**
171
169
 
172
170
  ```
173
- read_memory(titles_only=true) # all entries as compact ID + date + title listing
174
- read_memory(titles_only=true, prefix="L") # only lessons
171
+ read_memory(titles_only=true) # all entries, one line each
172
+ read_memory(titles_only=true, prefix="L") # only lessons
175
173
  ```
176
174
 
177
- V2 selection still applies (only newest + most-accessed + favorites shown), but without L2 children or links — just one line per entry with `(N)` child count hints.
178
-
179
- **Rule: depth parameter is useful for listings (max 4), not for ID queries.**
175
+ **Depth parameter** useful for listings (max 4), not for ID queries:
180
176
 
181
177
  ```
182
- read_memory(depth=2) # all entries with L2 children
183
- read_memory(prefix="L", depth=2) # all lessons with details
184
- read_memory(depth=4) # deep dive L2+L3+L4 (use sparingly, large output)
178
+ read_memory(depth=2) # all entries with L2 children
179
+ read_memory(prefix="L", depth=2) # all lessons with details
180
+ read_memory(depth=4) # deep dive L2+L3+L4 (large output, use sparingly)
185
181
  ```
186
182
 
187
183
  For L5 detail, drill into a specific node ID instead of using depth.
@@ -193,18 +189,11 @@ For L5 detail, drill into a specific node ID instead of using depth.
193
189
  Find entries created around a specific time or near another entry:
194
190
 
195
191
  ```
196
- # Entries created around 14:30 today (±2h window)
197
- read_memory(time="14:30")
198
-
199
- # Entries near a specific date + time
200
- read_memory(time="14:30", date="2026-02-20")
201
-
202
- # Custom window: only 1 hour before
203
- read_memory(time="14:30", period="-1h")
204
-
205
- # Entries created around the same time as P0001
206
- read_memory(time_around="P0001")
207
- read_memory(time_around="P0001", period="+2h") # only after P0001
192
+ read_memory(time="14:30") # ±2h window around 14:30 today
193
+ read_memory(time="14:30", date="2026-02-20") # specific date + time
194
+ read_memory(time="14:30", period="-1h") # custom window: only 1h before
195
+ read_memory(time_around="P0001") # entries created near P0001
196
+ read_memory(time_around="P0001", period="+2h") # only after P0001
208
197
  ```
209
198
 
210
199
  ---
@@ -218,49 +207,60 @@ search_memory(query="auth token", scope="memories")
218
207
 
219
208
  ---
220
209
 
221
- ## Show All Obsolete Entries
210
+ ## Original Context History (O-prefix)
222
211
 
223
- By default, bulk reads hide most obsolete entries (top 3 by access count shown). To see all:
212
+ O-entries store raw session context with progressive summarization. They are created
213
+ **automatically** by the Stop hook — every user/agent exchange is recorded as an O-entry
214
+ without manual intervention. When you switch projects, a new O-entry is started
215
+ automatically (project-based O-entries).
216
+
217
+ O-entries are hidden from bulk reads but searchable. Use them when you need the original
218
+ reasoning behind a decision or the full conversation that led to an entry:
224
219
 
225
220
  ```
226
- read_memory(show_obsolete=true)
221
+ read_memory(prefix="O") # browse recent context
222
+ read_memory(search="why did we choose per-node scoring") # search across raw context
223
+ read_memory(id="O0042", expand=true) # drill into specific entry
227
224
  ```
228
225
 
229
- ---
226
+ O-entries are linked to curated entries (P/L/D/E) via tags, so `context_for` will
227
+ surface relevant O-entries when their tags match.
230
228
 
231
- ## Stale Detection
229
+ **v5 checkpoint integration:** When `checkpointMode` is set to `"auto"`, a Haiku subagent
230
+ reads recent O-entry exchanges at configurable intervals and automatically extracts
231
+ L/D/E entries + writes a rolling checkpoint summary (`[CP]` node tagged `#checkpoint-summary`).
232
232
 
233
- Find entries you haven't accessed in a while — useful for curation:
233
+ **What `load_project` shows:** For the latest O-entry, it displays:
234
+ 1. The most recent checkpoint summary (if available)
235
+ 2. Only raw exchanges AFTER the summary (minimum 5 exchanges guaranteed)
236
+ 3. Skill-dialog exchanges (brainstorming, TDD, etc.) are filtered out automatically
234
237
 
235
- ```
236
- # Entries not accessed in 30 days (sorted oldest-access first)
237
- read_memory(stale_days=30)
238
+ This keeps `load_project` compact even for long sessions. To see the full unfiltered
239
+ history, use `read_memory(id="O0042", expand=true)`.
238
240
 
239
- # Filter: only stale lessons
240
- read_memory(stale_days=60, prefix="L")
241
- ```
241
+ The `recentOEntries` config parameter (default: 10) controls how many recent O-entries
242
+ `load_project` includes.
242
243
 
243
244
  ---
244
245
 
245
- ## Original Context History (O-prefix)
246
+ ## Show All Obsolete Entries
246
247
 
247
- O-entries store raw session context with progressive summarization (created by `flush_context`).
248
- They are hidden from bulk reads but searchable — use when you need the original reasoning
249
- behind a decision or the full conversation that led to an entry:
248
+ By default, bulk reads hide most obsolete entries (top 3 by access count shown). To see all:
250
249
 
251
250
  ```
252
- # Browse recent context entries
253
- read_memory(prefix="O")
251
+ read_memory(show_obsolete=true)
252
+ ```
254
253
 
255
- # Search across raw context
256
- read_memory(search="why did we choose per-node scoring")
254
+ ---
257
255
 
258
- # Drill into a specific context entry (L1→L2→L5 linear chain)
259
- read_memory(id="O0042", expand=true)
260
- ```
256
+ ## Stale Detection
261
257
 
262
- O-entries are linked to curated entries (P/L/D/E) via tags, so `context_for` will
263
- surface relevant O-entries when their tags match.
258
+ Find entries not accessed in a while useful for curation:
259
+
260
+ ```
261
+ read_memory(stale_days=30) # sorted oldest-access first
262
+ read_memory(stale_days=60, prefix="L") # only stale lessons
263
+ ```
264
264
 
265
265
  ---
266
266
 
@@ -269,42 +269,68 @@ surface relevant O-entries when their tags match.
269
269
  Quick overview of your memory health:
270
270
 
271
271
  ```
272
- memory_stats() # personal store
273
- memory_stats(store="company") # company store
272
+ memory_stats() # personal store
273
+ memory_stats(store="company") # company store
274
274
  ```
275
275
 
276
- Output includes: total entries by prefix, total nodes, favorites count, pinned count, unique hashtags, stale count (>30d), oldest entry, and top 5 most-accessed entries.
276
+ Output includes: total entries by prefix, total nodes, favorites count, pinned count,
277
+ unique hashtags, stale count (>30d), oldest entry, and top 5 most-accessed entries.
277
278
 
278
279
  ---
279
280
 
280
281
  ## Find Related
281
282
 
282
- Find entries similar to a given entry via FTS5 keyword matching — useful to spot potential duplicates or discover thematic connections:
283
+ Find entries similar to a given entry via FTS5 keyword matching — spots potential
284
+ duplicates or thematic connections:
283
285
 
284
286
  ```
285
- find_related(id="P0029") # up to 5 similar entries
287
+ find_related(id="P0029") # up to 5 similar entries
286
288
  find_related(id="L0042", limit=10)
287
289
  ```
288
290
 
289
- Returns title-only list of entries with overlapping keywords (different from `relatedEntries` in ID reads which uses shared tags).
291
+ Returns title-only list with overlapping keywords (different from `relatedEntries` in
292
+ ID reads which uses shared tags).
290
293
 
291
294
  ---
292
295
 
293
296
  ## Memory Health Audit
294
297
 
295
- Check your memory for structural issues before/after curation:
298
+ Check memory for structural issues before/after curation:
296
299
 
297
300
  ```
298
- memory_health() # personal store
301
+ memory_health() # personal store
299
302
  memory_health(store="company")
300
303
  ```
301
304
 
302
- Checks:
303
- - **Broken links** — links pointing to deleted entries
304
- - **Orphaned entries** — root entries with no sub-nodes (never expanded)
305
- - **Stale favorites/pinned** — not accessed in >60 days
306
- - **Broken obsolete chains** — `[✓ID]` pointing to non-existent entries
307
- - **Tag orphans** `memory_tags` rows with no matching entry/node
305
+ Checks: broken links, orphaned entries, stale favorites/pinned, broken obsolete chains,
306
+ tag orphans.
307
+
308
+ ---
309
+
310
+ ## Adapt Communication to User Skill Level
311
+
312
+ After loading memory, check H-prefix entries for **User Skill Assessments** (e.g. H0010).
313
+ These contain 1-10 scores per subtopic — adapt your language accordingly:
314
+
315
+ - **1-4**: Explain concepts, avoid jargon, use analogies
316
+ - **5-6**: Brief explanations, some jargon OK
317
+ - **7-8**: Direct technical language, skip basics
318
+ - **9-10**: Peer-level discussion, challenge assumptions
319
+
320
+ If no skill assessment exists yet, create one based on the user's vocabulary and questions
321
+ (see hmem-write skill for the H-prefix convention).
322
+
323
+ ---
324
+
325
+ ## After Loading — Proactive Cleanup
326
+
327
+ Only on the **first read of a session** (not after every read). Scan L1 summaries and flag:
328
+
329
+ - **Wrong** → write correction first, then `update_memory(id="E0023", content="Wrong — see [✓E0076]", obsolete=true)`
330
+ - **Noise** → `update_memory(id="T0005", irrelevant=true)` or `update_many(ids=["T0005","T0012"], irrelevant=true)`
331
+ - **Important** → `update_memory(id="S0001", favorite=true)`
332
+
333
+ For a thorough review, use the `/hmem-self-curate` skill.
308
334
 
309
335
  ---
310
336
 
@@ -313,10 +339,12 @@ Checks:
313
339
  | Wrong | Right |
314
340
  |-------|-------|
315
341
  | `read_memory()` after /compact | `read_memory(mode="essentials")` — you already have recent context |
316
- | Blind bulk read at session start | `read_memory(titles_only=true, prefix="P")` first pick project `read_memory()` |
342
+ | `update_memory(active=true)` + `read_memory()` | `load_project(id="P00XX")` one call does both |
343
+ | Blind bulk read at session start | `read_memory(titles_only=true, prefix="P")` first, then `load_project` |
317
344
  | `read_memory(id="E0042", depth=3)` | `read_memory(id="E0042.2")` — branch by branch |
318
345
  | Load everything without purpose | Check L1 first, then expand selectively |
319
- | Read .hmem file directly | Always use MCP tools — it's a SQLite binary |
320
- | Just display this skill text | **Call a read_memory variant immediately** |
346
+ | Read .hmem file directly | Always use MCP tools — it is a SQLite binary |
347
+ | Just display this skill text | **Call a read_memory or load_project variant immediately** |
321
348
  | `update_memory(id="X", obsolete=true)` without `[✓ID]` | Write correction first, then mark obsolete with `[✓ID]` tag |
322
349
  | Repeated `read_memory()` to find old entries | `read_memory(titles_only=true, prefix="L")` or `read_memory(search="...")` |
350
+ | Manually creating O-entries | O-entries are auto-logged by the Stop hook — do not create them manually |
@@ -0,0 +1,141 @@
1
+ ---
2
+ name: hmem-release
3
+ description: >
4
+ Pre-publish checklist for hmem-mcp releases. Ensures all skills are updated,
5
+ version is bumped, tests pass, and nothing is forgotten. Use before every
6
+ npm publish of hmem-mcp — when the user says "publish", "release", "publishen",
7
+ "neue Version", or when you're about to run npm publish on the hmem repo.
8
+ ---
9
+
10
+ # /hmem-release — Release Checklist
11
+
12
+ Run this checklist before every `npm publish` of hmem-mcp. Every release touches code, skills, config, and documentation — this skill ensures nothing falls through the cracks.
13
+
14
+ ---
15
+
16
+ ## Step 1: Version Bump
17
+
18
+ ```bash
19
+ npm version patch --no-git-tag-version # or minor/major as appropriate
20
+ ```
21
+
22
+ Decide the version type based on what changed:
23
+ - **patch**: bugfixes, skill text updates, small improvements
24
+ - **minor**: new features (new tools, new prefix, new config options, new skills)
25
+ - **major**: breaking changes (schema changes, removed tools, API changes)
26
+
27
+ ---
28
+
29
+ ## Step 2: Build & Type Check
30
+
31
+ ```bash
32
+ npx tsc --noEmit # type check first (fast)
33
+ npx tsc # full build
34
+ ```
35
+
36
+ Fix any errors before proceeding.
37
+
38
+ ---
39
+
40
+ ## Step 3: Skill Audit
41
+
42
+ Every code change can affect skill documentation. Check each skill against the current code:
43
+
44
+ | Skill | Check for | Common triggers |
45
+ |-------|-----------|-----------------|
46
+ | **hmem-write** | write_memory format, body syntax (`>`), char limits, tag rules | Changes to `parseTree`, `write()`, validation logic |
47
+ | **hmem-read** | read_memory output format, load_project display, O-entry format | Changes to `formatBulkRead`, `formatRecentOEntries`, `load_project` rendering |
48
+ | **hmem-config** | New config parameters, changed defaults, removed options | Changes to `HmemConfig` interface, `DEFAULT_CONFIG`, `loadHmemConfig` |
49
+ | **hmem-update** | New migration steps, new post-update checks | Any schema change, new features that need post-update setup |
50
+ | **hmem-curate** | Curation rules, new node types, new tags | New tagged node types (#checkpoint-summary, #skill-dialog), schema changes |
51
+ | **hmem-self-curate** | Same as curate but for agent self-curation | Same triggers as hmem-curate |
52
+ | **hmem-new-project** | P-entry schema (R0009), write_memory format | Changes to P-entry structure or write format |
53
+ | **hmem-setup** | Hook scripts, init flow, MCP config format | Changes to hooks, CLI commands, environment variables |
54
+ | **hmem-wipe** | Checkpoint references, context threshold | Changes to checkpointMode, contextTokenThreshold |
55
+ | **hmem-sync-setup** | Sync config format, sync commands | Changes to sync parsing, hmem-sync integration |
56
+
57
+ **How to check:** For each skill, grep for key terms from the code change:
58
+ ```bash
59
+ grep -l "relevant_term" skills/*/SKILL.md
60
+ ```
61
+
62
+ If a skill references something you changed, read and update it.
63
+
64
+ ---
65
+
66
+ ## Step 4: Config Schema Check
67
+
68
+ If you added new config parameters:
69
+ 1. Added to `HmemConfig` interface? (hmem-config.ts)
70
+ 2. Added to `DEFAULT_CONFIG`? (hmem-config.ts)
71
+ 3. Parsing logic in `loadHmemConfig`? (hmem-config.ts)
72
+ 4. Added to `MEMORY_KEYS` set? (hmem-config.ts)
73
+ 5. Included in `saveHmemConfig` output? (hmem-config.ts)
74
+ 6. Documented in **hmem-config** skill?
75
+
76
+ ---
77
+
78
+ ## Step 5: Prefix Check
79
+
80
+ If you added or changed prefixes:
81
+ 1. Added to `DEFAULT_PREFIXES`? (hmem-config.ts)
82
+ 2. Added to `DEFAULT_PREFIX_DESCRIPTIONS`? (hmem-config.ts)
83
+ 3. Documented in **hmem-write** skill (prefix list)?
84
+ 4. Documented in **hmem-read** skill?
85
+
86
+ ---
87
+
88
+ ## Step 6: Tool Parameter Check
89
+
90
+ If you changed MCP tool parameters (added, removed, changed types):
91
+ 1. Zod schema updated in mcp-server.ts?
92
+ 2. Using `z.coerce.boolean()` for booleans (not `z.boolean()`)?
93
+ 3. Tool description updated?
94
+ 4. Affected skills updated?
95
+
96
+ ---
97
+
98
+ ## Step 7: Migration Check
99
+
100
+ If the release introduces schema changes:
101
+ 1. `MIGRATIONS` array updated in hmem-store.ts? (ALTER TABLE for new columns)
102
+ 2. **hmem-update** skill documents the migration step?
103
+ 3. Auto-migration tested with an old DB?
104
+
105
+ ---
106
+
107
+ ## Step 8: Commit & Publish
108
+
109
+ ```bash
110
+ git add src/ skills/ package.json package-lock.json
111
+ git commit -m "feat/fix: description
112
+
113
+ Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
114
+ npm publish
115
+ git push
116
+ ```
117
+
118
+ ---
119
+
120
+ ## Step 9: Post-Publish
121
+
122
+ 1. Verify on npm: `npm view hmem-mcp version`
123
+ 2. Sync to devices: `hmem-sync push` (if applicable)
124
+ 3. Update hmem P-entry protocol: `append_memory(id="P0048.7", content="\tHandoff: v5.x.x released...")`
125
+ 4. Notify user via Telegram if relevant
126
+
127
+ ---
128
+
129
+ ## Quick Reference: What changed → What to check
130
+
131
+ | Code area | Skills to check |
132
+ |-----------|----------------|
133
+ | hmem-store.ts (write/read) | hmem-write, hmem-read, hmem-curate |
134
+ | hmem-store.ts (O-entries) | hmem-read, hmem-self-curate, hmem-curate |
135
+ | hmem-config.ts | hmem-config, hmem-update, hmem-setup |
136
+ | mcp-server.ts (tools) | hmem-write, hmem-read (tool params) |
137
+ | mcp-server.ts (load_project) | hmem-read, hmem-new-project |
138
+ | cli-checkpoint.ts | hmem-config (checkpoint docs), hmem-read (summary docs) |
139
+ | cli-log-exchange.ts | hmem-setup (hook docs) |
140
+ | cli-context-inject.ts | hmem-wipe, hmem-setup |
141
+ | Any new skill added | hmem-update (list of skills to sync) |