hmem-mcp 7.0.5 → 7.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hmem-mcp",
-  "version": "7.0.5",
+  "version": "7.2.0",
   "description": "Humanlike memory for AI agents — MCP server with 5-level lazy-loaded SQLite memory",
   "author": "Bumblebiber",
   "license": "MIT",

package/skills/hmem-activate/SKILL.md

@@ -45,6 +45,15 @@ Move at the batch or session level (e.g. `O0043.3`), not exchange by exchange.
 
 **If OLD_O has no today-exchanges, or all exchanges genuinely belong to OLD_PROJECT:** skip this step.
 
+## STEP 3.5: Noise Check
+
+Scan the load_project output:
+- **>4k tokens** → invoke `hmem-curate` first
+- **✓ DONE Roadmap items** → `update_memory(id, { irrelevant: true })`
+- **Decommissioned / concept entries in Infrastructure** → `update_memory(id, { irrelevant: true })`
+
+Fix immediately, do not defer.
+
 ## STEP 4: Confirm
 
 Output:

package/skills/hmem-curate/SKILL.md

@@ -39,6 +39,13 @@ Shows:
 - **Stale favorites/pinned** — not accessed in >60 days (demote or verify)
 - **Broken obsolete chains** — `[✓ID]` pointing to deleted entries
 
+**Severity classification — prioritize fixes in this order:**
+| Severity | Examples | Action |
+|----------|----------|--------|
+| **BLOCKER** | Broken links, broken obsolete chains | Fix before any other curation |
+| **WARNING** | Orphaned stubs, stale favorites >90 days, P-entry token bloat | Fix in current session |
+| **INFO** | Vague titles, duplicate candidates, minor tag cleanup | Fix if time allows |
+
 Useful before starting:
 ```
 memory_stats()

package/skills/hmem-dispatch/SKILL.md

@@ -11,6 +11,7 @@ description: "Dispatch an isolated sub-agent for a specific task. Sub-agent rece
 - **Searching** — "does a spec exist?", "find the plan for X", "search the codebase for Y", "check if skill Z covers this", "read the docs for W", "is there already a file that does X?" — any exploration or lookup task
 - **Calculation or lookup** — deterministic, context-free
 - **Writing an isolated section or document** — no conversation history needed
+- **Writing or modifying code** — never write code directly in the main context. Pass the project ID and relevant node IDs (e.g. `.2 Codebase`) in the task so the sub-agent can sync them after completing the work.
 
 **Never dispatch for tasks that require knowing the conversation context.**
 
@@ -22,6 +23,7 @@ Write out before dispatching:
 - INPUT: exactly what the sub-agent needs — no more, no less
 - TASK: what to do with the input
 - OUTPUT FORMAT: what to return
+- VERIFY (optional): a concrete shell command that proves completion (e.g. `npx tsc --noEmit`, `grep "pattern" file.ts`). Use for tasks that produce code or file changes.
 
 ## STEP 2: Dispatch
 
@@ -30,15 +32,21 @@ Send the sub-agent ONLY this prompt — no conversation history, no project cont
 ---
 Task: <TASK>
 Input: <INPUT>
+[If VERIFY set:] After completing the task, run: <VERIFY_CMD>
 Return your answer in exactly this format:
 [RESULT]
 <answer here>
 [/RESULT]
+[If VERIFY set:]
+[VERIFY_RESULT]
+pass | fail: <command output or error>
+[/VERIFY_RESULT]
 Max 200 words. Use the hmem-subagent skill.
 ---
 
 ## STEP 3: Inject result
 
 Take ONLY the content between [RESULT] and [/RESULT].
+If [VERIFY_RESULT] is present: check pass/fail. On fail, report the verification error instead of declaring the task complete.
 Discard all sub-agent reasoning and preamble.
 Use the result directly in the main conversation.

package/skills/hmem-new-project/SKILL.md

@@ -61,10 +61,30 @@ This creates:
 
 ## Step 4: Fill in details
 
-If a codebase was scanned, append the findings:
+If a codebase was scanned, append the findings. The Codebase node (`.2`) follows a strict schema:
+
+### Codebase node structure
+
+- **L3 — Pipeline** (first child): Data flow overview — `entry → moduleA → moduleB → storage`
+- **L3 — Modules**: One node per source file. Title = filename, body = purpose + `src/file.ts`
+- **L4 — Functions**: Under each module, one node per exported function/class. Title = full TypeScript signature, body = one-line description + `src/file.ts`
+
+```
+append_memory(id="P00XX.2", title="Pipeline", body="src/cli.ts → moduleA.ts → DB")
+append_memory(id="P00XX.2", title="moduleA.ts", body="Core logic handler. src/moduleA.ts")
+append_memory(id="P00XX.2.N", title="doThing(x: string): Promise<boolean>", body="Does the thing. src/moduleA.ts")
+```
+
+**L4 is critical.** Without function signatures, every agent must read source files for every task. Fill L4 for all exported functions when creating a new project — dispatch a subagent to extract them if the codebase is large.
+
+- **L5 — Extended Notes** (optional, use selectively): Add under an L4 node only when it adds real value:
+  - Usage example: `write("P", { content: "Title\n\nBody", tags: ["#foo"] })`
+  - Important caveats: "triggers sync push", "returns null if not found — never throws"
+  - Parameter details: field list for complex option types like `ReadOptions`
+
+  Not every function needs L5 — only where the signature alone leaves agents guessing.
 
 ```
-append_memory(id="P00XX.2", content="Entry point: src/index.ts\n\n...")
 append_memory(id="P00XX.3", content="Installation: npm install\n\n...")
 ```
 

package/skills/hmem-session-start/SKILL.md

@@ -19,7 +19,28 @@ Replace P00XX with the actual project ID (e.g., P0048).
 load_project returns the project brief, recent O-Entry summaries, rules, and lessons.
 Do NOT call read_memory separately. load_project is the only activation action.
 
-## STEP 2: O-Entry routing check
+## STEP 2: Noise Check
+
+**Do this immediately after load_project, before any other work.**
+
+Scan the output for:
+- **>4k tokens** → invoke `hmem-curate` on this project first, then continue
+- **✓ DONE items in Roadmap** → `update_memory(id, { irrelevant: true })`
+- **Decommissioned / concept entries in Infrastructure** → `update_memory(id, { irrelevant: true })`
+- **Old status snapshots in Overview** (superseded by newer) → mark obsolete
+
+Fix noise immediately. Do not note it and defer.
+
+## STEP 3: Calibrate explanation depth
+
+Read H0003 (IT Skills) — the scale is 1–9:
+- **7–9 = Expert**: use technical language directly, no padding, no basics
+- **4–6 = Proficient**: explain concepts but skip fundamentals
+- **1–3 = Basics**: explain with examples
+
+Apply this calibration for the entire session. When explaining something in a domain, check the matching H0003 skill first.
+
+## STEP 4: O-Entry routing check
 
 **This step is critical.** Every `load_project` call changes which O-entry receives session exchanges. If you called `load_project` on any project other than your working project — even briefly, even for administrative reasons (reconcile, curation, migration) — those exchanges were misrouted to the wrong O-entry.
 

package/skills/hmem-subagent/SKILL.md

@@ -22,3 +22,23 @@ You were dispatched for exactly one task. You have no conversation history. You
 [/RESULT]
 
 Nothing before [RESULT]. Nothing after [/RESULT].
+
+## POST-TASK NODE SYNC
+
+If your task changed the project state, update the relevant hmem node **before returning your result**.
+
+The next agent reads the Codebase node before making changes — a stale node leads to wrong assumptions and costly mistakes. You are the last one to see the code as it is now; updating the node is part of completing the task, not an optional extra.
+
+| What you did | Node to update | What to write |
+|---|---|---|
+| Wrote or modified code | `.2 Codebase` | L4: function signature + one-line purpose + file path. L5 optional: usage example, caveats, complex param details |
+| Fixed a bug | `.6 Bugs` → E-Entry | Mark `#solved`, one-line fix summary |
+| Made a release | `.1 Overview` + `.5 Deployment` | New version, date |
+| Added a dependency | `.15 Dependencies` | Package name + version |
+| Made an architectural decision | `.4 Context` | Decision + rationale |
+| Completed a roadmap milestone | `.8 Roadmap` | Mark DONE |
+| Discovered a new requirement | `.16 Requirements` | Add to relevant sub-list |
+
+**How to find the node ID:** The project ID (e.g. `P0048`) and relevant node IDs are in your task description. If only the project ID is given, the node ID is `<project-id>.<section-number>` — e.g. `P0048.2` for Codebase.
+
+Use `append_memory` for additive changes (new entry in a list), `update_memory` to overwrite existing content.

package/skills/hmem-update/SKILL.md

@@ -320,6 +320,56 @@ settings.windows.example.json is now in the Bumblebiber/hmem repository. If you
 
 ---
 
+## Step 2i: v7.1.0 — load_project Noise Reduction + Skill Improvements
+
+**Only needed when upgrading from < v7.1.0**
+
+### load_project: DONE-filter in schema mode
+
+`load_project` now hides `✓ DONE` and `DONE`-prefixed items from **Roadmap** and **Next Steps** sections when using schema-driven rendering. Previously this filter only applied to legacy rendering mode (no schema). No config change needed — automatic.
+
+### load_project: Project-specific R-entries only
+
+Rules (`R`-prefix entries) are now only shown in `load_project` if the rule has an explicit link to the current project (`r.links.includes(projectId)`). Global rules without a project link are no longer injected. This eliminates ~1k token duplication for projects with many global rules. **Action:** If you have project-specific rules that should appear in `load_project`, ensure they have a `links` entry pointing to the project.
+
+### Skill improvements
+
+- **hmem-dispatch**: New optional `VERIFY` field — specify a shell command the sub-agent must run and return as `[VERIFY_RESULT]`. Use for code-change tasks to close the feedback loop.
+- **hmem-curate**: Health check findings now classified as BLOCKER / WARNING / INFO for structured triage.
+- **hmem-write**: New "After Writing" verification step — for complex L/D/E entries, read back the written entry and verify it captures "why?", not just "what?".
+
+---
+
+## Step 2j: v7.2.0 — Codebase Node Schema + checkpointPolicy Fix
+
+**Only needed when upgrading from < v7.2.0**
+
+### checkpointPolicy: readonly now correctly scoped
+
+`readonly` on a schema section previously blocked ALL `append_memory` calls under that section (including adding L3 modules or L4 function signatures). This was a bug — the intent was only to prevent adding new L2 sections to a project root.
+
+**New behavior:**
+- `append_memory(id="P0048")` → blocked if schema has readonly sections (prevents new L2 sections) ✓
+- `append_memory(id="P0048.2")` → allowed (add module to Codebase) ✓
+- `append_memory(id="P0048.2.N")` → allowed (add function signature) ✓
+- `pointer` policy still enforced at all depths ✓
+
+**Action:** Change `"checkpointPolicy": "readonly"` on the **Codebase** section in your `hmem.config.json` to `"checkpointPolicy": "append"` — the section is now freely appendable by agents.
+
+### Codebase node schema standardized
+
+The `.2 Codebase` section now has a standard 4-level structure:
+- **L3 — Pipeline** (auto-created via `defaultChildren`): data flow overview
+- **L3.N — Module**: title = filename, body = purpose + `src/file.ts`
+- **L4 — Function** (mandatory): title = full TS signature, body = description + `src/file.ts`
+- **L5 — Extended Notes** (optional): usage example, caveats, complex param details
+
+Agents update L4 after every code change (enforced via `hmem-subagent` POST-TASK NODE SYNC).
+
+**Action:** Run `load_project` on each active project — the Pipeline sub-node is auto-created via `defaultChildren` reconcile if missing.
+
+---
+
 ## Step 3: Entry Migration
 
 Some versions introduce new data formats. Check if migration is needed:
@@ -360,7 +410,7 @@ All P-entries (projects) must follow the standard 16-section L2 structure define
 
 ```
 .1  Overview       (readonly)
-.2  Codebase       (readonly)
+.2  Codebase       (append — L3 modules + L4 signatures freely appendable by agents)
 .3  Dependencies   (readonly)
 .4  Usage          (readonly)
 .5  Requirements   (readonly)
@@ -382,6 +432,13 @@ All P-entries (projects) must follow the standard 16-section L2 structure define
 - `pointer` — Haiku may only add nodes that reference an entry ID (e.g. `[E0124]`)
 - `append` — Haiku may freely add sub-nodes
 
+**Codebase node structure (`.2`):**
+- L3 first child = **Pipeline** (data flow overview)
+- L3.N = **Module** (title: filename, body: purpose + `src/file.ts`)
+- L4 = **Function** (title: full TS signature, body: one-line description + `src/file.ts`)
+
+Agents update `.2` after every code change (POST-TASK NODE SYNC in hmem-subagent skill).
+
 For each active P-entry:
 1. `read_memory(id="P00XX", depth=2)` — check L2 structure
 2. Run `load_project(id="P00XX")` — auto-reconcile adds any missing sections
@@ -412,7 +469,7 @@ In `memory.schemas.P.sections`, make these changes:
 Full recommended policies (add to each section):
 ```json
 { "name": "Overview",     "checkpointPolicy": "readonly" },
-{ "name": "Codebase",     "checkpointPolicy": "readonly" },
+{ "name": "Codebase",     "checkpointPolicy": "append"   },
 { "name": "Dependencies", "checkpointPolicy": "readonly" },
 { "name": "Usage",        "checkpointPolicy": "readonly" },
 { "name": "Requirements", "checkpointPolicy": "readonly" },

package/skills/hmem-write/SKILL.md

@@ -590,6 +590,24 @@ Create new H-entries as topics emerge naturally from conversation.
 
 Match the language of existing entries. Before writing, check what language the memory store uses (run `read_memory()` if unsure). If existing entries are in German, write in German. If English, write in English. Do not mix languages within a single store — it makes search and curation harder.
 
+## After Writing: Verify the Entry Captured the Insight
+
+For L, D, and E entries with complex reasoning, do a quick read-back:
+```
+read_memory(id="X")
+```
+
+Ask: does this entry answer **"why?"** not just "what?"
+
+Update if any of these are true:
+- Entry is under 20 words with no body
+- Content is "Lesson learned: X" with no explanation or evidence
+- Entry would be incomprehensible to a future agent without this conversation context
+
+Skip for: simple factual entries, routine appends, O-entry checkpoints.
+
+---
+
 ## Anti-Patterns
 
 | Wrong | Right |