@dzhechkov/keysarium-core 1.0.0 → 1.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dzhechko
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -13,7 +13,7 @@ Think of it as the "operating system" for multi-agent workflows. You bring the d
13
13
  | Module | Purpose | Key Protocols |
14
14
  |--------|---------|---------------|
15
15
  | **governance/** | Structural rules and human checkpoints | Constitution, shard protocol, promise tags |
16
- | **memory/** | Persistent learning across executions | memory_query, memory_store, reward tracking, dream cycles |
16
+ | **memory/** | Persistent learning across executions | memory_query, memory_store, reward tracking, dream cycles, **2-tier index, COW branching, record lifecycle (v1.1)** |
17
17
  | **orchestration/** | Agent coordination and model routing | Queen protocol, 6 topologies, background workers, 3-tier routing |
18
18
  | **verification/** | Cryptographic integrity and isolation proofs | SHA-256 witness chain, judge attestation, audit trail |
19
19
  | **trust-tiers/** | Skill/artifact quality classification | 4-tier system (Advisory to Verified), promotion protocol |
@@ -71,9 +71,13 @@ keysarium-core has **zero dependencies** on either consumer package. Both consum
71
71
  - `shard-protocol.md` — How to create per-stage governance rules that are reloaded at each stage to prevent context drift
72
72
  - `checkpoint-protocol.md` — Human synchronization points with promise tags for machine-readable completion signals
73
73
 
74
- ### Memory
74
+ ### Memory (v1.1)
75
75
 
76
- - `memory-protocol.md` — Core `memory_query()` / `memory_store()` protocol for loading and persisting execution patterns with reward scores
76
+ - `memory-protocol.md` — Core `memory_query()` / `memory_store()` protocol with reward scores. **v1.1 enhancements:**
77
+ - **2-Tier Index** — `index.json` catalog for targeted reads instead of full directory scans
78
+ - **Brain Container Schema** — Portable brain exports with SHA-256 manifest and checksum verification
79
+ - **COW Branching** — Delta brain exports via JSON Patch (RFC 6902) for incremental knowledge transfer
80
+ - **Record Lifecycle** — HOT/WARM/COLD/PURGE tiering with automatic archive compression
77
81
  - `reward-tracker.md` — Analytics engine: per-stage averages, per-domain breakdowns, bottleneck detection, trend analysis
78
82
  - `dream-engine.md` — Background consolidation: builds concept graphs from accumulated data and generates cross-domain insights
79
83
 
@@ -120,6 +124,7 @@ keysarium-core was extracted from the [Keysarium](https://github.com/dzhechko/pr
120
124
  - **Ruflo** — 7-layer governance, 6 topologies, 3-tier model routing
121
125
  - **Agentic QE** — Trust tiers, reward-calibrated learning, dream cycles, PACT principles
122
126
  - **Quality Forge** — Portable brain containers, SHA-256 witness chains
127
+ - **RVF (RuVector Format)** — Manifest catalogs, COW branching, progressive loading, data tiering (concepts adapted to JSON-native implementation)
123
128
 
124
129
  ## License
125
130
 
package/index.md CHANGED
@@ -1,13 +1,13 @@
1
1
  # keysarium-core Module Index
2
2
 
3
- > Manifest of all modules in @dzhechkov/keysarium-core v1.0.0
3
+ > Manifest of all modules in @dzhechkov/keysarium-core v1.1.0
4
4
 
5
5
  ## Module Registry
6
6
 
7
7
  | Module | Version | Files | Trust Tier | Description |
8
8
  |--------|---------|-------|------------|-------------|
9
9
  | governance | 1.0 | 3 | Tier 1 — Structured | Constitution, shards, checkpoints |
10
- | memory | 1.0 | 3 | Tier 1 — Structured | Reward-calibrated learning + dream cycles |
10
+ | memory | 1.1 | 3 | Tier 1 — Structured | Reward-calibrated learning + dream cycles + index + tiering + COW |
11
11
  | orchestration | 1.0 | 4 | Tier 1 — Structured | Coordinator protocol + topologies + workers |
12
12
  | verification | 1.0 | 3 | Tier 1 — Structured | Hash chains + judge attestation + audit trail |
13
13
  | trust-tiers | 1.0 | 2 | Tier 1 — Structured | 4-tier classification + promotion |
@@ -27,7 +27,7 @@
27
27
  │ └── checkpoint-protocol.md ← v1.0 — Checkpoints + promise tags
28
28
 
29
29
  ├── memory/
30
- │ ├── memory-protocol.md ← v1.0 — memory_query + memory_store
30
+ │ ├── memory-protocol.md ← v1.1 — memory_query + memory_store + index + tiering + COW
31
31
  │ ├── reward-tracker.md ← v1.0 — Analytics + pattern detection
32
32
  │ └── dream-engine.md ← v1.0 — Background insight generation
33
33
 
@@ -59,6 +59,7 @@
59
59
  | Version | Date | Changes |
60
60
  |---------|------|---------|
61
61
  | 1.0 | 2026-03-01 | Initial extraction from Keysarium v1.1.x and lib/ protocols |
62
+ | 1.1 | 2026-03-02 | Memory module v1.1: 2-tier index, record lifecycle (HOT/WARM/COLD/PURGE), brain container manifest, COW branching |
62
63
 
63
64
  ## Dependency Graph
64
65
 
@@ -75,7 +76,7 @@ All modules are independent. A consumer may use any subset of modules without im
75
76
 
76
77
  ## Schema Compatibility
77
78
 
78
- All JSON schemas defined in this package use `"version": "1.0"` as a schema version field. Consumers should check this field and warn if it does not match expected version.
79
+ JSON schemas use `"version"` as a schema version field. Memory module uses `"1.1"`, all other modules use `"1.0"`. Consumers should check this field and warn if it does not match expected version. v1.1 readers MUST accept v1.0 files for backward compatibility.
79
80
 
80
81
  ## Terminology Mapping
81
82
 
@@ -55,7 +55,7 @@ The `{insights-root}` defaults to `.keysarium/insights/` but can be configured.
55
55
  2. Read reward-summary.json and domain-patterns.json if they exist.
56
56
  3. Scan all reward record files recursively.
57
57
  4. Exclude expired records.
58
- 5. Sort by reward DESC, then timestamp DESC.
58
+ 5. Sort by reward DESC, then usage_count DESC, then timestamp DESC. Records with higher usage_count carry more weight in concept graph construction.
59
59
  6. Take top 200 records.
60
60
  7. If fewer than 5 valid records, exit with status `insufficient_data`.
61
61
 
@@ -1,6 +1,8 @@
1
1
  # Memory Protocol — Reward-Calibrated Learning
2
2
 
3
3
  > Core protocol for persistent memory in multi-agent pipelines. Provides `memory_query()` before stages and `memory_store()` after stages.
4
+ >
5
+ > **Protocol version: 1.1** — adds Index, Brain Container Schema, COW Branching, and Record Lifecycle.
4
6
 
5
7
  ## Overview
6
8
 
@@ -13,13 +15,17 @@ All memory files live in a dedicated directory:
13
15
  ```
14
16
  {memory-root}/
15
17
  ├── config.json ← Global configuration
18
+ ├── index.json ← 2-tier index (v1.1)
16
19
  ├── _patterns/
17
20
  │ └── domain-patterns.json ← Detected domain patterns
18
21
  ├── _stats/
19
22
  │ └── reward-summary.json ← Aggregate statistics
20
23
  ├── {domain}/ ← Domain-specific subdirectory
21
- └── {project-slug}/
22
- └── {stage}_{timestamp}.json ← Individual reward records
24
+ ├── {project-slug}/
25
+ └── {stage}_{timestamp}.json ← HOT/WARM reward records
26
+ │ └── _archive/ ← COLD compressed records (v1.1)
27
+ │ └── {project-slug}/
28
+ │ └── {stage}_{timestamp}.json ← Archived records
23
29
  ```
24
30
 
25
31
  The `{memory-root}` defaults to `.keysarium/memory/` but can be configured.
@@ -30,7 +36,7 @@ The `{memory-root}` defaults to `.keysarium/memory/` but can be configured.
30
36
 
31
37
  ```json
32
38
  {
33
- "version": "1.0",
39
+ "version": "1.1",
34
40
  "retention_days": 90,
35
41
  "max_results_per_query": 10,
36
42
  "enabled": true,
@@ -40,10 +46,15 @@ The `{memory-root}` defaults to `.keysarium/memory/` but can be configured.
40
46
  "good": 0.7,
41
47
  "needs_work": 0.3,
42
48
  "failed": 0.0
43
- }
49
+ },
50
+ "tier_hot_days": 30,
51
+ "tier_warm_days": 90,
52
+ "tier_cold_days": 180
44
53
  }
45
54
  ```
46
55
 
56
+ **Tier fields (v1.1):** If `tier_hot_days` is absent, fall back to v1.0 behavior (flat `retention_days` with no tiering). When present, `retention_days` is ignored in favor of the tier thresholds.
57
+
47
58
  ## Protocol: memory_query(context)
48
59
 
49
60
  Call at the **start** of each pipeline stage to load relevant historical patterns.
@@ -62,12 +73,16 @@ Call at the **start** of each pipeline stage to load relevant historical pattern
62
73
  ### Algorithm
63
74
 
64
75
  1. **Check enabled:** Read `{memory-root}/config.json`. If `enabled` is false or directory does not exist, return empty result.
65
- 2. **Resolve path:** Construct `{memory-root}/{domain}/` (scan all project slugs, not just current).
66
- 3. **Scan records:** Read all `{stage}_*.json` files matching the requested stage across all slugs in the domain.
76
+ 2. **Read index (v1.1):** If `{memory-root}/index.json` exists, read it and filter `records` entries by `domain` + `stage`. Go to step 2a. If index does not exist, fall back to step 3 (v1.0 full scan).
77
+ - 2a. **Index hit:** If filtered record count ≤ `max_results_per_query`, read only those files by `file` path (Tier 2 targeted read). Go to step 4.
78
+ - 2b. **Index overflow:** If filtered count > limit, rank by `reward` from index entries, select top-N `file` paths, read those files. Go to step 4.
79
+ 3. **Full scan (fallback):** Construct `{memory-root}/{domain}/` (scan all project slugs). Read all `{stage}_*.json` files matching the requested stage.
67
80
  4. **Filter expired:** Exclude records where `expires_at < current_date`.
68
- 5. **Sort:** By `reward` DESC, then `timestamp` DESC.
69
- 6. **Limit:** Return top `max_results_per_query` records (default 10).
70
- 7. **Enrich:** Also load `{memory-root}/_patterns/domain-patterns.json` for matching domain patterns.
81
+ 5. **Archive old records (v1.1):** If tier config is present, check record ages. Move records older than `tier_cold_days` to `{memory-root}/{domain}/_archive/{slug}/` in compressed format (see Record Lifecycle). Update `index.json`.
82
+ 6. **Purge ancient records (v1.1):** Delete records from `_archive/` older than `tier_cold_days * 2` (default 360 days). Update `index.json`. In v1.0 mode, delete records where `expires_at < current_date`.
83
+ 7. **Sort:** By `reward` DESC, then `usage_count` DESC, then `timestamp` DESC. Records with higher usage_count are more battle-tested and should be preferred when rewards are equal.
84
+ 8. **Limit:** Return top `max_results_per_query` records (default 10). HOT and WARM records are preferred; COLD records are included only if result count < limit.
85
+ 9. **Enrich:** Also load `{memory-root}/_patterns/domain-patterns.json` for matching domain patterns.
71
86
 
72
87
  ### Output
73
88
 
@@ -103,6 +118,7 @@ Call at the **start** of each pipeline stage to load relevant historical pattern
103
118
  2. If `records` is non-empty, review the top 3 records for relevant approaches
104
119
  3. If `patterns` is non-empty, apply actionable advice to current stage execution
105
120
  4. If both are empty (first run), proceed normally
121
+ 5. **Increment usage_count:** For each record actually applied (top 3), increment `usage_count` in both the record file and the index entry. Records with higher usage_count are more proven — prioritize them in future queries.
106
122
 
107
123
  ## Protocol: memory_store(result, reward)
108
124
 
@@ -141,17 +157,23 @@ Call at each **checkpoint** after the human responds, to persist the stage outco
141
157
 
142
158
  1. **Ensure directory exists:** Create `{memory-root}/{domain}/{slug}/` if it does not exist.
143
159
  2. **Build record:** Construct full RewardRecord JSON from input.
144
- 3. **Compute expires_at:** `current_date + retention_days` (from config, default 90 days).
160
+ 3. **Compute expires_at:** `current_date + retention_days` (from config, default 90 days). If tier config is present, use `tier_cold_days * 2` instead.
145
161
  4. **Generate filename:** `{stage}_{ISO-timestamp}.json`.
146
162
  5. **Write file:** Write JSON to `{memory-root}/{domain}/{slug}/{filename}`.
147
- 6. **Log:** "Stored reward {reward} ({reward_label}) for {stage} of {slug}"
163
+ 6. **Update index (v1.1):** If `{memory-root}/index.json` exists (or tier config is present), update it:
164
+ - Add record entry to `records` map with key = record id, value = `{domain, stage, slug, reward, skill, tier: "hot", usage_count: 0, file, expires_at}`
165
+ - Increment `record_count`
166
+ - Update `by_domain`, `by_phase`, `by_skill` aggregates (count, avg_reward)
167
+ - Set `last_updated` to current timestamp
168
+ - If `index.json` does not exist, create it with this record as the first entry
169
+ 7. **Log:** "Stored reward {reward} ({reward_label}) for {stage} of {slug}"
148
170
 
149
171
  ### RewardRecord JSON Schema
150
172
 
151
173
  ```json
152
174
  {
153
175
  "id": "{slug}_{stage}_{timestamp}",
154
- "version": "1.0",
176
+ "version": "1.1",
155
177
  "timestamp": "ISO-8601",
156
178
  "project_slug": "{slug}",
157
179
  "domain": "{domain}",
@@ -164,6 +186,7 @@ Call at each **checkpoint** after the human responds, to persist the stage outco
164
186
  "context": { ... },
165
187
  "outcome": { ... },
166
188
  "promise_tag": "{PROMISE_TAG}",
189
+ "usage_count": 0,
167
190
  "expires_at": "ISO-8601"
168
191
  }
169
192
  ```
@@ -195,3 +218,264 @@ To prevent unbounded growth:
195
218
  | Malformed JSON file | Skip that record, log warning, continue |
196
219
  | Write fails (permissions, disk) | Log error, continue pipeline without storing |
197
220
  | Domain not in `known_domains` | Use "unknown" as domain directory |
221
+ | `index.json` corrupted | Delete and rebuild on next `memory_store()` call |
222
+ | Archive directory write fails | Log warning, keep record in active directory |
223
+
224
+ ---
225
+
226
+ ## Index Protocol (v1.1)
227
+
228
+ The index file provides a compact catalog of all records, enabling targeted file reads instead of full directory scans.
229
+
230
+ ### index.json Schema
231
+
232
+ ```json
233
+ {
234
+ "version": "1.0",
235
+ "last_updated": "ISO-8601",
236
+ "record_count": 47,
237
+ "by_domain": {
238
+ "{domain}": {
239
+ "count": 23,
240
+ "slugs": ["{slug-1}", "{slug-2}"],
241
+ "avg_reward": 0.82
242
+ }
243
+ },
244
+ "by_stage": {
245
+ "{stage-id}": {
246
+ "count": 12,
247
+ "avg_reward": 0.65
248
+ }
249
+ },
250
+ "by_skill": {
251
+ "{skill-name}": {
252
+ "count": 10,
253
+ "avg_reward": 0.78
254
+ }
255
+ },
256
+ "records": {
257
+ "{record-id}": {
258
+ "domain": "{domain}",
259
+ "stage": "{stage-id}",
260
+ "slug": "{slug}",
261
+ "reward": 0.7,
262
+ "skill": "{skill-name}",
263
+ "tier": "hot|warm|cold",
264
+ "usage_count": 0,
265
+ "file": "{domain}/{slug}/{stage}_{timestamp}.json",
266
+ "expires_at": "ISO-8601"
267
+ }
268
+ }
269
+ }
270
+ ```
271
+
272
+ ### Index Update Rules
273
+
274
+ 1. **On `memory_store()`:** Add new record entry, update aggregates.
275
+ 2. **On archive (WARM→COLD):** Update `tier` to `"cold"`, change `file` path to `_archive/` location.
276
+ 3. **On purge:** Remove record entry, decrement aggregates.
277
+ 4. **Rebuild:** If `index.json` is missing or corrupted, `memory_store()` creates a fresh index with the new record. Full rebuild requires scanning all files (expensive, avoid if possible).
278
+
279
+ ### Fallback Behavior
280
+
281
+ If `index.json` does not exist, `memory_query()` falls back to the v1.0 full-scan algorithm. This ensures backward compatibility with existing memory directories that predate v1.1.
282
+
283
+ ---
284
+
285
+ ## Brain Container Schema (v1.1)
286
+
287
+ Defines the portable brain export format with an integrity manifest.
288
+
289
+ ### Container Structure
290
+
291
+ ```json
292
+ {
293
+ "version": "1.1",
294
+ "format": "keysarium-brain",
295
+ "manifest": {
296
+ "created_at": "ISO-8601",
297
+ "source_project": "{project-name}",
298
+ "source_branch": "{git-branch}",
299
+ "checksum": "sha256:{64-hex-chars}",
300
+ "record_count": 47,
301
+ "domains": ["{domain-1}", "{domain-2}"],
302
+ "skills": ["{skill-1}", "{skill-2}"],
303
+ "research_count": 5,
304
+ "harvest_pattern_count": 23,
305
+ "size_bytes": 148200,
306
+ "parent": null,
307
+ "parent_checksum": null,
308
+ "delta_type": null
309
+ },
310
+ "skills": { },
311
+ "domain_patterns": { },
312
+ "research_summaries": [ ],
313
+ "harvest_patterns": [ ],
314
+ "pipeline_metrics": { },
315
+ "reward_data": { },
316
+ "metadata": { }
317
+ }
318
+ ```
319
+
320
+ ### Manifest Fields
321
+
322
+ | Field | Type | Description |
323
+ |-------|------|-------------|
324
+ | `created_at` | string | ISO-8601 timestamp of export |
325
+ | `source_project` | string | Project name from package.json or directory name |
326
+ | `source_branch` | string | Current git branch at export time |
327
+ | `checksum` | string | SHA-256 of the JSON-serialized content (all sections except `manifest`) |
328
+ | `record_count` | integer | Total records across all sections |
329
+ | `domains` | string[] | List of domains present in export |
330
+ | `skills` | string[] | List of skill names present |
331
+ | `research_count` | integer | Number of research summaries |
332
+ | `harvest_pattern_count` | integer | Number of harvest patterns |
333
+ | `size_bytes` | integer | Approximate size of the content payload |
334
+ | `parent` | string\|null | Filename of parent brain container (COW mode) |
335
+ | `parent_checksum` | string\|null | SHA-256 of parent container (COW mode) |
336
+ | `delta_type` | string\|null | `"rfc6902"` if this is a delta container |
337
+
338
+ ### Checksum Computation
339
+
340
+ 1. Serialize all sections except `manifest` as a JSON string (sorted keys, no extra whitespace)
341
+ 2. Compute SHA-256 of the resulting string
342
+ 3. Store as `"sha256:{64-hex-chars}"`
343
+
344
+ ### Version Negotiation
345
+
346
+ | Reader Version | File Version | Behavior |
347
+ |---------------|-------------|----------|
348
+ | v1.1 | v1.0 | Accept. Manifest will be absent — proceed without integrity check |
349
+ | v1.1 | v1.1 | Accept. Read manifest, verify checksum |
350
+ | v1.0 | v1.1 | Accept. Ignore unknown `manifest` field, read sections normally |
351
+ | Any | Unknown | Warn, attempt best-effort import |
352
+
353
+ ---
354
+
355
+ ## COW Branching Protocol (v1.1)
356
+
357
+ Copy-On-Write branching for efficient delta brain exports. A child container stores only the differences from a parent container.
358
+
359
+ ### Delta Container Structure
360
+
361
+ ```json
362
+ {
363
+ "version": "1.1",
364
+ "format": "keysarium-brain",
365
+ "manifest": {
366
+ "created_at": "ISO-8601",
367
+ "source_project": "{project-name}",
368
+ "source_branch": "{git-branch}",
369
+ "checksum": "sha256:{hash-of-patch-array}",
370
+ "record_count": 3,
371
+ "domains": ["{domains-in-delta}"],
372
+ "skills": [],
373
+ "research_count": 1,
374
+ "harvest_pattern_count": 2,
375
+ "size_bytes": 4200,
376
+ "parent": "{parent-filename}",
377
+ "parent_checksum": "sha256:{parent-hash}",
378
+ "delta_type": "rfc6902"
379
+ },
380
+ "patch": [
381
+ { "op": "add", "path": "/research_summaries/-", "value": { } },
382
+ { "op": "replace", "path": "/skills/{name}/trust_tier", "value": 2 },
383
+ { "op": "add", "path": "/harvest_patterns/-", "value": { } }
384
+ ]
385
+ }
386
+ ```
387
+
388
+ ### Export Protocol (delta mode)
389
+
390
+ 1. Load parent brain container from the specified path
391
+ 2. Verify parent checksum matches `manifest.checksum` of the parent file
392
+ 3. Build current full brain container (in memory, not written to disk)
393
+ 4. Compute JSON Patch (RFC 6902) between parent and current
394
+ 5. If patch is empty → log "No changes since parent" and skip export
395
+ 6. Write delta container with `manifest.parent` set to parent filename
396
+
397
+ ### Import Protocol (delta mode)
398
+
399
+ 1. Read delta container; detect `manifest.parent != null`
400
+ 2. Resolve parent file:
401
+ - Look in the same directory as the delta file
402
+ - Look in project root
403
+ - If not found → prompt user for path
404
+ - If still not found → offer partial import (self-contained `add` operations only)
405
+ 3. If parent is also a delta → resolve recursively (chain). Warn if chain depth > 3
406
+ 4. Load parent (or resolved chain base), apply JSON Patch operations in order
407
+ 5. Verify result checksum if available
408
+ 6. Proceed with standard import (selective sections, merge strategy)
409
+
410
+ ### JSON Patch Operations (RFC 6902)
411
+
412
+ | Operation | Usage |
413
+ |-----------|-------|
414
+ | `add` | New records (research summaries, harvest patterns, skills) |
415
+ | `replace` | Updated values (trust tier upgrade, new BTO score) |
416
+ | `remove` | Deleted entries (rare, mainly cleanup) |
417
+ | `move` | Renamed entries (rare) |
418
+ | `copy` | Duplicated entries (rare) |
419
+ | `test` | Pre-condition assertions (optional, for safety) |
420
+
421
+ ### Chain Depth Limit
422
+
423
+ Delta containers may reference another delta as parent, forming a chain. Import MUST warn if chain depth exceeds 3. Recommended: periodically re-export a full container to reset the chain.
424
+
425
+ ---
426
+
427
+ ## Record Lifecycle (v1.1)
428
+
429
+ Records transition through tiers based on age, trading detail for storage efficiency.
430
+
431
+ ### Tier Definitions
432
+
433
+ | Tier | Age Range | Location | Fields | Purpose |
434
+ |------|-----------|----------|--------|---------|
435
+ | **HOT** | 0 – `tier_hot_days` (default 30) | `{domain}/{slug}/` | All fields | Active learning, full context |
436
+ | **WARM** | `tier_hot_days` – `tier_warm_days` (default 90) | `{domain}/{slug}/` | All fields | Available but deprioritized in search |
437
+ | **COLD** | `tier_warm_days` – `tier_cold_days` (default 180) | `{domain}/_archive/{slug}/` | Compressed | Long-term pattern retention |
438
+ | **PURGE** | > `tier_cold_days` | Deleted | — | Cleanup |
439
+
440
+ ### COLD Record Schema (compressed)
441
+
442
+ ```json
443
+ {
444
+ "id": "{original-id}",
445
+ "stage": "{stage-id}",
446
+ "domain": "{domain}",
447
+ "slug": "{slug}",
448
+ "reward": 0.7,
449
+ "reward_label": "good",
450
+ "skill_used": "{skill}",
451
+ "promise_tag": "{PROMISE_TAG}",
452
+ "usage_count": 0,
453
+ "summary": "{first 200 chars of reward_reason + checkpoint_response}",
454
+ "archived_at": "ISO-8601",
455
+ "original_timestamp": "ISO-8601"
456
+ }
457
+ ```
458
+
459
+ ### Archive Procedure
460
+
461
+ Triggered during `memory_query()` step 5:
462
+
463
+ 1. For each record in the query result set, compute age = `current_date - timestamp`
464
+ 2. If age > `tier_warm_days` and record is not already archived:
465
+ a. Read full record
466
+ b. Generate `summary` from `reward_reason` + `outcome.checkpoint_response` (truncate to 200 chars)
467
+ c. Write compressed record to `{memory-root}/{domain}/_archive/{slug}/{filename}`
468
+ d. Delete original file from active directory
469
+ e. Update `index.json`: set `tier` to `"cold"`, update `file` path
470
+
471
+ ### Purge Procedure
472
+
473
+ Triggered during `memory_query()` step 6:
474
+
475
+ 1. Scan `{domain}/_archive/` for records where age > `tier_cold_days`
476
+ 2. Delete those files
477
+ 3. Remove entries from `index.json`
478
+
479
+ ### Backward Compatibility
480
+
481
+ If `tier_hot_days` is NOT present in `config.json`, the entire lifecycle system is disabled. Records use the v1.0 flat `retention_days` for expiration. No archiving occurs. This ensures existing memory directories work without changes.
@@ -82,12 +82,14 @@ Group records by `skill_used` and cross-reference with domain:
82
82
  "{skill-name}": {
83
83
  "overall_avg": 0.74,
84
84
  "total_runs": 15,
85
+ "total_usage_count": 42,
85
86
  "by_domain": {
86
- "{domain-a}": { "avg": 0.65, "runs": 8 },
87
- "{domain-b}": { "avg": 0.85, "runs": 7 }
87
+ "{domain-a}": { "avg": 0.65, "runs": 8, "usage_count": 18 },
88
+ "{domain-b}": { "avg": 0.85, "runs": 7, "usage_count": 24 }
88
89
  },
89
90
  "best_domain": "{domain}",
90
- "worst_domain": "{domain}"
91
+ "worst_domain": "{domain}",
92
+ "most_reused_domain": "{domain}"
91
93
  }
92
94
  }
93
95
  ```
@@ -106,6 +108,7 @@ Analyze accumulated data to detect actionable patterns.
106
108
  | Improving Trend | Trend = "improving" for stage in domain | "{stage} quality is improving in {domain}" |
107
109
  | Degrading Trend | Trend = "degrading" for stage in domain | "{stage} quality is degrading in {domain} -- investigate" |
108
110
  | Time Overhead | Stage avg iterations > 2.0 in domain | "{domain} projects require more iterations in {stage}" |
111
+ | High Reuse | Record usage_count >= 5 | "Pattern from {slug}/{stage} is highly reused ({count} times) — consider promoting to a rule" |
109
112
 
110
113
  **Confidence Calculation:**
111
114
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dzhechkov/keysarium-core",
3
- "version": "1.0.0",
3
+ "version": "1.1.1",
4
4
  "description": "Core framework for multi-agent pipelines: governance, memory, orchestration, verification, trust tiers, and multi-platform support",
5
5
  "main": "index.md",
6
6
  "files": [
@@ -34,11 +34,14 @@
34
34
  },
35
35
  "repository": {
36
36
  "type": "git",
37
- "url": "https://github.com/dzhechko/product-keysarium-2026",
38
- "directory": "packages/dz-keysarium-core"
37
+ "url": "https://github.com/djd1m/dz-harness-hub.git",
38
+ "directory": "packages/@dzhechkov/keysarium-core"
39
39
  },
40
- "homepage": "https://github.com/dzhechko/product-keysarium-2026#keysarium-core",
40
+ "homepage": "https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/keysarium-core#readme",
41
41
  "bugs": {
42
42
  "url": "https://github.com/dzhechko/product-keysarium-2026/issues"
43
+ },
44
+ "publishConfig": {
45
+ "access": "public"
43
46
  }
44
- }
47
+ }