hmem-mcp 2.2.0 → 2.4.0

package/README.md

@@ -2,8 +2,7 @@
 
 > AI agents forget everything when a session ends. hmem changes that.
 
-> **Beta:** hmem is functional and actively used in production, but APIs and file formats
-> may still change. Feedback and bug reports welcome. Also the parameters I chose need to be tested and tweaked.
+> hmem is actively used in production. APIs are stable since v2.0. Feedback and bug reports welcome.
 
 **hmem** is a Model Context Protocol (MCP) server that gives AI agents persistent, humanlike memory — modeled after how human memory actually works.
 
@@ -71,12 +70,13 @@ Each node gets a compound ID (`L0003.2.1`) so any branch is individually address
 Entries can be updated without deleting and recreating them:
 
 ```
-update_memory(id="L0003", content="Corrected L1 summary")
-update_memory(id="L0003.2", content="Fixed sub-node text")
+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). `append_memory` adds new child nodes to an existing entry.
+`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
 
@@ -104,13 +104,20 @@ A dedicated curator agent runs periodically to maintain memory health. It detect
 
 - **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
-- **Obsolete flag** — mark outdated entries as obsolete; hidden from bulk reads but still searchable — knowledge is never destroyed, only archived
-- **Favorite flag** — mark any entry as `[♥]` to always see it with L2 detail, regardless of category
-- **Access-count promotion** — the top-N most-accessed entries are automatically shown with L2 detail (`[★]`)
-- **Effective-date sorting** — entries with recent appends surface to the top (old P entries grow over time without losing their position)
-- **Token-efficient bulk reads** — only the most recent L2 child is shown in bulk reads, with a "+N more" hint
+- **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
@@ -134,7 +141,7 @@ That's it. The interactive installer will:
 
 After the installer finishes, restart your AI tool and call `read_memory()` to verify.
 
-> **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.py path/to/memory.hmem`.
+> **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`.
 
 > **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.
 >
@@ -271,10 +278,13 @@ done
 
 | Tool | Description |
 |------|-------------|
-| `read_memory` | Read hierarchical memories — L1 summaries or drill into any node by ID |
+| `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 the text of an existing entry or sub-node (children preserved) |
-| `append_memory` | Append new child nodes to an existing entry without overwriting it |
+| `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 |
 
 ### Curator Tools (role: ceo)
@@ -342,11 +352,13 @@ Place an optional `hmem.config.json` in your `HMEM_PROJECT_DIR` to tune behavior
   "maxL1Chars": 120,
   "maxLnChars": 50000,
   "maxDepth": 5,
+  "maxTitleChars": 50,
   "accessCountTopN": 5,
-  "recentDepthTiers": [
-    { "count": 10, "depth": 2 },
-    { "count": 3,  "depth": 3 }
-  ],
+  "bulkReadV2": {
+    "topNewestCount": 5,
+    "topAccessCount": 3,
+    "topObsoleteCount": 3
+  },
   "prefixes": {
     "R": "Research"
   }
@@ -375,13 +387,41 @@ To add your own, add entries to the `"prefixes"` key in `hmem.config.json`. Cust
 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", content="...", favorite=true)    # set on existing entry
-update_memory(id="D0010", content="...", favorite=false)   # clear the flag
+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
 ```
 
 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
+
+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.
+
+```
+write_memory(prefix="S", content="...", pinned=true)   # set at creation
+update_memory(id="S0005", pinned=true)                 # set on existing entry
+```
+
+| 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 |
+
+Use pinned for entries with many structured sub-entries (handbooks, reference lists, project summaries) where you always want to see the full outline.
+
+### Hashtags
+
+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)
+```
+
+Tags are lowercase, must start with `#`, max 10 per entry. They work on root entries and sub-nodes.
+
 ### Access-count auto-promotion (`accessCountTopN`)
 
 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.
@@ -405,11 +445,16 @@ This means a 1-day-old entry with 5 accesses (score 3.16) outranks a 1-year-old
 | **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 |
 
-### Token-efficient bulk reads
+### Bulk reads (V2 algorithm)
+
+`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:
 
-In a default `read_memory()` call, each entry shows only its **most recently added** L2 child (with that child's timestamp). A `+N more` hint indicates when additional L2 nodes exist. This keeps the bulk output compact while remaining discoverable.
+- **`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.
 
-To see all children of an entry, use `read_memory(id="P0005")`.
+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.
+
+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)`.
 
 ### Effective-date sorting
 
@@ -433,43 +478,31 @@ With 5 depth levels this yields: `[120, 12780, 25440, 38120, 50000]`
 { "maxCharsPerLevel": [120, 2500, 10000, 25000, 50000] }
 ```
 
-### Recency gradient (`recentDepthTiers`)
-
-Controls how deep children are inlined for the most recent entries in a default `read_memory()` call. Each tier is `{ count, depth }`: the *count* most recent entries get children inlined up to *depth*.
+### Bulk read tuning (`bulkReadV2`)
 
-Tiers are cumulative — the **highest applicable depth wins** for each entry position.
+Controls how many entries are expanded in each category during a bulk read:
 
 ```json
-"recentDepthTiers": [
-  { "count": 3,  "depth": 3 },   // last 3 entries  → L1 + L2 + L3
-  { "count": 10, "depth": 2 }    // last 10 entries → L1 + L2
-]
+"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)
+}
 ```
 
-Result:
-| Entry position | Depth inlined |
-|---|---|
-| 0–2 (most recent) | L1 + L2 + L3 |
-| 3–9 | L1 + L2 |
-| 10+ | L1 only |
-
-This mirrors how human memory works: you remember today's events in full detail, last week's in outline, older ones only as headlines.
-
-Set to `[]` to disable recency inlining (L1-only for all entries).
-
-**Backward compat:** The old `"recentChildrenCount": N` key is still accepted and treated as `[{ "count": N, "depth": 2 }]`.
+Favorites are always expanded regardless of these limits. Entries expanded by one slot (e.g. newest) don't count against another (e.g. access).
 
 ---
 
-## TUI Viewer (hmem.py)
+## TUI Viewer (hmem-reader.py)
 
 A terminal-based interactive viewer for browsing `.hmem` memory files. Built with [Textual](https://textual.textualize.io/).
 
 ```bash
 pip install textual     # one-time dependency
-python3 hmem.py         # agent selection screen (scans Agents/ directory)
-python3 hmem.py THOR    # open a specific agent's memory
-python3 hmem.py ~/path/to/file.hmem  # open any .hmem file directly
+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
 ```
 
 **Keys:**
@@ -480,7 +513,7 @@ python3 hmem.py ~/path/to/file.hmem  # open any .hmem file directly
 | `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, and favorite/promoted markers — so you can see exactly what an agent sees at session start.
+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.
 
 ---
 

package/dist/hmem-config.d.ts

@@ -58,12 +58,19 @@ export interface HmemConfig {
      * Controls how many entries receive expanded treatment in default reads.
      */
     bulkReadV2: {
-        /** Number of top-accessed entries to expand (default: 3) */
+        /** Number of top-accessed entries to expand — legacy fixed fallback (default: 3) */
         topAccessCount: number;
-        /** Number of newest entries to expand (default: 5) */
+        /** Number of newest entries to expand — legacy fixed fallback (default: 5) */
         topNewestCount: number;
         /** Number of obsolete entries to keep visible (default: 3) */
         topObsoleteCount: number;
+        /** Percentage-based selection (overrides fixed counts when set) */
+        newestPercent?: number;
+        newestMin?: number;
+        newestMax?: number;
+        accessPercent?: number;
+        accessMin?: number;
+        accessMax?: number;
     };
 }
 export declare const DEFAULT_PREFIXES: Record<string, string>;

package/dist/hmem-config.js

@@ -41,6 +41,12 @@ export const DEFAULT_CONFIG = {
         topAccessCount: 3,
         topNewestCount: 5,
         topObsoleteCount: 3,
+        newestPercent: 20,
+        newestMin: 5,
+        newestMax: 15,
+        accessPercent: 10,
+        accessMin: 3,
+        accessMax: 8,
     },
 };
 /**
@@ -115,6 +121,19 @@ export function loadHmemConfig(projectDir) {
                 cfg.bulkReadV2.topNewestCount = v2.topNewestCount;
             if (typeof v2.topObsoleteCount === "number" && v2.topObsoleteCount >= 0)
                 cfg.bulkReadV2.topObsoleteCount = v2.topObsoleteCount;
+            // Percentage-based selection
+            if (typeof v2.newestPercent === "number" && v2.newestPercent > 0)
+                cfg.bulkReadV2.newestPercent = v2.newestPercent;
+            if (typeof v2.newestMin === "number" && v2.newestMin >= 0)
+                cfg.bulkReadV2.newestMin = v2.newestMin;
+            if (typeof v2.newestMax === "number" && v2.newestMax > 0)
+                cfg.bulkReadV2.newestMax = v2.newestMax;
+            if (typeof v2.accessPercent === "number" && v2.accessPercent > 0)
+                cfg.bulkReadV2.accessPercent = v2.accessPercent;
+            if (typeof v2.accessMin === "number" && v2.accessMin >= 0)
+                cfg.bulkReadV2.accessMin = v2.accessMin;
+            if (typeof v2.accessMax === "number" && v2.accessMax > 0)
+                cfg.bulkReadV2.accessMax = v2.accessMax;
         }
         // Resolve char limits: explicit array > linear endpoints > default
         if (Array.isArray(raw.maxCharsPerLevel) && raw.maxCharsPerLevel.length >= 1) {

package/dist/hmem-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"hmem-config.js","sourceRoot":"","sources":["../src/hmem-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hmem-config.js","sourceRoot":"","sources":["../src/hmem-config.ts"],"names":[],"mappings":"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"}

package/dist/hmem-store.d.ts

@@ -75,6 +75,17 @@ export interface MemoryEntry {
     hiddenIrrelevantLinks?: number;
     /** If this entry was reached via obsolete chain resolution, the chain of IDs traversed. */
     obsoleteChain?: string[];
+    /** Optional hashtags for cross-cutting search, e.g. ["#hmem", "#curation"]. */
+    tags?: string[];
+    /** Entries sharing 2+ tags with this entry (populated on ID-based reads). */
+    relatedEntries?: {
+        id: string;
+        title: string;
+        created_at: string;
+        tags: string[];
+    }[];
+    /** True if the entry is pinned (super-favorite). Pinned entries show full L2 content in bulk reads. */
+    pinned?: boolean;
 }
 export interface MemoryNode {
     id: string;
@@ -89,8 +100,11 @@ export interface MemoryNode {
     access_count: number;
     last_accessed: string | null;
     favorite?: boolean;
+    irrelevant?: boolean;
     child_count?: number;
     children?: MemoryNode[];
+    /** Optional hashtags, e.g. ["#hmem", "#curation"]. */
+    tags?: string[];
 }
 export interface ReadOptions {
     id?: string;
@@ -125,25 +139,44 @@ export interface ReadOptions {
     titlesOnly?: boolean;
     /** Expand full tree with complete node content (for deep-dive into a project). depth controls how deep. */
     expand?: boolean;
-    /** IDs already delivered in this session — completely hidden in bulk reads. */
-    suppressedIds?: Set<string>;
-    /** Max newest entries per prefix (Fibonacci decay). */
-    maxNewNewest?: number;
-    /** Max most-accessed entries per prefix (Fibonacci decay). */
-    maxNewAccess?: number;
+    /** IDs already delivered in this session — shown as title-only in subsequent bulk reads. */
+    cachedIds?: Set<string>;
+    /** IDs within hidden phase (< 5 min) — completely excluded from output. */
+    hiddenIds?: Set<string>;
+    /** Slot reduction fraction: 1.0 = full, 0.5 = half percentage, 0.25 = quarter, ... */
+    slotFraction?: number;
     /** Bulk read mode: 'discover' (newest-heavy, default) or 'essentials' (importance-heavy). */
     mode?: "discover" | "essentials";
+    /** Curation mode: show ALL entries (bypass V2 selection + session cache), depth 3 children, no child V2. */
+    showAll?: boolean;
+    /** Filter by tag, e.g. "#hmem". Only entries/nodes with this tag are included. */
+    tag?: string;
 }
 export interface WriteResult {
     id: string;
     timestamp: string;
 }
+export interface ImportResult {
+    inserted: number;
+    merged: number;
+    nodesInserted: number;
+    nodesSkipped: number;
+    tagsImported: number;
+    remapped: boolean;
+    conflicts: number;
+}
 export declare class HmemStore {
     private db;
     private readonly dbPath;
+    getDbPath(): string;
     private readonly cfg;
     /** True if integrity_check found errors on open (read-only mode recommended). */
     readonly corrupted: boolean;
+    /**
+     * Char-limit tolerance: configured limits are the "recommended" target shown in skills/errors.
+     * Actual hard reject is at limit * CHAR_LIMIT_TOLERANCE (25% buffer to avoid wasted retries).
+     */
+    private static readonly CHAR_LIMIT_TOLERANCE;
     constructor(hmemPath: string, config?: HmemConfig);
     /** Throw if the database is corrupted — prevents silent data loss on write operations. */
     private guardCorrupted;
@@ -155,7 +188,7 @@ export declare class HmemStore {
      * Each indented line → its own memory_nodes row with compound ID
      * Multiple lines at the same indent depth → siblings (new capability)
      */
-    write(prefix: string, content: string, links?: string[], minRole?: AgentRole, favorite?: boolean): WriteResult;
+    write(prefix: string, content: string, links?: string[], minRole?: AgentRole, favorite?: boolean, tags?: string[], pinned?: boolean): WriteResult;
     /**
      * Read memories with flexible querying.
      *
@@ -165,6 +198,12 @@ export declare class HmemStore {
      * For bulk queries: returns L1 summaries (depth=1 default).
      */
     read(opts?: ReadOptions): MemoryEntry[];
+    /**
+     * Calculate V2 selection slot counts based on the number of relevant entries.
+     * Uses percentage-based scaling with min/max caps when configured,
+     * falls back to fixed topNewestCount/topAccessCount otherwise.
+     */
+    private calcV2Slots;
     /**
      * V2 bulk-read algorithm: per-prefix expansion, smart obsolete filtering,
      * expanded entries with all L2 children + links.
@@ -179,12 +218,27 @@ export declare class HmemStore {
      * Export entire memory to Markdown for git tracking.
      */
     exportMarkdown(): string;
+    /**
+     * Export memory to a new .hmem SQLite file.
+     * Creates a standalone copy that can be opened with HmemStore or hmem.py.
+     */
+    exportPublicToHmem(outputPath: string): {
+        entries: number;
+        nodes: number;
+        tags: number;
+    };
+    /**
+     * Import entries from another .hmem file with L1 deduplication and ID remapping.
+     */
+    importFromHmem(sourcePath: string, dryRun?: boolean): ImportResult;
+    private _doImport;
     /**
      * Get statistics about the memory store.
      */
     stats(): {
         total: number;
         byPrefix: Record<string, number>;
+        totalChars: number;
     };
     /**
      * Update specific fields of an existing root entry (curator use only).
@@ -201,7 +255,7 @@ export declare class HmemStore {
      * For sub-nodes: updates node content only.
      * Does NOT modify children — use appendChildren to extend the tree.
      */
-    updateNode(id: string, newContent: string, links?: string[], obsolete?: boolean, favorite?: boolean, curatorBypass?: boolean, irrelevant?: boolean): boolean;
+    updateNode(id: string, newContent: string, links?: string[], obsolete?: boolean, favorite?: boolean, curatorBypass?: boolean, irrelevant?: boolean, tags?: string[], pinned?: boolean): boolean;
     /**
      * Append new child nodes under an existing entry (root or node).
      * Content is tab-indented relative to the parent:
@@ -224,6 +278,32 @@ export declare class HmemStore {
      */
     getHeaders(): MemoryEntry[];
     close(): void;
+    private static readonly TAG_REGEX;
+    private static readonly MAX_TAGS_PER_ENTRY;
+    /** Validate and normalize tags: lowercase, must match #word pattern. */
+    private validateTags;
+    /** Replace all tags on an entry/node. Pass empty array to clear. */
+    private setTags;
+    /** Get tags for a single entry/node. */
+    private fetchTags;
+    /** Bulk-fetch tags for multiple IDs at once. */
+    private fetchTagsBulk;
+    /**
+     * Find entries sharing 2+ tags with the given entry.
+     * Returns title-only results sorted by number of shared tags (descending).
+     */
+    findRelated(entryId: string, tags: string[], limit?: number): {
+        id: string;
+        title: string;
+        created_at: string;
+        tags: string[];
+    }[];
+    /** Bulk-assign tags to entries + their children from a single fetchTagsBulk call. */
+    private assignBulkTags;
+    /** Recursively collect all node IDs from a tree of MemoryNodes. */
+    private collectNodeIds;
+    /** Get root IDs that have a specific tag (for bulk-read filtering). */
+    private getRootIdsByTag;
     private migrate;
     /**
      * One-time migration: move level_2..level_5 data to memory_nodes tree.