@tangleai/memory 0.21.1 → 0.24.1

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @tangleai/memory
 
+## 0.24.1
+
+### Patch Changes
+
+- @tangleai/context@0.24.1
+  - @tangleai/core@0.24.1
+
+## 0.24.0
+
+### Minor Changes
+
+- Add the outcomes package for independently evidenced decisions, deterministic scoring, atomic confidence projection, bounded artifact refinement and explicitly approved promotion and rollback. The public operation contract, two-domain adapter kit and keyless example share the same scoped request receipts, one-use held-out gates, full head revision checks and interruption recovery.
+
+  The store adapter owns outcome records and memory changes in one SQLite transaction. The new pure confidence helper preserves fact fields; existing applyOutcome calls retain their original duplicate-citation and timestamp behavior and do not acquire a durable replay guarantee. No existing persisted memory format changes. Hosts opt into the new lifecycle, provide evidence and approval authority, and use a new artifact key for schema or policy changes. Scripted paired measurements and Node/Bun packed consumers qualify the mechanism; downstream domain integrations and automatic promotion remain separate work.
+
+### Patch Changes
+
+- @tangleai/context@0.24.0
+  - @tangleai/core@0.24.0
+
+## 0.23.0
+
+### Minor Changes
+
+- Derive memory defaults from a registered held-out policy experiment and expose their values, evidence provenance and measured opt-ins through a public contract. Novelty filtering, contradiction resolution and crystallization now default to off; memory retrieval defaults to k 10 and minScore 0, and the independently measured offline hash width is 512.
+
+  Explicit policy overrides retain their meaning. Use the shipped-legacy policy data with a 64-dimensional hash embedder to reproduce the former settings; existing vectors retain their original embedding identity and require re-embedding to rank with the new offline default. Preserve the full live evidence, bounded-null decision and historical losses, enforce purchase and identity boundaries, and gate generated defaults, public contract compatibility, examples and documentation.
+
+### Patch Changes
+
+- @tangleai/context@0.23.0
+  - @tangleai/core@0.23.0
+
+## 0.22.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @tangleai/context@0.22.0
+  - @tangleai/core@0.22.0
+
 ## 0.21.1
 
 ### Patch Changes

package/README.md

@@ -1,7 +1,68 @@
 # @tangleai/memory
 
-Tangle AI memory policies — novelty gating, crystallization, contradiction resolution, outcome learning — over an injected store
+Evidenced memory storage, ingest policies, retrieval and outcome learning over an injected store.
 
-Install with `npm install @tangleai/memory`. The npm distribution provides ESM JavaScript, TypeScript declarations, and the documented package subpaths for Node 24 and Bun 1.4 or newer.
+Install with `npm install @tangleai/memory`. The distribution provides ESM JavaScript, TypeScript declarations and public subpaths for Node 24 and Bun 1.4 or newer.
 
-See the [Tangle documentation](https://github.com/jklarenbeek/tangleai#readme) for architecture, examples, and runtime requirements. All public Tangle packages use one coordinated version.
+The selected default disables novelty filtering, contradiction resolution and crystallization (each lowers to threshold 2). Memory retrieval uses k = 10 and minScore = 0. The pipeline's offline embedder is `hash-trigram-512`; its width was selected by lexical evidence recall independently of the live answer experiment. Explicit thresholds and retrieval overrides retain their meaning. Existing vectors keep their model/dimension identity and must be re-embedded before they can rank against a different embedder.
+
+```ts
+import {
+  DEFAULT_MEMORY_POLICY, POLICY_PROVENANCE, policyThresholds,
+  MEASURED_MEMORY_POLICIES, SHIPPED_LEGACY_POLICY, SHIPPED_LEGACY_CELL_ID,
+} from '@tangleai/memory/policy';
+
+const thresholds = policyThresholds(); // selected default: all three thresholds are 2
+console.log(DEFAULT_MEMORY_POLICY.retrieval); // { k: 10, minScore: 0 }
+console.log(POLICY_PROVENANCE.reportId); // exact source report for the decision
+```
+
+`MEASURED_MEMORY_POLICIES[cellId]` contains measured alternatives with their original effective values and labels. `SHIPPED_LEGACY_POLICY` aliases the historical shipped cell (novelty 0.97, contradiction 0.8, crystallization 0.9, maxPairs 20, k 10, minScore 0, hash width 64). This is opt-in data, not a recommended provider profile. To reproduce its pipeline settings:
+
+```ts
+import { createMemoryUnitStore } from '@tangleai/memory';
+import { createPipeline } from '@tangleai/pipeline';
+import { createHashEmbedder } from '@tangleai/models/embed';
+
+const store = createMemoryUnitStore();
+const legacyPipeline = createPipeline({
+  store,
+  thresholds: policyThresholds(SHIPPED_LEGACY_POLICY),
+  embedder: createHashEmbedder({ dims: SHIPPED_LEGACY_POLICY.embedding.dims }),
+});
+// Use SHIPPED_LEGACY_POLICY.retrieval explicitly when recalling its memories.
+```
+
+The [registered report](https://github.com/jklarenbeek/tangleai/blob/main/docs/LOCOMO_POLICY.md) selected inert: the challenger gained F1 0.000719 over 89 held-out questions, with 95% interval [-0.001464, 0.003216]. Its paired SD was 0.011458; the registered minimum detectable effect was 0.002380 (1.96 × standard error, a precision diagnostic rather than a powered equivalence test). Every clause except a positive overall interval passed. This does not prove equivalence or a general absence of benefit. The result is bounded to one dataset, model and sample; disabling resolution can leave conflicting observations retrievable.
+
+`POLICY_PROVENANCE` carries report, registration, cell, source, challenger and transition identities, per-field measurement tiers, decision clauses and power. `POLICY_CONTRACT_REVISION` is the Jaren contract revision; JSON contracts are exported at `@tangleai/memory/schemas/policy.contract.json` and `@tangleai/memory/schemas/policy.schema.json`. Config profiles reference this owner rather than copy its values. Generation reads validated benchmark evidence only during development; runtime packages never import benchmark files.
+
+From the repository root:
+
+```sh
+npm run policy:check
+npm run policy:contract:check
+npm run emit:policy -- --check
+```
+
+The drift check validates the immutable live evidence, regenerates the expected artifact in memory, checks the registry reference and probes the public runtime behavior. `npm run policy:generate` writes a default only from a complete eligible confirmation; regenerate declarations with `npm run emit:policy` after a contract change. Contract compatibility is checked against the committed v1 fixture.
+
+## Outcome confidence
+
+`applyOutcome(store, report, {options}?)` adjusts confidence once per cited entry
+in that call: success +0.15, failure −0.25, partial +0.05 by default, starting at
+0.5 when absent and clamping to [0.1, 1]. It preserves the legacy behavior:
+duplicate citations apply repeatedly, repeated calls apply again, and `report.at`
+replaces fact time. Its four-method store interface supplies no durable replay
+receipt or atomic multi-memory guarantee; a failed later write can leave an
+earlier write applied. A host-supplied report is not independently resolved by
+this helper.
+
+`projectOutcomeConfidence(unit, outcome, options?)` is the shared pure arithmetic
+helper. It returns a detached unit and preserves all fields except confidence.
+For independently evidenced scoring, sorted unique authorized citations,
+preserved fact timestamps and atomic receipt-plus-memory updates, use
+`@tangleai/outcomes` with its own memory store or `@tangleai/store`'s
+`createOutcomeStore(db)`. Missing cited ids are terminal counted skips there;
+a completed projection never reapplies after the id is restored. See the
+[outcome adapter kit](../outcomes/docs/ADAPTERS.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangleai/memory",
-  "version": "0.21.1",
+  "version": "0.24.1",
   "description": "Tangle AI memory policies — novelty gating, crystallization, contradiction resolution, outcome learning — over an injected store",
   "license": "MIT",
   "type": "module",
@@ -46,17 +46,24 @@
       "import": "./src/retrieval.js",
       "default": "./src/retrieval.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./policy": {
+      "types": "./src/policy.d.ts",
+      "import": "./src/policy.js",
+      "default": "./src/policy.js"
+    },
+    "./schemas/policy.schema.json": "./schemas/policy.schema.json",
+    "./schemas/policy.contract.json": "./schemas/policy.contract.json"
   },
   "engines": {
     "node": ">=24"
   },
   "sideEffects": false,
   "dependencies": {
-    "@tangleai/core": "^0.21.1",
-    "@jarenjs/core": "0.84.3",
-    "@jarenjs/validate": "0.84.3",
-    "@tangleai/context": "^0.21.1"
+    "@tangleai/core": "^0.24.1",
+    "@jarenjs/core": "0.86.0",
+    "@jarenjs/validate": "0.86.0",
+    "@tangleai/context": "^0.24.1"
   },
   "private": false,
   "types": "./src/index.d.ts",

package/schemas/policy.contract.json

@@ -0,0 +1,256 @@
+{
+  "$contract": "0.1",
+  "id": "tangle-memory-policy",
+  "version": "1",
+  "operations": {
+    "policy.provenance": {
+      "kind": "read",
+      "input": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [],
+        "properties": {}
+      },
+      "output": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "reportId",
+          "registrationId",
+          "cellId",
+          "sourceId",
+          "transitionId",
+          "challengerId",
+          "ingestTier",
+          "retrievalTier",
+          "embeddingTier",
+          "qualifiesAsDefault",
+          "statement",
+          "power",
+          "interval",
+          "clauses"
+        ],
+        "properties": {
+          "reportId": {
+            "type": "string"
+          },
+          "registrationId": {
+            "type": "string"
+          },
+          "cellId": {
+            "type": "string"
+          },
+          "sourceId": {
+            "type": "string"
+          },
+          "transitionId": {
+            "type": "string"
+          },
+          "challengerId": {
+            "type": "string"
+          },
+          "ingestTier": {
+            "const": "live"
+          },
+          "retrievalTier": {
+            "const": "live"
+          },
+          "embeddingTier": {
+            "const": "keyless"
+          },
+          "qualifiesAsDefault": {
+            "type": "boolean"
+          },
+          "statement": {
+            "type": "string"
+          },
+          "power": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "pairedSd",
+              "standardError",
+              "minimumDetectableEffect",
+              "tiedPairs",
+              "actingSetSize"
+            ],
+            "properties": {
+              "pairedSd": {
+                "type": "number"
+              },
+              "standardError": {
+                "type": "number"
+              },
+              "minimumDetectableEffect": {
+                "type": "number"
+              },
+              "tiedPairs": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "actingSetSize": {
+                "type": "integer",
+                "minimum": 0
+              }
+            }
+          },
+          "interval": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "low",
+              "high"
+            ],
+            "properties": {
+              "low": {
+                "type": "number"
+              },
+              "high": {
+                "type": "number"
+              }
+            }
+          },
+          "clauses": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "clause",
+                "passed",
+                "detail"
+              ],
+              "properties": {
+                "clause": {
+                  "type": "string"
+                },
+                "passed": {
+                  "type": "boolean"
+                },
+                "detail": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "policy.read": {
+      "kind": "read",
+      "input": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [],
+        "properties": {}
+      },
+      "output": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "novelty",
+          "contradiction",
+          "crystallization",
+          "retrieval",
+          "embedding"
+        ],
+        "properties": {
+          "novelty": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "enabled",
+              "threshold"
+            ],
+            "properties": {
+              "enabled": {
+                "type": "boolean"
+              },
+              "threshold": {
+                "type": "number"
+              }
+            }
+          },
+          "contradiction": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "enabled",
+              "threshold",
+              "maxPairs"
+            ],
+            "properties": {
+              "enabled": {
+                "type": "boolean"
+              },
+              "threshold": {
+                "type": "number"
+              },
+              "maxPairs": {
+                "type": "integer",
+                "minimum": 0
+              }
+            }
+          },
+          "crystallization": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "enabled",
+              "threshold"
+            ],
+            "properties": {
+              "enabled": {
+                "type": "boolean"
+              },
+              "threshold": {
+                "type": "number"
+              }
+            }
+          },
+          "retrieval": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "k",
+              "minScore"
+            ],
+            "properties": {
+              "k": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "minScore": {
+                "type": "number"
+              }
+            }
+          },
+          "embedding": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "model",
+              "dims",
+              "tier"
+            ],
+            "properties": {
+              "model": {
+                "type": "string"
+              },
+              "dims": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "tier": {
+                "type": "string",
+                "enum": [
+                  "keyless"
+                ]
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/policy.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://tangleai.dev/schemas/memory-policy-values",
+  "title": "MemoryPolicyValues",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "novelty",
+    "contradiction",
+    "crystallization",
+    "retrieval",
+    "embedding"
+  ],
+  "properties": {
+    "novelty": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "enabled",
+        "threshold"
+      ],
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "threshold": {
+          "type": "number"
+        }
+      }
+    },
+    "contradiction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "enabled",
+        "threshold",
+        "maxPairs"
+      ],
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "threshold": {
+          "type": "number"
+        },
+        "maxPairs": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "crystallization": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "enabled",
+        "threshold"
+      ],
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "threshold": {
+          "type": "number"
+        }
+      }
+    },
+    "retrieval": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "k",
+        "minScore"
+      ],
+      "properties": {
+        "k": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "minScore": {
+          "type": "number"
+        }
+      }
+    },
+    "embedding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "model",
+        "dims",
+        "tier"
+      ],
+      "properties": {
+        "model": {
+          "type": "string"
+        },
+        "dims": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "tier": {
+          "type": "string",
+          "enum": [
+            "keyless"
+          ]
+        }
+      }
+    }
+  }
+}

package/src/contradiction.d.ts

@@ -33,8 +33,8 @@
  */
 import type { JsonSchema, MemoryUnit } from '@tangleai/core/schemas/memory';
 import type { MemoryStore } from './store.ts';
-export declare const DEFAULT_CONTRADICTION_THRESHOLD = 0.75;
-export declare const DEFAULT_MAX_PAIRS = 20;
+export declare const DEFAULT_CONTRADICTION_THRESHOLD: number;
+export declare const DEFAULT_MAX_PAIRS: number;
 /** What a judge must answer. Wire it to @tangleai/models `createStructuredOutput`
  * as the `schema` and the repair loop enforces it for free. */
 export declare const CONTRADICTION_VERDICT_SCHEMA: JsonSchema;

package/src/contradiction.js

@@ -33,8 +33,9 @@
  */
 import { cosineSimilarity } from '@jarenjs/core/vector';
 import { createMemoryUnit } from "./ingest.js";
-export const DEFAULT_CONTRADICTION_THRESHOLD = 0.75;
-export const DEFAULT_MAX_PAIRS = 20;
+import { policyThresholds, DEFAULT_MEMORY_POLICY } from "./policy.js";
+export const DEFAULT_CONTRADICTION_THRESHOLD = policyThresholds().contradiction;
+export const DEFAULT_MAX_PAIRS = DEFAULT_MEMORY_POLICY.contradiction.maxPairs;
 /** What a judge must answer. Wire it to @tangleai/models `createStructuredOutput`
  * as the `schema` and the repair loop enforces it for free. */
 export const CONTRADICTION_VERDICT_SCHEMA = {

package/src/crystallize.d.ts

@@ -7,7 +7,7 @@
  * against a live Memgraph; here the plan is a value you can assert on.
  *
  * Policy (unchanged from memflow):
- *  - pairwise similarity >= threshold (default 0.92) marks a duplicate pair
+ *  - pairwise similarity >= threshold (selected policy; disabled by default) marks a duplicate pair
  *  - the higher-confidence record survives; ties keep the first
  *  - a record participates in at most one merge per pass — a chain
  *    A~B~C collapses over successive passes, not in one ambiguous step
@@ -34,7 +34,7 @@
  */
 import type { MemoryUnit } from '@tangleai/core/schemas/memory';
 import type { MemoryStore } from './store.ts';
-export declare const DEFAULT_CRYSTALLIZE_THRESHOLD = 0.92;
+export declare const DEFAULT_CRYSTALLIZE_THRESHOLD: number;
 export declare const CONFIDENCE_BOOST = 0.05;
 export declare const CONFIDENCE_FLOOR = 0.1;
 export interface CrystallizeMerge {

package/src/crystallize.js

@@ -7,7 +7,7 @@
  * against a live Memgraph; here the plan is a value you can assert on.
  *
  * Policy (unchanged from memflow):
- *  - pairwise similarity >= threshold (default 0.92) marks a duplicate pair
+ *  - pairwise similarity >= threshold (selected policy; disabled by default) marks a duplicate pair
  *  - the higher-confidence record survives; ties keep the first
  *  - a record participates in at most one merge per pass — a chain
  *    A~B~C collapses over successive passes, not in one ambiguous step
@@ -34,7 +34,8 @@
  */
 import { cosineSimilarity } from '@jarenjs/core/vector';
 import { sameIdentity } from '@tangleai/context/ledger';
-export const DEFAULT_CRYSTALLIZE_THRESHOLD = 0.92;
+import { policyThresholds, DEFAULT_MEMORY_POLICY } from "./policy.js";
+export const DEFAULT_CRYSTALLIZE_THRESHOLD = policyThresholds().crystallize;
 export const CONFIDENCE_BOOST = 0.05;
 export const CONFIDENCE_FLOOR = 0.1;
 /** Decide which records to merge. Pure. */

package/src/index.d.ts

@@ -9,7 +9,9 @@ export { planCrystallization, applyCrystallization, DEFAULT_CRYSTALLIZE_THRESHOL
 export type { CrystallizeMerge, CrystallizePlan, CrystallizeOptions, CrystallizeOutcome } from './crystallize.ts';
 export { planContradictionPairs, resolveContradictions, contradictionMessages, CONTRADICTION_VERDICT_SCHEMA, DEFAULT_CONTRADICTION_THRESHOLD, DEFAULT_MAX_PAIRS, } from './contradiction.ts';
 export type { ContradictionVerdict, ContradictionPair, ChatMessage, ResolveOptions, ResolveOutcome, } from './contradiction.ts';
-export { applyOutcome, outcomeAdjustment, DEFAULT_OUTCOME_OPTIONS } from './outcome.ts';
+export { applyOutcome, projectOutcomeConfidence, outcomeAdjustment, DEFAULT_OUTCOME_OPTIONS } from './outcome.ts';
 export type { OutcomeOptions, ApplyOutcomeResult } from './outcome.ts';
 export { rankByEmbedding, recallByEmbedding } from './retrieval.ts';
 export type { RankOptions, RankedMemory, RankedRecall } from './retrieval.ts';
+export { DEFAULT_MEMORY_POLICY, POLICY_PROVENANCE, MEASURED_MEMORY_POLICIES, SHIPPED_LEGACY_POLICY, SHIPPED_LEGACY_CELL_ID, POLICY_CONTRACT_REVISION, policyThresholds } from './policy.ts';
+export type { MemoryPolicyValues } from './policy.ts';

package/src/index.js

@@ -4,5 +4,6 @@ export { createMemoryUnit, memoryId } from "./ingest.js";
 export { noveltyGate, DEFAULT_NOVELTY_THRESHOLD } from "./novelty.js";
 export { planCrystallization, applyCrystallization, DEFAULT_CRYSTALLIZE_THRESHOLD, CONFIDENCE_BOOST, CONFIDENCE_FLOOR, } from "./crystallize.js";
 export { planContradictionPairs, resolveContradictions, contradictionMessages, CONTRADICTION_VERDICT_SCHEMA, DEFAULT_CONTRADICTION_THRESHOLD, DEFAULT_MAX_PAIRS, } from "./contradiction.js";
-export { applyOutcome, outcomeAdjustment, DEFAULT_OUTCOME_OPTIONS } from "./outcome.js";
+export { applyOutcome, projectOutcomeConfidence, outcomeAdjustment, DEFAULT_OUTCOME_OPTIONS } from "./outcome.js";
 export { rankByEmbedding, recallByEmbedding } from "./retrieval.js";
+export { DEFAULT_MEMORY_POLICY, POLICY_PROVENANCE, MEASURED_MEMORY_POLICIES, SHIPPED_LEGACY_POLICY, SHIPPED_LEGACY_CELL_ID, POLICY_CONTRACT_REVISION, policyThresholds } from "./policy.js";

package/src/novelty.d.ts

@@ -21,7 +21,7 @@
  * Pure: no store, no clock, no log. The caller applies the result.
  */
 import type { MemoryUnit } from '@tangleai/core/schemas/memory';
-export declare const DEFAULT_NOVELTY_THRESHOLD = 0.75;
+export declare const DEFAULT_NOVELTY_THRESHOLD: number;
 export interface NoveltyOptions {
     threshold?: number;
 }

package/src/novelty.js

@@ -22,7 +22,8 @@
  */
 import { cosineSimilarity } from '@jarenjs/core/vector';
 import { sameIdentity } from '@tangleai/context/ledger';
-export const DEFAULT_NOVELTY_THRESHOLD = 0.75;
+import { policyThresholds, DEFAULT_MEMORY_POLICY } from "./policy.js";
+export const DEFAULT_NOVELTY_THRESHOLD = policyThresholds().novelty;
 export function noveltyGate(candidates, existing, options = {}) {
     const threshold = options.threshold ?? DEFAULT_NOVELTY_THRESHOLD;
     const novel = [];

package/src/outcome.d.ts

@@ -11,7 +11,7 @@
  * down to the floor but never silently erased by arithmetic — deletion
  * is a separate, auditable decision.
  */
-import type { OutcomeReport } from '@tangleai/core/schemas/memory';
+import type { MemoryUnit, OutcomeReport } from '@tangleai/core/schemas/memory';
 import type { MemoryStore } from './store.ts';
 export interface OutcomeOptions {
     successBoost: number;
@@ -28,6 +28,8 @@ export interface ApplyOutcomeResult {
     adjustment: number;
     missing: string[];
 }
+/** Detached confidence projection; preserves fact time and all other fields. */
+export declare function projectOutcomeConfidence(unit: MemoryUnit, category: OutcomeReport['outcome'], options?: OutcomeOptions): MemoryUnit;
 /** Apply an outcome report to the store. */
 export declare function applyOutcome(store: MemoryStore, report: OutcomeReport, config?: {
     options?: OutcomeOptions;