@psiclawops/hypermem 0.6.2 → 0.8.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 (98) hide show
  1. package/ARCHITECTURE.md +31 -39
  2. package/README.md +20 -14
  3. package/bin/hypermem-status.mjs +1 -1
  4. package/dist/background-indexer.d.ts +14 -3
  5. package/dist/background-indexer.d.ts.map +1 -1
  6. package/dist/background-indexer.js +135 -27
  7. package/dist/budget-policy.d.ts +22 -0
  8. package/dist/budget-policy.d.ts.map +1 -0
  9. package/dist/budget-policy.js +27 -0
  10. package/dist/cache.d.ts +11 -0
  11. package/dist/cache.d.ts.map +1 -1
  12. package/dist/compositor-utils.d.ts +31 -0
  13. package/dist/compositor-utils.d.ts.map +1 -0
  14. package/dist/compositor-utils.js +47 -0
  15. package/dist/compositor.d.ts +163 -1
  16. package/dist/compositor.d.ts.map +1 -1
  17. package/dist/compositor.js +862 -130
  18. package/dist/content-hash.d.ts +43 -0
  19. package/dist/content-hash.d.ts.map +1 -0
  20. package/dist/content-hash.js +75 -0
  21. package/dist/context-store.d.ts +54 -0
  22. package/dist/context-store.d.ts.map +1 -1
  23. package/dist/context-store.js +102 -0
  24. package/dist/contradiction-audit-store.d.ts +54 -0
  25. package/dist/contradiction-audit-store.d.ts.map +1 -0
  26. package/dist/contradiction-audit-store.js +88 -0
  27. package/dist/contradiction-detector.d.ts +78 -0
  28. package/dist/contradiction-detector.d.ts.map +1 -0
  29. package/dist/contradiction-detector.js +362 -0
  30. package/dist/contradiction-resolution-policy.d.ts +21 -0
  31. package/dist/contradiction-resolution-policy.d.ts.map +1 -0
  32. package/dist/contradiction-resolution-policy.js +17 -0
  33. package/dist/cross-agent.d.ts +1 -1
  34. package/dist/cross-agent.js +17 -17
  35. package/dist/degradation.d.ts +102 -0
  36. package/dist/degradation.d.ts.map +1 -0
  37. package/dist/degradation.js +141 -0
  38. package/dist/dreaming-promoter.d.ts +39 -1
  39. package/dist/dreaming-promoter.d.ts.map +1 -1
  40. package/dist/dreaming-promoter.js +70 -4
  41. package/dist/expertise-store.d.ts +129 -0
  42. package/dist/expertise-store.d.ts.map +1 -0
  43. package/dist/expertise-store.js +342 -0
  44. package/dist/fact-store.d.ts +15 -0
  45. package/dist/fact-store.d.ts.map +1 -1
  46. package/dist/fact-store.js +52 -5
  47. package/dist/index.d.ts +74 -8
  48. package/dist/index.d.ts.map +1 -1
  49. package/dist/index.js +407 -29
  50. package/dist/knowledge-lint.d.ts +2 -0
  51. package/dist/knowledge-lint.d.ts.map +1 -1
  52. package/dist/knowledge-lint.js +40 -1
  53. package/dist/library-schema.d.ts +7 -2
  54. package/dist/library-schema.d.ts.map +1 -1
  55. package/dist/library-schema.js +307 -2
  56. package/dist/message-store.d.ts +64 -1
  57. package/dist/message-store.d.ts.map +1 -1
  58. package/dist/message-store.js +137 -1
  59. package/dist/proactive-pass.d.ts +2 -2
  60. package/dist/proactive-pass.d.ts.map +1 -1
  61. package/dist/proactive-pass.js +66 -12
  62. package/dist/replay-recovery.d.ts +29 -0
  63. package/dist/replay-recovery.d.ts.map +1 -0
  64. package/dist/replay-recovery.js +82 -0
  65. package/dist/reranker.d.ts +95 -0
  66. package/dist/reranker.d.ts.map +1 -0
  67. package/dist/reranker.js +308 -0
  68. package/dist/schema.d.ts +1 -1
  69. package/dist/schema.d.ts.map +1 -1
  70. package/dist/schema.js +46 -1
  71. package/dist/seed.d.ts +1 -1
  72. package/dist/seed.js +1 -1
  73. package/dist/session-flusher.d.ts +4 -4
  74. package/dist/session-flusher.d.ts.map +1 -1
  75. package/dist/session-flusher.js +3 -3
  76. package/dist/spawn-context.d.ts +1 -1
  77. package/dist/spawn-context.js +1 -1
  78. package/dist/temporal-store.d.ts +1 -0
  79. package/dist/temporal-store.d.ts.map +1 -1
  80. package/dist/tool-artifact-store.d.ts +98 -0
  81. package/dist/tool-artifact-store.d.ts.map +1 -0
  82. package/dist/tool-artifact-store.js +244 -0
  83. package/dist/topic-detector.js +2 -2
  84. package/dist/topic-store.d.ts +6 -0
  85. package/dist/topic-store.d.ts.map +1 -1
  86. package/dist/topic-store.js +39 -0
  87. package/dist/topic-synthesizer.js +1 -1
  88. package/dist/trigger-registry.d.ts +1 -1
  89. package/dist/trigger-registry.js +4 -4
  90. package/dist/types.d.ts +239 -3
  91. package/dist/types.d.ts.map +1 -1
  92. package/dist/vector-store.d.ts +2 -1
  93. package/dist/vector-store.d.ts.map +1 -1
  94. package/dist/vector-store.js +3 -0
  95. package/dist/version.d.ts +10 -10
  96. package/dist/version.d.ts.map +1 -1
  97. package/dist/version.js +10 -10
  98. package/package.json +6 -4
package/ARCHITECTURE.md CHANGED
@@ -1,13 +1,13 @@
1
1
  # hypermem Architecture
2
2
 
3
- _Agent-centric memory that outlives sessions._
3
+ _Agent-centric memory that outlives sessions, backed by SQLite memory databases._
4
4
 
5
5
  ---
6
6
 
7
7
  ## Memory Layers
8
8
 
9
9
  ```
10
- L1 Redis (Hot) Active session working memory
10
+ L1 SQLite Cache (Hot) Active session working memory
11
11
  │ Slots: system, identity, messages, facts, context
12
12
  │ Sub-millisecond reads, evicts on session end
13
13
  │ Fleet cache: agent profiles, fleet summary
@@ -28,9 +28,13 @@ L4 Library DB Fleet-wide structured knowledge
28
28
  Knowledge graph (DAG links between entities)
29
29
  ```
30
30
 
31
+ > Note: some internal method names and telemetry reasons still contain `redis`
32
+ > for backward compatibility. The runtime hot layer is SQLite `:memory:` cache,
33
+ > not an external Redis service.
34
+
31
35
  ## Database Schema
32
36
 
33
- ### messages.db (per agent, schema v3)
37
+ ### messages.db (per agent, schema v10)
34
38
  - `agent_meta` — agent metadata
35
39
  - `conversations` — session tracking
36
40
  - `messages` — raw message log (text, tool calls, tool results)
@@ -46,7 +50,7 @@ L4 Library DB Fleet-wide structured knowledge
46
50
  - `vec_index_map` — tracks what's been indexed (source_table, source_id, source_db)
47
51
  - `embedding_cache` — avoids redundant Ollama API calls
48
52
 
49
- ### library.db (shared, schema v5)
53
+ ### library.db (shared, schema v19)
50
54
  - `facts` — verifiable claims with confidence, domain, expiry, supersedes chains
51
55
  - `knowledge` — domain/key/value structured data
52
56
  - `knowledge_links` — DAG edges between entities (fact↔fact, fact↔knowledge, etc.)
@@ -70,7 +74,7 @@ Assembles LLM prompts from all four layers with token budgeting:
70
74
  ```
71
75
  User message arrives
72
76
 
73
- ├── L1 Redis: system prompt, identity, cached slots
77
+ ├── L1 Hot cache: system prompt, identity, cached slots
74
78
  ├── L2 Messages: recent conversation history (budget-truncated)
75
79
  ├── L3 Vectors: KNN semantic recall on user's latest message
76
80
  │ └── Related facts/knowledge/episodes with relevance scores
@@ -104,14 +108,14 @@ Compositor behavior is tuned via parameters tracked in `tune/TUNING_REGISTRY.md`
104
108
  - **Compaction fence:** Per-conversation boundary protecting the LLM's recent tail from compaction. Only moves forward (monotone progress). No fence = no compaction (explicit opt-in).
105
109
  - **Preservation gate:** Nomic-space geometric verification that summaries stay faithful to source content. Centroid alignment + source coverage → combined score (threshold: 0.65).
106
110
 
107
- ## Fleet Cache (Redis Hot Layer)
111
+ ## Fleet Cache (Hot Cache Layer)
108
112
 
109
113
  ```
110
114
  fleet:agent:{id} — Composite profile: registry + capabilities + desired state
111
115
  fleet:summary — Fleet-wide stats: agent count, drift count, tier breakdown
112
116
  ```
113
117
 
114
- - **Cache-aside** on reads: Redis first, SQLite fallback, warm on miss
118
+ - **Cache-aside** on reads: hot cache first, SQLite fallback, warm on miss
115
119
  - **Write-through invalidation** on fleet mutations
116
120
  - **Hydration** on gateway startup: bulk-populate from library.db
117
121
  - TTL: agent profiles 10min, summary 2min
@@ -148,7 +152,7 @@ Visibility-tiered access model for cross-agent knowledge queries:
148
152
 
149
153
  `visibilityFilter()` resolves access levels using an `OrgRegistry` — a mapping of agents to tiers, orgs, and capabilities. Currently loaded from a hardcoded `defaultOrgRegistry()` in `cross-agent.ts`.
150
154
 
151
- **Known limitation:** This duplicates fleet structure that lives authoritatively in `fleet_agents` + `fleet_orgs` in library.db. Near-term roadmap item: replace with live-loaded registry from library.db, with the hardcoded version as cold-start fallback only.
155
+ **Known limitation:** `defaultOrgRegistry()` duplicates fleet structure that lives authoritatively in `fleet_agents` + `fleet_orgs` in library.db. See [docs/ROADMAP.md](docs/ROADMAP.md) for the planned live-load migration.
152
156
 
153
157
  ### Unknown Agent Fallback (Restrictive Default)
154
158
 
@@ -164,10 +168,10 @@ This means:
164
168
  `plugin/src/index.ts` — OpenClaw context engine plugin (`hypercompositor`, fills `contextEngine` slot):
165
169
 
166
170
  ```
167
- gateway:startup → Init hypermem, auto-rotate DBs, hydrate fleet cache
168
- agent:bootstrap → Warm session (history, facts, profile → Redis)
171
+ gateway:startup → Init hypermem, auto-rotate DBs, seed fleet registry from workspace identities, hydrate fleet cache
172
+ agent:bootstrap → Warm session (history, facts, profile → hot cache)
169
173
  context:assemble → Full four-layer prompt assembly within token budget
170
- agent:afterTurn → Ingest new messages to SQLite + Redis, trigger background indexer
174
+ agent:afterTurn → Ingest new messages to SQLite + hot cache, trigger background indexer
171
175
  ```
172
176
 
173
177
  Registers with `ownsCompaction: true` — runtime skips legacy compaction entirely.
@@ -185,7 +189,7 @@ Registers with `ownsCompaction: true` — runtime skips legacy compaction entire
185
189
 
186
190
  ```
187
191
  ┌──────────────────────────────────────────────────┐
188
- REDIS (L1 Hot Layer)
192
+ HOT CACHE (SQLite :memory: CacheLayer)
189
193
  │ │
190
194
  │ hm:{a}:{s}:history ── Session archive (250 cap │
191
195
  │ (append-only) at bootstrap, 1000 soft │
@@ -210,34 +214,22 @@ Data Flow (current — P0 stabilized, window/cursor active):
210
214
  ▸ sessionExists() → skip if hot compose() slice(prePromptCount)
211
215
  ▸ SQLite ─→ warmSession() ─→ getHistory(limit) ✅ ─→ record*Message()
212
216
  ─→ pushHistory(250) ─→ dedup by id ─→ pushHistory(1, dedup)
213
- ─→ Redis :history ─→ budget assembly ─→ Redis :history
214
- ─→ write :window (120s) ─→ invalidateWindow()
215
- ─→ write :cursor (24h) ─→ background indexer
217
+ ─→ cache history ─→ budget assembly ─→ cache history
218
+ ─→ write window bundle ─→ invalidateWindow()
219
+ ─→ write cursor metadata ─→ background indexer
216
220
  ─→ → runtime → provider
217
221
 
218
222
  ### Key Invariants
219
223
 
220
- 1. Redis `history` is the warm archive. Append-only. Nothing reads it for direct submission.
221
- 2. Redis `window` is the compositor's output cache. Written ONLY by `compose()`. Read ONLY by `assemble()`. Invalidated by `afterTurn`.
222
- 3. Redis `cursor` tracks the newest message in the last window. Used by background indexer for high-signal mining.
224
+ 1. Hot-cache `history` is the warm archive. Append-only. Nothing reads it for direct submission.
225
+ 2. Hot-cache `window` is the compositor's output cache. Written ONLY by `compose()`. Read ONLY by `assemble()`. Invalidated by `afterTurn`.
226
+ 3. Hot-cache `cursor` tracks the newest message in the last window. Used by background indexer for high-signal mining.
223
227
  4. `warmSession()` seeds `history` only (capped at 250). Never writes `window`.
224
- 5. `pushHistory()` tail-checks before append (no duplicate IDs in Redis list).
228
+ 5. `pushHistory()` tail-checks before append (no duplicate IDs in the hot-cache history list).
225
229
  6. `compose()` deduplicates history by `id` before budget assembly.
226
- 7. `getHistory()` honors its `limit` parameter on BOTH Redis and SQLite paths.
227
-
228
- Design spec: `specs/HYPERMEM_QUEUE_SPLIT.md`
229
- Incident history: `specs/HYPERMEM_INCIDENT_HISTORY.md`
230
+ 7. `getHistory()` honors its `limit` parameter on BOTH hot-cache and SQLite paths.
230
231
 
231
- ### Open Items (Tracked)
232
-
233
- | Item | WQ | Status | Notes |
234
- |---|---|---|---|
235
- | Cross-session context boundary markers | WQ-20260402-001 | 🟡 OPEN | `buildCrossSessionContext()` renders flat previews, no per-message boundaries or sender identity. Incident 6. |
236
- | Cursor durability (SQLite dual-write) | — | 🟡 DEFERRED | Cursor TTL = 24h. Dual-write to SQLite required before background indexer reads cursor. Gate 2. |
237
- | Plugin type unification | — | 🟡 DEFERRED | Plugin uses dynamic imports; can't use TS types from core. Shims are intentional. Structural change needed. |
238
- | Strict topic mode: legacy NULL backfill | — | 🟡 DEFERRED | After ≥2 weeks of topic detection in production, run backfill to assign `topic_id` to legacy NULL messages, then narrow `getRecentMessagesByTopic()` to exclude NULL. Gate: topic detection must be stable and coverage >80% of new messages before narrowing. Tracked in `specs/DEFERRED.md`. |
239
- | ACA Step 4 — retrieval stubs replace static files | — | 🔲 PENDING | `systemPromptAddition` carries governance doc chunks instead of embedding full workspace files. Blocked on Step 3 ✅ |
240
- | ACA Step 5 — governance context assembly | — | 🔲 PENDING | Full on-demand assembly replaces static prompt injection. Requires Step 4. |
232
+ For open and deferred items, see [docs/ROADMAP.md](docs/ROADMAP.md).
241
233
 
242
234
  ### Runtime Contract
243
235
 
@@ -251,14 +243,14 @@ Incident history: `specs/HYPERMEM_INCIDENT_HISTORY.md`
251
243
  |---|---|---|---|
252
244
  | `index.ts` | ~1,340 | All | Facade — all public API |
253
245
  | `compositor.ts` | ~1,140 | L1-L4 | Prompt assembly + token budgeting + safety valve + window/cursor write |
254
- | `library-schema.ts` | ~780 | L4 | Library schema v5 + migrations |
246
+ | `library-schema.ts` | ~780 | L4 | Library schema v19 + migrations |
255
247
  | `background-indexer.ts` | ~680 | L2-L4 | LLM-powered extraction framework |
256
248
  | `vector-store.ts` | ~600 | L3 | Semantic search + embedding |
257
249
  | `hybrid-retrieval.ts` | ~450 | L3-L4 | FTS5 + KNN with Reciprocal Rank Fusion |
258
250
  | `fleet-store.ts` | ~440 | L4 | Fleet registry + capabilities |
259
251
  | `db.ts` | ~440 | - | Database manager + rotation |
260
252
  | `knowledge-graph.ts` | ~420 | L4 | DAG traversal + shortest path |
261
- | `redis.ts` | ~530 | L1 | Redis operations, window cache, cursor, fleet cache |
253
+ | `cache.ts` | ~700 | L1 | SQLite `:memory:` hot-cache operations, window cache, cursor, fleet cache |
262
254
  | `doc-chunker.ts` | ~400 | - | Section-aware markdown/file parser |
263
255
  | `work-store.ts` | ~400 | L4 | Work queue + FTS5 |
264
256
  | `provider-translator.ts` | ~390 | - | Neutral ↔ provider format conversion |
@@ -275,7 +267,7 @@ Incident history: `specs/HYPERMEM_INCIDENT_HISTORY.md`
275
267
  | `rate-limiter.ts` | ~230 | L3 | Token-bucket for embedding API |
276
268
  | `schema.ts` | ~200 | L2 | Messages schema + migrations |
277
269
  | `episode-store.ts` | ~180 | L4 | Significant event tracking |
278
- | `preference-store.ts` | ~170 | L4 | Operator behavioral patterns |
270
+ | `preference-store.ts` | ~170 | L4 | operator behavioral patterns |
279
271
  | `topic-store.ts` | ~160 | L4 | Cross-session thread tracking |
280
272
  | `plugin/src/index.ts` | ~590 | - | `hypercompositor` context engine plugin + window invalidation |
281
273
  | `memory-plugin/src/index.ts` | ~290 | - | `hypermem` memory slot plugin (memory_search via hybrid retrieval) |
@@ -287,12 +279,12 @@ _Test count reflects assertions, not individual test blocks. Suites contain inli
287
279
  | Suite | Key coverage |
288
280
  |---|---|
289
281
  | smoke | End-to-end create/write/read/close, provider translation |
290
- | redis-integration | Redis ops, slots, history limits, window cache, cursor, warming, dedup |
282
+ | redis-integration | Legacy suite name, covers hot-cache ops, slots, history limits, window cache, cursor, warming, dedup |
291
283
  | cross-agent | Cross-agent queries, fleet search, visibility tiers |
292
284
  | vector-search | Embedding, KNN, batch indexing |
293
285
  | library | All L4 collections (facts → desired state) |
294
286
  | compositor | Four-layer composition, budgets, providers, safety valve, Gate 1 |
295
- | fleet-cache | Redis fleet cache, hydration, cache-aside |
287
+ | fleet-cache | Fleet hot-cache hydration and cache-aside behavior |
296
288
  | rotation | DB rotation, auto-rotate, collision handling |
297
289
  | knowledge-graph | DAG traversal, shortest path, analytics |
298
290
  | rate-limiter | Token bucket, priority, timeout, embedder |
@@ -301,6 +293,6 @@ _Test count reflects assertions, not individual test blocks. Suites contain inli
301
293
  ## Dependencies
302
294
 
303
295
  - `node:sqlite` (Node 22+ built-in) — zero-dependency SQLite
304
- - `ioredis`Redis client
296
+ - No external cache service dependency hot cache is SQLite `:memory:`
305
297
  - `sqlite-vec` — optional, vector search extension
306
298
  - Ollama (localhost:11434) — optional, embedding generation
package/README.md CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  ---
8
8
 
9
- hypermem is a runtime context engine for OpenClaw agents.
9
+ hypermem is a SQLite-backed runtime context engine for OpenClaw agents.
10
10
 
11
11
  ```bash
12
12
  curl -fsSL https://raw.githubusercontent.com/PsiClawOps/hypermem/main/install.sh | bash
@@ -53,18 +53,18 @@ OpenClaw also ships compaction safeguards and hybrid file search. That's a solid
53
53
 
54
54
  ## hypermem
55
55
 
56
- Four storage layers, sub-millisecond retrieval, no external database services required. Runs in-process with local SQLite storage and local Nomic embeddings by default, with optional hosted embeddings for L3.
56
+ Four SQLite-backed memory databases, sub-millisecond retrieval, no external database services required. Runs in-process with local SQLite storage and local Nomic embeddings by default, with optional hosted embeddings for L3.
57
57
 
58
58
  | Layer | What it holds | Speed |
59
59
  |---|---|---|
60
- | **L1 In-memory** | What the agent needs right now. Identity, recent history, active state. | 0.08ms |
60
+ | **L1 SQLite `:memory:`** | What the agent needs right now. Identity, recent history, active state. | 0.08ms |
61
61
  | **L2 History** | Every conversation, queryable and concurrent-safe. Per-agent. | 0.13ms |
62
62
  | **L3 Semantic** | Finds related content even when the words don't match. | 0.29ms |
63
63
  | **L4 Knowledge** | Facts, wiki pages, episodes, preferences. Shared across agents. | 0.09ms |
64
64
 
65
65
  Everything is retained. Storage survives session boundaries. The retry logic decision from last week, the deployment preferences from last month, the architecture choices from day one: all queryable, all available for composition.
66
66
 
67
- **Session warming.** Before the first turn fires, hypermem pre-loads the agent's full working state from the in-memory SQLite cache: recent history, facts ranked by confidence and recency, active topic context, cached embeddings for fast semantic recall. The agent's first reply draws from everything that was in scope at the end of the last session. The agent picks up where it left off.
67
+ **Session warming.** Before the first turn fires, hypermem pre-loads the agent's full working state from its SQLite-backed memory stores and hot `:memory:` cache: recent history, facts ranked by confidence and recency, active topic context, cached embeddings for fast semantic recall. The agent's first reply draws from everything that was in scope at the end of the last session. The agent picks up where it left off.
68
68
 
69
69
  ---
70
70
 
@@ -77,7 +77,7 @@ Your agent has four layers of stored context, but what shows up in the prompt? H
77
77
  The hypercompositor queries all four layers in parallel on every turn and composes context within a fixed token budget. No transcript accumulates. No lossy transcript summarization. Amnesia isn't a storage problem; the memories exist, but nobody composed them into a coherent prompt. Compaction isn't inevitable; content that doesn't fit this turn stays in storage instead of being destroyed.
78
78
 
79
79
  **Bigger context windows don't help if you fill them with stale history.**
80
- 128k tokens of stale history and irrelevant memory is worse than 32k of precisely selected content. 10 budget categories, priority-ordered, greedy-fill. Every token in the prompt earned its spot.
80
+ 128k tokens of stale history and irrelevant memory is worse than 32k of precisely selected content. 9 budget categories, priority-ordered, greedy-fill. Every token in the prompt earned its spot.
81
81
 
82
82
  ### What the model actually sees
83
83
 
@@ -111,7 +111,7 @@ Standard hypercompositor
111
111
  ──────────────────────────────── ────────────────────────────────
112
112
  message → append to transcript message → detect active topic
113
113
  transcript full → trim oldest query 4 storage layers in parallel
114
- trimmed content → summarize (lossy) budget allocator: 10 slots, fixed cap
114
+ trimmed content → summarize (lossy) budget allocator: 9 slots, fixed cap
115
115
  send transcript to model tool compression by turn age
116
116
  model responds → append again keystone guard + hyperform profile
117
117
  composed prompt → model
@@ -217,7 +217,7 @@ Most memory systems store what was said. hypermem synthesizes what was learned.
217
217
 
218
218
  When a topic goes quiet, hypermem compiles the thread into a structured wiki page: decisions, open questions, artifacts, participants. When the topic resurfaces, the agent gets a compact structured summary rather than a raw history replay.
219
219
 
220
- OpenClaw 2026.4.7 ships memory wiki for structured storage. hypermem goes further: wiki pages are synthesized automatically and injected by the compositor within token budget.
220
+ OpenClaw 2026.4.7 ships memory wiki for structured storage. hypermem goes further: wiki pages are synthesized automatically and injected by the compositor within token budget, backed by SQLite memory databases instead of an external cache service.
221
221
 
222
222
  ### Subagents that hit the ground running
223
223
 
@@ -332,7 +332,7 @@ FTS5 queries use compound indexes on `agentId + sort key` and prefix optimizatio
332
332
  | Knowledge | Domain/key/value structured data with full-text search |
333
333
  | Episodes | Significant events with impact scores and participant tracking |
334
334
  | Topics | Cross-session thread tracking and synthesized wiki pages |
335
- | Preferences | Operator behavioral patterns |
335
+ | Preferences | operator behavioral patterns |
336
336
  | Fleet Registry | Agent registry with tier, org, and capability metadata |
337
337
  | System Registry | Service state and lifecycle |
338
338
  | Work Items | Work queue with status transitions and FTS5 |
@@ -383,7 +383,7 @@ Slot-level budget allocation is shown in the [hypercompositor diagram](#what-the
383
383
 
384
384
  ## Requirements
385
385
 
386
- **Current release: hypermem 0.5.6.** Changelog: [CHANGELOG.md](./CHANGELOG.md)
386
+ **Current release: hypermem 0.8.0.** Changelog: [CHANGELOG.md](./CHANGELOG.md)
387
387
 
388
388
  | Requirement | Version | Notes |
389
389
  |---|---|---|
@@ -396,11 +396,11 @@ SQLite is a library, not a service. All four layers run in-process with no exter
396
396
  **Runtime version constants** (importable from the package):
397
397
  ```typescript
398
398
  import {
399
- ENGINE_VERSION, // '0.5.6'
399
+ ENGINE_VERSION, // '0.8.0'
400
400
  MIN_NODE_VERSION, // '22.0.0'
401
401
  SQLITE_VEC_VERSION, // '0.1.9'
402
- MAIN_SCHEMA_VERSION, // 6 (hypermem.db)
403
- LIBRARY_SCHEMA_VERSION_EXPORT, // 12 (library.db)
402
+ MAIN_SCHEMA_VERSION, // 10 (messages.db)
403
+ LIBRARY_SCHEMA_VERSION_EXPORT, // 19 (library.db)
404
404
  } from '@psiclawops/hypermem';
405
405
  ```
406
406
 
@@ -440,6 +440,12 @@ If you prefer, hand the install to your OpenClaw agent:
440
440
 
441
441
  > "Install hypermem following INSTALL.md. I'm running a [solo / multi-agent] setup."
442
442
 
443
+ ### operator guides
444
+
445
+ - **[docs/MEMORY_MD_AUTHORING.md](./docs/MEMORY_MD_AUTHORING.md)**, how to keep `MEMORY.md` compact, durable, and reviewable
446
+ - **[docs/TUNING.md](./docs/TUNING.md)**, context assembly and output shaping profiles
447
+ - **[docs/MIGRATION_GUIDE.md](./docs/MIGRATION_GUIDE.md)**, moving data in from existing memory systems
448
+
443
449
  ### Tuning
444
450
 
445
451
  Two independent surfaces: **context assembly** (what fills the context window) and **output shaping** (how the model writes). Pick a profile first — most deployments adjust one or two settings on top.
@@ -493,7 +499,7 @@ Full reference: **[docs/TUNING.md](./docs/TUNING.md)**
493
499
 
494
500
  ## API
495
501
 
496
- > **Note:** The examples below use placeholder agent names (`my-agent`, `agent1`, etc.). Replace these with your actual agent IDs from your OpenClaw config. Single-agent installs typically use `main`. Multi-agent fleets use whatever IDs you've configured. See [INSTALL.md § "Configure your fleet"](./INSTALL.md#step-5--configure-your-fleet-multi-agent-only) for details.
502
+ > **Note:** The examples below use placeholder agent names (`my-agent`, `alice`, etc.). Replace these with your actual agent IDs from your OpenClaw config. Single-agent installs typically use `main`. Multi-agent fleets use whatever IDs you've configured. See [INSTALL.md § "Configure your fleet"](./INSTALL.md#step-5--configure-your-fleet-multi-agent-only) for details.
497
503
 
498
504
  ```typescript
499
505
  import { HyperMem } from '@psiclawops/hypermem';
@@ -572,7 +578,7 @@ The migration guide includes worked examples showing how to bring data from Open
572
578
 
573
579
  All examples default to dry-run. Nothing is written until you add `--apply`.
574
580
 
575
- Operator guide: **[docs/MIGRATION_GUIDE.md](./docs/MIGRATION_GUIDE.md)**
581
+ operator guide: **[docs/MIGRATION_GUIDE.md](./docs/MIGRATION_GUIDE.md)**
576
582
 
577
583
 
578
584
  ---
@@ -4,7 +4,7 @@
4
4
  *
5
5
  * Usage:
6
6
  * node bin/hypermem-status.mjs # full dashboard
7
- * node bin/hypermem-status.mjs --agent forge # scoped to one agent
7
+ * node bin/hypermem-status.mjs --agent carol # scoped to one agent
8
8
  * node bin/hypermem-status.mjs --json # machine-readable output
9
9
  * node bin/hypermem-status.mjs --health # health checks only (exit 1 on failure)
10
10
  *
@@ -17,8 +17,9 @@
17
17
  * - Observable: logs extraction stats for monitoring
18
18
  */
19
19
  import type { DatabaseSync } from 'node:sqlite';
20
- import type { IndexerConfig, SessionCursor } from './types.js';
20
+ import type { IndexerConfig, SessionCursor, MaintenanceTickDiagnostics } from './types.js';
21
21
  import { type DreamerConfig } from './dreaming-promoter.js';
22
+ import { type ContradictionResolutionPolicy } from './contradiction-resolution-policy.js';
22
23
  import type { VectorStore } from './vector-store.js';
23
24
  export interface IndexerStats {
24
25
  agentId: string;
@@ -29,6 +30,12 @@ export interface IndexerStats {
29
30
  knowledgeUpserted: number;
30
31
  /** Number of superseded fact vectors tombstoned from the vector index this tick. */
31
32
  tombstoned: number;
33
+ /** Number of contradiction audits recorded for review this tick. */
34
+ contradictionAuditsLogged: number;
35
+ /** Number of old facts auto-superseded via contradiction policy this tick. */
36
+ contradictionsAutoSuperseded: number;
37
+ /** Number of old facts auto-invalidated via contradiction policy this tick. */
38
+ contradictionsAutoInvalidated: number;
32
39
  elapsedMs: number;
33
40
  /** Number of messages that were post-cursor (unseen by model, high-signal priority). */
34
41
  postCursorMessages: number;
@@ -51,6 +58,8 @@ export declare class BackgroundIndexer {
51
58
  private getCursor?;
52
59
  private readonly config;
53
60
  private readonly dreamerConfig;
61
+ private readonly globalWritePolicy;
62
+ private readonly contradictionPolicy;
54
63
  private intervalHandle;
55
64
  private running;
56
65
  private vectorStore;
@@ -60,7 +69,9 @@ export declare class BackgroundIndexer {
60
69
  private consecutiveFailures;
61
70
  /** True when the indexer is running in backoff mode due to repeated failures. */
62
71
  private inBackoff;
63
- constructor(config?: Partial<IndexerConfig>, getMessageDb?: ((agentId: string) => DatabaseSync) | undefined, getLibraryDb?: (() => DatabaseSync) | undefined, listAgents?: (() => string[]) | undefined, getCursor?: CursorFetcher | undefined, dreamerConfig?: Partial<DreamerConfig>);
72
+ private readonly _conversationLastProcessed;
73
+ lastMaintenanceDiagnostics: MaintenanceTickDiagnostics | null;
74
+ constructor(config?: Partial<IndexerConfig>, getMessageDb?: ((agentId: string) => DatabaseSync) | undefined, getLibraryDb?: (() => DatabaseSync) | undefined, listAgents?: (() => string[]) | undefined, getCursor?: CursorFetcher | undefined, dreamerConfig?: Partial<DreamerConfig>, globalWritePolicy?: import('./types.js').GlobalWritePolicy, contradictionPolicy?: ContradictionResolutionPolicy);
64
75
  /**
65
76
  * Set the vector store for embedding new facts/episodes at index time.
66
77
  * Optional — if not set, indexer runs without embedding (FTS5-only mode).
@@ -146,5 +157,5 @@ export declare class BackgroundIndexer {
146
157
  * Create and start a background indexer connected to hypermem databases.
147
158
  * Used by the hook or a standalone daemon.
148
159
  */
149
- export declare function createIndexer(getMessageDb: (agentId: string) => DatabaseSync, getLibraryDb: () => DatabaseSync, listAgents: () => string[], config?: Partial<IndexerConfig>, getCursor?: CursorFetcher, vectorStore?: VectorStore, dreamerConfig?: Partial<DreamerConfig>): BackgroundIndexer;
160
+ export declare function createIndexer(getMessageDb: (agentId: string) => DatabaseSync, getLibraryDb: () => DatabaseSync, listAgents: () => string[], config?: Partial<IndexerConfig>, getCursor?: CursorFetcher, vectorStore?: VectorStore, dreamerConfig?: Partial<DreamerConfig>, globalWritePolicy?: import('./types.js').GlobalWritePolicy): BackgroundIndexer;
150
161
  //# sourceMappingURL=background-indexer.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"background-indexer.d.ts","sourceRoot":"","sources":["../src/background-indexer.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"background-indexer.d.ts","sourceRoot":"","sources":["../src/background-indexer.ts"],"names":[],"mappings":"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"}