npm - hmem-mcp - Versions diffs - 3.9.0 → 4.0.0 - Mend

hmem-mcp 3.9.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +198 -415
package/dist/cli.js +0 -0
package/dist/hmem-store.js +18 -1
package/dist/hmem-store.js.map +1 -1
package/dist/mcp-server.js +115 -7
package/dist/mcp-server.js.map +1 -1
package/package.json +1 -1
package/skills/hmem-write/SKILL.md +40 -8

package/README.md CHANGED Viewed

@@ -1,204 +1,156 @@
 # hmem — Humanlike Memory for AI Agents
-> AI agents forget everything when a session ends. hmem changes that.
+> **Your AI loads 5k tokens and has full context of 400k+.** That's hmem — persistent, hierarchical memory that works across sessions, devices, and AI tools. Zero tokens wasted.
-> hmem is actively used in production. APIs are stable since v2.0. Feedback and bug reports welcome.
+**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.
-**hmem** is a Model Context Protocol (MCP) server that gives AI agents persistent, humanlike memory — modeled after how human memory actually works.
-Born as a side project of a multi-agent AI system, hmem solves a real problem: when you work across multiple machines or sessions, your AI instances start from zero every time. They duplicate work, contradict previous decisions, and lose hard-won context.
-**hmem fixes this.**
+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.
 ---
+## Why hmem?
-## Examples
-<img width="1110" height="665" alt="image" src="https://github.com/user-attachments/assets/af7688d2-73e3-44f8-b414-f6afa8904e6c" />
-Well, it claims that it can't pinpoint timestamps. But that's not true. It just cant see them (due to token efficiency) :)
-<img width="1096" height="941" alt="image" src="https://github.com/user-attachments/assets/a751c8f3-41fc-46b6-916a-bcd3862008ad" />
+**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.
----
-## The Problem
-When working across multiple PCs with AI coding agents, every new session was a fresh start. Agents had no knowledge of previous decisions, duplicated work, produced inconsistencies, and wasted tokens catching up.
-Existing RAG solutions are flat — every memory fragment has the same abstraction level. The agent either gets too much detail and wastes tokens, or too little and loses nuance.
----
-## The Solution: 5-Level Humanlike Memory
-hmem stores and retrieves memory in five nested levels of detail — mirroring how human memory works.
-```
-Level 1  ──  Coarse summary         (always loaded on spawn)
-  Level 2  ──  More detail
-    Level 3  ──  Deep context
-      Level 4  ──  Fine-grained specifics
-        Level 5  ──  Full verbatim detail
-```
-A freshly spawned agent receives only Level 1 — the broadest strokes. When it needs more detail on a specific topic, it makes a tool call to retrieve Level 2 for that entry. And so on, down to full detail.
-**Result: Agents load exactly as much context as they need — no more, no less.**
+**With hmem:**
+- **5k tokens** loads a complete overview of 300+ memories 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-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
 ---
 ## How It Works
-<img width="693" height="715" alt="image" src="https://github.com/user-attachments/assets/9dcb382a-6567-4040-99d2-61916a6d7531" />
-### Saving Memory
-After completing a task, an agent calls `write_memory` with tab-indented content. The indentation depth maps to memory levels — multiple entries at the same depth become siblings.
-```
-write_memory(prefix="L", content="Always restart MCP server after recompiling TypeScript
-	Running process holds old dist — tool calls return stale results
-	Fix: kill $(pgrep -f mcp-server)")
-```
-### Loading Memory
-On spawn, the agent receives all Level 1 summaries. Deeper levels are fetched on demand — by ID, one branch at a time.
-```
-read_memory()              # → all L1 summaries
-read_memory(id="L0003")    # → L1 + direct L2 children for this entry
-read_memory(id="L0003.2")  # → that L2 node + its L3 children
-```
-Each node gets a compound ID (`L0003.2.1`) so any branch is individually addressable.
-### Updating Memory
-Entries can be updated without deleting and recreating them:
-```
-update_memory(id="L0003", content="Corrected L1 summary")   # update text
-update_memory(id="L0003", favorite=true)                     # toggle flag only
-update_memory(id="L0003.2", content="Fixed sub-node text")   # fix a sub-node
-append_memory(id="L0003", content="New finding\n\tSub-detail")
-```
-`update_memory` replaces the text of a single node (children preserved). Content is optional — pass only flags to toggle them without repeating the text. `append_memory` adds new child nodes to an existing entry.
-### Obsolete Entries
-When an entry is outdated, mark it as obsolete — never delete it:
-```
-update_memory(id="E0023", content="...", obsolete=true)
-```
-Obsolete entries are **hidden from bulk reads** and replaced by a summary line at the bottom:
 ```
---- 3 obsolete entries hidden (E0023, D0007, L0012) — use read_memory(id=X) to view ---
+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)
 ```
-They remain fully searchable and accessible by ID. Past errors still teach future agents what not to do — knowledge is never destroyed, only archived.
+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.
-### Memory Curation
+**Categories keep things organized:**
-A dedicated curator agent runs periodically to maintain memory health. It detects duplicates, merges fragmented entries, marks stale pointers, and prunes low-value content — a form of the Ebbinghaus Forgetting Curve.
+| 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) |
 ---
 ## Key Features
-- **Hierarchical retrieval** — lazy loading of detail levels saves tokens
-- **True tree structure** — multiple siblings at the same depth (not just one chain)
-- **Compact output** — child IDs render as `.7` instead of `P0029.7`; dates shown only when differing from parent
-- **Persistent across sessions** — agents remember previous work even after restart
-- **Editable without deletion** — `update_memory` and `append_memory` modify entries in place; content is optional when toggling flags
-- **Markers** — `[♥]` favorite, `[P]` pinned, `[!]` obsolete, `[-]` irrelevant, `[*]` active, `[s]` secret — on root entries and sub-nodes
-- **Pinned entries** — super-favorites that show all children titles in bulk reads (not just the latest); use for reference entries you need in full every session
-- **Hashtags** — cross-cutting tags (`#hmem`, `#security`) for filtering and discovering related entries across prefixes
-- **Import/Export** — `export_memory` as Markdown or `.hmem` SQLite clone (excluding secrets); `import_memory` with L1 deduplication, sub-node merge, and automatic ID remapping on conflict
-- **Obsolete chain resolution** — mark entries/sub-nodes obsolete with `[✓ID]` reference; `read_memory` auto-follows the chain to the current version
-- **Access-count promotion** — most-accessed entries get expanded automatically (`[★]`); most-referenced sub-nodes shown as "Hot Nodes"
-- **Session cache** — bulk reads suppress already-seen entries with Fibonacci decay; two modes: `discover` (newest-heavy) and `essentials` (importance-heavy)
-- **Active-prefix filtering** — mark entries as `[*]` active to focus bulk reads on what matters now; non-active entries still show as compact titles
-- **Secret entries** — `[s]` entries/nodes excluded from `export_memory`
-- **Titles & compact views** — auto-extracted titles; `titles_only` mode for table-of-contents view
-- **Effective-date sorting** — entries with recent appends surface to the top
-- **Per-agent memory** — each agent has its own `.hmem` file (SQLite)
-- **Skill-file driven** — agents are instructed via skill files, no hardcoded logic
-- **MCP-native** — works with Claude Code, Gemini CLI, OpenCode, and any MCP-compatible tool
+- **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
 ---
-## Quick Start
+## Installation
-### Option A: Install from npm (Recommended)
+### Step 1: Install the package
 ```bash
-npx hmem-mcp init
+npm install -g hmem-mcp
 ```
-That's it. The interactive installer will:
-- Detect your installed AI coding tools (Claude Code, OpenCode, Cursor, Windsurf, Cline)
-- Ask whether to install **system-wide** (memories in `~/.hmem/`) or **project-local** (memories in current directory)
-- **Offer an example memory** with 67 real entries from hmem development — or start fresh
-- Configure each tool's MCP settings automatically
-- Create the memory directory and `hmem.config.json`
+Skills are **automatically copied** to detected AI tools (Claude Code, OpenCode, Gemini CLI) via postinstall hook.
-After the installer finishes, restart your AI tool and call `read_memory()` to verify.
+### Step 2: Configure your MCP client
-> **Example memory:** The installer includes `hmem_developer.hmem` — a real `.hmem` database with 67 entries and 287 nodes from actual hmem development. It contains lessons learned, architecture decisions, error fixes, and project milestones — a great way to see how hmem works in practice before writing your own entries. You can explore it immediately with `read_memory()` after install, or browse it in the TUI viewer with `python3 hmem-reader.py path/to/memory.hmem`.
+**IMPORTANT:** Do NOT use `claude mcp add` — it misplaces environment variables. Configure manually:
-> **Don't forget the skill files!** The MCP server provides the tools (read_memory, write_memory, etc.), but the slash commands (`/hmem-save`, `/hmem-read`) require skill files to be copied to your tool's skills directory. See the [Skill Files](#skill-files) section below — it's a one-time copy-paste.
->
-> **Coming from the MCP Registry?** Run `npx hmem-mcp init` first — it configures your tools and creates the memory directory. Then copy the skill files as described below.
+#### Claude Code
-### Option B: Install from source
+Edit `~/.claude/.mcp.json` (create if it doesn't exist):
-```bash
-git clone https://github.com/Bumblebiber/hmem.git
-cd hmem
-npm install && npm run build
-node dist/cli.js init
+```json
+{
+  "mcpServers": {
+    "hmem": {
+      "command": "node",
+      "args": ["/path/to/hmem-mcp/dist/mcp-server.js"],
+      "env": {
+        "HMEM_PROJECT_DIR": "/home/yourname/.hmem"
+      }
+    }
+  }
+}
 ```
-### Option C: Manual Setup (no installer)
-If you prefer to configure everything yourself:
-#### 1. Install
+**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
-npm install -g hmem-mcp
+echo "$(which node)"
+# e.g. /home/yourname/.nvm/versions/node/v24.14.0/bin/node
 ```
-Or from source: `git clone https://github.com/Bumblebiber/hmem.git && cd hmem && npm install && npm run build`
+Then use that as the `"command"` value.
-#### 2. Register the MCP server
+#### With agent ID (multi-agent setups)
-**Claude Code** — global registration:
+If you use `HMEM_AGENT_ID`, the database path changes:
-```bash
-claude mcp add hmem -s user -- npx hmem-mcp serve \
-  --env HMEM_PROJECT_DIR="$HOME/.hmem"
+```
+Without HMEM_AGENT_ID:  {HMEM_PROJECT_DIR}/memory.hmem
+With HMEM_AGENT_ID=X:   {HMEM_PROJECT_DIR}/Agents/X/X.hmem
 ```
-**OpenCode** — add to `~/.config/opencode/opencode.json` (or project-level `opencode.json`):
+```json
+{
+  "mcpServers": {
+    "hmem": {
+      "command": "/absolute/path/to/node",
+      "args": ["/absolute/path/to/hmem-mcp/dist/mcp-server.js"],
+      "env": {
+        "HMEM_PROJECT_DIR": "/home/yourname/.hmem",
+        "HMEM_AGENT_ID": "DEVELOPER"
+      }
+    }
+  }
+}
+```
+#### OpenCode
+Edit `~/.config/opencode/opencode.json`:
 ```json
 {
   "mcp": {
     "hmem": {
       "type": "local",
-      "command": ["npx", "hmem", "serve"],
+      "command": ["/absolute/path/to/node", "/absolute/path/to/hmem-mcp/dist/mcp-server.js"],
       "environment": {
-        "HMEM_PROJECT_DIR": "~/.hmem"
+        "HMEM_PROJECT_DIR": "/home/yourname/.hmem"
       },
       "enabled": true
     }
@@ -206,352 +158,183 @@ claude mcp add hmem -s user -- npx hmem-mcp serve \
 }
 ```
-**Cursor / Windsurf / Cline** — add to `~/.cursor/mcp.json` (or equivalent):
+#### Cursor / Windsurf / Cline
+Edit the respective MCP config file (`~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, or `.vscode/mcp.json`):
 ```json
 {
   "mcpServers": {
     "hmem": {
-      "command": "npx",
-      "args": ["hmem", "serve"],
+      "command": "/absolute/path/to/node",
+      "args": ["/absolute/path/to/hmem-mcp/dist/mcp-server.js"],
       "env": {
-        "HMEM_PROJECT_DIR": "~/.hmem"
+        "HMEM_PROJECT_DIR": "/home/yourname/.hmem"
       }
     }
   }
 }
 ```
-> **Windows note:** Use forward slashes or double backslashes in JSON paths.
-#### 3. Verify the connection
-Fully restart your AI tool, then call `read_memory()`. You should see a memory listing (empty on first run is fine).
-In Claude Code, run `/mcp` to check the server status.
----
-## Skill Files
-Skill files teach your AI tool how to use hmem correctly. Copy them to your tool's global skills directory, then restart your AI tool.
-> **After copying skills, fully restart your terminal and AI tool** — skills are loaded at startup and won't appear in a running session.
-### Available skills
-| Slash command | What it does |
-|---|---|
-| `/hmem-read` | Load your memory at session start — call at the beginning of every session |
-| `/hmem-write` | Protocol for writing memories correctly (prefixes, hierarchy, anti-patterns) |
-| `/hmem-save` | Save session learnings to memory, then commit + push |
-| `/hmem-config` | View and adjust memory settings (`hmem.config.json`) interactively |
-| `/hmem-curate` | Audit and clean up memory entries (curator role required) |
-### Copy skills to your tool
-Find the skills directory in the installed package:
+### Step 3: Create the memory directory
 ```bash
-HMEM_DIR="$(npm root -g)/hmem-mcp"
+mkdir -p ~/.hmem
+# Or with agent ID:
+mkdir -p ~/.hmem/Agents/DEVELOPER
 ```
-If you cloned from source, the skills are in the `skills/` directory.
+### Step 4: Restart and verify
-**Claude Code:**
-```bash
-for skill in hmem-read hmem-write hmem-save hmem-config hmem-curate; do
-  mkdir -p ~/.claude/skills/$skill
-  cp "$HMEM_DIR/skills/$skill/SKILL.md" ~/.claude/skills/$skill/SKILL.md
-done
-```
+Restart your AI tool completely, then:
-**Gemini CLI:**
-```bash
-for skill in hmem-read hmem-write hmem-save hmem-config hmem-curate; do
-  mkdir -p ~/.gemini/skills/$skill
-  cp "$HMEM_DIR/skills/$skill/SKILL.md" ~/.gemini/skills/$skill/SKILL.md
-done
 ```
-**OpenCode:**
-```bash
-for skill in hmem-read hmem-write hmem-save hmem-config hmem-curate; do
-  mkdir -p ~/.config/opencode/skills/$skill
-  cp "$HMEM_DIR/skills/$skill/SKILL.md" ~/.config/opencode/skills/$skill/SKILL.md
-done
+read_memory()
 ```
----
-## MCP Tools
-### Memory Tools
-| Tool | Description |
-|------|-------------|
-| `read_memory` | Read memories — L1 summaries, drill by ID, filter by prefix, search by time |
-| `write_memory` | Save new memory entries with tab-indented hierarchy |
-| `update_memory` | Update text and/or flags of an entry or sub-node (content optional) |
-| `append_memory` | Append new child nodes to an existing entry or sub-node |
-| `export_memory` | Export non-secret entries as Markdown text or `.hmem` SQLite file |
-| `import_memory` | Import entries from a `.hmem` file with deduplication and ID remapping |
-| `reset_memory_cache` | Clear session cache so all entries are treated as unseen |
-| `search_memory` | Full-text search across all agent `.hmem` databases |
-| `memory_stats` | Overview: total entries by prefix, nodes, favorites, pinned, stale count, most-accessed |
-| `find_related` | FTS5-based similarity search — find entries with overlapping keywords |
-| `memory_health` | Audit report: broken links, orphaned entries, stale favorites, broken obsolete chains |
-| `tag_bulk` | Apply tag changes (add/remove) to all entries matching a filter |
-| `tag_rename` | Rename a hashtag across all entries and nodes |
-| `move_memory` | Move a sub-node (+ entire subtree) to a different parent — updates all IDs and references |
-### Curator Tools (role: ceo)
-| Tool | Description |
-|------|-------------|
-| `get_audit_queue` | List agents whose memory has changed since last audit |
-| `read_agent_memory` | Read any agent's full memory (for curation) |
-| `fix_agent_memory` | Correct a specific entry or sub-node in any agent's memory |
-| `append_agent_memory` | Add content to an existing entry in any agent's memory (for merging duplicates) |
-| `delete_agent_memory` | Delete a memory entry (prefer `fix_agent_memory(obsolete=true)` — deletion is permanent) |
-| `move_agent_memory` | Move a sub-node in any agent's memory to a different parent — updates all IDs and references |
-| `mark_audited` | Mark an agent as audited |
----
-## Memory Directory
-hmem stores all memory files (`.hmem` SQLite databases) and its configuration (`hmem.config.json`) in a single directory. The location depends on how you install:
-| Install mode | Memory directory | Example |
-|---|---|---|
-| **System-wide** | `~/.hmem/` | `/home/alice/.hmem/` or `C:\Users\Alice\.hmem\` |
-| **Project-local** | Project root (cwd) | `/home/alice/my-project/` |
-The `hmem init` installer asks which mode you prefer and creates the directory automatically.
-### Directory structure
+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)
+The server logs its configuration on startup:
 ```
-~/.hmem/                     # System-wide memory directory
-  memory.hmem                # Default agent memory (when no HMEM_AGENT_ID is set)
-  SIGURD.hmem                # Named agent memory (HMEM_AGENT_ID=SIGURD)
-  hmem.config.json           # Configuration file
-  audit_state.json           # Curator state (optional)
+[hmem:DEVELOPER] MCP Server running on stdio | Agent: DEVELOPER | DB: /home/you/.hmem/Agents/DEVELOPER/DEVELOPER.hmem (0 entries)
 ```
-The MCP configuration files are written to each tool's own config directory — not into `~/.hmem/`:
-| Tool | Global MCP config path |
-|---|---|
-| Claude Code | `~/.claude/.mcp.json` |
-| OpenCode | `~/.config/opencode/opencode.json` |
-| Cursor | `~/.cursor/mcp.json` |
-| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
-| Cline / Roo Code | `.vscode/mcp.json` (project-only) |
 ---
-## Environment Variables
+## Cross-Device Sync (hmem-sync)
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `HMEM_PROJECT_DIR` | Root directory where `.hmem` files are stored | *(required)* |
-| `HMEM_AGENT_ID` | Agent identifier — used as filename and directory name | `""` → `memory.hmem` |
-| `HMEM_AGENT_ROLE` | Permission level: `worker` · `al` · `pl` · `ceo` | `worker` |
+Sync your memories across all devices with zero-knowledge encryption.
----
-## Configuration (hmem.config.json)
-Place an optional `hmem.config.json` in your `HMEM_PROJECT_DIR` to tune behavior. All keys are optional — missing keys fall back to defaults.
-```json
-{
-  "maxL1Chars": 120,
-  "maxLnChars": 50000,
-  "maxDepth": 5,
-  "maxTitleChars": 50,
-  "accessCountTopN": 5,
-  "bulkReadV2": {
-    "topNewestCount": 5,
-    "topAccessCount": 3,
-    "topObsoleteCount": 3
-  },
-  "prefixes": {
-    "R": "Research"
-  }
-}
+```bash
+npm install -g hmem-sync
 ```
-### Memory prefixes
+### First device
-The default prefixes cover most use cases:
-| 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 |
-| `N` | Navigator | Code pointers — where something lives in the codebase |
-To add your own, add entries to the `"prefixes"` key in `hmem.config.json`. Custom prefixes are **merged** with the defaults — you don't need to repeat the built-in ones.
-### Favorites
-Any entry can be marked as a **favorite** — regardless of its prefix category. Favorites always appear with their L2 detail in bulk reads, marked with `[♥]`.
-```
-write_memory(prefix="D", content="...", favorite=true)   # set at creation
-update_memory(id="D0010", favorite=true)                 # set on existing entry
-update_memory(id="D0010", favorite=false)                # clear the flag
+```bash
+npx hmem-sync connect
 ```
-Use favorites for reference info you need to see every session — key decisions, API endpoints, frequently consulted patterns. Use sparingly: if everything is a favorite, nothing is.
-### Pinned entries
+Interactive wizard: creates account, generates encryption keys, pushes your data.
-Pinned entries are "super-favorites" — they show **all** children titles in bulk reads, not just the latest one. While favorites show the newest child + `[+N more →]`, pinned entries give you the full table of contents at a glance.
+### Additional devices
-```
-write_memory(prefix="S", content="...", pinned=true)   # set at creation
-update_memory(id="S0005", pinned=true)                 # set on existing entry
+```bash
+npx hmem-sync connect
 ```
-| Display | Normal | Favorite `[♥]` | Pinned `[P]` | `expand=true` |
-|---|---|---|---|---|
-| Children shown | Latest only | All titles | All titles | All with full content |
-| `[+N more →]` hint | Yes | No | No | No |
+Same wizard — choose "existing account", enter your credentials from the first device.
-Use pinned for entries with many structured sub-entries (handbooks, reference lists, project summaries) where you always want to see the full outline.
+### Enable auto-sync
-### Hashtags
+Add `HMEM_SYNC_PASSPHRASE` to your MCP config:
-Tag entries for cross-cutting search across prefix categories:
-```
-write_memory(prefix="L", content="...", tags=["#security", "#hmem"])
-read_memory(tag="#security")      # filter bulk reads by tag
-read_memory(id="L0042")          # shows related entries (2+ shared tags)
-tag_bulk(filter={prefix: "E"}, add_tags=["#bugfix"])    # batch-tag all E-entries
-tag_rename(old_tag="#old", new_tag="#new")               # rename everywhere
+```json
+{
+  "env": {
+    "HMEM_PROJECT_DIR": "/home/you/.hmem",
+    "HMEM_AGENT_ID": "DEVELOPER",
+    "HMEM_SYNC_PASSPHRASE": "your-passphrase"
+  }
+}
 ```
-Tags are lowercase, must start with `#`, max 10 per entry. They work on root entries and sub-nodes.
-### Stale Detection and Memory Health
-```
-read_memory(stale_days=30)        # entries not accessed in 30 days, sorted oldest-first
-memory_stats()                    # count by prefix, stale count, favorites, most-accessed
-memory_health()                   # audit: broken links, orphans, stale favorites
-find_related(id="P0029")         # FTS5 keyword similarity — find thematically related entries
-```
+With this set, every `read_memory` automatically pulls and every `write_memory` automatically pushes. 30-second cooldown prevents spam.
-### Access-count auto-promotion (`accessCountTopN`)
+### Multi-server redundancy
-The top-N most-accessed entries are automatically promoted to L2 depth in bulk reads, marked with `[★]`. This creates "organic favorites" — entries that proved important in practice rise to the surface automatically.
+In `hmem.config.json`, configure multiple servers:
 ```json
-{ "accessCountTopN": 5 }
-```
-Set to `0` to disable. Default: `5`.
-**Time-weighted scoring:** Raw access counts would systematically favor older entries (more time to accumulate accesses). hmem uses a logarithmic age decay instead:
-```
-score = access_count / log2(age_in_days + 2)
+{
+  "sync": [
+    { "name": "primary", "serverUrl": "https://server1/hmem-sync", "userId": "me", "salt": "...", "token": "..." },
+    { "name": "backup", "serverUrl": "https://server2/hmem-sync", "userId": "me", "salt": "...", "token": "..." }
+  ]
+}
 ```
-This means a 1-day-old entry with 5 accesses (score 3.16) outranks a 1-year-old entry with 6 accesses (score 0.70) — but a genuinely important old entry with 50 accesses (score 5.87) still stays at the top. The decay is gentle enough that consistently useful entries are never buried.
-| Mechanism | When useful |
-|---|---|
-| **favorite flag** | Entries you know are important from day 1 — even with zero access history |
-| **accessCountTopN** | Entries that proved important over time — emerges from actual usage |
+Push/pull goes to all servers. Use during migration or for redundant backup.
-### Bulk reads (V2 algorithm)
+### Announcements
-`read_memory()` groups entries by prefix category. Each category expands a limited number of entries (newest + most-accessed + favorites) with their L2 children; the rest show only the L1 title. Two modes:
+Broadcast urgent messages to all synced AI agents across all devices:
-- **`discover`** (default on first read): newest-heavy — good for getting an overview after session start.
-- **`essentials`** (auto-selected after context compression): importance-heavy — more favorites + most-accessed, fewer newest.
-A **session cache** tracks which entries were already shown. Subsequent bulk reads suppress seen entries with Fibonacci decay `[5,3,2,1,0]`, keeping output fresh without repetition. Use `reset_memory_cache` to clear the cache.
+```bash
+npx hmem-sync announce --message "Server URL changing — update your config!"
+```
-To see all children of an entry, use `read_memory(id="P0005")`. For a deep dive with full content, use `read_memory(id="P0005", expand=true)`. For a compact table of contents, use `read_memory(titles_only=true)`.
+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.
-### Effective-date sorting
+---
-Entries are sorted by `effective_date` — the most recent timestamp across the entry and all its nodes. This means a project entry (`P0005`) that was first written months ago but had a new session note appended today will appear near the top of the listing, alongside truly recent entries.
+## Auto-Logging (O-prefix)
-### Character limits
+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.
-Two ways to set per-level character limits:
+### Setup the hook
-**Option A — linear interpolation** (recommended): set only the endpoints; all levels in between are computed automatically.
+Add to `~/.claude/settings.json`:
 ```json
-{ "maxL1Chars": 120, "maxLnChars": 50000 }
+{
+  "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
+          }
+        ]
+      }
+    ]
+  }
+}
 ```
-With 5 depth levels this yields: `[120, 12780, 25440, 38120, 50000]`
-**Option B — explicit per-level array**: set each level individually. If fewer entries than `maxDepth`, the last value is repeated.
+O-entries are hidden from bulk reads (no noise) but searchable and linked to your active project.
-```json
-{ "maxCharsPerLevel": [120, 2500, 10000, 25000, 50000] }
-```
+---
-### Bulk read tuning (`bulkReadV2`)
+## Configuration
-Controls how many entries are expanded in each category during a bulk read:
+`hmem.config.json` in your `HMEM_PROJECT_DIR`:
 ```json
-"bulkReadV2": {
-  "topNewestCount": 5,     // expand the 5 newest entries per prefix
-  "topAccessCount": 3,     // expand the 3 most-accessed per prefix
-  "topObsoleteCount": 3    // show up to 3 obsolete entries (by access count)
+{
+  "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": "..."
+  }
 }
 ```
-Favorites are always expanded regardless of these limits. Entries expanded by one slot (e.g. newest) don't count against another (e.g. access).
+All keys are optional. Missing keys use defaults.
 ---
-## TUI Viewer (hmem-reader.py)
-A terminal-based interactive viewer for browsing `.hmem` memory files. Built with [Textual](https://textual.textualize.io/).
+## Updating
 ```bash
-pip install textual     # one-time dependency
-python3 hmem-reader.py         # agent selection screen (scans Agents/ directory)
-python3 hmem-reader.py THOR    # open a specific agent's memory
-python3 hmem-reader.py ~/path/to/file.hmem  # open any .hmem file directly
+# Always global — NOT inside a project directory
+npm update -g hmem-mcp
+npm update -g hmem-sync
 ```
-**Keys:**
-| Key | Action |
-|-----|--------|
-| `r` | Toggle V2 bulk-read view (what agents see on `read_memory()`) |
-| `e` / `c` | Expand / collapse all nodes |
-| `q` | Quit |
-| `Escape` | Back to agent list |
-The V2 view mirrors the MCP server's bulk-read algorithm — including time-weighted access scoring, per-prefix selection, active-prefix filtering, and all markers (`[♥]`, `[!]`, `[*]`, `[s]`, `[-]`) — so you can see exactly what an agent sees at session start.
----
-## Origin
-hmem was developed out of necessity: working on a large AI project across multiple machines meant every new Claude Code session started blind. Agents redid work, lost decisions, and contradicted each other.
-The solution was a memory protocol that works the way humans remember — broad strokes first, details on demand.
+Skills are automatically updated via postinstall hook. No manual copy needed.
 ---