hmem-mcp 5.0.0 → 5.1.22

package/README.md

@@ -1,137 +1,151 @@
 # hmem — Humanlike Memory for AI Agents
 
-> **700 tokens to load a project. 5k for everything.** That's hmem — persistent, hierarchical memory that works across sessions, devices, and AI tools. Zero tokens wasted.
+> Your AI forgets everything between sessions. **hmem fixes that.**
 
-**hmem** is an MCP server that gives AI agents human-like long-term memory. Instead of dumping everything into context, it stores knowledge in a 5-level hierarchy — like how you remember: broad strokes first, details on demand.
-
-The result? An AI that starts a new session and *already knows* your projects, your decisions, your past mistakes, your preferences — across your laptop, your PC, and your server. Simultaneously.
+One `read_memory()` call. 5k tokens. Your agent knows every project, every past mistake, every decision you ever made together — across sessions, devices, and AI providers. No setup per conversation. No "let me re-read the codebase." It just *remembers*.
 
 ---
 
-## Why hmem?
+## The Problem
+
+Every AI session starts from zero. Your agent asks the same questions, makes the same mistakes, contradicts last week's decisions, and wastes 50k tokens loading context it already processed yesterday.
+
+You've tried workarounds — CLAUDE.md files, custom prompts, manually pasting context. They don't scale. You have 10 projects. You switch between 3 devices. You use different AI tools.
+
+## The Solution
 
-**Without hmem:** Every session starts from zero. Your AI asks the same questions, makes the same mistakes, contradicts last week's decisions, and wastes tokens loading context it already processed.
+```
+You:    "Load project hmem"
+Agent:  [calls load_project("P0048") — 700 tokens]
+Agent:  "Got it. v5.0.0, TypeScript/SQLite/npm, 10 source files,
+         3 open tasks, 9 ideas. Last session you implemented
+         auto-checkpoints via Haiku. What's next?"
+```
 
-**With hmem:**
-- **700 tokens** to load a project — `load_project("P0048")` returns the full briefing: tech stack, architecture, codebase structure, open tasks, ideas, and related errors/lessons. Ready to work immediately
-- **5k tokens** for the full picture — `read_memory()` loads a complete overview across ALL projects, decisions, errors, lessons, and rules spanning months of work
-- **Gets more efficient over time** — as your memory grows, the bulk read algorithm gets *better*, not worse. New entries push older, less relevant ones into title-only mode. 1,000 entries cost barely more tokens than 100.
-- **Original context preserved** — nothing is summarized away or compressed. Every detail you stored is still there at full fidelity, accessible on demand. Level 1 is a summary, but Levels 2-5 hold the complete original text, word for word.
-- **Drill on demand** — the AI only fetches details when it actually needs them
-- **Cross-device** — encrypted sync means your laptop, PC, and server share the same brain
-- **Cross-provider** — Claude, Gemini, GPT, DeepSeek, local models — all read and write the same memory. Switch providers without losing context. Your Gemini session picks up where Claude left off.
-- **Cross-tool** — works with Claude Code, Gemini CLI, Cursor, Windsurf, OpenCode, Cline
-- **Auto-logging** — via Claude Code's Stop hook, every conversation is automatically preserved
-- **No token waste** — hierarchical lazy loading means the AI never loads more than it needs
+That's it. 700 tokens for a complete project briefing. The agent knows the stack, the architecture, the open bugs, the recent decisions, and exactly where you left off — even if "you" was a different AI on a different machine yesterday.
 
 ---
 
 ## How It Works
 
 ```
-Level 1  ──  One-line summary          (always loaded — ~5k tokens for 300 entries)
+Level 1  ──  One-line summary          (always loaded — ~5k tokens for 300+ entries)
   Level 2  ──  Paragraph detail        (loaded on demand)
     Level 3  ──  Full context           (loaded on demand)
-      Level 4  ──  Extended detail       (loaded on demand)
-        Level 5  ──  Raw/verbatim data   (loaded on demand)
+      Level 4  ──  Extended detail      (loaded on demand)
+        Level 5  ──  Raw/verbatim data  (loaded on demand)
 ```
 
-At session start, the agent loads Level 1 summaries — one line per memory. When it needs more detail on a specific topic, it drills down: `read_memory(id="L0042")` loads that entry's Level 2 children. And so on.
+At session start, the agent loads Level 1 summaries — one line per memory. When it needs detail, it drills down. Your 300-entry memory costs 5k tokens to overview. A single project costs 700.
 
-**Categories keep things organized:**
+**Nothing is summarized away.** Level 1 is a summary, but Levels 2-5 hold the complete original text, word for word, accessible on demand.
 
-| Prefix | Category | Example |
-|--------|----------|---------|
-| P | Project | `hmem-mcp \| Active \| TS/SQLite/npm \| Persistent hierarchical AI memory` |
-| L | Lesson | `Always restart MCP server after recompiling TypeScript` |
-| E | Error | `hmem-sync Schema-Drift: access_count missing after pull` |
-| D | Decision | `Per-node tag scoring instead of union-set for related discovery` |
-| H | Human | `User Skill: IT — TypeScript: 3, Architecture: 9, AHK: 9` |
-| R | Rule | `Max one npm publish per day — batch changes` |
-| I | Infrastructure | `Strato Server \| Active \| Linux \| 4 cores, 8GB RAM` |
-| T | Task | `Config consolidation: merge 6 files into 1` |
-| O | Original | Auto-recorded raw conversation history (via Stop hook) |
+---
+
+## What Makes v5 Different
+
+### Automatic Session Memory
+
+Every conversation is recorded automatically. No "save your work" prompts. No manual checkpoints.
+
+```
+You type  →  Agent responds  →  Stop hook fires  →  Exchange saved to O-entry
+                                                  →  Linked to active project
+                                                  →  Haiku auto-titles the session
+```
+
+Switch projects mid-session? The O-entry switches too. Start a new session on a different PC? The next agent sees every exchange from every device — **the conversation never dies**.
+
+### Haiku Background Checkpoints
+
+Every 20 exchanges, a Haiku subagent wakes up in the background. It reads the recent conversation, extracts lessons learned, errors encountered, and decisions made, then writes them to long-term memory — with full MCP tool access. Your main agent is never interrupted.
+
+The checkpoint also writes a **handoff note** to the project: "Here's what was done, here's what's in progress, here's the next step." The next agent — on any device, any provider — picks up exactly where you left off.
+
+### Project-Based, Not Session-Based
+
+Sessions are meaningless. Projects are everything.
+
+- O-entries are linked to the active project, not the session
+- Checkpoint counters count project exchanges, not session messages
+- 10 messages on your laptop + 10 on your server = checkpoint fires on message 20
+- `load_project` shows recent conversations with full context — across all devices
 
 ---
 
 ## Key Features
 
-- **5-level lazy loading** — tokens scale with need, not with total memory size
-- **Smart bulk reads** — V2 algorithm expands newest, most-accessed, and favorites; suppresses the rest to titles
-- **Project-aware filtering** — activate a project, and only relevant memories are expanded; others show title-only
-- **`#universal` tag** — cross-project knowledge (MCP patterns, deployment rules) always shown regardless of active project
-- **Duplicate detection** — `write_memory` warns if similar entries exist (tag overlap + FTS5 title similarity)
-- **Encrypted sync** — AES-256-GCM client-side encryption, zero-knowledge server, multi-server redundancy
-- **Auto-logging** — Claude Code Stop hook records every conversation automatically (O-prefix)
-- **Announcements** — broadcast urgent messages to all synced devices (server migration, config changes)
-- **User skill assessment** — agents silently track your expertise per topic (1-10 scale) and adapt communication
-- **Hashtags** — cross-cutting tags for filtering and related-entry discovery
-- **Obsolete chains** — mark entries wrong with `[✓ID]` correction reference; auto-follows to current version
-- **Import/Export** — share memories between agents or back up as Markdown
-- **Multi-agent routing** — `route_task` scores all agent memory stores to find the best agent for a task
-
-### New in v4
-
-- **`load_project` tool** — one call to activate a project and get a complete briefing (~500 tokens). The recommended way to start working on a project
-- **P-Entry Standard Schema** — validated project structure with 10 L2 categories. The MCP server enforces consistency across all agents
-- **Context Injection `[⚡]`** — activate a task, and related errors + lessons appear automatically in bulk reads. No manual searching for past mistakes
-- **Multi-server sync** — push to multiple servers for redundancy. `"sync": [{ ... }, { ... }]` in config
+| Feature | What it does |
+|---------|-------------|
+| **5-level lazy loading** | Tokens scale with need, not memory size |
+| **Smart bulk reads** | Expands newest + most-accessed; compresses the rest to titles |
+| **Project gate** | Activate a project — only relevant memories are expanded |
+| **Duplicate detection** | Warns before creating entries that already exist |
+| **Encrypted sync** | AES-256-GCM, zero-knowledge server, multi-server redundancy |
+| **Auto-logging** | Every exchange recorded via Stop hook (O-prefix) |
+| **Auto-checkpoint** | Haiku extracts L/D/E entries every N exchanges |
+| **Project handoff** | Background agent maintains "current state" in Protocol section |
+| **User skill tracking** | Agents track your expertise (1-10) and adapt communication |
+| **Hashtags** | Cross-cutting tags for discovery across all categories |
+| **Obsolete chains** | Mark entries wrong with correction reference — auto-follows |
+| **Cross-provider** | Claude, Gemini, GPT, DeepSeek, local models — same memory |
+| **Cross-tool** | Claude Code, Gemini CLI, Cursor, Windsurf, OpenCode, Cline |
+| **Import/Export** | Share memories between agents or back up as Markdown |
+
+### Categories
+
+| Prefix | Category | Example |
+|--------|----------|---------|
+| **P** | Project | `hmem-mcp \| Active \| TS/SQLite/npm \| Persistent AI memory` |
+| **L** | Lesson | `HMEM_AGENT_ID must be set in hooks — resolveHmemPath falls back to wrong DB` |
+| **E** | Error | `158 spurious O-entries created when Haiku MCP lacked HMEM_NO_SESSION guard` |
+| **D** | Decision | `Project-based O-entries over session-based — sessions are meaningless` |
+| **H** | Human | `User Skill: TypeScript 9, Architecture 9, React 3` |
+| **R** | Rule | `Max one npm publish per day — batch changes` |
+| **O** | Original | Auto-recorded conversation history (every exchange, every device) |
+| **I** | Infra | `Strato Server \| Active \| Linux \| 87.106.22.11` |
 
 ---
 
-## Installation
+## Quick Start
 
-### Step 1: Install the package
+### 1. Install
 
 ```bash
 npm install -g hmem-mcp
 ```
 
-Skills are **automatically copied** to detected AI tools (Claude Code, OpenCode, Gemini CLI) via postinstall hook.
+### 2. Run the interactive installer
 
-### Step 2: Configure your MCP client
+```bash
+npx hmem init
+```
 
-**IMPORTANT:** Do NOT use `claude mcp add` — it misplaces environment variables. Configure manually:
+This detects your AI tools, creates the memory directory, configures MCP, and installs all 4 hooks:
 
-#### Claude Code
+| Hook | When | What |
+|------|------|------|
+| `UserPromptSubmit` | Every message | First message: load memory. Every Nth: checkpoint reminder |
+| `Stop` (sync) | Every response | Log exchange to active O-entry |
+| `Stop` (async) | Every response | Haiku auto-titles untitled sessions |
+| `SessionStart[clear]` | After /clear | Re-inject project context |
 
-Edit `~/.claude/.mcp.json` (create if it doesn't exist):
+### 3. Verify
 
-```json
-{
-  "mcpServers": {
-    "hmem": {
-      "command": "node",
-      "args": ["/path/to/hmem-mcp/dist/mcp-server.js"],
-      "env": {
-        "HMEM_PROJECT_DIR": "/home/yourname/.hmem"
-      }
-    }
-  }
-}
-```
+Restart your AI tool, then:
 
-**Find the path** to `mcp-server.js`:
-```bash
-echo "$(npm root -g)/hmem-mcp/dist/mcp-server.js"
 ```
-
-**nvm users:** Use the absolute path to `node` instead of just `"node"`:
-```bash
-echo "$(which node)"
-# e.g. /home/yourname/.nvm/versions/node/v24.14.0/bin/node
+read_memory()
 ```
 
-Then use that as the `"command"` value.
+Empty response = working (first run). Error = check the [troubleshooting section](#troubleshooting).
 
-#### With agent ID (multi-agent setups)
+### Manual setup
 
-If you use `HMEM_AGENT_ID`, the database path changes:
+If you prefer manual configuration over `hmem init`:
 
-```
-Without HMEM_AGENT_ID:  {HMEM_PROJECT_DIR}/memory.hmem
-With HMEM_AGENT_ID=X:   {HMEM_PROJECT_DIR}/Agents/X/X.hmem
-```
+<details>
+<summary>Claude Code — edit ~/.claude/.mcp.json</summary>
 
 ```json
 {
@@ -148,9 +162,15 @@ With HMEM_AGENT_ID=X:   {HMEM_PROJECT_DIR}/Agents/X/X.hmem
 }
 ```
 
-#### OpenCode
+Find the paths:
+```bash
+echo "Node: $(which node)"
+echo "Server: $(npm root -g)/hmem-mcp/dist/mcp-server.js"
+```
+</details>
 
-Edit `~/.config/opencode/opencode.json`:
+<details>
+<summary>OpenCode — edit ~/.config/opencode/opencode.json</summary>
 
 ```json
 {
@@ -158,18 +178,18 @@ Edit `~/.config/opencode/opencode.json`:
     "hmem": {
       "type": "local",
       "command": ["/absolute/path/to/node", "/absolute/path/to/hmem-mcp/dist/mcp-server.js"],
-      "environment": {
-        "HMEM_PROJECT_DIR": "/home/yourname/.hmem"
-      },
+      "environment": { "HMEM_PROJECT_DIR": "/home/yourname/.hmem" },
       "enabled": true
     }
   }
 }
 ```
+</details>
 
-#### Cursor / Windsurf / Cline
+<details>
+<summary>Cursor / Windsurf / Cline</summary>
 
-Edit the respective MCP config file (`~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, or `.vscode/mcp.json`):
+Edit `~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, or `.vscode/mcp.json`:
 
 ```json
 {
@@ -177,174 +197,101 @@ Edit the respective MCP config file (`~/.cursor/mcp.json`, `~/.codeium/windsurf/
     "hmem": {
       "command": "/absolute/path/to/node",
       "args": ["/absolute/path/to/hmem-mcp/dist/mcp-server.js"],
-      "env": {
-        "HMEM_PROJECT_DIR": "/home/yourname/.hmem"
-      }
+      "env": { "HMEM_PROJECT_DIR": "/home/yourname/.hmem" }
     }
   }
 }
 ```
+</details>
 
-### Step 3: Create the memory directory
-
-```bash
-mkdir -p ~/.hmem
-# Or with agent ID:
-mkdir -p ~/.hmem/Agents/DEVELOPER
-```
+---
 
-### Step 4: Restart and verify
+## Configuration
 
-Restart your AI tool completely, then:
+`hmem.config.json` in your `HMEM_PROJECT_DIR` (or `Agents/NAME/`):
 
-```
-read_memory()
+```json
+{
+  "memory": {
+    "maxCharsPerLevel": [200, 2500, 10000, 25000, 50000],
+    "maxDepth": 5,
+    "checkpointMode": "auto",
+    "checkpointInterval": 20,
+    "recentOEntries": 10,
+    "maxTitleChars": 50,
+    "prefixes": { "X": "Custom" }
+  },
+  "sync": {
+    "serverUrl": "https://your-server/hmem-sync",
+    "userId": "yourname",
+    "salt": "...",
+    "token": "..."
+  }
+}
 ```
 
-You should see a response. If empty, that's fine — first run. If you get an error, check:
-- Is `HMEM_PROJECT_DIR` an absolute path?
-- Does the directory exist?
-- Is `node` path correct? (nvm users: use absolute path)
+| Key | Default | What it does |
+|-----|---------|-------------|
+| `checkpointMode` | `"remind"` | `"auto"` = Haiku writes L/D/E in background. `"remind"` = asks the main agent |
+| `checkpointInterval` | `20` | Exchanges between checkpoints. Set `0` to disable |
+| `recentOEntries` | `10` | How many recent sessions to show in `load_project` |
 
-The server logs its configuration on startup:
-```
-[hmem:DEVELOPER] MCP Server running on stdio | Agent: DEVELOPER | DB: /home/you/.hmem/Agents/DEVELOPER/DEVELOPER.hmem (0 entries)
-```
+All keys are optional. Missing keys use defaults.
 
 ---
 
-## Cross-Device Sync (hmem-sync)
+## Cross-Device Sync
 
-Sync your memories across all devices with zero-knowledge encryption.
+Sync memories across all devices with zero-knowledge encryption.
 
 ```bash
 npm install -g hmem-sync
+npx hmem-sync connect     # Interactive wizard — first device creates, others join
 ```
 
-### First device
-
-```bash
-npx hmem-sync connect
-```
-
-Interactive wizard: creates account, generates encryption keys, pushes your data.
-
-### Additional devices
-
-```bash
-npx hmem-sync connect
-```
-
-Same wizard — choose "existing account", enter your credentials from the first device.
-
-### Enable auto-sync
-
-Add `HMEM_SYNC_PASSPHRASE` to your MCP config:
-
-```json
-{
-  "env": {
-    "HMEM_PROJECT_DIR": "/home/you/.hmem",
-    "HMEM_AGENT_ID": "DEVELOPER",
-    "HMEM_SYNC_PASSPHRASE": "your-passphrase"
-  }
-}
-```
-
-With this set, every `read_memory` automatically pulls and every `write_memory` automatically pushes. 30-second cooldown prevents spam.
+Add `HMEM_SYNC_PASSPHRASE` to your MCP config for automatic sync on every read/write.
 
 ### Multi-server redundancy
 
-In `hmem.config.json`, configure multiple servers:
-
 ```json
 {
   "sync": [
     { "name": "primary", "serverUrl": "https://server1/hmem-sync", "userId": "me", "salt": "...", "token": "..." },
-    { "name": "backup", "serverUrl": "https://server2/hmem-sync", "userId": "me", "salt": "...", "token": "..." }
+    { "name": "backup",  "serverUrl": "https://server2/hmem-sync", "userId": "me", "salt": "...", "token": "..." }
   ]
 }
 ```
 
-Push/pull goes to all servers. Use during migration or for redundant backup.
-
 ### Announcements
 
-Broadcast urgent messages to all synced AI agents across all devices:
+Broadcast to all synced agents across all devices:
 
 ```bash
 npx hmem-sync announce --message "Server URL changing — update your config!"
 ```
 
-Every agent on every device sees the announcement on its next sync pull. Use for config changes, server migrations, or coordination across your fleet of AI instances.
-
----
-
-## Auto-Logging (O-prefix)
-
-With Claude Code's Stop hook, every conversation exchange (your message + agent response) is automatically recorded in O-prefix entries. Zero token cost — runs in the background.
-
-### Setup the hook
-
-Add to `~/.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "HMEM_PROJECT_DIR=/home/you/.hmem HMEM_AGENT_ID=DEVELOPER node /path/to/hmem-mcp/dist/cli.js log-exchange",
-            "timeout": 10
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-O-entries are hidden from bulk reads (no noise) but searchable and linked to your active project.
-
 ---
 
-## Configuration
-
-`hmem.config.json` in your `HMEM_PROJECT_DIR`:
-
-```json
-{
-  "memory": {
-    "maxCharsPerLevel": [200, 2500, 10000, 25000, 50000],
-    "maxDepth": 5,
-    "maxTitleChars": 50,
-    "prefixes": { "X": "Custom" }
-  },
-  "sync": {
-    "serverUrl": "https://your-server/hmem-sync",
-    "userId": "yourname",
-    "salt": "...",
-    "token": "..."
-  }
-}
-```
+## Troubleshooting
 
-All keys are optional. Missing keys use defaults.
+| Problem | Fix |
+|---------|-----|
+| `read_memory()` fails | Check `HMEM_PROJECT_DIR` is absolute path and directory exists |
+| nvm: `node not found` | Use absolute path: `which node` → use as `"command"` |
+| Hooks not firing | Restart Claude Code. Check `~/.claude/settings.json` has all 4 hooks |
+| Exchanges not logged | Check `HMEM_AGENT_ID` matches your `Agents/` directory name |
+| Sync fails | Run `npx hmem-sync connect` to re-authenticate |
 
 ---
 
 ## Updating
 
 ```bash
-# Always global — NOT inside a project directory
-npm update -g hmem-mcp
-npm update -g hmem-sync
+npm update -g hmem-mcp       # MCP server
+npm update -g hmem-sync       # Sync (if installed)
+npx hmem update-skills        # Refresh skill files
 ```
 
-Skills are automatically updated via postinstall hook. No manual copy needed.
-
 ---
 
 ## License