@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 +21 -0
- package/README.md +8 -3
- package/index.md +5 -4
- package/memory/dream-engine.md +1 -1
- package/memory/memory-protocol.md +296 -12
- package/memory/reward-tracker.md +6 -3
- package/package.json +8 -5
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
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
-
|
|
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
|
|
package/memory/dream-engine.md
CHANGED
|
@@ -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
|
-
│
|
|
22
|
-
│
|
|
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.
|
|
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. **
|
|
66
|
-
|
|
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. **
|
|
69
|
-
6. **
|
|
70
|
-
7. **
|
|
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. **
|
|
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.
|
|
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.
|
package/memory/reward-tracker.md
CHANGED
|
@@ -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.
|
|
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/
|
|
38
|
-
"directory": "packages/
|
|
37
|
+
"url": "https://github.com/djd1m/dz-harness-hub.git",
|
|
38
|
+
"directory": "packages/@dzhechkov/keysarium-core"
|
|
39
39
|
},
|
|
40
|
-
"homepage": "https://github.com/
|
|
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
|
+
}
|