agent-working-memory 0.7.16 → 0.8.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +156 -15
- package/dist/adapters/claude-code.d.ts.map +1 -1
- package/dist/adapters/claude-code.js +2 -16
- package/dist/adapters/claude-code.js.map +1 -1
- package/dist/adapters/codex.d.ts.map +1 -1
- package/dist/adapters/codex.js +2 -11
- package/dist/adapters/codex.js.map +1 -1
- package/dist/adapters/common.d.ts +18 -0
- package/dist/adapters/common.d.ts.map +1 -1
- package/dist/adapters/common.js +254 -141
- package/dist/adapters/common.js.map +1 -1
- package/dist/adapters/cursor.d.ts.map +1 -1
- package/dist/adapters/cursor.js +2 -15
- package/dist/adapters/cursor.js.map +1 -1
- package/dist/adapters/http.d.ts.map +1 -1
- package/dist/adapters/http.js +28 -34
- package/dist/adapters/http.js.map +1 -1
- package/dist/api/routes.d.ts +1 -1
- package/dist/api/routes.d.ts.map +1 -1
- package/dist/api/routes.js +280 -113
- package/dist/api/routes.js.map +1 -1
- package/dist/cli/migrate.d.ts +42 -0
- package/dist/cli/migrate.d.ts.map +1 -0
- package/dist/cli/migrate.js +268 -0
- package/dist/cli/migrate.js.map +1 -0
- package/dist/cli.js +45 -1
- package/dist/cli.js.map +1 -1
- package/dist/coordination/circuit-breaker.d.ts +24 -0
- package/dist/coordination/circuit-breaker.d.ts.map +1 -0
- package/dist/coordination/circuit-breaker.js +70 -0
- package/dist/coordination/circuit-breaker.js.map +1 -0
- package/dist/coordination/failure-modes.d.ts +21 -0
- package/dist/coordination/failure-modes.d.ts.map +1 -0
- package/dist/coordination/failure-modes.js +49 -0
- package/dist/coordination/failure-modes.js.map +1 -0
- package/dist/coordination/peer-decisions.js +7 -7
- package/dist/coordination/routes.d.ts.map +1 -1
- package/dist/coordination/routes.js +44 -1
- package/dist/coordination/routes.js.map +1 -1
- package/dist/coordination/schema.d.ts.map +1 -1
- package/dist/coordination/schema.js +18 -0
- package/dist/coordination/schema.js.map +1 -1
- package/dist/coordination/schemas.d.ts +9 -9
- package/dist/coordination/stale.d.ts +9 -1
- package/dist/coordination/stale.d.ts.map +1 -1
- package/dist/coordination/stale.js +53 -9
- package/dist/coordination/stale.js.map +1 -1
- package/dist/core/embeddings.d.ts +16 -10
- package/dist/core/embeddings.d.ts.map +1 -1
- package/dist/core/embeddings.js +54 -38
- package/dist/core/embeddings.js.map +1 -1
- package/dist/core/ml-worker-entry.d.ts +17 -0
- package/dist/core/ml-worker-entry.d.ts.map +1 -0
- package/dist/core/ml-worker-entry.js +193 -0
- package/dist/core/ml-worker-entry.js.map +1 -0
- package/dist/core/ml-worker.d.ts +59 -0
- package/dist/core/ml-worker.d.ts.map +1 -0
- package/dist/core/ml-worker.js +253 -0
- package/dist/core/ml-worker.js.map +1 -0
- package/dist/core/query-expander.d.ts +13 -15
- package/dist/core/query-expander.d.ts.map +1 -1
- package/dist/core/query-expander.js +48 -54
- package/dist/core/query-expander.js.map +1 -1
- package/dist/core/reranker.d.ts +9 -19
- package/dist/core/reranker.d.ts.map +1 -1
- package/dist/core/reranker.js +33 -35
- package/dist/core/reranker.js.map +1 -1
- package/dist/core/salience.d.ts +32 -5
- package/dist/core/salience.d.ts.map +1 -1
- package/dist/core/salience.js +201 -28
- package/dist/core/salience.js.map +1 -1
- package/dist/core/write-pipeline.d.ts +128 -0
- package/dist/core/write-pipeline.d.ts.map +1 -0
- package/dist/core/write-pipeline.js +405 -0
- package/dist/core/write-pipeline.js.map +1 -0
- package/dist/engine/activation.d.ts +2 -2
- package/dist/engine/activation.d.ts.map +1 -1
- package/dist/engine/activation.js +238 -115
- package/dist/engine/activation.js.map +1 -1
- package/dist/engine/confidence.d.ts +62 -0
- package/dist/engine/confidence.d.ts.map +1 -0
- package/dist/engine/confidence.js +100 -0
- package/dist/engine/confidence.js.map +1 -0
- package/dist/engine/connections.d.ts +47 -8
- package/dist/engine/connections.d.ts.map +1 -1
- package/dist/engine/connections.js +83 -22
- package/dist/engine/connections.js.map +1 -1
- package/dist/engine/consolidation-scheduler.d.ts +46 -10
- package/dist/engine/consolidation-scheduler.d.ts.map +1 -1
- package/dist/engine/consolidation-scheduler.js +170 -50
- package/dist/engine/consolidation-scheduler.js.map +1 -1
- package/dist/engine/consolidation.d.ts +16 -2
- package/dist/engine/consolidation.d.ts.map +1 -1
- package/dist/engine/consolidation.js +143 -44
- package/dist/engine/consolidation.js.map +1 -1
- package/dist/engine/eval.d.ts +2 -2
- package/dist/engine/eval.d.ts.map +1 -1
- package/dist/engine/eval.js +9 -9
- package/dist/engine/eval.js.map +1 -1
- package/dist/engine/eviction.d.ts +4 -4
- package/dist/engine/eviction.d.ts.map +1 -1
- package/dist/engine/eviction.js +15 -15
- package/dist/engine/eviction.js.map +1 -1
- package/dist/engine/retraction.d.ts +93 -5
- package/dist/engine/retraction.d.ts.map +1 -1
- package/dist/engine/retraction.js +238 -19
- package/dist/engine/retraction.js.map +1 -1
- package/dist/engine/staging.d.ts +1 -1
- package/dist/engine/staging.d.ts.map +1 -1
- package/dist/engine/staging.js +3 -3
- package/dist/engine/staging.js.map +1 -1
- package/dist/hooks/sidecar.d.ts +1 -1
- package/dist/hooks/sidecar.d.ts.map +1 -1
- package/dist/hooks/sidecar.js +4 -4
- package/dist/hooks/sidecar.js.map +1 -1
- package/dist/index.js +48 -31
- package/dist/index.js.map +1 -1
- package/dist/mcp.js +110 -155
- package/dist/mcp.js.map +1 -1
- package/dist/storage/factory.d.ts +55 -0
- package/dist/storage/factory.d.ts.map +1 -0
- package/dist/storage/factory.js +135 -0
- package/dist/storage/factory.js.map +1 -0
- package/dist/storage/pglite-schema.d.ts +20 -0
- package/dist/storage/pglite-schema.d.ts.map +1 -0
- package/dist/storage/pglite-schema.js +165 -0
- package/dist/storage/pglite-schema.js.map +1 -0
- package/dist/storage/pglite.d.ts +187 -0
- package/dist/storage/pglite.d.ts.map +1 -0
- package/dist/storage/pglite.js +1114 -0
- package/dist/storage/pglite.js.map +1 -0
- package/dist/storage/sqlite.d.ts +117 -0
- package/dist/storage/sqlite.d.ts.map +1 -1
- package/dist/storage/sqlite.js +357 -8
- package/dist/storage/sqlite.js.map +1 -1
- package/dist/storage/store.d.ts +63 -0
- package/dist/storage/store.d.ts.map +1 -0
- package/dist/storage/store.js +27 -0
- package/dist/storage/store.js.map +1 -0
- package/dist/types/engram.d.ts +92 -2
- package/dist/types/engram.d.ts.map +1 -1
- package/dist/types/engram.js.map +1 -1
- package/package.json +3 -1
- package/src/adapters/claude-code.ts +218 -234
- package/src/adapters/codex.ts +252 -262
- package/src/adapters/common.ts +411 -284
- package/src/adapters/cursor.ts +135 -150
- package/src/adapters/http.ts +93 -100
- package/src/adapters/index.ts +31 -31
- package/src/adapters/types.ts +75 -75
- package/src/api/index.ts +3 -3
- package/src/api/routes.ts +367 -120
- package/src/cli/migrate.ts +307 -0
- package/src/cli.ts +37 -1
- package/src/coordination/circuit-breaker.ts +83 -0
- package/src/coordination/events.ts +90 -90
- package/src/coordination/failure-modes.ts +50 -0
- package/src/coordination/peer-decisions.ts +105 -105
- package/src/coordination/plugin-loader.ts +60 -60
- package/src/coordination/plugin.ts +44 -44
- package/src/coordination/routes.ts +56 -1
- package/src/coordination/schema.ts +13 -0
- package/src/coordination/stale.ts +80 -11
- package/src/coordination/types.ts +311 -311
- package/src/coordination/write-mutex.ts +69 -69
- package/src/core/auto-tagger.ts +168 -168
- package/src/core/decay.ts +63 -63
- package/src/core/embeddings.ts +110 -93
- package/src/core/index.ts +5 -5
- package/src/core/logger.ts +36 -36
- package/src/core/ml-worker-entry.ts +194 -0
- package/src/core/ml-worker.ts +281 -0
- package/src/core/query-expander.ts +122 -128
- package/src/core/reranker.ts +119 -125
- package/src/core/salience.ts +200 -33
- package/src/core/write-pipeline.ts +521 -0
- package/src/engine/activation.ts +235 -109
- package/src/engine/confidence.ts +120 -0
- package/src/engine/connections.ts +162 -103
- package/src/engine/consolidation-scheduler.ts +242 -125
- package/src/engine/consolidation.ts +138 -45
- package/src/engine/eval.ts +102 -102
- package/src/engine/eviction.ts +101 -101
- package/src/engine/index.ts +8 -8
- package/src/engine/retraction.ts +366 -116
- package/src/engine/staging.ts +74 -74
- package/src/hooks/sidecar.ts +5 -5
- package/src/index.ts +42 -28
- package/src/mcp.ts +105 -152
- package/src/storage/factory.ts +147 -0
- package/src/storage/index.ts +3 -3
- package/src/storage/pglite-schema.ts +166 -0
- package/src/storage/pglite.ts +1363 -0
- package/src/storage/sqlite.ts +402 -7
- package/src/storage/store.ts +80 -0
- package/src/types/agent.ts +67 -67
- package/src/types/checkpoint.ts +46 -46
- package/src/types/engram.ts +101 -3
- package/src/types/eval.ts +100 -100
- package/src/types/index.ts +6 -6
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Backend-agnostic storage contract for AWM.
|
|
3
|
+
*
|
|
4
|
+
* AWM 0.8.x introduces a pluggable storage layer:
|
|
5
|
+
* - SQLiteEngramStore: better-sqlite3 + FTS5 + BLOB embeddings (current default)
|
|
6
|
+
* - PGliteEngramStore: @electric-sql/pglite + pgvector + tsvector (opt-in via
|
|
7
|
+
* `AWM_STORE_BACKEND=pglite`, planned default in 0.9.x)
|
|
8
|
+
* - PostgresEngramStore: real Postgres backend for scale (planned, post-1.0)
|
|
9
|
+
*
|
|
10
|
+
* All backends provide the same public surface — defined here as `IEngramStore`.
|
|
11
|
+
* The cognitive engines (activation, consolidation, Hebbian, eviction, etc.)
|
|
12
|
+
* accept `IEngramStore` and work against any conforming backend.
|
|
13
|
+
*
|
|
14
|
+
* The interface is derived from the SQLite implementation via TypeScript's
|
|
15
|
+
* `Omit<>` so it stays in sync automatically. SQLite-specific methods
|
|
16
|
+
* (DB handle access, WAL checkpointing, slim-cache management, integrity
|
|
17
|
+
* checks) are excluded — these are implementation-internal and don't belong
|
|
18
|
+
* in a backend-agnostic contract.
|
|
19
|
+
*
|
|
20
|
+
* Future backends MUST implement every method on `IEngramStore`. They MAY
|
|
21
|
+
* additionally expose backend-specific methods (e.g., PGlite-specific tooling,
|
|
22
|
+
* Postgres pool management) — those are not part of the contract.
|
|
23
|
+
*/
|
|
24
|
+
import type { EngramStore as SqliteEngramStore } from './sqlite.js';
|
|
25
|
+
/**
|
|
26
|
+
* Backend-specific methods on SqliteEngramStore that are NOT part of the
|
|
27
|
+
* shared contract. Other backends may provide functionally-similar methods
|
|
28
|
+
* under different names or not at all.
|
|
29
|
+
*/
|
|
30
|
+
type SqliteSpecificMethods = 'getDb' | 'integrityCheck' | 'walCheckpoint' | 'stopWalCheckpointTimer' | 'backup' | 'warmSlimCache' | 'resetSlimCache' | 'getSlimCacheStats' | 'transaction';
|
|
31
|
+
/**
|
|
32
|
+
* MaybePromise — covariant union that lets sync and async backends share one contract.
|
|
33
|
+
*
|
|
34
|
+
* Engines `await` every store call. `await T` resolves to T immediately when
|
|
35
|
+
* the backend is sync (SQLite, returning bare values) and resolves the Promise
|
|
36
|
+
* when the backend is async (PGlite). Both shapes satisfy the same interface.
|
|
37
|
+
*/
|
|
38
|
+
type MaybePromise<T> = T | Promise<T>;
|
|
39
|
+
/**
|
|
40
|
+
* Turn every method return type R into `MaybePromise<Awaited<R>>` so the
|
|
41
|
+
* contract accepts both sync and async backends.
|
|
42
|
+
*/
|
|
43
|
+
type AsyncifyMethods<T> = {
|
|
44
|
+
[K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => MaybePromise<Awaited<R>> : T[K];
|
|
45
|
+
};
|
|
46
|
+
/**
|
|
47
|
+
* The backend-agnostic storage contract.
|
|
48
|
+
*
|
|
49
|
+
* Any class with this shape can be used as the EngramStore for the AWM
|
|
50
|
+
* cognitive engines. New backends should `implements IEngramStore` to get
|
|
51
|
+
* compile-time enforcement of the full surface.
|
|
52
|
+
*/
|
|
53
|
+
export type IEngramStore = AsyncifyMethods<Omit<SqliteEngramStore, SqliteSpecificMethods>>;
|
|
54
|
+
/**
|
|
55
|
+
* Convenience type-only re-export so consumers can `import type { EngramStore }`
|
|
56
|
+
* from this module and get the backend-agnostic contract instead of the
|
|
57
|
+
* SQLite-specific class. Existing imports from `'../storage/sqlite.js'`
|
|
58
|
+
* continue to work and resolve to the SQLite class (which is a structural
|
|
59
|
+
* supertype of IEngramStore).
|
|
60
|
+
*/
|
|
61
|
+
export type EngramStore = IEngramStore;
|
|
62
|
+
export {};
|
|
63
|
+
//# sourceMappingURL=store.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/storage/store.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,WAAW,IAAI,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEpE;;;;GAIG;AACH,KAAK,qBAAqB,GACtB,OAAO,GACP,gBAAgB,GAChB,eAAe,GACf,wBAAwB,GACxB,QAAQ,GACR,eAAe,GACf,gBAAgB,GAChB,mBAAmB,GACnB,aAAa,CAAC;AAElB;;;;;;GAMG;AACH,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC;;;GAGG;AACH,KAAK,eAAe,CAAC,CAAC,IAAI;KACvB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,GACtD,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GACxC,CAAC,CAAC,CAAC,CAAC;CACT,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,CAAC,IAAI,CAAC,iBAAiB,EAAE,qBAAqB,CAAC,CAAC,CAAC;AAE3F;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,YAAY,CAAC"}
|
|
@@ -0,0 +1,27 @@
|
|
|
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
|
+
export {};
|
|
27
|
+
//# sourceMappingURL=store.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/storage/store.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,sCAAsC;AACtC;;;;;;;;;;;;;;;;;;;;;;GAsBG"}
|
package/dist/types/engram.d.ts
CHANGED
|
@@ -26,13 +26,15 @@ export interface Engram {
|
|
|
26
26
|
episodeId: string | null;
|
|
27
27
|
memoryClass: MemoryClass;
|
|
28
28
|
memoryType: MemoryType;
|
|
29
|
+
sequence: number | null;
|
|
30
|
+
references: EngramReference[] | null;
|
|
29
31
|
supersededBy: string | null;
|
|
30
32
|
supersedes: string | null;
|
|
31
33
|
taskStatus: TaskStatus | null;
|
|
32
34
|
taskPriority: TaskPriority | null;
|
|
33
35
|
blockedBy: string | null;
|
|
34
36
|
}
|
|
35
|
-
export type EngramStage = 'staging' | 'active' | 'consolidated' | 'archived';
|
|
37
|
+
export type EngramStage = 'staging' | 'active' | 'consolidated' | 'fading' | 'archived';
|
|
36
38
|
export type TaskStatus = 'open' | 'in_progress' | 'blocked' | 'done';
|
|
37
39
|
export type TaskPriority = 'urgent' | 'high' | 'medium' | 'low';
|
|
38
40
|
/**
|
|
@@ -45,7 +47,38 @@ export type TaskPriority = 'urgent' | 'high' | 'medium' | 'low';
|
|
|
45
47
|
* ephemeral: Temporary context (debugging traces, session-specific notes).
|
|
46
48
|
* Stronger time decay, lower recall priority.
|
|
47
49
|
*/
|
|
48
|
-
|
|
50
|
+
/**
|
|
51
|
+
* Memory class — write-time classification controlling salience behavior
|
|
52
|
+
* and downstream retrieval semantics.
|
|
53
|
+
*
|
|
54
|
+
* canonical: Source-of-truth memories. Salience floor 0.7, never stage.
|
|
55
|
+
* Surfaced via cognitive `/activate` and deterministic queries.
|
|
56
|
+
*
|
|
57
|
+
* working: Default. Observations, findings, progress notes. Standard
|
|
58
|
+
* salience rules apply. Surfaced via all retrieval paths.
|
|
59
|
+
*
|
|
60
|
+
* ephemeral: Temporary context. Stronger time decay, lower recall priority.
|
|
61
|
+
*
|
|
62
|
+
* structural: (0.8+) System-written event-log records — chapter analyses,
|
|
63
|
+
* promise advancements, materialized-view feeds. Salience floor
|
|
64
|
+
* 0.7 like canonical, but EXCLUDED from cognitive `/activate`
|
|
65
|
+
* by default (callers opt in via `includeStructural: true`),
|
|
66
|
+
* skip temporal-adjacency edges, skip default embedding. Used
|
|
67
|
+
* for high-volume deterministic substrate where cognitive
|
|
68
|
+
* retrieval would just add noise.
|
|
69
|
+
*/
|
|
70
|
+
export type MemoryClass = 'canonical' | 'working' | 'ephemeral' | 'structural';
|
|
71
|
+
/**
|
|
72
|
+
* Typed cross-record link stored alongside an engram in references_json.
|
|
73
|
+
* Wired through HTTP in 0.8 Cluster D; schema slot added in Cluster A.
|
|
74
|
+
*/
|
|
75
|
+
export interface EngramReference {
|
|
76
|
+
type: 'advances' | 'resolves' | 'subverts' | 'abandons' | 'extends' | 'supersedes';
|
|
77
|
+
/** ID of the referenced engram. Either this or matchConcept must be set. */
|
|
78
|
+
matchEngramId?: string;
|
|
79
|
+
/** Concept of the referenced engram (resolved at write time in 0.8 D). */
|
|
80
|
+
matchConcept?: string;
|
|
81
|
+
}
|
|
49
82
|
/**
|
|
50
83
|
* Memory type — content classification for retrieval routing.
|
|
51
84
|
*
|
|
@@ -84,6 +117,10 @@ export interface EngramCreate {
|
|
|
84
117
|
taskStatus?: TaskStatus;
|
|
85
118
|
taskPriority?: TaskPriority;
|
|
86
119
|
blockedBy?: string;
|
|
120
|
+
/** Optional story-time / sequence ordering (0.8 Cluster A). */
|
|
121
|
+
sequence?: number;
|
|
122
|
+
/** Typed cross-record links (0.8 Cluster A schema; HTTP in Cluster D). */
|
|
123
|
+
references?: EngramReference[];
|
|
87
124
|
}
|
|
88
125
|
/**
|
|
89
126
|
* Association — weighted edge between two engrams.
|
|
@@ -112,6 +149,20 @@ export interface ActivationResult {
|
|
|
112
149
|
phaseScores: PhaseScores;
|
|
113
150
|
why: string;
|
|
114
151
|
associations: Association[];
|
|
152
|
+
/**
|
|
153
|
+
* Recall confidence — score-distribution-aware signal in [0, 1].
|
|
154
|
+
* Same value on every result in the same recall (it describes the
|
|
155
|
+
* *set*, not the individual). Computed once after final ranking.
|
|
156
|
+
* See `src/engine/confidence.ts` for the formula.
|
|
157
|
+
*/
|
|
158
|
+
confidence?: number;
|
|
159
|
+
/**
|
|
160
|
+
* Confidence-adaptive content preview (Paper 3: cognitive teaming).
|
|
161
|
+
* Set when the query opts in via `granularity: 'compact' | 'auto'`.
|
|
162
|
+
* Trades depth for breadth — short when the agent should scan a diverse
|
|
163
|
+
* set, full when there is a clear winner worth absorbing in full.
|
|
164
|
+
*/
|
|
165
|
+
summary?: string;
|
|
115
166
|
}
|
|
116
167
|
/**
|
|
117
168
|
* Per-phase scoring breakdown — full audit of how each phase contributed.
|
|
@@ -147,11 +198,36 @@ export interface ActivationQuery {
|
|
|
147
198
|
useReranker?: boolean;
|
|
148
199
|
useExpansion?: boolean;
|
|
149
200
|
abstentionThreshold?: number;
|
|
201
|
+
/**
|
|
202
|
+
* Opt-in confidence-based abstention. When set, the recall returns []
|
|
203
|
+
* if the computed recall confidence (see src/engine/confidence.ts) falls
|
|
204
|
+
* below the threshold. Independent of `abstentionThreshold` (reranker-based);
|
|
205
|
+
* uses score-distribution shape rather than reranker score.
|
|
206
|
+
* Typical values: 0.10 (strict — only abstain on clearly noisy queries),
|
|
207
|
+
* 0.25 (balanced), 0.40 (aggressive — only return high-confidence recall).
|
|
208
|
+
*/
|
|
209
|
+
requireConfidence?: number;
|
|
150
210
|
internal?: boolean;
|
|
151
211
|
memoryType?: MemoryType;
|
|
152
212
|
mode?: QueryMode;
|
|
153
213
|
workspace?: string;
|
|
154
214
|
bm25Only?: boolean;
|
|
215
|
+
/**
|
|
216
|
+
* Output granularity (Paper 3: cognitive teaming, Brill 2018 ACT-R collaboration).
|
|
217
|
+
* Controls how much engram content the activation engine surfaces back to the caller,
|
|
218
|
+
* trading depth for breadth based on recall quality.
|
|
219
|
+
*
|
|
220
|
+
* 'full' (default): no change — callers get the raw engram with full content.
|
|
221
|
+
* 'compact': every result gets a short `summary` field (first ~200 chars of content).
|
|
222
|
+
* Engram body is unchanged; callers can choose summary or content.
|
|
223
|
+
* 'auto': confidence-adaptive. When the recall has a clear winner (confidence
|
|
224
|
+
* ≥ AWM_GRANULARITY_AUTO_THRESHOLD, default 0.4), the top result keeps a
|
|
225
|
+
* full-content summary and lower-ranked results get compact ones —
|
|
226
|
+
* the agent absorbs the strong match in detail and scans alternatives.
|
|
227
|
+
* When confidence is low, all results get compact summaries so the
|
|
228
|
+
* agent can scan a diverse set without drowning in content.
|
|
229
|
+
*/
|
|
230
|
+
granularity?: 'full' | 'compact' | 'auto';
|
|
155
231
|
}
|
|
156
232
|
/**
|
|
157
233
|
* Search query — deterministic retrieval for diagnostics and debugging.
|
|
@@ -161,11 +237,25 @@ export interface SearchQuery {
|
|
|
161
237
|
agentId: string;
|
|
162
238
|
text?: string;
|
|
163
239
|
concept?: string;
|
|
240
|
+
/** Tag filter — AND semantics. Existing field kept for compat; equivalent to `tagsAll`.
|
|
241
|
+
* If both `tags` and `tagsAll` are passed, results match tags from both arrays
|
|
242
|
+
* (intersection of both AND-filters). */
|
|
164
243
|
tags?: string[];
|
|
244
|
+
/** AND-filter: engram must have ALL of these tags. Alias for legacy `tags`. (0.8 Cluster B) */
|
|
245
|
+
tagsAll?: string[];
|
|
246
|
+
/** OR-filter: engram must have AT LEAST ONE of these tags. (0.8 Cluster B) */
|
|
247
|
+
tagsAny?: string[];
|
|
248
|
+
/** NOT-filter: engram must have NONE of these tags. (0.8 Cluster B) */
|
|
249
|
+
tagsNone?: string[];
|
|
165
250
|
stage?: EngramStage;
|
|
166
251
|
retracted?: boolean;
|
|
167
252
|
limit?: number;
|
|
168
253
|
offset?: number;
|
|
254
|
+
/** Sort field. Defaults to `lastAccessed` (existing behavior preserved when
|
|
255
|
+
* unspecified). `sequence` sorts NULL last. (0.8 Cluster B) */
|
|
256
|
+
sortBy?: 'createdAt' | 'sequence' | 'salience' | 'confidence' | 'lastAccessed';
|
|
257
|
+
/** Sort direction. Default `desc`. (0.8 Cluster B) */
|
|
258
|
+
sortOrder?: 'asc' | 'desc';
|
|
169
259
|
}
|
|
170
260
|
/**
|
|
171
261
|
* Retrieval feedback — agent reports whether a memory was useful.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"engram.d.ts","sourceRoot":"","sources":["../../src/types/engram.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAG3B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,IAAI,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAGhB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,WAAW,EAAE,MAAM,EAAE,CAAC;IAGtB,KAAK,EAAE,WAAW,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAGnB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IAGzB,IAAI,EAAE,MAAM,EAAE,CAAC;IAGf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAGzB,WAAW,EAAE,WAAW,CAAC;IAGzB,UAAU,EAAE,UAAU,CAAC;
|
|
1
|
+
{"version":3,"file":"engram.d.ts","sourceRoot":"","sources":["../../src/types/engram.ts"],"names":[],"mappings":"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"}
|
package/dist/types/engram.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"engram.js","sourceRoot":"","sources":["../../src/types/engram.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,sCAAsC;AACtC;;;;;GAKG;
|
|
1
|
+
{"version":3,"file":"engram.js","sourceRoot":"","sources":["../../src/types/engram.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,sCAAsC;AACtC;;;;;GAKG;AA8KH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agent-working-memory",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.5",
|
|
4
4
|
"description": "Cognitive memory layer for AI agents — activation-based retrieval, salience filtering, associative connections",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -25,6 +25,7 @@
|
|
|
25
25
|
"test:stress": "tsx tests/stress-test/runner.ts",
|
|
26
26
|
"test:edge": "tsx tests/edge-cases/runner.ts",
|
|
27
27
|
"test:pilot": "tsx tests/pilot-metrics/runner.ts",
|
|
28
|
+
"test:perf": "tsx tests/perf-test/runner.ts",
|
|
28
29
|
"eval": "tsx tests/eval/run.ts",
|
|
29
30
|
"eval:generate": "tsx tests/eval/generate.ts",
|
|
30
31
|
"test:all": "vitest run && tsx tests/mcp-smoke.ts"
|
|
@@ -41,6 +42,7 @@
|
|
|
41
42
|
"LICENSE"
|
|
42
43
|
],
|
|
43
44
|
"dependencies": {
|
|
45
|
+
"@electric-sql/pglite": "^0.4.6",
|
|
44
46
|
"@huggingface/transformers": "^3.8.1",
|
|
45
47
|
"@modelcontextprotocol/sdk": "^1.27.1",
|
|
46
48
|
"better-sqlite3": "^12.6.2",
|