hmem-mcp 1.1.0

package/skills/hmem-setup/SKILL.md

@@ -0,0 +1,200 @@
+---
+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.
+---
+
+# hmem Setup
+
+## Step 0 — Prerequisites
+
+Check before proceeding:
+
+```bash
+node --version    # must be >= 18
+npm --version     # any recent version
+```
+
+`better-sqlite3` requires native build tools. If `npm install` fails later:
+
+| OS | Install |
+|----|---------|
+| Linux (Debian/Ubuntu) | `sudo apt install python3 make g++` |
+| Linux (Arch) | `sudo pacman -S python make gcc` |
+| macOS | `xcode-select --install` |
+| Windows | `npm install -g windows-build-tools` |
+
+---
+
+## Step 1 — Clone and Build
+
+```bash
+git clone https://github.com/Bumblebiber/hmem.git
+cd hmem
+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
+
+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:
+
+```bash
+mkdir -p /your/project/Agents/YOUR_NAME
+```
+
+For shared team knowledge (optional), hmem uses a `FIRMENWISSEN.hmem` file at the
+project root — created automatically on first `write_memory(store="company")`.
+
+---
+
+## Step 3 — Configure MCP
+
+Add hmem to your `.mcp.json` (create it at your project root if it doesn't exist).
+
+> **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.
+
+```json
+{
+  "mcpServers": {
+    "hmem": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/absolute/path/to/hmem/dist/mcp-server.js"],
+      "env": {
+        "HMEM_PROJECT_DIR": "/absolute/path/to/your/project",
+        "HMEM_AGENT_ID": "YOUR_NAME",
+        "HMEM_AGENT_ROLE": "worker"
+      }
+    }
+  }
+}
+```
+
+**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` |
+
+Roles control what entries in the shared `FIRMENWISSEN` store are visible.
+`worker` sees everything marked `min_role: worker`. Higher roles unlock more.
+
+---
+
+## 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:
+
+**Claude Code:**
+```bash
+mkdir -p ~/.claude/skills/hmem-read ~/.claude/skills/hmem-write ~/.claude/skills/save ~/.claude/skills/memory-curate
+cp /path/to/hmem/skills/hmem-read/SKILL.md ~/.claude/skills/hmem-read/SKILL.md
+cp /path/to/hmem/skills/hmem-write/SKILL.md ~/.claude/skills/hmem-write/SKILL.md
+cp /path/to/hmem/skills/save/SKILL.md ~/.claude/skills/save/SKILL.md
+cp /path/to/hmem/skills/memory-curate/SKILL.md ~/.claude/skills/memory-curate/SKILL.md
+```
+
+**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
+```
+
+**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 — 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,
+  "recentDepthTiers": [
+    { "count": 10, "depth": 2 },
+    { "count": 3,  "depth": 3 }
+  ]
+}
+```
+
+**Character limits** — two options:
+- `"maxL1Chars"` + `"maxLnChars"`: set endpoints only, intermediate levels interpolated linearly
+- `"maxCharsPerLevel"`: explicit array `[L1, L2, L3, L4, L5]`
+
+**Recency gradient** (`recentDepthTiers`): controls how deeply children are inlined for recent entries in a default `read_memory()` call.
+
+Each tier is `{ "count": N, "depth": D }` — the N most recent entries get children inlined up to depth D. The highest applicable depth wins.
+
+Default behavior:
+| Entry position | What you see |
+|---|---|
+| 0–2 (most recent) | L1 + L2 + L3 |
+| 3–9 | L1 + L2 |
+| 10+ | L1 only |
+
+Set to `[]` to disable (L1-only for all entries).
+
+---
+
+## Step 6 — Verify
+
+**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).
+
+**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) |
+| `read_memory` returns empty after writing | MCP server process is stale — restart tool |
+
+---
+
+## Quick Reference — After Setup
+
+```
+read_memory()                          # see all your Level 1 memories
+read_memory(id="L0001")               # drill into one entry
+write_memory(prefix="L", content="…") # save a lesson learned
+search_memory(query="error node.js")  # search across all memories
+```
+
+See `skills/hmem-read/SKILL.md` and `skills/hmem-write/SKILL.md` for full usage.

package/skills/hmem-write/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: hmem-write
+description: How to write long-term memories. Follow these rules whenever you call write_memory.
+---
+
+# How to use write_memory
+
+When you need to save a lesson, error, decision, or project insight to long-term memory,
+call the MCP tool `write_memory` following these rules.
+
+If the tool `write_memory` is not available:
+1. Tell the user: "write_memory tool not found. Please reconnect the MCP server (in Claude Code: `/mcp`, in other tools: restart the tool)."
+2. **NEVER write directly to the .hmem SQLite file via shell commands.** The database has WAL journaling, integrity checks, and tree-structure logic that raw SQL INSERT will bypass — causing corruption or data loss.
+
+---
+
+## Syntax
+
+```
+write_memory(
+  prefix: "E",
+  content: "L1 sentence — concise, understandable without context\n\tL2 detail (1 tab)\n\t\tL3 detail (2 tabs)\n\t\t\tL4 raw data (3 tabs — rarely needed)"
+)
+```
+
+**Indentation:** 1 tab = 1 level. Alternatively: 2 or 4 spaces per level (auto-detected).
+**IDs and timestamps** are assigned automatically — never write them yourself.
+
+---
+
+## Prefixes
+
+| Prefix | Category | When to use |
+|--------|----------|-------------|
+| **P** | Project | Project experiences, summaries |
+| **L** | Lesson | Lessons learned, best practices |
+| **E** | Error | Bugs, errors + their fix |
+| **D** | Decision | Architecture decisions with reasoning |
+| **T** | Task | Task notes, work progress |
+| **M** | Milestone | Key milestones, releases |
+| **S** | Skill | Skills, processes, how-to guides |
+| **F** | Favorite | Frequently needed reference info (always loaded with L2 detail) |
+
+---
+
+## L1 Quality Rule
+
+- **One complete, informative sentence** — ~15–20 tokens
+- Must be understandable without any context
+- Not "Fixed a bug" — instead "SQLite connection failed due to wrong path in .mcp.json"
+
+---
+
+## Company Knowledge (requires AL+ role)
+
+```
+write_memory(
+  prefix: "S",
+  store: "company",
+  min_role: "worker",
+  content: "..."
+)
+```
+
+---
+
+## When to save?
+
+**Mandatory before terminating.** Only save what is still valuable in 6 months.
+
+| Save | Don't save |
+|------|-----------|
+| New root cause + fix | Routine actions without learning value |
+| Insight that changes future work | What's already in the codebase |
+| Architecture decision + reasoning | Temporary debugging notes |
+| Unexpected tool/API behavior | What's in the documentation |
+
+One `write_memory` call per category — entire hierarchy in one `content` string.
+
+**Custom prefixes:** Additional prefixes can be added in `hmem.config.json` under the `"prefixes"` key (e.g. `"R": "Research"`).
+
+---
+
+## Anti-Patterns
+
+| Wrong | Right |
+|-------|-------|
+| L1 too short: "Fixed bug" | Full sentence with root cause |
+| Mixed spaces and tabs | Stay consistent — either tabs or spaces |
+| Everything flat, no indentation | Use hierarchy — L2/L3 for details |
+| Save trivial things | Quality over quantity |
+| Forget to write_memory | Always call BEFORE setting Status: Completed |
+| Write to .hmem via sqlite3/SQL | ONLY use `write_memory` MCP tool — never raw SQL |
+| MCP unavailable → skip saving | Reconnect MCP first (`/mcp` or restart tool) |

package/skills/memory-curate/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: memory-curate
+description: >
+  Memory curation workflow. Use when asked to curate, audit, or clean up agent memories.
+  Processes one agent at a time — read, fix, mark audited, summarize, terminate.
+  Requires role: ceo.
+---
+
+# /memory-curate — hmem Curation Workflow
+
+You are the memory curator. Process **one agent per run**, then terminate.
+
+---
+
+## Step-by-Step
+
+```
+1. get_audit_queue()
+   → Empty → write a short summary to a LAST_CURATION.md file and terminate
+   → Not empty → take the FIRST agent from the list
+
+2. read_agent_memory(agent_name, depth=3)
+   → Study all entries carefully
+
+3. Fix every issue found:
+   - L1 too long (>2 sentences)  → fix_agent_memory(agent_name, entry_id, level_1="shorter")
+   - Duplicate entry              → delete_agent_memory(agent_name, weaker_entry_id)
+   - Factually wrong              → delete_agent_memory, optionally write correct entry
+   - Vague/useless content        → delete_agent_memory
+
+4. mark_audited(agent_name)
+
+5. Append one line to LAST_CURATION.md:
+   "- **AGENTNAME**: N entries — [OK | fixed L0003 L1 | deleted E0002 (dup of E0001)]"
+
+6. Terminate.
+```
+
+---
+
+## Quality Criteria
+
+| Check | Rule |
+|-------|------|
+| L1 length | Single concise sentence, ~15–20 tokens |
+| L2 | Adds context, does not repeat L1 |
+| Duplicates | Keep the better entry, delete the weaker |
+| Prefix | P=Project L=Lesson E=Error T=Task D=Decision M=Milestone F=Favorite S=Skill (+ custom prefixes from hmem.config.json) |
+| Personal limit | 300 entries max |
+| Company limit | 200 entries max |
+
+**Over limit → triage order:**
+1. Delete duplicates and vague entries
+2. Merge similar lessons (fix keeper, delete rest)
+3. Apply access curve: delete entries that are old (>3 months) + rarely accessed (count 0–1) + generic
+
+---
+
+## Company Store
+
+After processing all personal queues:
+
+```
+read_memory(store="company")
+```
+
+→ Remove outdated company entries, update clearance levels if needed.
+
+---
+
+## Rules
+
+- Never invent or fabricate memories.
+- Skip yourself (the curator agent) if you appear in the queue.
+- One agent per run — be called again for the next agent.
+- Always write to LAST_CURATION.md, even for clean runs ("OK — nothing to fix").

package/skills/save/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: save
+description: >
+  End-of-session save routine. Use when the user types /save or asks to
+  "save", "save session", or "save progress".
+  Saves session learnings to memory via write_memory, commits git changes,
+  then compacts the conversation context.
+---
+
+# Save Session
+
+Execute these steps in order. Report results after all complete.
+
+## Step 1 — Write Memory
+
+**IMPORTANT:** You MUST use the `write_memory` MCP tool. NEVER write directly to `.hmem` files via sqlite3 or shell commands — this bypasses WAL journaling, integrity checks, and tree logic, causing corruption or data loss.
+
+If `write_memory` is not available, **STOP and tell the user** to reconnect the MCP server first (Claude Code: `/mcp` → reconnect; other tools: restart the tool). Do NOT proceed without a working MCP connection.
+
+Your L1 memory summaries are already in your context (injected at session start).
+**Check them first** — do not re-write anything that already exists.
+
+Only write what is **new since the last `/save` or session start**:
+
+| Prefix | When to use |
+|--------|-------------|
+| `P` | What was worked on this session — decisions made, outcome |
+| `L` | Lessons learned applicable beyond this session |
+| `E` | Error patterns — root cause + fix |
+| `D` | Architectural or design decisions |
+
+Quality over quantity. Skip trivial things and anything already captured.
+
+**Example calls:**
+
+```
+write_memory(prefix="P", content="Implemented auth flow with JWT
+	Chose short-lived access tokens + refresh token rotation
+	Decision: store refresh tokens in httpOnly cookie, not localStorage")
+
+write_memory(prefix="L", content="Always restart MCP server after recompiling TypeScript
+	Running process holds the old dist — tool calls return stale results otherwise")
+
+write_memory(prefix="E", content="write_memory returned HMEM_PROJECT_DIR not set
+	Cause: relative path in .mcp.json env — must be absolute
+	Fix: replace with full absolute path, restart AI tool")
+```
+
+## Step 2 — Commit & Push
+
+If in a git repository:
+
+```bash
+git add -A
+git commit -m "concise imperative summary of this session's changes"
+git push
+```
+
+Skip if there are no changes or no git repo.
+
+## Step 3 — Compact (Claude only)
+
+If you are running on **Claude** (Claude Code, claude.ai): run `/compact` to compress the conversation context. The next interaction starts fresh with your updated memories already loaded.
+
+If you are running on **Gemini CLI, OpenCode, or another tool**: skip this step — `/compact` is a Claude-specific command.