hmem-mcp 5.0.0 → 5.1.21

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

@@ -1,6 +1,6 @@
 ---
 name: hmem-self-curate
-description: Curate your own memory. Systematically review entries — mark obsolete, irrelevant, or favorite. Run periodically to keep memory clean.
+description: Curate your own memory. Systematically review entries — mark obsolete, irrelevant, or favorite. Run periodically to keep memory clean. Use when asked to "aufräumen", "clean up memory", "alte Einträge prüfen", "memory review", "Speicher bereinigen", "curate", "tidy up", or when memory_health() shows issues.
 ---
 
 # Self-Curation: Review Your Own Memory
@@ -39,14 +39,53 @@ Work through one prefix at a time. Load all entries of a prefix with full depth:
 read_memory(prefix="P", show_all=true)
 ```
 
-This bypasses V2 selection and session cache — every entry is expanded with L2+L3 children visible. Review each entry in the output directly — no need to drill into individual entries.
+This bypasses the bulk-read algorithm and session cache — every entry is expanded with L2+L3 children visible. Review each entry in the output directly — no need to drill into individual entries.
 
-**Order:** Start with the prefix that has the most entries (usually P), then move to L, E, D, etc.
+**Order:** Start with the prefix that has the most entries (usually P), then move to L, E, D, O, etc.
 
 If context overflows mid-prefix, continue with the remaining entries — your memory survives compression.
 
 ---
 
+## O-Entries (Session Logs)
+
+O-entries accumulate automatically via the Stop hook — each session creates one per project. `load_project` injects the latest session's **checkpoint summary** (if available) plus the most recent raw exchanges.
+
+**Checkpoint summaries:** Auto-checkpoints write a `[CP]` prefixed summary node (tagged `#checkpoint-summary`) under the O-entry. These rolling summaries compress older exchanges so `load_project` stays compact. Older summaries are further compressed into 1-2 sentences by each new checkpoint.
+
+**Skill-dialog filtering:** Exchanges containing skill activations (brainstorming, TDD, debugging) are tagged `#skill-dialog` at the exchange-node level and automatically excluded from `load_project` / `/clear` output. The full content remains accessible via `read_memory(id="O0123")`.
+
+**Curation rules for O-entries:**
+- **Leave them alone.** Old O-entries don't cause harm — they're excluded from bulk reads and `load_project` only shows the most recent one.
+- **Don't mark them irrelevant or obsolete** — they serve as historical record and can be useful for checkpoint agents extracting L/D/E.
+- **Skip O-entries during curation.** Focus your time on L, E, D, P entries where curation has real impact.
+
+---
+
+## Bulk Operations
+
+For large-scale curation across many entries, use the bulk tools instead of updating one by one:
+
+| Tool | Purpose |
+|------|---------|
+| `update_many(updates=[...])` | Batch-update multiple entries at once (content, flags, etc.) |
+| `tag_bulk(ids=[...], add_tags=[...], remove_tags=[...])` | Add or remove tags across many entries in one call |
+| `tag_rename(old_tag="...", new_tag="...")` | Rename a tag globally across all entries |
+
+These are especially useful when a curation pass reveals a pattern (e.g., 10 entries that all need the same tag added, or a batch of stale entries to mark irrelevant).
+
+---
+
+## Title Quality Check
+
+Since v5.1, every node has a **title** (short navigation label, ~50 chars) and an optional **body** (detailed content shown on drill-down). During curation, check whether titles are good navigation labels:
+
+- **Vague title?** Update it: `update_memory(id="L0003", content="Better, specific title")`
+- **Title = full content?** Old entries without `>` body lines have `title = autoExtract(content)`. If the content is valuable but the title is truncated gibberish, rewrite the title to be a clear summary.
+- **Long content in a leaf node?** Consider whether it would benefit from title/body separation — though this requires rewriting via the `>` format (write new entry + mark old obsolete).
+
+---
+
 ## For Each Entry: Decide and Act
 
 | Decision | Action |
@@ -55,7 +94,7 @@ If context overflows mid-prefix, continue with the remaining entries — your me
 | Important reference I need 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)` |
-| L1 wording is vague or misleading | `update_memory(id="X", content="Better wording")` |
+| Title 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)` |
 
 ---
@@ -89,9 +128,9 @@ Look for entries covering the same topic (common with P entries). Merge them:
 
 1. Pick the **keeper** (the more complete one)
 2. Copy unique info from the duplicate: `append_memory(id="P0029", content="Session from duplicate\n\tDetail carried over")`
-3. **Delete** the duplicate: `delete_agent_memory(agent_name="YOUR_NAME", entry_id="P0031")`
+3. Mark the duplicate obsolete with a correction reference: `update_memory(id="P0031", content="Merged into [✓P0029]", obsolete=true)`
 
-**Delete, don't mark irrelevant.** Irrelevant duplicates still show up with `show_all=true` and flood the context on future curation runs. True duplicates (entire content exists in the keeper) must be deleted to keep the memory clean.
+**Note:** Only curators (ceo role) can delete entries via `delete_agent_memory`. As a worker agent, use `obsolete=true` with `[✓ID]` to point to the keeper. Obsolete entries are hidden from bulk reads and won't cause confusion.
 
 ---
 
@@ -148,5 +187,8 @@ Check `[♥]` markers in the output.
 | `update_memory(id, content, obsolete=true)` | Mark as wrong (needs [✓ID]) |
 | `append_memory(id, content)` | Merge info into keeper |
 | `move_memory(source_id, target_parent_id)` | Relocate misplaced sub-node (updates all refs) |
-| `delete_agent_memory(agent_name, entry_id)` | Delete true duplicates |
+| `update_memory(id, content="Merged into [✓X]", obsolete=true)` | Mark duplicate as obsolete (point to keeper) |
+| `update_many(updates=[...])` | Batch-update multiple entries at once |
+| `tag_bulk(ids=[...], add_tags, remove_tags)` | Add/remove tags across many entries |
+| `tag_rename(old_tag, new_tag)` | Rename a tag globally |
 | `read_memory(show_obsolete=true, prefix="X")` | Review already-obsolete entries |

package/skills/hmem-setup/SKILL.md

@@ -1,22 +1,163 @@
 ---
 name: hmem-setup
 description: Interactive setup guide for hmem. Run this skill to install and configure
-  the hmem MCP server — installs dependencies, configures .mcp.json, and deploys
-  skill files to the correct global locations for Claude Code, Gemini CLI, or OpenCode.
+  the hmem MCP server — installs dependencies, configures .mcp.json, deploys skill
+  files, and registers auto-memory hooks for Claude Code, Gemini CLI, or OpenCode.
 ---
 
 # hmem Setup
 
-## Step 0 — Prerequisites
+## Recommended: `hmem init`
 
-Check before proceeding:
+Install hmem globally, then run the interactive installer:
+
+```bash
+npm install -g hmem-mcp
+hmem init
+```
+
+`hmem init` performs all setup steps automatically:
+1. Detects installed AI tools (Claude Code, Gemini CLI, OpenCode, Cursor, Windsurf, Cline)
+2. Asks for installation scope (system-wide or project-local)
+3. Creates the memory directory and optional example database
+4. Writes `.mcp.json` with the correct paths for each detected tool
+5. Adds session-start instructions to the tool's config file (CLAUDE.md, GEMINI.md, etc.)
+6. Creates `hmem.config.json` with sensible defaults
+7. Installs all 4 auto-memory hooks (Claude Code only — see Hook Reference below)
+8. Copies skill files (slash commands) to the tool's skill directory
+
+After `hmem init`, install the slash-command skills:
+
+```bash
+npx hmem update-skills
+```
+
+Restart your AI tool and call `read_memory()` to verify.
+
+Non-interactive mode (CI / scripting):
+
+```bash
+hmem init --global --tools claude-code --dir ~/.hmem --no-example
+```
+
+---
+
+## Hook Reference (Claude Code)
+
+`hmem init` registers 4 hooks in `~/.claude/settings.json`. Each hook is a bash script in `~/.claude/hooks/`.
+
+### 1. UserPromptSubmit — memory load + checkpoint reminder
+
+Script: `~/.claude/hooks/hmem-startup.sh`
+
+- **First message**: injects `additionalContext` telling the agent to call `read_memory()` silently.
+- **Every Nth message** (N = `checkpointInterval`, default 20): injects a checkpoint reminder.
+  - `checkpointMode: "remind"` — adds an `additionalContext` nudge; the agent decides what to save.
+  - `checkpointMode: "auto"` — checkpoint is handled by the Stop hook instead (no reminder injected).
+- Subagents (messages with `parentUuid`) are skipped.
+- Uses a per-session counter file at `/tmp/claude-hmem-counter-{SESSION_ID}`.
+
+### 2. Stop (async) — exchange logging + checkpoint
+
+Script: `~/.claude/hooks/hmem-log-exchange.sh`
+
+- Runs asynchronously after every agent response (timeout: 10s).
+- Pipes the Stop hook JSON (containing `transcript_path` and `last_assistant_message`) to `hmem log-exchange`.
+- `hmem log-exchange` reads the last user message from the JSONL transcript, combines it with the agent response, and appends both to the currently active O-entry (session history).
+- If no active O-entry exists, one is created automatically.
+- Every N exchanges (configurable via `checkpointInterval`, default 20), triggers a checkpoint:
+  - **auto mode**: Spawns `hmem checkpoint` in background — Haiku subagent with MCP tools that:
+    - Titles each exchange with a descriptive summary (max 50 chars)
+    - Writes L/D/E entries for non-obvious insights
+    - Updates P-entry (protocol, bugs, open tasks, overview, codebase)
+    - Writes a checkpoint summary for context re-injection
+    - Verifies project relevance and fixes links
+  - **remind mode**: Injects a reminder for the main agent to save knowledge manually
+- Checks transcript file size and writes a warning flag when context exceeds `contextTokenThreshold` (default 100k tokens).
+
+### 3. SessionStart[clear] — context re-injection
+
+Script: `~/.claude/hooks/hmem-context-inject.sh`
+
+- Fires only after `/clear` (matcher: `"clear"`).
+- Pipes session JSON to `hmem context-inject`, which outputs `additionalContext` containing:
+  - Last 20 user/assistant messages from the pre-clear transcript
+  - Active project briefing (title + overview)
+  - Recent O-entries (session logs) linked to the project
+  - R-entries (rules)
+- Keeps the agent oriented after a context reset without a full `read_memory()` call.
+
+---
+
+## Configuration Reference
+
+Place `hmem.config.json` in your memory directory (the path you chose during `hmem init`). All keys are optional — defaults are applied for anything missing.
+
+```json
+{
+  "memory": {
+    "maxCharsPerLevel": [200, 2500, 10000, 25000, 50000],
+    "maxDepth": 5,
+    "defaultReadLimit": 100,
+    "maxTitleChars": 50,
+    "checkpointInterval": 20,
+    "checkpointMode": "remind",
+    "recentOEntries": 10,
+    "contextTokenThreshold": 100000,
+    "bulkReadV2": {
+      "topAccessCount": 3,
+      "topNewestCount": 5,
+      "topObsoleteCount": 3,
+      "topSubnodeCount": 3,
+      "newestPercent": 20,
+      "newestMin": 5,
+      "newestMax": 15,
+      "accessPercent": 10,
+      "accessMin": 3,
+      "accessMax": 8
+    }
+  }
+}
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `maxCharsPerLevel` | `number[]` | `[200,2500,10000,25000,50000]` | Character limit per tree depth (L1..L5). Alternative: set `maxL1Chars` + `maxLnChars` and levels are interpolated linearly. |
+| `maxDepth` | `number` | `5` | Max tree depth (1 = L1 only, 5 = full). |
+| `defaultReadLimit` | `number` | `100` | Max entries returned by a default `read_memory()`. |
+| `maxTitleChars` | `number` | `50` | Max characters for auto-extracted titles. |
+| `checkpointInterval` | `number` | `20` | Messages between checkpoint reminders. Set 0 to disable. |
+| `checkpointMode` | `"remind"` or `"auto"` | `"remind"` | `"remind"` = inject a save-reminder via `additionalContext`. `"auto"` = spawn a Haiku subagent that saves directly (no user interaction). |
+| `recentOEntries` | `number` | `10` | Number of recent O-entries (session logs) injected at startup and on `load_project`. Set 0 to disable. |
+| `contextTokenThreshold` | `number` | `100000` | Token threshold for context-clear recommendation. When cumulative hmem output exceeds this, the agent is told to flush + `/clear`. Set 0 to disable. |
+
+**Bulk-read tuning** (`bulkReadV2`): controls which entries get expanded (all L2 children shown) in a default `read_memory()` call. Per prefix category, the top N newest + top M most-accessed entries are expanded. Favorites are always expanded.
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `topAccessCount` | `3` | Fixed fallback: top-accessed entries to expand. |
+| `topNewestCount` | `5` | Fixed fallback: newest entries to expand. |
+| `topObsoleteCount` | `3` | Obsolete entries to keep visible. |
+| `topSubnodeCount` | `3` | Entries with most sub-nodes to always expand. |
+| `newestPercent` | `20` | Percentage-based selection (overrides `topNewestCount`). |
+| `newestMin` / `newestMax` | `5` / `15` | Clamp for percentage-based newest selection. |
+| `accessPercent` | `10` | Percentage-based selection (overrides `topAccessCount`). |
+| `accessMin` / `accessMax` | `3` / `8` | Clamp for percentage-based access selection. |
+
+---
+
+## Manual Setup (Fallback)
+
+Use these steps only if `hmem init` is not available (e.g., local clone without global install).
+
+### Step 0 — Prerequisites
 
 ```bash
 node --version    # must be >= 18
 npm --version     # any recent version
 ```
 
-`better-sqlite3` requires native build tools. If `npm install` fails later:
+`better-sqlite3` requires native build tools:
 
 | OS | Install |
 |----|---------|
@@ -25,9 +166,7 @@ npm --version     # any recent version
 | macOS | `xcode-select --install` |
 | Windows | `npm install -g windows-build-tools` |
 
----
-
-## Step 1 — Clone and Build
+### Step 1 — Clone and Build
 
 ```bash
 git clone https://github.com/Bumblebiber/hmem.git
@@ -36,33 +175,19 @@ npm install
 npm run build
 ```
 
-Verify: `dist/mcp-server.js` must exist after build. If the build fails, fix errors
-before continuing — everything else depends on this file.
-
----
-
-## Step 2 — Create Agent Directory
+Verify: `dist/mcp-server.js` must exist after build.
 
-hmem stores each agent's memory at `{HMEM_PROJECT_DIR}/Agents/{AGENT_ID}/{AGENT_ID}.hmem`.
-The SQLite file is created automatically on first write — just create the folder:
+### Step 2 — Create Memory Directory
 
 ```bash
 mkdir -p /your/project/Agents/YOUR_NAME
 ```
 
+The SQLite `.hmem` file is created automatically on first write.
 
----
-
-## Step 3 — Configure MCP
-
-Add hmem to your `.mcp.json` (create it at your project root if it doesn't exist).
+### Step 3 — Configure MCP
 
-> **Important:** `.mcp.json` must be in the directory where you start your terminal
-> or AI tool. Claude Code, Gemini CLI, and OpenCode discover it from the current
-> working directory — if you open your project in `/home/alice/myproject`, that's
-> where `.mcp.json` belongs. The `.hmem` memory files will be created in that same
-> directory (under `Agents/YOUR_NAME/`) unless you point `HMEM_PROJECT_DIR`
-> elsewhere.
+Add hmem to your `.mcp.json` (create it at your project root if it does not exist). All paths must be absolute.
 
 ```json
 {
@@ -81,23 +206,15 @@ Add hmem to your `.mcp.json` (create it at your project root if it doesn't exist
 }
 ```
 
-**All paths must be absolute** — relative paths will fail silently.
-
 | Variable | Description |
 |----------|-------------|
 | `HMEM_PROJECT_DIR` | Root directory where `.hmem` files are stored |
 | `HMEM_AGENT_ID` | Unique identifier for this agent (e.g. `ALICE`, `DEVELOPER`) |
-| `HMEM_AGENT_ROLE` | Permission level: `worker` · `al` · `pl` · `ceo` |
+| `HMEM_AGENT_ROLE` | Permission level: `worker` / `al` / `pl` / `ceo` |
 
-Roles control what entries in the shared company store are visible.
-`worker` sees everything marked `min_role: worker`. Higher roles unlock more.
+### Step 4 — Install Skill Files
 
----
-
-## Step 4 — Install Skill Files
-
-Skill files teach your AI tool how to use `read_memory`, `write_memory`, and `/save`.
-Copy them to the global skills directory for your tool:
+Copy skill files to the global skills directory for your tool:
 
 **Claude Code:**
 ```bash
@@ -111,78 +228,43 @@ cp /path/to/hmem/skills/memory-curate/SKILL.md ~/.claude/skills/memory-curate/SK
 **Gemini CLI:**
 ```bash
 mkdir -p ~/.gemini/skills/hmem-read ~/.gemini/skills/hmem-write ~/.gemini/skills/save ~/.gemini/skills/memory-curate
-cp /path/to/hmem/skills/hmem-read/SKILL.md ~/.gemini/skills/hmem-read/SKILL.md
-cp /path/to/hmem/skills/hmem-write/SKILL.md ~/.gemini/skills/hmem-write/SKILL.md
-cp /path/to/hmem/skills/save/SKILL.md ~/.gemini/skills/save/SKILL.md
-cp /path/to/hmem/skills/memory-curate/SKILL.md ~/.gemini/skills/memory-curate/SKILL.md
+cp /path/to/hmem/skills/*/SKILL.md to corresponding ~/.gemini/skills/*/SKILL.md
 ```
 
-**OpenCode:**
-```bash
-mkdir -p ~/.config/opencode/skills/hmem-read ~/.config/opencode/skills/hmem-write ~/.config/opencode/skills/save ~/.config/opencode/skills/memory-curate
-cp /path/to/hmem/skills/hmem-read/SKILL.md ~/.config/opencode/skills/hmem-read/SKILL.md
-cp /path/to/hmem/skills/hmem-write/SKILL.md ~/.config/opencode/skills/hmem-write/SKILL.md
-cp /path/to/hmem/skills/save/SKILL.md ~/.config/opencode/skills/save/SKILL.md
-cp /path/to/hmem/skills/memory-curate/SKILL.md ~/.config/opencode/skills/memory-curate/SKILL.md
-```
+### Step 5 — Verify
 
----
-
-## Step 5 — Optional: hmem.config.json
-
-Place `hmem.config.json` in your `HMEM_PROJECT_DIR` to customize behavior. All keys are optional.
-
-```json
-{
-  "maxL1Chars": 500,
-  "maxLnChars": 50000,
-  "maxDepth": 5,
-  "defaultReadLimit": 100,
-  "bulkReadV2": {
-    "topAccessCount": 3,
-    "topNewestCount": 5,
-    "topObsoleteCount": 3
-  }
-}
-```
-
-**Character limits** — two options:
-- `"maxL1Chars"` + `"maxLnChars"`: set endpoints only, intermediate levels interpolated linearly
-- `"maxCharsPerLevel"`: explicit array `[L1, L2, L3, L4, L5]`
-
-**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.
-
----
-
-## Step 6 — Verify
-
-**Fully restart** your AI tool (exit and reopen — `/clear` is not enough).
-Then call:
+Fully restart your AI tool (exit and reopen — `/clear` is not enough). Then call:
 
 ```
 read_memory()
 ```
 
-Expected: `Memory is empty` (or your existing memories if any).
+Expected: `Memory is empty` (or your existing memories).
+
+---
 
-**Troubleshooting:**
+## Troubleshooting
 
 | Symptom | Likely cause |
 |---------|-------------|
 | `HMEM_PROJECT_DIR not set` | Path missing or wrong env var name in `.mcp.json` |
 | `No such tool: read_memory` | Tool not restarted after adding `.mcp.json` |
-| `npm install` fails | Missing build tools (see Step 0) |
+| `npm install` fails | Missing build tools (see Prerequisites above) |
 | `read_memory` returns empty after writing | MCP server process is stale — restart tool |
+| Hooks not firing | Check `~/.claude/settings.json` — hooks must be registered there |
+| Checkpoint reminders not appearing | Verify `checkpointInterval > 0` in `hmem.config.json` |
 
 ---
 
 ## Quick Reference — After Setup
 
 ```
-read_memory()                          # see all your Level 1 memories
+read_memory()                          # see all L1 memories
 read_memory(id="L0001")               # drill into one entry
-write_memory(prefix="L", content="…") # save a lesson learned
+write_memory(prefix="L", content="Short title\n> Detailed body text\n\tL2 sub-node")
 search_memory(query="error node.js")  # search across all memories
 ```
 
+Use `>` lines for body text (hidden in listings, shown on drill-down). See `hmem-write` skill for details.
+
 See `skills/hmem-read/SKILL.md` and `skills/hmem-write/SKILL.md` for full usage.

package/skills/hmem-sync-setup/SKILL.md

@@ -27,6 +27,10 @@ It automatically:
 4. Asks the user what to sync (push, pull, merge, or skip)
 5. Verifies the result
 
+**Custom / Self-hosted servers:** The `--server-url` flag accepts any hmem-sync compatible
+server, not just the default. Examples: `https://yourdomain.com/hmem-sync` for a self-hosted
+instance, or `http://localhost:3100` for a local development server.
+
 For non-interactive use:
 ```bash
 # New account
@@ -34,6 +38,9 @@ npx hmem-sync connect --user-id myname --passphrase "pass" --hmem-path ~/.hmem/
 
 # Existing account
 npx hmem-sync connect --user-id myname --passphrase "pass" --token abc123... --hmem-path ~/.hmem/ --agent-id DEVELOPER
+
+# Custom server
+npx hmem-sync connect --server-url http://localhost:3100 --user-id myname --passphrase "pass" --hmem-path ~/.hmem/ --agent-id DEVELOPER
 ```
 
 The legacy `setup` and `restore` commands still work for backwards compatibility.
@@ -104,10 +111,10 @@ The user needs these values on their other devices:
 - **Token** — from `.hmem-sync-token`
 - **Passphrase** — the one they chose in Step 2
 
-Show the user where these files are:
+Show the user where these files are (adjust AGENT_ID to match your `HMEM_AGENT_ID`):
 ```bash
-cat $(dirname $(echo $HMEM_PROJECT_DIR)/Agents/*//*.hmem)/.hmem-sync-config.json
-cat $(dirname $(echo $HMEM_PROJECT_DIR)/Agents/*//*.hmem)/.hmem-sync-token
+cat "$HMEM_PROJECT_DIR/Agents/$HMEM_AGENT_ID/.hmem-sync-config.json"
+cat "$HMEM_PROJECT_DIR/Agents/$HMEM_AGENT_ID/.hmem-sync-token"
 ```
 
 ---
@@ -250,3 +257,9 @@ Config files are always stored next to the .hmem file:
 .hmem-sync-token        — auth token (chmod 600, never commit)
 .hmem-sync.json         — sync state (last push/pull timestamps)
 ```
+
+## Multi-Server Sync
+
+For redundancy, you can configure multiple servers in `hmem.config.json` as an array.
+hmem-sync will push to and pull from all configured servers, so data survives if one
+server goes down. See the hmem-sync README for the exact schema.