hmem-mcp 2.4.1 → 2.5.1
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.
- package/README.md +30 -0
- package/dist/hmem-config.d.ts +2 -0
- package/dist/hmem-config.js +3 -0
- package/dist/hmem-config.js.map +1 -1
- package/dist/hmem-store.d.ts +102 -1
- package/dist/hmem-store.js +625 -48
- package/dist/hmem-store.js.map +1 -1
- package/dist/mcp-server.js +311 -7
- package/dist/mcp-server.js.map +1 -1
- package/package.json +8 -3
- package/scripts/use-prebuild.cjs +45 -0
- package/skills/hmem-config/SKILL.md +4 -1
- package/skills/hmem-read/SKILL.md +92 -13
- package/skills/hmem-self-curate/SKILL.md +83 -44
- package/skills/hmem-write/SKILL.md +115 -0
package/README.md
CHANGED
|
@@ -10,6 +10,18 @@ Born as a side project of a multi-agent AI system, hmem solves a real problem: w
|
|
|
10
10
|
|
|
11
11
|
**hmem fixes this.**
|
|
12
12
|
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
## Examples
|
|
17
|
+
|
|
18
|
+
<img width="1110" height="665" alt="image" src="https://github.com/user-attachments/assets/af7688d2-73e3-44f8-b414-f6afa8904e6c" />
|
|
19
|
+
Well, it claims that it can't pinpoint timestamps. But that's not true. It just cant see them (due to token efficiency) :)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
<img width="1096" height="941" alt="image" src="https://github.com/user-attachments/assets/a751c8f3-41fc-46b6-916a-bcd3862008ad" />
|
|
23
|
+
|
|
24
|
+
|
|
13
25
|
---
|
|
14
26
|
|
|
15
27
|
## The Problem
|
|
@@ -286,6 +298,12 @@ done
|
|
|
286
298
|
| `import_memory` | Import entries from a `.hmem` file with deduplication and ID remapping |
|
|
287
299
|
| `reset_memory_cache` | Clear session cache so all entries are treated as unseen |
|
|
288
300
|
| `search_memory` | Full-text search across all agent `.hmem` databases |
|
|
301
|
+
| `memory_stats` | Overview: total entries by prefix, nodes, favorites, pinned, stale count, most-accessed |
|
|
302
|
+
| `find_related` | FTS5-based similarity search — find entries with overlapping keywords |
|
|
303
|
+
| `memory_health` | Audit report: broken links, orphaned entries, stale favorites, broken obsolete chains |
|
|
304
|
+
| `tag_bulk` | Apply tag changes (add/remove) to all entries matching a filter |
|
|
305
|
+
| `tag_rename` | Rename a hashtag across all entries and nodes |
|
|
306
|
+
| `move_memory` | Move a sub-node (+ entire subtree) to a different parent — updates all IDs and references |
|
|
289
307
|
|
|
290
308
|
### Curator Tools (role: ceo)
|
|
291
309
|
|
|
@@ -296,6 +314,7 @@ done
|
|
|
296
314
|
| `fix_agent_memory` | Correct a specific entry or sub-node in any agent's memory |
|
|
297
315
|
| `append_agent_memory` | Add content to an existing entry in any agent's memory (for merging duplicates) |
|
|
298
316
|
| `delete_agent_memory` | Delete a memory entry (prefer `fix_agent_memory(obsolete=true)` — deletion is permanent) |
|
|
317
|
+
| `move_agent_memory` | Move a sub-node in any agent's memory to a different parent — updates all IDs and references |
|
|
299
318
|
| `mark_audited` | Mark an agent as audited |
|
|
300
319
|
|
|
301
320
|
---
|
|
@@ -418,10 +437,21 @@ Tag entries for cross-cutting search across prefix categories:
|
|
|
418
437
|
write_memory(prefix="L", content="...", tags=["#security", "#hmem"])
|
|
419
438
|
read_memory(tag="#security") # filter bulk reads by tag
|
|
420
439
|
read_memory(id="L0042") # shows related entries (2+ shared tags)
|
|
440
|
+
tag_bulk(filter={prefix: "E"}, add_tags=["#bugfix"]) # batch-tag all E-entries
|
|
441
|
+
tag_rename(old_tag="#old", new_tag="#new") # rename everywhere
|
|
421
442
|
```
|
|
422
443
|
|
|
423
444
|
Tags are lowercase, must start with `#`, max 10 per entry. They work on root entries and sub-nodes.
|
|
424
445
|
|
|
446
|
+
### Stale Detection and Memory Health
|
|
447
|
+
|
|
448
|
+
```
|
|
449
|
+
read_memory(stale_days=30) # entries not accessed in 30 days, sorted oldest-first
|
|
450
|
+
memory_stats() # count by prefix, stale count, favorites, most-accessed
|
|
451
|
+
memory_health() # audit: broken links, orphans, stale favorites
|
|
452
|
+
find_related(id="P0029") # FTS5 keyword similarity — find thematically related entries
|
|
453
|
+
```
|
|
454
|
+
|
|
425
455
|
### Access-count auto-promotion (`accessCountTopN`)
|
|
426
456
|
|
|
427
457
|
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.
|
package/dist/hmem-config.d.ts
CHANGED
|
@@ -64,6 +64,8 @@ export interface HmemConfig {
|
|
|
64
64
|
topNewestCount: number;
|
|
65
65
|
/** Number of obsolete entries to keep visible (default: 3) */
|
|
66
66
|
topObsoleteCount: number;
|
|
67
|
+
/** Number of entries with the most sub-nodes to always expand (default: 3) */
|
|
68
|
+
topSubnodeCount: number;
|
|
67
69
|
/** Percentage-based selection (overrides fixed counts when set) */
|
|
68
70
|
newestPercent?: number;
|
|
69
71
|
newestMin?: number;
|
package/dist/hmem-config.js
CHANGED
|
@@ -41,6 +41,7 @@ export const DEFAULT_CONFIG = {
|
|
|
41
41
|
topAccessCount: 3,
|
|
42
42
|
topNewestCount: 5,
|
|
43
43
|
topObsoleteCount: 3,
|
|
44
|
+
topSubnodeCount: 3,
|
|
44
45
|
newestPercent: 20,
|
|
45
46
|
newestMin: 5,
|
|
46
47
|
newestMax: 15,
|
|
@@ -121,6 +122,8 @@ export function loadHmemConfig(projectDir) {
|
|
|
121
122
|
cfg.bulkReadV2.topNewestCount = v2.topNewestCount;
|
|
122
123
|
if (typeof v2.topObsoleteCount === "number" && v2.topObsoleteCount >= 0)
|
|
123
124
|
cfg.bulkReadV2.topObsoleteCount = v2.topObsoleteCount;
|
|
125
|
+
if (typeof v2.topSubnodeCount === "number" && v2.topSubnodeCount >= 0)
|
|
126
|
+
cfg.bulkReadV2.topSubnodeCount = v2.topSubnodeCount;
|
|
124
127
|
// Percentage-based selection
|
|
125
128
|
if (typeof v2.newestPercent === "number" && v2.newestPercent > 0)
|
|
126
129
|
cfg.bulkReadV2.newestPercent = v2.newestPercent;
|
package/dist/hmem-config.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"hmem-config.js","sourceRoot":"","sources":["../src/hmem-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;
|
|
1
|
+
{"version":3,"file":"hmem-config.js","sourceRoot":"","sources":["../src/hmem-config.ts"],"names":[],"mappings":"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"}
|
package/dist/hmem-store.d.ts
CHANGED
|
@@ -55,7 +55,7 @@ export interface MemoryEntry {
|
|
|
55
55
|
* 'favorite' = favorite flag set, 'access' = top-N by access_count.
|
|
56
56
|
* Rendered as [♥] or [★] in output.
|
|
57
57
|
*/
|
|
58
|
-
promoted?: "access" | "favorite";
|
|
58
|
+
promoted?: "access" | "favorite" | "subnode";
|
|
59
59
|
/**
|
|
60
60
|
* In bulk reads: number of direct children NOT shown (only the latest child is included).
|
|
61
61
|
* undefined = ID-based read (all direct children shown as usual).
|
|
@@ -151,6 +151,8 @@ export interface ReadOptions {
|
|
|
151
151
|
showAll?: boolean;
|
|
152
152
|
/** Filter by tag, e.g. "#hmem". Only entries/nodes with this tag are included. */
|
|
153
153
|
tag?: string;
|
|
154
|
+
/** Show entries not accessed in the last N days (stale detection). Sorted oldest-access first. */
|
|
155
|
+
staleDays?: number;
|
|
154
156
|
}
|
|
155
157
|
export interface WriteResult {
|
|
156
158
|
id: string;
|
|
@@ -323,6 +325,12 @@ export declare class HmemStore {
|
|
|
323
325
|
* artificially surface in "top most-accessed" rankings.
|
|
324
326
|
*/
|
|
325
327
|
private migrateObsoleteAccessCount;
|
|
328
|
+
/**
|
|
329
|
+
* One-time migration: build FTS5 index from existing data.
|
|
330
|
+
* Idempotent — tracked via schema_version key 'fts5_v1'.
|
|
331
|
+
* For fresh DBs the triggers handle indexing; this migration covers pre-existing rows.
|
|
332
|
+
*/
|
|
333
|
+
private migrateFts5;
|
|
326
334
|
/**
|
|
327
335
|
* Add a link from sourceId to targetId (idempotent).
|
|
328
336
|
* Only works for root entries (not nodes).
|
|
@@ -349,6 +357,12 @@ export declare class HmemStore {
|
|
|
349
357
|
* Returns the final (non-obsolete) entry ID and the full chain of IDs traversed.
|
|
350
358
|
*/
|
|
351
359
|
private resolveObsoleteChain;
|
|
360
|
+
/**
|
|
361
|
+
* Rewrite all external links that reference `obsoleteId` to point to `correctionId` instead.
|
|
362
|
+
* Called automatically when an entry is marked obsolete with a [✓ID] correction reference.
|
|
363
|
+
* Skips the obsolete entry itself and its correction (those are handled via addLink).
|
|
364
|
+
*/
|
|
365
|
+
private rewriteLinksToObsolete;
|
|
352
366
|
/** Fetch direct children of a node (root or compound), including their grandchild counts. */
|
|
353
367
|
/** Bulk-fetch direct child counts for multiple parent IDs in one query. */
|
|
354
368
|
private bulkChildCount;
|
|
@@ -410,6 +424,93 @@ export declare class HmemStore {
|
|
|
410
424
|
* startSeq: the first seq number to assign to direct children (continuing after existing siblings).
|
|
411
425
|
*/
|
|
412
426
|
private parseRelativeTree;
|
|
427
|
+
/** Return a statistical overview of the memory store. */
|
|
428
|
+
getStats(): {
|
|
429
|
+
totalEntries: number;
|
|
430
|
+
byPrefix: Record<string, number>;
|
|
431
|
+
totalNodes: number;
|
|
432
|
+
favorites: number;
|
|
433
|
+
pinned: number;
|
|
434
|
+
mostAccessed: {
|
|
435
|
+
id: string;
|
|
436
|
+
title: string;
|
|
437
|
+
access_count: number;
|
|
438
|
+
}[];
|
|
439
|
+
oldestEntry: {
|
|
440
|
+
id: string;
|
|
441
|
+
created_at: string;
|
|
442
|
+
title: string;
|
|
443
|
+
} | null;
|
|
444
|
+
staleCount: number;
|
|
445
|
+
uniqueTags: number;
|
|
446
|
+
avgDepth: number;
|
|
447
|
+
};
|
|
448
|
+
/**
|
|
449
|
+
* Find entries similar to the given entry via FTS5 keyword matching.
|
|
450
|
+
* Extracts significant words from level_1, queries FTS5, returns up to `limit` results.
|
|
451
|
+
*/
|
|
452
|
+
findRelatedCombined(entryId: string, limit?: number): {
|
|
453
|
+
id: string;
|
|
454
|
+
title: string;
|
|
455
|
+
created_at: string;
|
|
456
|
+
tags: string[];
|
|
457
|
+
matchType: "tags" | "fts";
|
|
458
|
+
}[];
|
|
459
|
+
findRelatedByFts(entryId: string, limit?: number): {
|
|
460
|
+
id: string;
|
|
461
|
+
title: string;
|
|
462
|
+
created_at: string;
|
|
463
|
+
tags: string[];
|
|
464
|
+
}[];
|
|
465
|
+
/** Audit report: broken links, orphaned entries, stale favorites, broken obsolete chains, tag orphans. */
|
|
466
|
+
healthCheck(): {
|
|
467
|
+
brokenLinks: {
|
|
468
|
+
id: string;
|
|
469
|
+
title: string;
|
|
470
|
+
brokenIds: string[];
|
|
471
|
+
}[];
|
|
472
|
+
orphanedEntries: {
|
|
473
|
+
id: string;
|
|
474
|
+
title: string;
|
|
475
|
+
created_at: string;
|
|
476
|
+
}[];
|
|
477
|
+
staleFavorites: {
|
|
478
|
+
id: string;
|
|
479
|
+
title: string;
|
|
480
|
+
lastAccessed: string | null;
|
|
481
|
+
}[];
|
|
482
|
+
brokenObsoleteChains: {
|
|
483
|
+
id: string;
|
|
484
|
+
title: string;
|
|
485
|
+
badRef: string;
|
|
486
|
+
}[];
|
|
487
|
+
tagOrphans: number;
|
|
488
|
+
};
|
|
489
|
+
/**
|
|
490
|
+
* Apply tag changes (add/remove) to all entries matching a filter.
|
|
491
|
+
* Returns the number of entries modified.
|
|
492
|
+
*/
|
|
493
|
+
tagBulk(filter: {
|
|
494
|
+
prefix?: string;
|
|
495
|
+
search?: string;
|
|
496
|
+
tag?: string;
|
|
497
|
+
}, addTags?: string[], removeTags?: string[]): number;
|
|
498
|
+
/**
|
|
499
|
+
* Rename a tag across all entries and nodes.
|
|
500
|
+
* Returns the number of rows updated.
|
|
501
|
+
*/
|
|
502
|
+
tagRename(oldTag: string, newTag: string): number;
|
|
503
|
+
/**
|
|
504
|
+
* Move a sub-node (and its entire subtree) to a different parent.
|
|
505
|
+
* sourceId must be a sub-node (e.g. "P0029.15"), not a root entry.
|
|
506
|
+
* targetParentId can be a root (e.g. "L0074") or a sub-node (e.g. "P0029.20").
|
|
507
|
+
* All IDs in links and [✓ID] content references are updated automatically.
|
|
508
|
+
*/
|
|
509
|
+
moveNode(sourceId: string, targetParentId: string): {
|
|
510
|
+
moved: number;
|
|
511
|
+
newId: string;
|
|
512
|
+
idMap: Record<string, string>;
|
|
513
|
+
};
|
|
413
514
|
}
|
|
414
515
|
export declare function resolveHmemPath(projectDir: string, templateName: string): string;
|
|
415
516
|
/**
|