@tangleai/memory 0.20.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @tangleai/memory
+
+## 0.20.0
+
+### Minor Changes
+
+- Establish the coordinated 0.20.0 release with JavaScript and TypeScript declaration distributions, preserved public subpaths and JSON schemas, and verified Node and Bun consumers. Use published JarenJS 0.83.3 fixes without a consumer installation patch. Prepare versions before release commits, verify locally, push directly to main and publish CI-verified tarballs. Deploy the website independently from local Tangle workspace source with JarenJS packages from npm, verifying dependency sources and the live commit.
+
+### Patch Changes
+
+- Updated dependencies
+  - @tangleai/core@0.20.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joham (jklarenbeek@gmail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @tangleai/memory
+
+Tangle AI memory policies — novelty gating, crystallization, contradiction resolution, 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.
+
+See the [Tangle documentation](https://github.com/jklarenbeek/tangleai#readme) for architecture, examples, and runtime requirements. All public Tangle packages use one coordinated version.

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@tangleai/memory",
+  "version": "0.20.0",
+  "description": "Tangle AI memory policies — novelty gating, crystallization, contradiction resolution, outcome learning — over an injected store",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./store": {
+      "types": "./src/store.d.ts",
+      "import": "./src/store.js",
+      "default": "./src/store.js"
+    },
+    "./ingest": {
+      "types": "./src/ingest.d.ts",
+      "import": "./src/ingest.js",
+      "default": "./src/ingest.js"
+    },
+    "./novelty": {
+      "types": "./src/novelty.d.ts",
+      "import": "./src/novelty.js",
+      "default": "./src/novelty.js"
+    },
+    "./crystallize": {
+      "types": "./src/crystallize.d.ts",
+      "import": "./src/crystallize.js",
+      "default": "./src/crystallize.js"
+    },
+    "./contradiction": {
+      "types": "./src/contradiction.d.ts",
+      "import": "./src/contradiction.js",
+      "default": "./src/contradiction.js"
+    },
+    "./outcome": {
+      "types": "./src/outcome.d.ts",
+      "import": "./src/outcome.js",
+      "default": "./src/outcome.js"
+    },
+    "./retrieval": {
+      "types": "./src/retrieval.d.ts",
+      "import": "./src/retrieval.js",
+      "default": "./src/retrieval.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@jarenjs/ai": "0.83.3",
+    "@tangleai/core": "^0.20.0",
+    "@jarenjs/core": "0.83.3",
+    "@jarenjs/validate": "0.83.3"
+  },
+  "private": false,
+  "types": "./src/index.d.ts",
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "schemas/**/*.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/tangleai.git",
+    "directory": "packages/memory"
+  }
+}

package/src/contradiction.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Contradiction resolution — ported from memflow `ContradictionModule`,
+ * with the LLM moved behind a seam.
+ *
+ * memflow called `llm.invoke()` inline and regex-scraped JSON out of the
+ * reply. Here the judge is INJECTED: any async function answering the
+ * verdict shape. The intended production judge is two lines of
+ * @jarenjs/ai — `createStructuredOutput({ client, schema:
+ * CONTRADICTION_VERDICT_SCHEMA })` over `contradictionMessages(a, b)` —
+ * which buys schema-constrained decoding and the bounded repair loop
+ * instead of a regex. The tests inject a table.
+ *
+ * Policy (unchanged): only pairs similar enough to be ABOUT the same
+ * thing (>= threshold, default 0.75) are worth judging; the most similar
+ * pairs are judged first; at most `maxPairs` LLM calls per pass. On a
+ * confirmed contradiction the OLDER record is marked superseded (never
+ * deleted — "what did we believe before" stays answerable). A judge
+ * failure skips the pair; it never kills the pass.
+ *
+ * Tolerance is not silence. A pass that skipped every pair because the
+ * judge was down and a pass that judged every pair and found nothing
+ * are different outcomes, and a measurement that cannot tell them apart
+ * cannot say what a threshold did — so the outcome counts both halves
+ * of both forks: every attempt is judged or failed, and every confirmed
+ * verdict is applied or skipped because its older record was already
+ * gone.
+ *
+ * Only a SYNTHESIZED resolution becomes a new record. When the judge
+ * answers with the newer record's own text (or nothing), the newer
+ * record IS the resolution — writing it again would content-address to
+ * the same id and overwrite the embedded fact with an un-embedded
+ * summary, which is how the winner disappears from ranked recall.
+ */
+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;
+/** What a judge must answer. Wire it to @jarenjs/ai `createStructuredOutput`
+ * as the `schema` and the repair loop enforces it for free. */
+export declare const CONTRADICTION_VERDICT_SCHEMA: JsonSchema;
+export interface ContradictionVerdict {
+    contradiction: boolean;
+    reason?: string;
+    resolution?: string;
+}
+export interface ChatMessage {
+    role: string;
+    content: string;
+}
+/**
+ * The judge's chat messages for one pair — kept beside the schema so the
+ * prompt and the contract cannot drift apart.
+ */
+export declare function contradictionMessages(a: MemoryUnit, b: MemoryUnit): ChatMessage[];
+export interface ContradictionPair {
+    a: MemoryUnit;
+    b: MemoryUnit;
+    similarity: number;
+}
+export interface ContradictionPlanOptions {
+    threshold?: number;
+    maxPairs?: number;
+}
+/** Select the pairs worth judging. Pure. */
+export declare function planContradictionPairs(units: MemoryUnit[], options?: ContradictionPlanOptions): ContradictionPair[];
+export interface ResolveOptions {
+    judge: (a: MemoryUnit, b: MemoryUnit) => Promise<ContradictionVerdict | null>;
+    /** RFC 3339. */
+    now: () => string;
+}
+export interface ResolveOutcome {
+    /** Planned pairs handed to the judge. */
+    attempted: number;
+    /** Pairs the judge answered. */
+    judged: number;
+    /** Judge calls that threw: the pair is skipped, the pass continues. */
+    judgeFailures: number;
+    /** Verdicts that confirmed a contradiction — applied or skipped. */
+    confirmed: number;
+    /** Confirmed contradictions written: the older record marked superseded. */
+    contradictions: number;
+    /** Confirmed contradictions whose older record was gone at write time. */
+    applicationSkips: number;
+    resolutions: MemoryUnit[];
+}
+/** Judge the planned pairs and resolve confirmed contradictions in the store. */
+export declare function resolveContradictions(store: MemoryStore, pairs: ContradictionPair[], options: ResolveOptions): Promise<ResolveOutcome>;

package/src/contradiction.js

@@ -0,0 +1,138 @@
+/**
+ * Contradiction resolution — ported from memflow `ContradictionModule`,
+ * with the LLM moved behind a seam.
+ *
+ * memflow called `llm.invoke()` inline and regex-scraped JSON out of the
+ * reply. Here the judge is INJECTED: any async function answering the
+ * verdict shape. The intended production judge is two lines of
+ * @jarenjs/ai — `createStructuredOutput({ client, schema:
+ * CONTRADICTION_VERDICT_SCHEMA })` over `contradictionMessages(a, b)` —
+ * which buys schema-constrained decoding and the bounded repair loop
+ * instead of a regex. The tests inject a table.
+ *
+ * Policy (unchanged): only pairs similar enough to be ABOUT the same
+ * thing (>= threshold, default 0.75) are worth judging; the most similar
+ * pairs are judged first; at most `maxPairs` LLM calls per pass. On a
+ * confirmed contradiction the OLDER record is marked superseded (never
+ * deleted — "what did we believe before" stays answerable). A judge
+ * failure skips the pair; it never kills the pass.
+ *
+ * Tolerance is not silence. A pass that skipped every pair because the
+ * judge was down and a pass that judged every pair and found nothing
+ * are different outcomes, and a measurement that cannot tell them apart
+ * cannot say what a threshold did — so the outcome counts both halves
+ * of both forks: every attempt is judged or failed, and every confirmed
+ * verdict is applied or skipped because its older record was already
+ * gone.
+ *
+ * Only a SYNTHESIZED resolution becomes a new record. When the judge
+ * answers with the newer record's own text (or nothing), the newer
+ * record IS the resolution — writing it again would content-address to
+ * the same id and overwrite the embedded fact with an un-embedded
+ * summary, which is how the winner disappears from ranked recall.
+ */
+import { cosineSimilarity } from '@jarenjs/core/vector';
+import { createMemoryUnit } from "./ingest.js";
+export const DEFAULT_CONTRADICTION_THRESHOLD = 0.75;
+export const DEFAULT_MAX_PAIRS = 20;
+/** What a judge must answer. Wire it to @jarenjs/ai `createStructuredOutput`
+ * as the `schema` and the repair loop enforces it for free. */
+export const CONTRADICTION_VERDICT_SCHEMA = {
+    $id: 'https://tangleai.dev/schemas/contradiction-verdict.json',
+    type: 'object',
+    properties: {
+        contradiction: { type: 'boolean' },
+        reason: { type: 'string' },
+        resolution: { type: 'string' },
+    },
+    required: ['contradiction'],
+    additionalProperties: false,
+};
+/**
+ * The judge's chat messages for one pair — kept beside the schema so the
+ * prompt and the contract cannot drift apart.
+ */
+export function contradictionMessages(a, b) {
+    return [
+        {
+            role: 'system',
+            content: 'You judge whether two memory records contradict each other. '
+                + 'Two records contradict when both cannot be true at once — differing detail or scope is not contradiction. '
+                + 'When they do contradict, state the reason and write a single resolution sentence that reflects the better-evidenced record.',
+        },
+        {
+            role: 'user',
+            content: `Record A (${a.at}): "${a.text}" (evidence: ${a.evidence})\n`
+                + `Record B (${b.at}): "${b.text}" (evidence: ${b.evidence})\n`
+                + 'Do these contradict?',
+        },
+    ];
+}
+/** Select the pairs worth judging. Pure. */
+export function planContradictionPairs(units, options = {}) {
+    const threshold = options.threshold ?? DEFAULT_CONTRADICTION_THRESHOLD;
+    const maxPairs = options.maxPairs ?? DEFAULT_MAX_PAIRS;
+    const candidates = [];
+    const live = units.filter((u) => !u.supersededBy);
+    for (let i = 0; i < live.length; i++) {
+        for (let j = i + 1; j < live.length; j++) {
+            const a = live[i];
+            const b = live[j];
+            if (!a.embedding || !b.embedding)
+                continue;
+            const sim = cosineSimilarity(a.embedding, b.embedding);
+            if (sim >= threshold)
+                candidates.push({ a, b, similarity: sim });
+        }
+    }
+    candidates.sort((x, y) => y.similarity - x.similarity);
+    return candidates.slice(0, maxPairs);
+}
+/** Judge the planned pairs and resolve confirmed contradictions in the store. */
+export async function resolveContradictions(store, pairs, options) {
+    let contradictions = 0;
+    let judged = 0;
+    let judgeFailures = 0;
+    let confirmed = 0;
+    let applicationSkips = 0;
+    const resolutions = [];
+    for (const pair of pairs) {
+        let verdict = null;
+        try {
+            verdict = await options.judge(pair.a, pair.b);
+        }
+        catch {
+            judgeFailures++; // a judge failure skips the pair, never the pass — and is counted
+            continue;
+        }
+        judged++;
+        if (!verdict?.contradiction)
+            continue;
+        confirmed++;
+        const older = pair.a.at <= pair.b.at ? pair.a : pair.b;
+        const newer = older === pair.a ? pair.b : pair.a;
+        const supersededAt = options.now();
+        const loser = await store.get(older.id);
+        if (!loser) {
+            applicationSkips++;
+            continue;
+        } // a prior pass or a host raced us
+        loser.supersededBy = newer.id;
+        loser.supersededAt = supersededAt;
+        loser.supersededReason = verdict.reason ?? 'contradiction detected';
+        await store.put(loser);
+        if (verdict.resolution !== undefined && verdict.resolution !== newer.text) {
+            const resolution = createMemoryUnit({
+                text: verdict.resolution,
+                evidence: `contradiction resolution of ${older.id} by ${newer.id}: ${verdict.reason ?? 'contradiction detected'}`,
+                tags: [...new Set([...older.tags, ...newer.tags, 'resolution'])],
+                at: supersededAt,
+                kind: 'summary',
+            });
+            await store.put(resolution);
+            resolutions.push(resolution);
+        }
+        contradictions++;
+    }
+    return { attempted: pairs.length, judged, judgeFailures, confirmed, contradictions, applicationSkips, resolutions };
+}

package/src/crystallize.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Crystallization — merge near-duplicate memories into canonical forms.
+ * Ported from memflow `CrystallizerModule`, split into the house shape:
+ * a PURE planner that decides what to merge, and an applier that executes
+ * the plan against a store. memflow fused deciding and Cypher-executing
+ * in one method, which meant the merge policy could only ever be tested
+ * 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
+ *  - 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
+ *  - only records embedded by the same identity are compared (the
+ *    jarenjs rule: vectors from two models never rank against each
+ *    other); the metric is `@jarenjs/core/vector`'s cosine
+ *
+ * Application details that changed, deliberately:
+ *  - the survivor's confidence rises by `boost` (0.05), clamped to
+ *    [floor, 1]; the floor keeps a record demotable but never erasable
+ *  - the absorbed record's id lands in `mergedFrom` (provenance — the
+ *    Cypher version kept `originalIds`, same idea)
+ *  - tags are unioned, relations are concatenated with per-target
+ *    weight summing, evidence strings are joined — nothing is dropped
+ *  - the absorbed record is DELETED from the store; its id in
+ *    `mergedFrom` is the tombstone
+ *
+ * The applier counts what it planned as well as what it did: a merge
+ * whose keep or remove record vanished between planning and writing is
+ * skipped rather than guessed, and that skip is a value, because a pass
+ * that merged nothing because nothing matched and a pass that merged
+ * nothing because every planned record had been raced away are
+ * different outcomes.
+ */
+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 CONFIDENCE_BOOST = 0.05;
+export declare const CONFIDENCE_FLOOR = 0.1;
+export interface CrystallizeMerge {
+    keepId: string;
+    removeId: string;
+    similarity: number;
+}
+export interface CrystallizePlan {
+    merges: CrystallizeMerge[];
+    examined: number;
+}
+export interface CrystallizeOptions {
+    threshold?: number;
+}
+/** Decide which records to merge. Pure. */
+export declare function planCrystallization(units: MemoryUnit[], options?: CrystallizeOptions): CrystallizePlan;
+export interface ApplyOptions {
+    /** Returns RFC 3339 — injected, like every clock in the suite. */
+    now: () => string;
+}
+export interface CrystallizeOutcome {
+    /** Merges the plan asked for. */
+    planned: number;
+    /** Merges written. */
+    crystallized: number;
+    /** Planned merges whose keep or remove record was gone at write time. */
+    applicationSkips: number;
+}
+/** Execute a crystallization plan against a store. */
+export declare function applyCrystallization(store: MemoryStore, plan: CrystallizePlan, options: ApplyOptions): Promise<CrystallizeOutcome>;

package/src/crystallize.js

@@ -0,0 +1,106 @@
+/**
+ * Crystallization — merge near-duplicate memories into canonical forms.
+ * Ported from memflow `CrystallizerModule`, split into the house shape:
+ * a PURE planner that decides what to merge, and an applier that executes
+ * the plan against a store. memflow fused deciding and Cypher-executing
+ * in one method, which meant the merge policy could only ever be tested
+ * 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
+ *  - 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
+ *  - only records embedded by the same identity are compared (the
+ *    jarenjs rule: vectors from two models never rank against each
+ *    other); the metric is `@jarenjs/core/vector`'s cosine
+ *
+ * Application details that changed, deliberately:
+ *  - the survivor's confidence rises by `boost` (0.05), clamped to
+ *    [floor, 1]; the floor keeps a record demotable but never erasable
+ *  - the absorbed record's id lands in `mergedFrom` (provenance — the
+ *    Cypher version kept `originalIds`, same idea)
+ *  - tags are unioned, relations are concatenated with per-target
+ *    weight summing, evidence strings are joined — nothing is dropped
+ *  - the absorbed record is DELETED from the store; its id in
+ *    `mergedFrom` is the tombstone
+ *
+ * The applier counts what it planned as well as what it did: a merge
+ * whose keep or remove record vanished between planning and writing is
+ * skipped rather than guessed, and that skip is a value, because a pass
+ * that merged nothing because nothing matched and a pass that merged
+ * nothing because every planned record had been raced away are
+ * different outcomes.
+ */
+import { cosineSimilarity } from '@jarenjs/core/vector';
+import { sameIdentity } from '@jarenjs/ai';
+export const DEFAULT_CRYSTALLIZE_THRESHOLD = 0.92;
+export const CONFIDENCE_BOOST = 0.05;
+export const CONFIDENCE_FLOOR = 0.1;
+/** Decide which records to merge. Pure. */
+export function planCrystallization(units, options = {}) {
+    const threshold = options.threshold ?? DEFAULT_CRYSTALLIZE_THRESHOLD;
+    const candidates = [];
+    for (let i = 0; i < units.length; i++) {
+        for (let j = i + 1; j < units.length; j++) {
+            const a = units[i];
+            const b = units[j];
+            if (!sameIdentity(a.embeddedBy, b.embeddedBy))
+                continue;
+            if (a.supersededBy || b.supersededBy)
+                continue;
+            const sim = cosineSimilarity(a.embedding, b.embedding);
+            if (sim >= threshold) {
+                const keep = (a.confidence ?? 0.5) >= (b.confidence ?? 0.5) ? a : b;
+                const remove = keep === a ? b : a;
+                candidates.push({ keepId: keep.id, removeId: remove.id, similarity: sim });
+            }
+        }
+    }
+    // one merge per record per pass
+    const taken = new Set();
+    const merges = [];
+    for (const m of candidates) {
+        if (taken.has(m.keepId) || taken.has(m.removeId))
+            continue;
+        taken.add(m.keepId);
+        taken.add(m.removeId);
+        merges.push(m);
+    }
+    return { merges, examined: units.length };
+}
+/** Execute a crystallization plan against a store. */
+export async function applyCrystallization(store, plan, options) {
+    let crystallized = 0;
+    let applicationSkips = 0;
+    for (const merge of plan.merges) {
+        const keep = await store.get(merge.keepId);
+        const remove = await store.get(merge.removeId);
+        if (!keep || !remove) {
+            applicationSkips++;
+            continue;
+        } // a prior merge or a host raced us; skip, don't guess
+        keep.confidence = Math.min(1, Math.max(CONFIDENCE_FLOOR, (keep.confidence ?? 0.5) + CONFIDENCE_BOOST));
+        keep.at = options.now();
+        keep.mergedFrom = [...(keep.mergedFrom ?? []), remove.id, ...(remove.mergedFrom ?? [])];
+        keep.tags = [...new Set([...keep.tags, ...remove.tags])];
+        if (remove.evidence && !keep.evidence.includes(remove.evidence)) {
+            keep.evidence = `${keep.evidence}; ${remove.evidence}`;
+        }
+        if (remove.relations?.length) {
+            const relations = keep.relations ? [...keep.relations] : [];
+            for (const rel of remove.relations) {
+                const existing = relations.find((r) => r.target === rel.target && r.relType === rel.relType);
+                if (existing)
+                    existing.weight = (existing.weight ?? 0.5) + (rel.weight ?? 0.5);
+                else
+                    relations.push({ ...rel });
+            }
+            keep.relations = relations;
+        }
+        await store.put(keep);
+        await store.delete(remove.id);
+        crystallized++;
+    }
+    return { planned: plan.merges.length, crystallized, applicationSkips };
+}

package/src/index.d.ts

@@ -0,0 +1,15 @@
+/** @tangleai/memory barrel. */
+export { createMemoryUnitStore } from './store.ts';
+export type { MemoryStore, MemoryUnitStoreOptions } from './store.ts';
+export { createMemoryUnit, memoryId } from './ingest.ts';
+export type { MemoryUnitInput } from './ingest.ts';
+export { noveltyGate, DEFAULT_NOVELTY_THRESHOLD } from './novelty.ts';
+export type { NoveltyOptions, NoveltyOutcome } from './novelty.ts';
+export { planCrystallization, applyCrystallization, DEFAULT_CRYSTALLIZE_THRESHOLD, CONFIDENCE_BOOST, CONFIDENCE_FLOOR, } from './crystallize.ts';
+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 type { OutcomeOptions, ApplyOutcomeResult } from './outcome.ts';
+export { rankByEmbedding, recallByEmbedding } from './retrieval.ts';
+export type { RankOptions, RankedMemory, RankedRecall } from './retrieval.ts';

package/src/index.js

@@ -0,0 +1,8 @@
+/** @tangleai/memory barrel. */
+export { createMemoryUnitStore } from "./store.js";
+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 { rankByEmbedding, recallByEmbedding } from "./retrieval.js";

package/src/ingest.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Turning raw observations into memory units.
+ *
+ * Ids are content-addressed — `m-<fnv1a(text)>-<length>` via the same
+ * `hashContent` the @jarenjs/ai recall slots use — so ingesting the same
+ * observation twice produces the same id and the second write is an
+ * overwrite, not a duplicate. Idempotence by construction beats
+ * deduplication by policy; the crystallizer then only has to handle
+ * NEAR-duplicates, which no hash can catch.
+ */
+import type { EmbeddedBy, MemoryKind, MemoryUnit } from '@tangleai/core/schemas/memory';
+export declare function memoryId(text: string): string;
+export interface MemoryUnitInput {
+    text: string;
+    /** Where this came from — required at the call site, not defaulted:
+     * the jarenjs rule that an unevidenced memory is a guess starts here,
+     * where it is cheapest to enforce. */
+    evidence: string;
+    /** RFC 3339 timestamp (injected, never Date.now here). */
+    at: string;
+    tags?: string[];
+    kind?: MemoryKind;
+    /** The vector and its identity travel together, or not at all. */
+    embedding?: number[];
+    embeddedBy?: EmbeddedBy;
+    confidence?: number;
+}
+export declare function createMemoryUnit(input: MemoryUnitInput): MemoryUnit;

package/src/ingest.js

@@ -0,0 +1,31 @@
+/**
+ * Turning raw observations into memory units.
+ *
+ * Ids are content-addressed — `m-<fnv1a(text)>-<length>` via the same
+ * `hashContent` the @jarenjs/ai recall slots use — so ingesting the same
+ * observation twice produces the same id and the second write is an
+ * overwrite, not a duplicate. Idempotence by construction beats
+ * deduplication by policy; the crystallizer then only has to handle
+ * NEAR-duplicates, which no hash can catch.
+ */
+import { hashContent } from '@jarenjs/core/string';
+export function memoryId(text) {
+    return `m-${hashContent(text)}-${text.length}`;
+}
+export function createMemoryUnit(input) {
+    const unit = {
+        id: memoryId(input.text),
+        text: input.text,
+        evidence: input.evidence,
+        tags: input.tags ?? [],
+        at: input.at,
+        kind: input.kind ?? 'fact',
+    };
+    if (input.embedding !== undefined && input.embeddedBy !== undefined) {
+        unit.embedding = input.embedding;
+        unit.embeddedBy = { ...input.embeddedBy };
+    }
+    if (input.confidence !== undefined)
+        unit.confidence = input.confidence;
+    return unit;
+}

package/src/novelty.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Novelty gate — LightMem's Tier-1 sensory filter (arXiv 2510.18866),
+ * ported from memflow `NoveltyGateModule` as a pure function.
+ *
+ * A candidate passes if it is sufficiently DIFFERENT from every existing
+ * memory and from every candidate already admitted in this batch (the
+ * batch self-check is what stops ten copies of the same observation from
+ * all being "novel against the store"). A candidate without an embedding
+ * passes — novelty cannot be measured, and silently dropping what we
+ * cannot measure would bias the store toward whatever the embedder was
+ * given first. For the same reason a candidate is only measured against
+ * records embedded by the SAME identity (`embeddedBy`): vectors from two
+ * models compare into plausible garbage, and jarenjs's rule is that they
+ * are never compared — so a record from another embedder is, to this
+ * candidate, unmeasurable.
+ *
+ * The metric is `cosineSimilarity` from `@jarenjs/core/vector` — the one
+ * the suite ranks by, and the one under which the pipeline's normalized
+ * vectors agree with dot and Euclidean in rank anyway.
+ *
+ * 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 interface NoveltyOptions {
+    threshold?: number;
+}
+export interface NoveltyOutcome {
+    novel: MemoryUnit[];
+    filtered: MemoryUnit[];
+}
+export declare function noveltyGate(candidates: MemoryUnit[], existing: MemoryUnit[], options?: NoveltyOptions): NoveltyOutcome;

package/src/novelty.js

@@ -0,0 +1,52 @@
+/**
+ * Novelty gate — LightMem's Tier-1 sensory filter (arXiv 2510.18866),
+ * ported from memflow `NoveltyGateModule` as a pure function.
+ *
+ * A candidate passes if it is sufficiently DIFFERENT from every existing
+ * memory and from every candidate already admitted in this batch (the
+ * batch self-check is what stops ten copies of the same observation from
+ * all being "novel against the store"). A candidate without an embedding
+ * passes — novelty cannot be measured, and silently dropping what we
+ * cannot measure would bias the store toward whatever the embedder was
+ * given first. For the same reason a candidate is only measured against
+ * records embedded by the SAME identity (`embeddedBy`): vectors from two
+ * models compare into plausible garbage, and jarenjs's rule is that they
+ * are never compared — so a record from another embedder is, to this
+ * candidate, unmeasurable.
+ *
+ * The metric is `cosineSimilarity` from `@jarenjs/core/vector` — the one
+ * the suite ranks by, and the one under which the pipeline's normalized
+ * vectors agree with dot and Euclidean in rank anyway.
+ *
+ * Pure: no store, no clock, no log. The caller applies the result.
+ */
+import { cosineSimilarity } from '@jarenjs/core/vector';
+import { sameIdentity } from '@jarenjs/ai';
+export const DEFAULT_NOVELTY_THRESHOLD = 0.75;
+export function noveltyGate(candidates, existing, options = {}) {
+    const threshold = options.threshold ?? DEFAULT_NOVELTY_THRESHOLD;
+    const novel = [];
+    const filtered = [];
+    const duplicates = (unit, against) => {
+        for (const other of against) {
+            if (!sameIdentity(unit.embeddedBy, other.embeddedBy))
+                continue;
+            if (cosineSimilarity(unit.embedding, other.embedding) >= threshold)
+                return true;
+        }
+        return false;
+    };
+    for (const unit of candidates) {
+        if (unit.embedding === undefined || unit.embeddedBy === undefined) {
+            novel.push(unit);
+            continue;
+        }
+        if (duplicates(unit, existing) || duplicates(unit, novel)) {
+            filtered.push(unit);
+        }
+        else {
+            novel.push(unit);
+        }
+    }
+    return { novel, filtered };
+}

package/src/outcome.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Outcome learning — ported from memflow `OutcomeLearnerModule`.
+ *
+ * The one idea worth keeping from the "Karpathy loop": confidence moves
+ * on GROUND TRUTH, not on the model's opinion of itself. A host files an
+ * `OutcomeReport` after acting on recalled memories — the report carries
+ * evidence of what actually happened — and the cited memories move:
+ * success boosts, failure penalizes (harder than success boosts, which
+ * is the asymmetry that makes the loop conservative), partial nudges.
+ * Confidence is clamped to [floor, max]: a memory can be discredited
+ * 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 { MemoryStore } from './store.ts';
+export interface OutcomeOptions {
+    successBoost: number;
+    failurePenalty: number;
+    partialBoost: number;
+    minConfidence: number;
+    maxConfidence: number;
+}
+export declare const DEFAULT_OUTCOME_OPTIONS: OutcomeOptions;
+/** The signed confidence delta for an outcome. Pure. */
+export declare function outcomeAdjustment(outcome: OutcomeReport['outcome'], options?: OutcomeOptions): number;
+export interface ApplyOutcomeResult {
+    adjusted: number;
+    adjustment: number;
+    missing: string[];
+}
+/** Apply an outcome report to the store. */
+export declare function applyOutcome(store: MemoryStore, report: OutcomeReport, config?: {
+    options?: OutcomeOptions;
+}): Promise<ApplyOutcomeResult>;

package/src/outcome.js

@@ -0,0 +1,48 @@
+/**
+ * Outcome learning — ported from memflow `OutcomeLearnerModule`.
+ *
+ * The one idea worth keeping from the "Karpathy loop": confidence moves
+ * on GROUND TRUTH, not on the model's opinion of itself. A host files an
+ * `OutcomeReport` after acting on recalled memories — the report carries
+ * evidence of what actually happened — and the cited memories move:
+ * success boosts, failure penalizes (harder than success boosts, which
+ * is the asymmetry that makes the loop conservative), partial nudges.
+ * Confidence is clamped to [floor, max]: a memory can be discredited
+ * down to the floor but never silently erased by arithmetic — deletion
+ * is a separate, auditable decision.
+ */
+export const DEFAULT_OUTCOME_OPTIONS = {
+    successBoost: 0.15,
+    failurePenalty: 0.25,
+    partialBoost: 0.05,
+    minConfidence: 0.1,
+    maxConfidence: 1.0,
+};
+/** The signed confidence delta for an outcome. Pure. */
+export function outcomeAdjustment(outcome, options = DEFAULT_OUTCOME_OPTIONS) {
+    switch (outcome) {
+        case 'success': return options.successBoost;
+        case 'failure': return -options.failurePenalty;
+        case 'partial': return options.partialBoost;
+        default: return 0;
+    }
+}
+/** Apply an outcome report to the store. */
+export async function applyOutcome(store, report, config = {}) {
+    const options = config.options ?? DEFAULT_OUTCOME_OPTIONS;
+    const adjustment = outcomeAdjustment(report.outcome, options);
+    let adjusted = 0;
+    const missing = [];
+    for (const id of report.memoryIds) {
+        const unit = await store.get(id);
+        if (!unit) {
+            missing.push(id); // reported, not swallowed — a report citing a
+            continue; // vanished memory is a fact the host should see
+        }
+        unit.confidence = Math.min(options.maxConfidence, Math.max(options.minConfidence, (unit.confidence ?? 0.5) + adjustment));
+        unit.at = report.at;
+        await store.put(unit);
+        adjusted++;
+    }
+    return { adjusted, adjustment, missing };
+}

package/src/retrieval.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Embedding-ranked retrieval over memory units.
+ *
+ * This is Tangle's ranker over its OWN store of full units, beside the
+ * @jarenjs/ai ledger's `recall({ near })` (which ranks the mirrored
+ * ledger records the same way, through the same kernels). Superseded
+ * records never surface — they exist for audit, not for recall. Records
+ * without embeddings never surface either, which is a real bias (see
+ * novelty.ts for the opposite choice on admission) — an un-embedded
+ * record can be ADMITTED honestly but cannot be RANKED honestly, so it
+ * waits for an embed pass rather than polluting the ranking with a fake
+ * score.
+ *
+ * The identity rule is the ledger's: a vector never ranks against one
+ * from another model. Given the query embedder's `identity`, only
+ * records embedded by it are ranked; the rest are reported in
+ * `skipped`, never scored and never hidden. Without an identity every
+ * embedded record is ranked — the caller has declared that it knows
+ * what it is comparing.
+ *
+ * The metric is `cosineSimilarity` from `@jarenjs/core/vector`: the one
+ * the suite ranks by, higher-is-better, 0 for a malformed pair.
+ */
+import { type Vector } from '@jarenjs/core/vector';
+import type { EmbeddedBy, MemoryUnit } from '@tangleai/core/schemas/memory';
+export interface RankOptions {
+    k?: number;
+    minScore?: number;
+    /** The query embedder's identity; records embedded by another are skipped. */
+    identity?: EmbeddedBy;
+}
+export interface RankedMemory {
+    unit: MemoryUnit;
+    score: number;
+}
+export interface RankedRecall {
+    /** Best first, at most `k`. */
+    ranked: RankedMemory[];
+    /** Live records that carry no vector, or a vector from another identity. */
+    skipped: number;
+}
+/**
+ * Rank the live, comparably-embedded units against a query vector and
+ * report what could not be ranked. `queryEmbedding` may be the
+ * `Float32Array` an embedder answers or the `number[]` a record stores.
+ */
+export declare function recallByEmbedding(units: MemoryUnit[], queryEmbedding: Vector, options?: RankOptions): RankedRecall;
+/** Best first, at most `k` — `recallByEmbedding` without the skip report. */
+export declare function rankByEmbedding(units: MemoryUnit[], queryEmbedding: Vector, options?: RankOptions): RankedMemory[];

package/src/retrieval.js

@@ -0,0 +1,57 @@
+/**
+ * Embedding-ranked retrieval over memory units.
+ *
+ * This is Tangle's ranker over its OWN store of full units, beside the
+ * @jarenjs/ai ledger's `recall({ near })` (which ranks the mirrored
+ * ledger records the same way, through the same kernels). Superseded
+ * records never surface — they exist for audit, not for recall. Records
+ * without embeddings never surface either, which is a real bias (see
+ * novelty.ts for the opposite choice on admission) — an un-embedded
+ * record can be ADMITTED honestly but cannot be RANKED honestly, so it
+ * waits for an embed pass rather than polluting the ranking with a fake
+ * score.
+ *
+ * The identity rule is the ledger's: a vector never ranks against one
+ * from another model. Given the query embedder's `identity`, only
+ * records embedded by it are ranked; the rest are reported in
+ * `skipped`, never scored and never hidden. Without an identity every
+ * embedded record is ranked — the caller has declared that it knows
+ * what it is comparing.
+ *
+ * The metric is `cosineSimilarity` from `@jarenjs/core/vector`: the one
+ * the suite ranks by, higher-is-better, 0 for a malformed pair.
+ */
+import { cosineSimilarity } from '@jarenjs/core/vector';
+import { sameIdentity } from '@jarenjs/ai';
+/**
+ * Rank the live, comparably-embedded units against a query vector and
+ * report what could not be ranked. `queryEmbedding` may be the
+ * `Float32Array` an embedder answers or the `number[]` a record stores.
+ */
+export function recallByEmbedding(units, queryEmbedding, options = {}) {
+    const k = options.k ?? 5;
+    const minScore = options.minScore ?? 0;
+    const identity = options.identity;
+    const scored = [];
+    let skipped = 0;
+    for (const unit of units) {
+        if (unit.supersededBy !== undefined)
+            continue;
+        const comparable = unit.embedding !== undefined && unit.embeddedBy !== undefined
+            && (identity === undefined || sameIdentity(unit.embeddedBy, identity));
+        if (!comparable) {
+            skipped++;
+            continue;
+        }
+        scored.push({ unit, score: cosineSimilarity(unit.embedding, queryEmbedding) });
+    }
+    const ranked = scored
+        .filter((s) => s.score >= minScore)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, k);
+    return { ranked, skipped };
+}
+/** Best first, at most `k` — `recallByEmbedding` without the skip report. */
+export function rankByEmbedding(units, queryEmbedding, options = {}) {
+    return recallByEmbedding(units, queryEmbedding, options).ranked;
+}

package/src/store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The memory store seam and its default in-memory implementation.
+ *
+ * The contract is four async methods — `get`, `put`, `delete`, `list` —
+ * the same injection shape as the @jarenjs/ai ledger's storage seam, one
+ * level up: this store holds validated memory UNITS, not raw strings.
+ * A host backs it with SQLite, OPFS, a graph database, whatever; the
+ * policies in this package only ever see the contract.
+ *
+ * Every `put` is validated against `MEMORY_UNIT_SCHEMA`. The rule is the
+ * ledger's rule: a malformed write is rejected at the boundary, because
+ * a store that accepts junk makes every later policy pass unsound.
+ * Records are JSON-cloned on the way in and out, so no caller holds a
+ * live reference into the store — mutation happens through `put`, or
+ * not at all.
+ *
+ * TS note: `JarenValidator<true>` (inferred from `collectErrors: true`)
+ * makes `compile()` return a collector whose outcome is a typed
+ * `{ valid, errors }` — the shape-reading dance the JS version did is
+ * carried by the published d.ts now.
+ */
+import { JarenValidator } from '@jarenjs/validate';
+import { type MemoryUnit } from '@tangleai/core/schemas/memory';
+export interface MemoryStore {
+    get(id: string): Promise<MemoryUnit | undefined>;
+    put(unit: MemoryUnit): Promise<void>;
+    delete(id: string): Promise<void>;
+    list(): Promise<MemoryUnit[]>;
+}
+export interface MemoryUnitStoreOptions {
+    validator?: JarenValidator<true>;
+}
+export declare function createMemoryUnitStore(options?: MemoryUnitStoreOptions): MemoryStore;

package/src/store.js

@@ -0,0 +1,52 @@
+/**
+ * The memory store seam and its default in-memory implementation.
+ *
+ * The contract is four async methods — `get`, `put`, `delete`, `list` —
+ * the same injection shape as the @jarenjs/ai ledger's storage seam, one
+ * level up: this store holds validated memory UNITS, not raw strings.
+ * A host backs it with SQLite, OPFS, a graph database, whatever; the
+ * policies in this package only ever see the contract.
+ *
+ * Every `put` is validated against `MEMORY_UNIT_SCHEMA`. The rule is the
+ * ledger's rule: a malformed write is rejected at the boundary, because
+ * a store that accepts junk makes every later policy pass unsound.
+ * Records are JSON-cloned on the way in and out, so no caller holds a
+ * live reference into the store — mutation happens through `put`, or
+ * not at all.
+ *
+ * TS note: `JarenValidator<true>` (inferred from `collectErrors: true`)
+ * makes `compile()` return a collector whose outcome is a typed
+ * `{ valid, errors }` — the shape-reading dance the JS version did is
+ * carried by the published d.ts now.
+ */
+import { JarenValidator } from '@jarenjs/validate';
+import { callerError } from '@tangleai/core/errors';
+import { MEMORY_UNIT_SCHEMA, MEMORY_RELATION_SCHEMA, } from '@tangleai/core/schemas/memory';
+function clone(value) {
+    return value === undefined ? value : JSON.parse(JSON.stringify(value));
+}
+export function createMemoryUnitStore(options = {}) {
+    const validator = options.validator
+        ?? new JarenValidator({ skipErrors: false, collectErrors: true, unknownFormats: 'ignore' });
+    validator.addSchema(MEMORY_RELATION_SCHEMA);
+    const validate = validator.compile(MEMORY_UNIT_SCHEMA);
+    const units = new Map();
+    return {
+        async get(id) {
+            return clone(units.get(id));
+        },
+        async put(unit) {
+            const outcome = validate(unit);
+            if (outcome.valid !== true) {
+                throw callerError(`memory unit rejected by schema: ${JSON.stringify(outcome.errors?.[0] ?? null)}`);
+            }
+            units.set(unit.id, clone(unit));
+        },
+        async delete(id) {
+            units.delete(id);
+        },
+        async list() {
+            return [...units.values()].map((u) => clone(u));
+        },
+    };
+}