agent-working-memory 0.10.0 → 0.12.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 (136) hide show
  1. package/README.md +118 -19
  2. package/dist/adapters/claude-code.d.ts.map +1 -1
  3. package/dist/adapters/claude-code.js +63 -3
  4. package/dist/adapters/claude-code.js.map +1 -1
  5. package/dist/adapters/common.d.ts.map +1 -1
  6. package/dist/adapters/common.js +329 -302
  7. package/dist/adapters/common.js.map +1 -1
  8. package/dist/api/routes.d.ts.map +1 -1
  9. package/dist/api/routes.js +31 -8
  10. package/dist/api/routes.js.map +1 -1
  11. package/dist/cli/migrate.js +29 -29
  12. package/dist/cli.js +82 -2
  13. package/dist/cli.js.map +1 -1
  14. package/dist/coordination/circuit-breaker.js +23 -23
  15. package/dist/coordination/routes.d.ts.map +1 -1
  16. package/dist/coordination/routes.js +174 -170
  17. package/dist/coordination/routes.js.map +1 -1
  18. package/dist/core/embeddings.d.ts.map +1 -1
  19. package/dist/core/embeddings.js +3 -0
  20. package/dist/core/embeddings.js.map +1 -1
  21. package/dist/core/entity-extract.d.ts +3 -0
  22. package/dist/core/entity-extract.d.ts.map +1 -0
  23. package/dist/core/entity-extract.js +47 -0
  24. package/dist/core/entity-extract.js.map +1 -0
  25. package/dist/core/salience.d.ts.map +1 -1
  26. package/dist/core/salience.js +14 -2
  27. package/dist/core/salience.js.map +1 -1
  28. package/dist/core/whoami.d.ts +24 -0
  29. package/dist/core/whoami.d.ts.map +1 -0
  30. package/dist/core/whoami.js +66 -0
  31. package/dist/core/whoami.js.map +1 -0
  32. package/dist/core/write-pipeline.d.ts +9 -0
  33. package/dist/core/write-pipeline.d.ts.map +1 -1
  34. package/dist/core/write-pipeline.js +109 -68
  35. package/dist/core/write-pipeline.js.map +1 -1
  36. package/dist/core/write-telemetry.d.ts +33 -0
  37. package/dist/core/write-telemetry.d.ts.map +1 -0
  38. package/dist/core/write-telemetry.js +110 -0
  39. package/dist/core/write-telemetry.js.map +1 -0
  40. package/dist/engine/activation.d.ts +22 -12
  41. package/dist/engine/activation.d.ts.map +1 -1
  42. package/dist/engine/activation.js +133 -17
  43. package/dist/engine/activation.js.map +1 -1
  44. package/dist/engine/consolidation-scheduler.d.ts +1 -1
  45. package/dist/engine/consolidation-scheduler.js +1 -1
  46. package/dist/engine/consolidation.d.ts +1 -0
  47. package/dist/engine/consolidation.d.ts.map +1 -1
  48. package/dist/engine/consolidation.js +18 -0
  49. package/dist/engine/consolidation.js.map +1 -1
  50. package/dist/engine/eval.d.ts.map +1 -1
  51. package/dist/engine/eval.js +5 -1
  52. package/dist/engine/eval.js.map +1 -1
  53. package/dist/index.js +21 -2
  54. package/dist/index.js.map +1 -1
  55. package/dist/mcp.d.ts +2 -1
  56. package/dist/mcp.d.ts.map +1 -1
  57. package/dist/mcp.js +212 -97
  58. package/dist/mcp.js.map +1 -1
  59. package/dist/onboard/index.d.ts +68 -0
  60. package/dist/onboard/index.d.ts.map +1 -0
  61. package/dist/onboard/index.js +265 -0
  62. package/dist/onboard/index.js.map +1 -0
  63. package/dist/recipes/index.d.ts +57 -0
  64. package/dist/recipes/index.d.ts.map +1 -0
  65. package/dist/recipes/index.js +81 -0
  66. package/dist/recipes/index.js.map +1 -0
  67. package/dist/storage/pglite-schema.d.ts.map +1 -1
  68. package/dist/storage/pglite-schema.js +170 -143
  69. package/dist/storage/pglite-schema.js.map +1 -1
  70. package/dist/storage/pglite.d.ts +5 -0
  71. package/dist/storage/pglite.d.ts.map +1 -1
  72. package/dist/storage/pglite.js +180 -138
  73. package/dist/storage/pglite.js.map +1 -1
  74. package/dist/storage/postgres.d.ts +5 -0
  75. package/dist/storage/postgres.d.ts.map +1 -1
  76. package/dist/storage/postgres.js +44 -2
  77. package/dist/storage/postgres.js.map +1 -1
  78. package/dist/storage/sqlite.d.ts +9 -0
  79. package/dist/storage/sqlite.d.ts.map +1 -1
  80. package/dist/storage/sqlite.js +394 -326
  81. package/dist/storage/sqlite.js.map +1 -1
  82. package/dist/types/engram.d.ts +14 -0
  83. package/dist/types/engram.d.ts.map +1 -1
  84. package/dist/types/engram.js.map +1 -1
  85. package/dist/version.d.ts +2 -0
  86. package/dist/version.d.ts.map +1 -0
  87. package/dist/version.js +27 -0
  88. package/dist/version.js.map +1 -0
  89. package/package.json +9 -1
  90. package/src/adapters/claude-code.ts +66 -3
  91. package/src/adapters/common.ts +538 -511
  92. package/src/api/index.ts +3 -3
  93. package/src/api/routes.ts +999 -970
  94. package/src/cli/migrate.ts +307 -307
  95. package/src/cli.ts +77 -2
  96. package/src/coordination/circuit-breaker.ts +83 -83
  97. package/src/coordination/failure-modes.ts +50 -50
  98. package/src/coordination/routes.ts +2155 -2150
  99. package/src/core/decay.ts +63 -63
  100. package/src/core/embeddings.ts +113 -110
  101. package/src/core/entity-extract.ts +47 -0
  102. package/src/core/index.ts +5 -5
  103. package/src/core/logger.ts +36 -36
  104. package/src/core/ml-worker-entry.ts +194 -194
  105. package/src/core/ml-worker.ts +281 -281
  106. package/src/core/query-expander.ts +122 -122
  107. package/src/core/reranker.ts +119 -119
  108. package/src/core/salience.ts +529 -514
  109. package/src/core/whoami.ts +92 -0
  110. package/src/core/write-pipeline.ts +60 -8
  111. package/src/core/write-telemetry.ts +131 -0
  112. package/src/engine/activation.ts +1468 -1369
  113. package/src/engine/confidence.ts +120 -120
  114. package/src/engine/consolidation-scheduler.ts +242 -242
  115. package/src/engine/consolidation.ts +887 -869
  116. package/src/engine/eval.ts +107 -102
  117. package/src/engine/eviction.ts +101 -101
  118. package/src/engine/index.ts +8 -8
  119. package/src/engine/retraction.ts +366 -366
  120. package/src/engine/staging.ts +74 -74
  121. package/src/index.ts +248 -226
  122. package/src/mcp.ts +1341 -1211
  123. package/src/onboard/index.ts +298 -0
  124. package/src/recipes/index.ts +125 -0
  125. package/src/storage/index.ts +3 -3
  126. package/src/storage/pglite-schema.ts +193 -166
  127. package/src/storage/pglite.ts +1420 -1372
  128. package/src/storage/postgres.ts +50 -2
  129. package/src/storage/sqlite.ts +1936 -1861
  130. package/src/storage/store.ts +80 -80
  131. package/src/types/agent.ts +67 -67
  132. package/src/types/checkpoint.ts +46 -46
  133. package/src/types/engram.ts +22 -0
  134. package/src/types/eval.ts +100 -100
  135. package/src/types/index.ts +6 -6
  136. package/src/version.ts +26 -0
@@ -1,80 +1,80 @@
1
- // Copyright 2026 Robert Winter / Complete Ideas
2
- // SPDX-License-Identifier: Apache-2.0
3
- /**
4
- * Backend-agnostic storage contract for AWM.
5
- *
6
- * AWM 0.8.x introduces a pluggable storage layer:
7
- * - SQLiteEngramStore: better-sqlite3 + FTS5 + BLOB embeddings (current default)
8
- * - PGliteEngramStore: @electric-sql/pglite + pgvector + tsvector (opt-in via
9
- * `AWM_STORE_BACKEND=pglite`, planned default in 0.9.x)
10
- * - PostgresEngramStore: real Postgres backend for scale (planned, post-1.0)
11
- *
12
- * All backends provide the same public surface — defined here as `IEngramStore`.
13
- * The cognitive engines (activation, consolidation, Hebbian, eviction, etc.)
14
- * accept `IEngramStore` and work against any conforming backend.
15
- *
16
- * The interface is derived from the SQLite implementation via TypeScript's
17
- * `Omit<>` so it stays in sync automatically. SQLite-specific methods
18
- * (DB handle access, WAL checkpointing, slim-cache management, integrity
19
- * checks) are excluded — these are implementation-internal and don't belong
20
- * in a backend-agnostic contract.
21
- *
22
- * Future backends MUST implement every method on `IEngramStore`. They MAY
23
- * additionally expose backend-specific methods (e.g., PGlite-specific tooling,
24
- * Postgres pool management) — those are not part of the contract.
25
- */
26
-
27
- import type { EngramStore as SqliteEngramStore } from './sqlite.js';
28
-
29
- /**
30
- * Backend-specific methods on SqliteEngramStore that are NOT part of the
31
- * shared contract. Other backends may provide functionally-similar methods
32
- * under different names or not at all.
33
- */
34
- type SqliteSpecificMethods =
35
- | 'getDb' // Returns better-sqlite3 Database — SQLite-only API
36
- | 'integrityCheck' // SQLite PRAGMA integrity_check
37
- | 'walCheckpoint' // SQLite WAL checkpoint
38
- | 'stopWalCheckpointTimer'
39
- | 'backup' // SQLite backup API; PGlite/Postgres use pg_dump
40
- | 'warmSlimCache' // In-memory cache pre-population (SQLite-specific perf opt)
41
- | 'resetSlimCache'
42
- | 'getSlimCacheStats'
43
- | 'transaction'; // SQLite sync transaction helper — PGlite uses withTransaction
44
-
45
- /**
46
- * MaybePromise — covariant union that lets sync and async backends share one contract.
47
- *
48
- * Engines `await` every store call. `await T` resolves to T immediately when
49
- * the backend is sync (SQLite, returning bare values) and resolves the Promise
50
- * when the backend is async (PGlite). Both shapes satisfy the same interface.
51
- */
52
- type MaybePromise<T> = T | Promise<T>;
53
-
54
- /**
55
- * Turn every method return type R into `MaybePromise<Awaited<R>>` so the
56
- * contract accepts both sync and async backends.
57
- */
58
- type AsyncifyMethods<T> = {
59
- [K in keyof T]: T[K] extends (...args: infer A) => infer R
60
- ? (...args: A) => MaybePromise<Awaited<R>>
61
- : T[K];
62
- };
63
-
64
- /**
65
- * The backend-agnostic storage contract.
66
- *
67
- * Any class with this shape can be used as the EngramStore for the AWM
68
- * cognitive engines. New backends should `implements IEngramStore` to get
69
- * compile-time enforcement of the full surface.
70
- */
71
- export type IEngramStore = AsyncifyMethods<Omit<SqliteEngramStore, SqliteSpecificMethods>>;
72
-
73
- /**
74
- * Convenience type-only re-export so consumers can `import type { EngramStore }`
75
- * from this module and get the backend-agnostic contract instead of the
76
- * SQLite-specific class. Existing imports from `'../storage/sqlite.js'`
77
- * continue to work and resolve to the SQLite class (which is a structural
78
- * supertype of IEngramStore).
79
- */
80
- export type EngramStore = IEngramStore;
1
+ // Copyright 2026 Robert Winter / Complete Ideas
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ /**
4
+ * Backend-agnostic storage contract for AWM.
5
+ *
6
+ * AWM 0.8.x introduces a pluggable storage layer:
7
+ * - SQLiteEngramStore: better-sqlite3 + FTS5 + BLOB embeddings (current default)
8
+ * - PGliteEngramStore: @electric-sql/pglite + pgvector + tsvector (opt-in via
9
+ * `AWM_STORE_BACKEND=pglite`, planned default in 0.9.x)
10
+ * - PostgresEngramStore: real Postgres backend for scale (planned, post-1.0)
11
+ *
12
+ * All backends provide the same public surface — defined here as `IEngramStore`.
13
+ * The cognitive engines (activation, consolidation, Hebbian, eviction, etc.)
14
+ * accept `IEngramStore` and work against any conforming backend.
15
+ *
16
+ * The interface is derived from the SQLite implementation via TypeScript's
17
+ * `Omit<>` so it stays in sync automatically. SQLite-specific methods
18
+ * (DB handle access, WAL checkpointing, slim-cache management, integrity
19
+ * checks) are excluded — these are implementation-internal and don't belong
20
+ * in a backend-agnostic contract.
21
+ *
22
+ * Future backends MUST implement every method on `IEngramStore`. They MAY
23
+ * additionally expose backend-specific methods (e.g., PGlite-specific tooling,
24
+ * Postgres pool management) — those are not part of the contract.
25
+ */
26
+
27
+ import type { EngramStore as SqliteEngramStore } from './sqlite.js';
28
+
29
+ /**
30
+ * Backend-specific methods on SqliteEngramStore that are NOT part of the
31
+ * shared contract. Other backends may provide functionally-similar methods
32
+ * under different names or not at all.
33
+ */
34
+ type SqliteSpecificMethods =
35
+ | 'getDb' // Returns better-sqlite3 Database — SQLite-only API
36
+ | 'integrityCheck' // SQLite PRAGMA integrity_check
37
+ | 'walCheckpoint' // SQLite WAL checkpoint
38
+ | 'stopWalCheckpointTimer'
39
+ | 'backup' // SQLite backup API; PGlite/Postgres use pg_dump
40
+ | 'warmSlimCache' // In-memory cache pre-population (SQLite-specific perf opt)
41
+ | 'resetSlimCache'
42
+ | 'getSlimCacheStats'
43
+ | 'transaction'; // SQLite sync transaction helper — PGlite uses withTransaction
44
+
45
+ /**
46
+ * MaybePromise — covariant union that lets sync and async backends share one contract.
47
+ *
48
+ * Engines `await` every store call. `await T` resolves to T immediately when
49
+ * the backend is sync (SQLite, returning bare values) and resolves the Promise
50
+ * when the backend is async (PGlite). Both shapes satisfy the same interface.
51
+ */
52
+ type MaybePromise<T> = T | Promise<T>;
53
+
54
+ /**
55
+ * Turn every method return type R into `MaybePromise<Awaited<R>>` so the
56
+ * contract accepts both sync and async backends.
57
+ */
58
+ type AsyncifyMethods<T> = {
59
+ [K in keyof T]: T[K] extends (...args: infer A) => infer R
60
+ ? (...args: A) => MaybePromise<Awaited<R>>
61
+ : T[K];
62
+ };
63
+
64
+ /**
65
+ * The backend-agnostic storage contract.
66
+ *
67
+ * Any class with this shape can be used as the EngramStore for the AWM
68
+ * cognitive engines. New backends should `implements IEngramStore` to get
69
+ * compile-time enforcement of the full surface.
70
+ */
71
+ export type IEngramStore = AsyncifyMethods<Omit<SqliteEngramStore, SqliteSpecificMethods>>;
72
+
73
+ /**
74
+ * Convenience type-only re-export so consumers can `import type { EngramStore }`
75
+ * from this module and get the backend-agnostic contract instead of the
76
+ * SQLite-specific class. Existing imports from `'../storage/sqlite.js'`
77
+ * continue to work and resolve to the SQLite class (which is a structural
78
+ * supertype of IEngramStore).
79
+ */
80
+ export type EngramStore = IEngramStore;
@@ -1,67 +1,67 @@
1
- // Copyright 2026 Robert Winter / Complete Ideas
2
- // SPDX-License-Identifier: Apache-2.0
3
- /**
4
- * Agent — a consciousness boundary.
5
- * Each agent has its own isolated memory space with capacity budgets.
6
- */
7
-
8
- export interface Agent {
9
- id: string;
10
- name: string;
11
- createdAt: Date;
12
- config: AgentConfig;
13
- }
14
-
15
- export interface AgentConfig {
16
- // Salience filter thresholds
17
- salienceThreshold: number; // Below this → discard
18
- stagingThreshold: number; // Below salience but above this → staging buffer
19
- stagingTtlMs: number; // Default TTL for staging entries
20
-
21
- // Capacity budgets (eviction triggers when exceeded)
22
- maxActiveEngrams: number; // Hard cap on active memory
23
- maxStagingEngrams: number; // Hard cap on staging buffer
24
- maxEdgesPerEngram: number; // Prevent graph explosion
25
-
26
- // Activation pipeline tuning
27
- activationLimit: number; // Max results per activation query
28
- hebbianRate: number; // Learning rate for association strengthening
29
- decayExponent: number; // ACT-R d parameter (default 0.5)
30
- edgeDecayHalfLifeDays: number; // How fast unused edges weaken
31
-
32
- // Connection engine
33
- connectionThreshold: number; // Min resonance score to form a connection
34
- connectionCheckIntervalMs: number;
35
-
36
- // Consolidation
37
- consolidationIntervalMs: number; // How often to check for merge candidates
38
- consolidationSimilarity: number; // Threshold for merging similar engrams
39
-
40
- // Confidence updates
41
- feedbackPositiveBoost: number; // How much positive feedback increases confidence
42
- feedbackNegativePenalty: number; // How much negative feedback decreases confidence
43
- }
44
-
45
- export const DEFAULT_AGENT_CONFIG: AgentConfig = {
46
- salienceThreshold: 0.4,
47
- stagingThreshold: 0.2,
48
- stagingTtlMs: 24 * 60 * 60 * 1000, // 24 hours
49
-
50
- maxActiveEngrams: 10_000,
51
- maxStagingEngrams: 1_000,
52
- maxEdgesPerEngram: 20,
53
-
54
- activationLimit: 10,
55
- hebbianRate: 0.25,
56
- decayExponent: 0.5,
57
- edgeDecayHalfLifeDays: 7,
58
-
59
- connectionThreshold: 0.7,
60
- connectionCheckIntervalMs: 60_000,
61
-
62
- consolidationIntervalMs: 300_000, // 5 minutes
63
- consolidationSimilarity: 0.85,
64
-
65
- feedbackPositiveBoost: 0.05,
66
- feedbackNegativePenalty: 0.1,
67
- };
1
+ // Copyright 2026 Robert Winter / Complete Ideas
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ /**
4
+ * Agent — a consciousness boundary.
5
+ * Each agent has its own isolated memory space with capacity budgets.
6
+ */
7
+
8
+ export interface Agent {
9
+ id: string;
10
+ name: string;
11
+ createdAt: Date;
12
+ config: AgentConfig;
13
+ }
14
+
15
+ export interface AgentConfig {
16
+ // Salience filter thresholds
17
+ salienceThreshold: number; // Below this → discard
18
+ stagingThreshold: number; // Below salience but above this → staging buffer
19
+ stagingTtlMs: number; // Default TTL for staging entries
20
+
21
+ // Capacity budgets (eviction triggers when exceeded)
22
+ maxActiveEngrams: number; // Hard cap on active memory
23
+ maxStagingEngrams: number; // Hard cap on staging buffer
24
+ maxEdgesPerEngram: number; // Prevent graph explosion
25
+
26
+ // Activation pipeline tuning
27
+ activationLimit: number; // Max results per activation query
28
+ hebbianRate: number; // Learning rate for association strengthening
29
+ decayExponent: number; // ACT-R d parameter (default 0.5)
30
+ edgeDecayHalfLifeDays: number; // How fast unused edges weaken
31
+
32
+ // Connection engine
33
+ connectionThreshold: number; // Min resonance score to form a connection
34
+ connectionCheckIntervalMs: number;
35
+
36
+ // Consolidation
37
+ consolidationIntervalMs: number; // How often to check for merge candidates
38
+ consolidationSimilarity: number; // Threshold for merging similar engrams
39
+
40
+ // Confidence updates
41
+ feedbackPositiveBoost: number; // How much positive feedback increases confidence
42
+ feedbackNegativePenalty: number; // How much negative feedback decreases confidence
43
+ }
44
+
45
+ export const DEFAULT_AGENT_CONFIG: AgentConfig = {
46
+ salienceThreshold: 0.4,
47
+ stagingThreshold: 0.2,
48
+ stagingTtlMs: 24 * 60 * 60 * 1000, // 24 hours
49
+
50
+ maxActiveEngrams: 10_000,
51
+ maxStagingEngrams: 1_000,
52
+ maxEdgesPerEngram: 20,
53
+
54
+ activationLimit: 10,
55
+ hebbianRate: 0.25,
56
+ decayExponent: 0.5,
57
+ edgeDecayHalfLifeDays: 7,
58
+
59
+ connectionThreshold: 0.7,
60
+ connectionCheckIntervalMs: 60_000,
61
+
62
+ consolidationIntervalMs: 300_000, // 5 minutes
63
+ consolidationSimilarity: 0.85,
64
+
65
+ feedbackPositiveBoost: 0.05,
66
+ feedbackNegativePenalty: 0.1,
67
+ };
@@ -1,46 +1,46 @@
1
- // Copyright 2026 Robert Winter / Complete Ideas
2
- // SPDX-License-Identifier: Apache-2.0
3
- /**
4
- * Checkpoint types — conscious state preservation across compaction.
5
- *
6
- * ConsciousState: explicit structured snapshot (saved by agent)
7
- * AutoCheckpoint: implicit lightweight tracking (updated on every write/recall)
8
- */
9
-
10
- export interface ConsciousState {
11
- currentTask: string;
12
- decisions: string[];
13
- activeFiles: string[];
14
- nextSteps: string[];
15
- relatedMemoryIds: string[];
16
- notes: string;
17
- episodeId: string | null;
18
- }
19
-
20
- export interface AutoCheckpoint {
21
- lastWriteId: string | null;
22
- lastRecallContext: string | null;
23
- lastRecallIds: string[];
24
- lastActivityAt: Date;
25
- writeCountSinceConsolidation: number;
26
- recallCountSinceConsolidation: number;
27
- }
28
-
29
- export interface CheckpointRow {
30
- agentId: string;
31
- auto: AutoCheckpoint;
32
- executionState: ConsciousState | null;
33
- checkpointAt: Date | null;
34
- lastConsolidationAt: Date | null;
35
- lastMiniConsolidationAt: Date | null;
36
- updatedAt: Date;
37
- }
38
-
39
- export interface RestoreResult {
40
- executionState: ConsciousState | null;
41
- checkpointAt: Date | null;
42
- recalledMemories: Array<{ id: string; concept: string; content: string; score: number }>;
43
- lastWrite: { id: string; concept: string; content: string } | null;
44
- idleMs: number;
45
- miniConsolidationTriggered: boolean;
46
- }
1
+ // Copyright 2026 Robert Winter / Complete Ideas
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ /**
4
+ * Checkpoint types — conscious state preservation across compaction.
5
+ *
6
+ * ConsciousState: explicit structured snapshot (saved by agent)
7
+ * AutoCheckpoint: implicit lightweight tracking (updated on every write/recall)
8
+ */
9
+
10
+ export interface ConsciousState {
11
+ currentTask: string;
12
+ decisions: string[];
13
+ activeFiles: string[];
14
+ nextSteps: string[];
15
+ relatedMemoryIds: string[];
16
+ notes: string;
17
+ episodeId: string | null;
18
+ }
19
+
20
+ export interface AutoCheckpoint {
21
+ lastWriteId: string | null;
22
+ lastRecallContext: string | null;
23
+ lastRecallIds: string[];
24
+ lastActivityAt: Date;
25
+ writeCountSinceConsolidation: number;
26
+ recallCountSinceConsolidation: number;
27
+ }
28
+
29
+ export interface CheckpointRow {
30
+ agentId: string;
31
+ auto: AutoCheckpoint;
32
+ executionState: ConsciousState | null;
33
+ checkpointAt: Date | null;
34
+ lastConsolidationAt: Date | null;
35
+ lastMiniConsolidationAt: Date | null;
36
+ updatedAt: Date;
37
+ }
38
+
39
+ export interface RestoreResult {
40
+ executionState: ConsciousState | null;
41
+ checkpointAt: Date | null;
42
+ recalledMemories: Array<{ id: string; concept: string; content: string; score: number }>;
43
+ lastWrite: { id: string; concept: string; content: string } | null;
44
+ idleMs: number;
45
+ miniConsolidationTriggered: boolean;
46
+ }
@@ -59,6 +59,19 @@ export interface Engram {
59
59
  supersededBy: string | null; // ID of the engram that replaced this one
60
60
  supersedes: string | null; // ID of the engram this one replaces
61
61
 
62
+ // Memory spine — provenance (D5, 2026-07-30). LOG-ONLY: recorded on write,
63
+ // never used in ranking until an eval proves benefit (design-proposals D6).
64
+ // Optional so pre-D5 code paths and fixtures stay valid; readers treat
65
+ // undefined and null identically.
66
+ originClass?: string | null; // 'user-stated' | 'tool-output' | 'inference' | 'recipe'
67
+ writerSession?: string | null; // session/conversation id that wrote this
68
+ recipeId?: string | null; // cognition-recipe id+version when origin is 'recipe'
69
+
70
+ // Memory spine — temporal validity (D8, 2026-07-30). Bi-temporal fields:
71
+ // created_at is ingestion time; these bound when the FACT holds. Null = open.
72
+ validFrom?: string | null; // ISO date/datetime
73
+ validTo?: string | null; // ISO date/datetime — set when a fact expires/superseded by time
74
+
62
75
  // Task management (null = not a task)
63
76
  taskStatus: TaskStatus | null;
64
77
  taskPriority: TaskPriority | null;
@@ -158,6 +171,15 @@ export interface EngramCreate {
158
171
  sequence?: number;
159
172
  /** Typed cross-record links (0.8 Cluster A schema; HTTP in Cluster D). */
160
173
  references?: EngramReference[];
174
+ /** Provenance (D5, log-only): 'user-stated' | 'tool-output' | 'inference' | 'recipe'. */
175
+ originClass?: string;
176
+ /** Provenance (D5): session/conversation id that performed the write. */
177
+ writerSession?: string;
178
+ /** Provenance (D5): cognition-recipe id+version when originClass is 'recipe'. */
179
+ recipeId?: string;
180
+ /** Temporal validity (D8): ISO bounds on when the FACT holds (not ingestion time). */
181
+ validFrom?: string;
182
+ validTo?: string;
161
183
  }
162
184
 
163
185
  /**
package/src/types/eval.ts CHANGED
@@ -1,100 +1,100 @@
1
- // Copyright 2026 Robert Winter / Complete Ideas
2
- // SPDX-License-Identifier: Apache-2.0
3
- /**
4
- * Evaluation types — measuring whether memory actually helps.
5
- *
6
- * Four measurement dimensions:
7
- * 1. Retrieval quality (precision, recall, latency)
8
- * 2. Connection quality (edge utility, stability)
9
- * 3. Staging accuracy (promotion precision, discard regret)
10
- * 4. Task impact (with/without memory comparison)
11
- */
12
-
13
- /**
14
- * Single activation event record — logged for offline analysis.
15
- */
16
- export interface ActivationEvent {
17
- id: string;
18
- agentId: string;
19
- timestamp: Date;
20
- context: string;
21
- resultsReturned: number;
22
- topScore: number;
23
- latencyMs: number;
24
- engramIds: string[];
25
- feedback?: RetrievalFeedbackEvent[];
26
- }
27
-
28
- export interface RetrievalFeedbackEvent {
29
- engramId: string;
30
- useful: boolean;
31
- timestamp: Date;
32
- }
33
-
34
- /**
35
- * Staging lifecycle event — tracks promote/discard decisions.
36
- */
37
- export interface StagingEvent {
38
- engramId: string;
39
- agentId: string;
40
- action: 'promoted' | 'discarded' | 'expired';
41
- resonanceScore: number | null;
42
- timestamp: Date;
43
- ageMs: number; // How long it lived in staging
44
- }
45
-
46
- /**
47
- * Aggregate metrics snapshot — computed periodically.
48
- */
49
- export interface EvalMetrics {
50
- agentId: string;
51
- timestamp: Date;
52
- window: string; // e.g., "24h", "7d"
53
-
54
- // Retrieval quality
55
- activationCount: number;
56
- avgPrecisionAtK: number; // Of returned results, % judged useful
57
- avgLatencyMs: number;
58
- p95LatencyMs: number;
59
-
60
- // Connection quality
61
- totalEdges: number;
62
- edgesUsedInActivation: number;
63
- edgeUtilityRate: number; // % of edges that contributed to retrieval
64
- avgEdgeSurvivalDays: number;
65
-
66
- // Staging accuracy
67
- totalStaged: number;
68
- promotedCount: number;
69
- discardedCount: number;
70
- promotionPrecision: number; // % of promoted items later used
71
- discardRegret: number; // % of discarded items agent re-introduced
72
-
73
- // Memory health
74
- activeEngramCount: number;
75
- stagingEngramCount: number;
76
- retractedCount: number;
77
- consolidatedCount: number;
78
- avgConfidence: number;
79
-
80
- // Contamination tracking
81
- staleUsageCount: number; // Activations using outdated engrams
82
- retractionRate: number; // Rate of memories being invalidated
83
- }
84
-
85
- /**
86
- * Task trial — for with/without memory comparison.
87
- */
88
- export interface TaskTrial {
89
- id: string;
90
- agentId: string;
91
- taskDescription: string;
92
- memoryEnabled: boolean;
93
- startedAt: Date;
94
- completedAt: Date | null;
95
- success: boolean | null;
96
- stepsToCompletion: number;
97
- errorsEncountered: number;
98
- memoriesActivated: number;
99
- userCorrections: number;
100
- }
1
+ // Copyright 2026 Robert Winter / Complete Ideas
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ /**
4
+ * Evaluation types — measuring whether memory actually helps.
5
+ *
6
+ * Four measurement dimensions:
7
+ * 1. Retrieval quality (precision, recall, latency)
8
+ * 2. Connection quality (edge utility, stability)
9
+ * 3. Staging accuracy (promotion precision, discard regret)
10
+ * 4. Task impact (with/without memory comparison)
11
+ */
12
+
13
+ /**
14
+ * Single activation event record — logged for offline analysis.
15
+ */
16
+ export interface ActivationEvent {
17
+ id: string;
18
+ agentId: string;
19
+ timestamp: Date;
20
+ context: string;
21
+ resultsReturned: number;
22
+ topScore: number;
23
+ latencyMs: number;
24
+ engramIds: string[];
25
+ feedback?: RetrievalFeedbackEvent[];
26
+ }
27
+
28
+ export interface RetrievalFeedbackEvent {
29
+ engramId: string;
30
+ useful: boolean;
31
+ timestamp: Date;
32
+ }
33
+
34
+ /**
35
+ * Staging lifecycle event — tracks promote/discard decisions.
36
+ */
37
+ export interface StagingEvent {
38
+ engramId: string;
39
+ agentId: string;
40
+ action: 'promoted' | 'discarded' | 'expired';
41
+ resonanceScore: number | null;
42
+ timestamp: Date;
43
+ ageMs: number; // How long it lived in staging
44
+ }
45
+
46
+ /**
47
+ * Aggregate metrics snapshot — computed periodically.
48
+ */
49
+ export interface EvalMetrics {
50
+ agentId: string;
51
+ timestamp: Date;
52
+ window: string; // e.g., "24h", "7d"
53
+
54
+ // Retrieval quality
55
+ activationCount: number;
56
+ avgPrecisionAtK: number; // Of returned results, % judged useful
57
+ avgLatencyMs: number;
58
+ p95LatencyMs: number;
59
+
60
+ // Connection quality
61
+ totalEdges: number;
62
+ edgesUsedInActivation: number;
63
+ edgeUtilityRate: number; // % of edges that contributed to retrieval
64
+ avgEdgeSurvivalDays: number;
65
+
66
+ // Staging accuracy
67
+ totalStaged: number;
68
+ promotedCount: number;
69
+ discardedCount: number;
70
+ promotionPrecision: number; // % of promoted items later used
71
+ discardRegret: number; // % of discarded items agent re-introduced
72
+
73
+ // Memory health
74
+ activeEngramCount: number;
75
+ stagingEngramCount: number;
76
+ retractedCount: number;
77
+ consolidatedCount: number;
78
+ avgConfidence: number;
79
+
80
+ // Contamination tracking
81
+ staleUsageCount: number; // Activations using outdated engrams
82
+ retractionRate: number; // Rate of memories being invalidated
83
+ }
84
+
85
+ /**
86
+ * Task trial — for with/without memory comparison.
87
+ */
88
+ export interface TaskTrial {
89
+ id: string;
90
+ agentId: string;
91
+ taskDescription: string;
92
+ memoryEnabled: boolean;
93
+ startedAt: Date;
94
+ completedAt: Date | null;
95
+ success: boolean | null;
96
+ stepsToCompletion: number;
97
+ errorsEncountered: number;
98
+ memoriesActivated: number;
99
+ userCorrections: number;
100
+ }
@@ -1,6 +1,6 @@
1
- // Copyright 2026 Robert Winter / Complete Ideas
2
- // SPDX-License-Identifier: Apache-2.0
3
- export * from './engram.js';
4
- export * from './agent.js';
5
- export * from './eval.js';
6
- export * from './checkpoint.js';
1
+ // Copyright 2026 Robert Winter / Complete Ideas
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ export * from './engram.js';
4
+ export * from './agent.js';
5
+ export * from './eval.js';
6
+ export * from './checkpoint.js';
package/src/version.ts ADDED
@@ -0,0 +1,26 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import { fileURLToPath } from 'node:url';
3
+ import { dirname, join } from 'node:path';
4
+
5
+ /**
6
+ * The running package version, read from package.json at runtime so the number
7
+ * reported by /health, the startup banner, and the MCP server always matches
8
+ * the actually-deployed build. Hand-maintained version literals drifted across
9
+ * releases (a 0.10.0 build was still reporting 0.8.5/0.8.8) — this removes them.
10
+ */
11
+ function resolveVersion(): string {
12
+ const here = dirname(fileURLToPath(import.meta.url));
13
+ // src/version.ts (dev) and dist/version.js (build) both sit one level below
14
+ // the package root; the ../../ fallback covers a deeper output nesting.
15
+ for (const rel of ['../package.json', '../../package.json']) {
16
+ try {
17
+ const v = JSON.parse(readFileSync(join(here, rel), 'utf8')).version;
18
+ if (typeof v === 'string' && v) return v;
19
+ } catch {
20
+ /* try the next candidate path */
21
+ }
22
+ }
23
+ return '0.0.0';
24
+ }
25
+
26
+ export const VERSION: string = resolveVersion();