hmem-mcp 4.0.0 → 5.1.21

package/skills/hmem-update/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: hmem-update
+description: >
+  Post-update checklist for hmem-mcp and hmem-sync. Run after npm update or when
+  hmem detects a version change. Covers skill sync, entry migration, schema enforcement,
+  O-entry curation, and smoke tests. Use when the user says "update hmem", "hmem updaten",
+  or when the startup version-check detects a new version.
+---
+
+# /hmem-update — Post-Update Checklist
+
+Run this after updating hmem-mcp or hmem-sync. Every step is important — do not skip steps.
+
+---
+
+## Step 1: Version Check
+
+Determine what changed:
+
+```bash
+hmem --version                    # current installed version
+npm view hmem-mcp version         # latest on npm
+npm view hmem-mcp versions --json # all versions
+```
+
+Read the changelog for the version range:
+```bash
+cd ~/projects/hmem && git log --oneline <old-tag>..HEAD  # if local repo exists
+```
+
+Or check GitHub releases: `gh release list -R Bumblebiber/hmem --limit 5`
+
+**If already on latest:** Tell the user and skip to Step 7 (smoke test).
+
+---
+
+## Step 2: Update Skills
+
+```bash
+hmem update-skills
+```
+
+This syncs all skill files from the npm package to the local skills directory. Verify:
+
+```bash
+ls ~/.claude/skills/hmem-*/SKILL.md   # Claude Code
+ls ~/.config/gemini/skills/hmem-*/     # Gemini CLI (if applicable)
+```
+
+Check for new skills that weren't there before — inform the user about new capabilities.
+
+---
+
+## Step 2b: Verify Hooks
+
+Hooks are critical — without them, O-entries are never logged and auto-checkpoints never fire.
+
+Check the current hook configuration:
+```bash
+cat ~/.claude/settings.json | grep -A5 hooks
+```
+
+**Required hooks (for `checkpointMode: "auto"`):**
+- **UserPromptSubmit** — memory load + checkpoint reminder
+- **Stop** — exchange logging (`hmem log-exchange`) + O-entry title generation
+- **SessionStart[clear]** — context re-injection after `/clear`
+
+**If hooks are missing or empty (`hooks: {}`):**
+1. Inform the user: "Hooks are not configured — O-entries won't be logged and auto-checkpoints won't fire."
+2. Suggest: "Run `/hmem-config` to set up hooks, or run `hmem init` to re-initialize."
+
+**If hooks exist but reference old paths or scripts:**
+- Check that hook scripts exist and are executable
+- Verify they reference the current hmem installation path
+
+---
+
+## Step 2c: Check load_project Display Config
+
+Since v5.1.8, `load_project` supports configurable section expansion:
+- `loadProjectExpand.withBody`: sections showing L3 title + body (default: `[1]` = Overview)
+- `loadProjectExpand.withChildren`: sections listing all L3 children as titles (default: `[6, 8]` = Bugs, Open Tasks)
+
+Check if the user has customized this in `hmem.config.json`. If not, inform them about the option:
+```json
+{ "memory": { "loadProjectExpand": { "withBody": [1], "withChildren": [6, 8] } } }
+```
+
+---
+
+## Step 3: Entry Migration
+
+Some versions introduce new data formats. Check if migration is needed:
+
+**v5.1.0+ Title/Body Separation:**
+- Entries now support `>` body lines (title shown in listings, body on drill-down)
+- Check if old entries need title/body split:
+  ```
+  read_memory(titles_only=true)
+  ```
+- Look for entries where the title is truncated mid-word or contains too much detail
+- Fix with: `update_memory(id="L0042", content="Clear title\n> Detailed body text")`
+
+**v5.1.2+ Checkpoint Summaries:**
+- O-entries with >10 exchanges should have `[CP]` checkpoint summaries
+- Check recent O-entries: `read_memory(prefix="O")`
+- If summaries are missing, write them:
+  ```
+  append_memory(id="O00XX", content="\t[CP] Factual 3-8 sentence summary of the session")
+  ```
+
+**v5.1.2+ Skill-Dialog Tags:**
+- Exchanges containing skill activations should be tagged `#skill-dialog`
+- These are auto-tagged by the checkpoint process going forward
+- For old exchanges: the checkpoint auto-tagger picks them up on the next run
+
+**General migration pattern:**
+1. Read a sample of entries to assess the current state
+2. Identify entries that don't match the new format
+3. Fix in batches — don't try to fix everything at once
+4. Prioritize: favorites and pinned entries first, then high-access, then the rest
+
+---
+
+## Step 4: P-Entry Schema Enforcement (R0009)
+
+All P-entries (projects) must follow the standard L2 structure:
+
+```
+.1 Overview
+.2 Codebase
+.3 Usage
+.4 Context
+.5 Deployment
+.6 Bugs
+.7 Protocol
+.8 Open tasks
+.9 Ideas
+```
+
+For each active P-entry:
+1. `read_memory(id="P00XX", depth=2)` — check L2 structure
+2. Compare against the schema above
+3. Add missing sections: `append_memory(id="P00XX", content="\tOverview\n\t\tCurrent state: ...")`
+4. L1 body should be: `Name | Status | Stack | Description`
+
+**Do not restructure entries that already follow the schema.** Only fix what's missing or wrong.
+
+---
+
+## Step 5: O-Entry Curation
+
+Check recent O-entries for quality:
+
+```
+read_memory(prefix="O")
+```
+
+**Titles:**
+- Replace "unassigned" or generic titles (e.g., "hmem-mcp") with descriptive ones
+- Good: "Title/Body Separation design + v5.1.0 release"
+- Fix: `update_memory(id="O00XX", content="Descriptive session title")`
+
+**Tags:**
+- Every O-entry should have at least `#session`
+- Add topic tags where obvious: `#release`, `#bugfix`, `#refactor`, `#brainstorming`
+- Fix: `update_memory(id="O00XX", tags=["#session", "#release"])`
+
+**Checkpoint Summaries:**
+- O-entries with >10 exchanges and no `[CP]` summary need one
+- Write summary: `append_memory(id="O00XX", content="\t[CP] Summary...")`
+- The auto-tagger will tag it `#checkpoint-summary` on the next checkpoint run
+
+**Cleanup:**
+- Look for duplicate O-entries (same title, same date, 1-2 exchanges) — these are likely subagent artifacts
+- Mark as irrelevant or delete if clearly junk
+
+---
+
+## Step 6: hmem-sync Update (if installed)
+
+Check if hmem-sync is installed and needs updating:
+
+```bash
+which hmem-sync && hmem-sync --version  # check if installed
+npm view hmem-sync version              # latest on npm
+```
+
+If outdated:
+```bash
+npm update -g hmem-sync
+```
+
+Verify sync still works:
+```bash
+hmem-sync status    # check connection to sync server
+hmem-sync push      # test push
+hmem-sync pull      # test pull
+```
+
+**If hmem-sync is not installed:** Skip this step. Mention to the user that hmem-sync is available for cross-device sync.
+
+---
+
+## Step 7: Smoke Test
+
+Verify everything works after the update:
+
+```
+read_memory()                           # bulk read works
+read_memory(id="P00XX")                 # drill-down works
+load_project(id="P00XX")               # project loading works
+write_memory(prefix="T", content="Update smoke test — delete me", tags=["#test"])
+                                        # write works → note the ID
+update_memory(id="T00XX", content="Update smoke test — verified", irrelevant=true)
+                                        # update works + mark for cleanup
+```
+
+If any step fails: report the error to the user. Do not proceed with normal work until the issue is resolved.
+
+---
+
+## Step 8: Report
+
+Tell the user what was done:
+
+```
+hmem-mcp updated: v5.1.2 → v5.1.4
+
+Changes applied:
+- Skills synced (2 new, 3 updated)
+- 5 P-entries checked against R0009 schema (2 fixed)
+- 12 O-entries curated (4 titles fixed, 3 summaries added)
+- Smoke test passed
+
+New features in this version:
+- Rolling checkpoint summaries
+- Skill-dialog exchange filtering
+- hmem --version reads from package.json
+```
+
+---
+
+## Auto-Detection (for hook integration)
+
+This skill can be triggered automatically. At session startup, if the hmem MCP server detects that the installed version differs from the last-seen version stored in the config, it appends a notice to the first `read_memory()` response:
+
+```
+⚠ hmem-mcp updated: v5.1.2 → v5.1.4. Run /hmem-update to apply post-update steps.
+```
+
+The agent should then invoke this skill automatically or ask the user if they want to run it.
+
+**Last-seen version** is stored in `hmem.config.json` under `lastSeenVersion`. Updated automatically after a successful `/hmem-update` run.

package/skills/hmem-wipe/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: hmem-wipe
+description: >
+  Prepare for /clear by optionally saving high-value knowledge. Use when:
+  - User types /wipe
+  - Context threshold warning appears (100k tokens)
+  - User says "context aufräumen", "clear machen", "wipe"
+  Handles pre-clear cleanup, then instructs user to /clear for automatic context restoration.
+---
+
+# Wipe — Prepare & Clear Context
+
+Follow these steps in order.
+
+## Step 1: Optionally save high-value knowledge
+
+Check `checkpointMode` in hmem.config.json to decide what to do:
+
+### checkpointMode: "auto"
+
+The Haiku subagent already extracts L/D/E entries every 20 exchanges automatically.
+Skip manual writes unless you have **specific high-value knowledge** that:
+- Was discovered in the last few exchanges (too recent for the last auto-checkpoint)
+- Is critical enough that losing it would cost significant rework
+- Is NOT already covered by a recent auto-checkpoint
+
+If nothing qualifies, proceed directly to Step 2.
+
+### checkpointMode: "remind"
+
+Manually save unsaved insights from this project context:
+- New lessons learned: `write_memory(prefix="L", ...)`
+- Project progress: `append_memory(id="P00XX.7", ...)` (Protocol node)
+- Decisions made: `write_memory(prefix="D", ...)`
+- Errors encountered: `write_memory(prefix="E", ...)`
+
+Skip if the last checkpoint was fewer than 5 messages ago.
+
+### Why gate on checkpointMode?
+
+Redundant writes waste tokens and create duplicates that clutter memory.
+Auto-checkpoints already call `read_memory` to deduplicate before writing —
+manual writes during wipe bypass that check and risk creating noise.
+
+## Step 2: Tell the user to /clear
+
+O-entries are auto-logged by the Stop hook — every exchange is already saved
+to the active project's O-entry. No need to manually create O-entries or call
+`flush_context` for conversation history.
+
+Reply with exactly:
+
+> Context ready for clear. Type `/clear` — the SessionStart hook will automatically restore your project context.
+
+Do NOT attempt to run /clear yourself — it is a built-in CLI command only the user can execute.
+
+## What happens after /clear
+
+The `SessionStart[clear]` hook automatically:
+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
+  project's O-entry. Wipe does not need to handle conversation history.
+- **Checkpoints are covered (auto mode).** The Haiku subagent extracts knowledge
+  every 20 exchanges. Wipe only needs to catch the tail end, if anything.
+- **Context restoration is covered.** The SessionStart[clear] hook handles
+  re-injection automatically. The agent just needs the user to type /clear.

package/skills/hmem-write/SKILL.md

@@ -19,13 +19,30 @@ If the tool `write_memory` is not available:
 ```
 write_memory(
   prefix: "E",
-  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)"
+  content: "Short Title (~50 chars)\n> L1 body — detailed explanation, can span multiple lines\n> second body line with more context\n\tL2 node title\n\t> L2 body text (supports newlines)\n\t> more L2 body\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.
+**Title + Body convention:** Every node has a **title** (short navigation label) and an optional **body** (detailed content loaded on drill-down).
 
-**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.
+- **Title:** The first non-indented line (L1) or first line at a given indent level (L2+). ~50 chars, like a chapter title.
+- **Body:** Lines starting with `> ` at the same indent level. Joined with newlines. Shown only when the node is drilled into, not in listings.
+- **Backward-compatible:** Without `> ` lines, the full text is stored as `content` and the title is auto-extracted from the first `maxTitleChars` characters (existing behavior).
+
+**L1 example with body:**
+```
+Short Error Title
+> SQLite connection failed because .mcp.json used a relative path.
+> The fix was to use an absolute path in the HMEM_PROJECT_DIR env var.
+	Details about reproduction
+	> Steps: 1. Set HMEM_PROJECT_DIR=./hmem  2. Run hmem serve  3. Observe SQLITE_CANTOPEN
+```
+
+**L1 example without body (old format, still works):**
+```
+SQLite connection failed due to wrong path in .mcp.json
+	Fix: use absolute path in env var
+```
 
 **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.
@@ -70,15 +87,40 @@ tag_rename(old_tag="#hmem-store", new_tag="#hmem")           # rename a tag ever
 | Prefix | Category | When to use |
 |--------|----------|-------------|
 | **P** | (P)roject | Project entries — standardized L1 format (see below) |
-| **L** | (L)esson | Lessons learned, best practices |
-| **E** | (E)rror | Bugs, errors + their fix |
-| **D** | (D)ecision | Architecture decisions with reasoning |
-| **T** | (T)ask | Task notes, work progress |
-| **M** | (M)ilestone | Key milestones, releases |
+| **L** | (L)esson | Lessons learned, best practices — cross-project knowledge |
+| **E** | (E)rror | Bugs, errors + their fix — cross-project knowledge |
+| **D** | (D)ecision | Architecture decisions with reasoning — cross-project knowledge |
+| **T** | (T)ask | Cross-project or infrastructure tasks ONLY (see note below) |
+| **M** | (M)ilestone | Cross-project milestones ONLY — project milestones go in P-entry L2 "Protocol" |
 | **S** | (S)kill | Skills, processes, how-to guides |
 | **N** | (N)avigator | Code pointers — where something lives in the codebase |
 | **H** | (H)uman | Knowledge about the user — preferences, context, working style |
 | **R** | (R)ule | User-defined rules and constraints — "always do X", "never do Y" |
+| **I** | (I)nfrastructure | Devices, servers, deployments, network — one entry per device/server |
+
+### Where do tasks, errors, lessons, and decisions go?
+
+**Tasks** belong inside the project's P-entry L2 "Open tasks" node:
+```
+append_memory(id="P0048.8", content="Implement multi-server sync\n\tPush/pull to all configured servers", tags=["#hmem-sync"])
+```
+Use the T-prefix ONLY for tasks that span multiple projects or are infrastructure/meta tasks (e.g. "Set up Strato server", "Run curation pass"). These get `links=["P00XX"]` to the most relevant project.
+
+**Milestones** belong in the P-entry L2 "Protocol" node as a chronological entry:
+```
+append_memory(id="P0048.7", content="v4.0.0 published — project gate + load_project tool (2026-03-27)", tags=["#release"])
+```
+Use the M-prefix ONLY for milestones that span multiple projects (e.g. "First cross-device sync working").
+
+**Errors (E), Lessons (L), Decisions (D)** stay as independent root entries — they are **cross-project knowledge**. An SQLite lesson learned in hmem applies to every SQLite project. Always add `tags` and `links` to connect them back:
+```
+write_memory(prefix="E", content="...", tags=["#hmem", "#sqlite"], links=["P0048"])
+```
+
+**P-entry "Known issues" (L2)** contains short summaries pointing to E-entries — not the errors themselves:
+```
+append_memory(id="P0048.6", content="Auto-sync fails with multiple .hmem in CWD → E0097, T0043", tags=["#hmem-sync"])
+```
 
 **Custom prefixes:** If none of the above fit, you can use any single uppercase letter. To register it officially (so the system validates it), add it to `hmem.config.json` under `"prefixes"`:
 ```json
@@ -89,10 +131,11 @@ Custom prefixes are merged with the defaults — they don't replace them. Withou
 ### P-Entry Standard Schema (enforced by MCP server)
 
 Every project entry MUST follow this structure. The MCP server validates L2 nodes
-against the required categories when `prefix="P"`.
+against the standard categories when `prefix="P"`.
 
-**L1 Title:** `Name | Status | Tech | Repo`
-**L1 Body:** One-line description
+**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.
+**L1 Body:** (same line or next non-indented line) One-sentence project summary.
 
 **Status values:**
 
@@ -104,49 +147,51 @@ against the required categories when `prefix="P"`.
 | Paused | On hold, will resume later |
 | Archived | Done or abandoned |
 
-**Required L2 categories (fixed order, omit empty ones):**
-
-```
-P00XX Title | Status | Tech | Repo
-One-line description
-	Overview — what an agent should read FIRST (like CLAUDE.md /init output)
-		Current state — what works, what doesn't, current version
-		Goals — short-term and long-term objectives
-		Architecture — high-level data flow, core concepts (no code)
-		Environment — paths, servers, repo URL, how to start
-	Codebase — code structure description (no code, only signatures + purpose)
-		Entry point — main/index, start command
-		Core modules — per L4 node: name, signature, purpose, return value
-		Helpers / Utilities — per L4 node with links to consuming modules
-		Config / Constants — important configuration values
-		Tests — how to test, what's covered
-	Usage — how the project is used
-		Installation / Setup
-		CLI / API — commands, endpoints, MCP tools
-		Common workflows
-	Context — background and classification
-		Initiator — who, why, when started
-		Target audience
-		Business context
-		Dependencies / Related projects (links to other P/T/D)
-	Deployment — build, CI/CD, npm publish, server config
-	Known issues — current bugs/limitations (links to E-entries)
-	Protocol — session log, chronological, one-liner + links to O-entries
-	Open tasks — current TODOs (links to T-entries)
-```
-
-**P0000** is the reserved "Non-Project" catch-all. Entries not tied to any project
-link to P0000. There must ALWAYS be at least one active project — if nothing else
-applies, activate P0000.
-
-**Examples:**
-
-```
-hmem-mcp | Active | TS/SQLite/npm | Persistente hierarchische AI-Memory mit 5-Level Lazy Loading
-Heimdall | Paused | TS/Bun/OpenCode-Fork | Permanenter Fork von OpenCode CLI mit hmem + Groupchat
-EasySAP | Active | AHK v2/SAP GUI Scripting | SAP-Automatisierung für Carl Zeiss
+**L2 categories (fixed order, skip sections that are empty):**
+
+The MCP server validates that L2 nodes start with one of these names. Minimum for a new project: Overview + Codebase (or Usage).
+
+| L2 Category | What goes here | L3 children |
+|-------------|---------------|-------------|
+| **Overview** | First thing an agent reads (like CLAUDE.md /init) | Current state, Goals, Architecture, Environment |
+| **Codebase** | Code structure — NO code, only names + signatures | Entry point, Core modules (each module = L4 node with signature + purpose + return), Helpers, Config, Tests |
+| **Usage** | How the project is used | Installation/Setup, CLI/API commands, Common workflows |
+| **Context** | Background and motivation | Initiator, Target audience, Business context, Dependencies (links) |
+| **Deployment** | Build/CI/CD/publish process | (flat or with L3 sub-steps) |
+| **Bugs** | Active bugs + known limitations | L3: inline report (symptom + cause) OR pointer to E-entry (`→ E0097`). L4: reproduction steps |
+| **Protocol** | Session log, chronological | One-liner per session + links to O-entries |
+| **Open tasks** | Project-specific TODOs | One per L3 node. Cross-project tasks → T-prefix with links |
+| **Ideas** | Feature ideas, brainstorming | L3: short description, L4: implementation details |
+
+**load_project tool:** Use `load_project(id="P0048")` to activate a project and get the full briefing (L2 content + L3 titles) in one call. This is the recommended way to start working on a project — it combines read + activate.
+
+**Markers you may see on entries:**
+
+| Marker | Meaning |
+|--------|---------|
+| `[♥]` | Favorite — always expanded in bulk reads |
+| `[★]` | Top-accessed — high weighted access score |
+| `[≡]` | Top-subnode — many children |
+| `[⚡]` | Task-promoted — relevant to an active T/P/D entry (tag overlap) |
+| `[*]` | Active — currently in focus |
+| `[P]` | Pinned — super-favorite, shows full L2 |
+| `[!]` | Obsolete — superseded, kept for history |
+| `[-]` | Irrelevant — hidden from bulk reads |
+| `✓` | Synced — backed up to all sync servers |
+
+**Complete P-entry example (WeatherBot):**
+
+```
+write_memory(
+  prefix="P",
+  content="WeatherBot | New | Python/Discord.py | GH: user/weatherbot\n> Discord bot for weather forecasts — slash commands for current weather and multi-day forecasts\n\tOverview\n\t\tCurrent state\n\t\t> Scaffolding done, no commands yet. Bot connects to Discord but has no slash commands registered.\n\t\tGoals\n\t\t> Daily/hourly forecasts via slash commands, multi-city support, embed formatting\n\t\tArchitecture\n\t\t> Discord slash command → OpenWeatherMap API → formatted embed. Single-file cog pattern.\n\t\tEnvironment\n\t\t> /home/user/weatherbot, python bot.py, needs DISCORD_TOKEN + WEATHER_API_KEY in .env\n\tCodebase\n\t\tEntry point — bot.py, start: python bot.py\n\t\tCore modules\n\t\t\tweather_cog.py — WeatherCog(Cog); fetch_forecast(city: str) → discord.Embed\n\t\t\tformatter.py — format_embed(data: dict) → discord.Embed\n\t\tHelpers / Utilities\n\t\t\tapi_client.py — get_weather(city: str) → dict; wraps HTTP to OpenWeatherMap\n\t\tConfig / Constants — .env: DISCORD_TOKEN, WEATHER_API_KEY, DEFAULT_CITY\n\t\tTests — pytest, test_weather_cog.py (3 tests)\n\tUsage\n\t\tInstallation / Setup — pip install -r requirements.txt, cp .env.example .env\n\t\tCLI / API — /weather <city>, /forecast <city> (planned)\n\tContext\n\t\tInitiator — personal project, Mar 2026\n\t\tTarget audience — personal Discord server\n\t\tDependencies — discord.py, OpenWeatherMap API, aiohttp\n\tOpen tasks\n\t\tImplement /forecast command\n\t\t> Multi-day view with daily highs/lows and weather icons per day\n\t\tAdd city autocomplete",
+  tags=["#discord", "#python", "#weather", "#bot"],
+  links=[]
+)
 ```
 
+Note: L2 nodes use 1 tab, L3 uses 2 tabs, L4 uses 3 tabs. Use `> ` for body text that should be hidden in listings but shown on drill-down. Skip empty sections — no need for placeholder text.
+
 ### Marking entries as favorites
 
 Mark any entry as a favorite to ensure it always appears with its L2 detail in bulk reads (alongside a `[♥]` marker). Use this for reference info you need to see every session — API endpoints, key decisions, frequently looked-up patterns.
@@ -206,22 +251,22 @@ write_memory(
 
 ---
 
-## Title + L1 Quality Rules
+## Title + Body 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)
 
-**L1:** One complete, informative sentence — ~15–20 tokens.
+**Body (via `>` lines):** Detailed explanation — full sentences, multiline OK. Shown on drill-down, hidden in listings.
 - Must be understandable without any context
-- Not "Fixed a bug" — instead "SQLite connection failed due to wrong path in .mcp.json"
+- Not "Fixed a bug" — instead explain root cause, fix, and impact
 
-**With explicit title (recommended):**
+**With title + body (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")
+write_memory(prefix="L", content="hmem.py Performance: Bulk-Queries statt N+1\n> Alle Nodes in 2 Bulk-Queries laden, nicht pro Entry einzeln.\n> Vorher: load_nodes() pro Entry = N+1 SQLite-Connections.\n\tImplementation detail\n\t> Changed read() to batch-fetch all nodes for visible entries in one query")
 ```
 
-**Without explicit title (auto-extracted):**
+**Without body (simple entries, backward-compatible):**
 ```
 write_memory(prefix="E", content="SQLite connection failed due to wrong path in .mcp.json\n\tFix: use absolute path in env var")
 ```
@@ -302,7 +347,13 @@ Only use `write_memory` when:
 
 ## When to save?
 
-**Mandatory before terminating.** Only save what is still valuable in 6 months.
+**Checkpoint mode matters.** Check `checkpointMode` in hmem.config.json:
+
+- **`"auto"` (recommended):** A background Haiku subagent handles checkpoints automatically every N exchanges. It reads recent O-entry exchanges, calls `read_memory` to avoid duplicates, and writes L/D/E entries + handoff via MCP tools. It also writes a rolling checkpoint summary (`[CP]` node tagged `#checkpoint-summary`) that compresses older exchanges for `load_project`. Skill-dialog exchanges are auto-tagged `#skill-dialog` and filtered from context injection. **You do NOT need to write entries yourself** unless the user explicitly asks you to save something specific.
+
+- **`"remind"`:** You will receive a CHECKPOINT reminder every N messages. When you see it, save key learnings yourself using `write_memory` / `append_memory`.
+
+**In both modes:** Only save what is still valuable in 6 months.
 
 | Save | Don't save |
 |------|-----------|
@@ -336,13 +387,14 @@ Use when: the wording is wrong, outdated, or needs clarification.
 Appends new child nodes under an existing root or node. Existing children are preserved.
 
 Content indentation is **relative to the parent** — 0 tabs = direct child of `id`.
+Body lines (`> `) work the same as in `write_memory`.
 
 ```
 append_memory(
   id="L0003",
-  content="New finding discovered later\n\tSub-detail about it"
+  content="New finding discovered later\n> Detailed explanation of what was found and why it matters.\n> This can span multiple lines.\n\tSub-detail about it"
 )
-# → adds L0003.N (L2) and L0003.N.1 (L3)
+# → adds L0003.N (L2 with title + body) and L0003.N.1 (L3)
 
 append_memory(
   id="L0003.2",