@knolo/core 3.2.2 → 3.2.4

package/README.md

@@ -309,6 +309,74 @@ Properties:
 
 ---
 
+# 🧠 Knolo Cortex
+
+Knolo Cortex is a local-first overlay memory layer for `.knolo` packs.
+
+It gives you:
+
+* Deterministic append-only memory writes
+* Lexical-first recall with label and namespace filters
+* Portable memory logs you can serialize and replay
+* Consolidation back into pack docs without mutating the pack itself
+* Deterministic graph export via `memoryToClaimOps()`
+
+## Example
+
+```ts
+import {
+  buildPack,
+  consolidateMemories,
+  createCortex,
+  mountPack,
+  recall,
+  remember,
+} from "@knolo/core";
+
+const cortex = createCortex({ actor: "notes-app" });
+const { cortex: next, memory } = remember(cortex, {
+  kind: "note",
+  text: "Project alpha uses a local-first memory overlay.",
+  labels: ["project.alpha"],
+  namespace: "project.alpha",
+});
+
+const hits = recall(next, "project alpha");
+const docs = consolidateMemories(next, { namespacePrefix: "memory" });
+const bytes = await buildPack(docs);
+const pack = await mountPack({ src: bytes });
+```
+
+If you need to load a local file in Node, use `@knolo/core/node` or read the bytes first and pass a `Uint8Array` into `mountPack()`.
+
+## Cortex API
+
+```ts
+import {
+  createCortex,
+  remember,
+  forget,
+  labelMemory,
+  linkMemories,
+  recall,
+  consolidateMemories,
+  memoryToClaimOps,
+} from "@knolo/core";
+```
+
+* `createCortex({ actor?, now?, log? })` creates an immutable memory runtime
+* `remember()` appends a new memory entry
+* `forget()` tombstones a memory
+* `labelMemory()` adds labels without mutating the original cortex
+* `linkMemories()` records deterministic memory relationships
+* `recall()` ranks memories with lexical-first scoring
+* `consolidateMemories()` converts selected memories back into `BuildInputDoc[]`
+* `memoryToClaimOps()` emits deterministic ClaimGraph ops for memory nodes, labels, and links
+
+The full example lives in [`examples/memory-overlay/README.md`](../../examples/memory-overlay/README.md).
+
+---
+
 # 🗺 Roadmap
 
 * Incremental pack updates
@@ -388,4 +456,3 @@ Runtimes that ignore unknown trailing bytes remain compatible.
 # 📄 License
 
 Apache-2.0
-

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { getClaimGraph, validateClaimGraph, } from './graph/claim_graph.js';
 export { buildClaimGraph } from './graph/build_claim_graph.js';
 export { createGraphLog, appendOp, applyClaimGraphLog, mergeClaimGraphLogs, serializeClaimGraphLog, deserializeClaimGraphLog, } from './graph/log.js';
 export { expandQueryWithGraph } from './graph/query_expand.js';
+export * from './memory/index.js';
 export type { MountOptions, PackMeta, Pack } from './pack.runtime.js';
 export type { QueryOptions, Hit } from './query.js';
 export type { EmbeddingProvider, SemanticSidecar, SemanticQueryOptions, RetrievalEvidence } from './semantic/types.js';

package/dist/index.js

@@ -13,6 +13,7 @@ export { getClaimGraph, validateClaimGraph, } from './graph/claim_graph.js';
 export { buildClaimGraph } from './graph/build_claim_graph.js';
 export { createGraphLog, appendOp, applyClaimGraphLog, mergeClaimGraphLogs, serializeClaimGraphLog, deserializeClaimGraphLog, } from './graph/log.js';
 export { expandQueryWithGraph } from './graph/query_expand.js';
+export * from './memory/index.js';
 export { parseToolCallV1FromText } from './tool_parse.js';
 export { nowIso, createTrace } from './trace.js';
 export { assertToolCallAllowed } from './tool_gate.js';

package/dist/indexer.d.ts

@@ -13,11 +13,12 @@ export type IndexBuildResult = {
  * sequences of blockId and positions for that term, with zeros as delimiters.
  * The structure looks like:
  *
- *     [termId, blockId+1, pos, pos, 0, blockId+1, pos, 0, 0, termId, ...]
+ *     [termId, blockId+1, pos+1, pos+1, 0, blockId+1, pos+1, 0, 0, termId, ...]
  *
  * Block IDs are stored as bid+1 so that 0 can remain a sentinel delimiter.
- * Each block section ends with a 0, and each term section ends with a 0. The
- * entire array can be streamed sequentially without needing to know the sizes
- * of individual lists ahead of time.
+ * Positions are also stored as pos+1 for the same reason. Each block section
+ * ends with a 0, and each term section ends with a 0. The entire array can be
+ * streamed sequentially without needing to know the sizes of individual lists
+ * ahead of time.
  */
 export declare function buildIndex(blocks: Block[]): IndexBuildResult;

package/dist/indexer.js

@@ -14,12 +14,13 @@ import { tokenize } from "./tokenize.js";
  * sequences of blockId and positions for that term, with zeros as delimiters.
  * The structure looks like:
  *
- *     [termId, blockId+1, pos, pos, 0, blockId+1, pos, 0, 0, termId, ...]
+ *     [termId, blockId+1, pos+1, pos+1, 0, blockId+1, pos+1, 0, 0, termId, ...]
  *
  * Block IDs are stored as bid+1 so that 0 can remain a sentinel delimiter.
- * Each block section ends with a 0, and each term section ends with a 0. The
- * entire array can be streamed sequentially without needing to know the sizes
- * of individual lists ahead of time.
+ * Positions are also stored as pos+1 for the same reason. Each block section
+ * ends with a 0, and each term section ends with a 0. The entire array can be
+ * streamed sequentially without needing to know the sizes of individual lists
+ * ahead of time.
  */
 export function buildIndex(blocks) {
     // Map term to termId and interim map of termId -> blockId -> positions
@@ -61,7 +62,7 @@ export function buildIndex(blocks) {
     for (const [tid, blockMap] of termBlockPositions) {
         postings.push(tid);
         for (const [bid, positions] of blockMap) {
-            postings.push(bid + 1, ...positions, 0);
+            postings.push(bid + 1, ...positions.map((pos) => pos + 1), 0);
         }
         postings.push(0); // end of term
     }

package/dist/memory/consolidate.d.ts

@@ -0,0 +1,15 @@
+import type { BuildInputDoc } from '../builder.js';
+import type { CortexV1 } from './cortex.js';
+import type { MemoryEngramV1 } from './engram.js';
+export type ConsolidateMemoriesOptionsV1 = {
+    namespacePrefix?: string;
+    kind?: string | readonly string[];
+    labels?: string | readonly string[];
+    namespace?: string | readonly string[];
+    minImportance?: number;
+    minConfidence?: number;
+    minAgeMs?: number;
+    maxAgeMs?: number;
+    now?: number;
+};
+export declare function consolidateMemories(cortexOrMemories: CortexV1 | readonly MemoryEngramV1[], opts?: ConsolidateMemoriesOptionsV1): BuildInputDoc[];

package/dist/memory/consolidate.js

@@ -0,0 +1,71 @@
+import { matchesMemoryLabels, validateMemoryLabels } from './label.js';
+import { normalizeMemoryLabel } from './label.js';
+import { normalize } from '../tokenize.js';
+export function consolidateMemories(cortexOrMemories, opts = {}) {
+    const memories = isCortex(cortexOrMemories)
+        ? cortexOrMemories.memories
+        : cortexOrMemories;
+    const now = opts.now ?? (isCortex(cortexOrMemories) ? cortexOrMemories.now() : Date.now());
+    const namespacePrefix = normalizeNamespacePrefix(opts.namespacePrefix);
+    const kindFilters = normalizeKindFilters(opts.kind);
+    const labelsFilter = validateMemoryLabels(opts.labels);
+    const namespaceFilters = normalizeNamespaceFilters(opts.namespace);
+    return memories
+        .filter((memory) => {
+        if (kindFilters.length > 0 && !kindFilters.includes(normalizeKind(memory.kind)))
+            return false;
+        if (labelsFilter.length > 0 && !matchesMemoryLabels(memory.labels, labelsFilter))
+            return false;
+        if (namespaceFilters.length > 0 && !matchesNamespace(memory.namespace, namespaceFilters))
+            return false;
+        if (opts.minImportance !== undefined && valueOrDefault(memory.importance, 0.5) < opts.minImportance)
+            return false;
+        if (opts.minConfidence !== undefined && valueOrDefault(memory.confidence, 0.5) < opts.minConfidence)
+            return false;
+        const ageMs = now - memory.ts;
+        if (opts.minAgeMs !== undefined && ageMs < opts.minAgeMs)
+            return false;
+        if (opts.maxAgeMs !== undefined && ageMs > opts.maxAgeMs)
+            return false;
+        return true;
+    })
+        .slice()
+        .sort((a, b) => a.ts - b.ts || a.id.localeCompare(b.id))
+        .map((memory) => ({
+        id: memory.id,
+        heading: `${memory.kind}: ${memory.labels.join('/')}`,
+        namespace: `${namespacePrefix}.${memory.kind}`,
+        text: memory.text,
+    }));
+}
+function isCortex(input) {
+    return !Array.isArray(input) && typeof input === 'object' && input !== null && 'memories' in input;
+}
+function normalizeNamespacePrefix(value) {
+    const normalized = normalizeMemoryLabel(value ?? 'memory');
+    return normalized || 'memory';
+}
+function normalizeKindFilters(kind) {
+    if (kind === undefined)
+        return [];
+    const values = Array.isArray(kind) ? kind : [kind];
+    return [...new Set(values.map(normalizeKind).filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}
+function normalizeNamespaceFilters(value) {
+    if (value === undefined)
+        return [];
+    const values = Array.isArray(value) ? value : [value];
+    return [...new Set(values.map((entry) => normalizeMemoryLabel(entry)).filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}
+function normalizeKind(kind) {
+    return normalize(kind).replace(/\s+/g, ' ').trim();
+}
+function matchesNamespace(value, filters) {
+    if (!value)
+        return false;
+    const normalized = normalizeMemoryLabel(value);
+    return filters.some((filter) => normalized === filter || normalized.startsWith(`${filter}.`));
+}
+function valueOrDefault(value, fallback) {
+    return Number.isFinite(value) ? value : fallback;
+}

package/dist/memory/cortex.d.ts

@@ -0,0 +1,43 @@
+import type { MemoryEngramV1, MemoryInputV1, MemoryLinkV1 } from './engram.js';
+import { type MemoryLogV1, type MemoryOpV1 } from './log.js';
+export type CortexV1 = {
+    version: 1;
+    actor: string;
+    now: () => number;
+    log: MemoryLogV1;
+    memories: MemoryEngramV1[];
+};
+export type CortexWriteResult<T extends object> = T & {
+    cortex: CortexV1;
+};
+export declare function createCortex(opts?: {
+    actor?: string;
+    now?: () => number;
+    log?: MemoryLogV1;
+}): CortexV1;
+export declare function remember(cortex: CortexV1, input: MemoryInputV1): CortexWriteResult<{
+    memory: MemoryEngramV1;
+    op: MemoryOpV1;
+}>;
+export declare function forget(cortex: CortexV1, id: string, provenance?: {
+    ts?: number;
+    actor?: string;
+}): CortexWriteResult<{
+    memoryId: string;
+    op: MemoryOpV1;
+}>;
+export declare function labelMemory(cortex: CortexV1, id: string, labels: string | readonly string[], provenance?: {
+    ts?: number;
+    actor?: string;
+}): CortexWriteResult<{
+    memory?: MemoryEngramV1;
+    op: MemoryOpV1;
+}>;
+export declare function linkMemories(cortex: CortexV1, from: string, to: string, relation: string, provenance?: {
+    ts?: number;
+    actor?: string;
+    confidence?: number;
+}): CortexWriteResult<{
+    link: MemoryLinkV1;
+    op: MemoryOpV1;
+}>;

package/dist/memory/cortex.js

@@ -0,0 +1,93 @@
+import { createMemoryId, normalizeMemoryActor, normalizeMemoryInput, normalizeMemoryKind, normalizeMemoryTimestamp, } from './engram.js';
+import { appendMemoryOp, applyMemoryLog, createMemoryLog, } from './log.js';
+import { validateMemoryLabels } from './label.js';
+export function createCortex(opts = {}) {
+    const log = opts.log ? { version: 1, ops: [...opts.log.ops] } : createMemoryLog();
+    return {
+        version: 1,
+        actor: normalizeMemoryActor(opts.actor ?? 'cortex'),
+        now: opts.now ?? (() => Date.now()),
+        log,
+        memories: applyMemoryLog(log),
+    };
+}
+export function remember(cortex, input) {
+    const memory = normalizeMemoryInput(input, {
+        actor: cortex.actor,
+        ts: cortex.now(),
+    });
+    const op = {
+        op: 'remember',
+        ts: memory.ts,
+        actor: memory.actor,
+        memory,
+    };
+    return applyWrite(cortex, op, { memory });
+}
+export function forget(cortex, id, provenance = {}) {
+    const op = {
+        op: 'forget',
+        id,
+        ts: normalizeMemoryTimestamp(provenance.ts ?? cortex.now()),
+        actor: normalizeMemoryActor(provenance.actor ?? cortex.actor),
+    };
+    return applyWrite(cortex, op, { memoryId: id });
+}
+export function labelMemory(cortex, id, labels, provenance = {}) {
+    const normalizedLabels = validateMemoryLabels(labels);
+    const op = {
+        op: 'label',
+        id,
+        labels: normalizedLabels,
+        ts: normalizeMemoryTimestamp(provenance.ts ?? cortex.now()),
+        actor: normalizeMemoryActor(provenance.actor ?? cortex.actor),
+    };
+    return applyWrite(cortex, op, {
+        memory: cortex.memories.find((memory) => memory.id === id),
+    });
+}
+export function linkMemories(cortex, from, to, relation, provenance = {}) {
+    const normalizedRelation = normalizeMemoryKind(relation);
+    const ts = normalizeMemoryTimestamp(provenance.ts ?? cortex.now());
+    const actor = normalizeMemoryActor(provenance.actor ?? cortex.actor);
+    const link = {
+        version: 1,
+        id: createMemoryId({
+            kind: 'link',
+            text: [from, normalizedRelation, to, provenance.confidence ?? ''].join('\u0001'),
+            ts,
+            actor,
+        }),
+        from,
+        to,
+        relation: normalizedRelation,
+        ts,
+        actor,
+        confidence: provenance.confidence,
+    };
+    const op = {
+        op: 'link',
+        from,
+        to,
+        relation: normalizedRelation,
+        confidence: provenance.confidence,
+        ts,
+        actor,
+    };
+    return applyWrite(cortex, op, { link });
+}
+function applyWrite(cortex, op, extra) {
+    const log = appendMemoryOp(cortex.log, op);
+    const memories = applyMemoryLog(log);
+    return {
+        ...extra,
+        op,
+        cortex: {
+            version: 1,
+            actor: cortex.actor,
+            now: cortex.now,
+            log,
+            memories,
+        },
+    };
+}

package/dist/memory/engram.d.ts

@@ -0,0 +1,48 @@
+export type MemoryKind = string;
+export type MemoryLinkV1 = {
+    version: 1;
+    id: string;
+    from: string;
+    to: string;
+    relation: string;
+    ts: number;
+    actor: string;
+    confidence?: number;
+};
+export type MemoryEngramV1 = {
+    version: 1;
+    id: string;
+    kind: MemoryKind;
+    text: string;
+    labels: string[];
+    namespace?: string;
+    source?: string;
+    importance?: number;
+    confidence?: number;
+    ts: number;
+    actor: string;
+    links: MemoryLinkV1[];
+};
+export type MemoryInputV1 = {
+    kind: MemoryKind;
+    text: string;
+    labels?: string | readonly string[];
+    namespace?: string;
+    source?: string;
+    importance?: number;
+    confidence?: number;
+    ts?: number;
+    actor?: string;
+};
+export type MemoryProvenanceV1 = {
+    ts?: number;
+    actor?: string;
+};
+export declare function createMemoryId(input: Pick<MemoryEngramV1, 'kind' | 'text' | 'ts' | 'actor'>): string;
+export declare function normalizeMemoryInput(input: MemoryInputV1, provenance?: MemoryProvenanceV1): MemoryEngramV1;
+export declare function normalizeMemoryKind(kind: string): string;
+export declare function normalizeMemoryText(text: string): string;
+export declare function normalizeMemoryNamespace(namespace?: string): string | undefined;
+export declare function normalizeMemorySource(source?: string): string | undefined;
+export declare function normalizeMemoryActor(actor: string): string;
+export declare function normalizeMemoryTimestamp(ts: number): number;

package/dist/memory/engram.js

@@ -0,0 +1,90 @@
+import { normalize } from '../tokenize.js';
+import { normalizeMemoryLabel, validateMemoryLabels } from './label.js';
+export function createMemoryId(input) {
+    const payload = [
+        normalizeMemoryKind(input.kind),
+        normalizeMemoryTextForId(input.text),
+        normalizeMemoryTimestamp(input.ts),
+        normalizeMemoryActor(input.actor),
+    ].join('\u0001');
+    return `mem_${hash64Hex(payload)}`;
+}
+export function normalizeMemoryInput(input, provenance = {}) {
+    const kind = normalizeMemoryKind(input.kind);
+    if (!kind) {
+        throw new Error('Memory kind must be a non-empty string.');
+    }
+    const text = normalizeMemoryText(input.text);
+    if (!text) {
+        throw new Error('Memory text must be a non-empty string.');
+    }
+    const ts = normalizeMemoryTimestamp(input.ts ?? provenance.ts ?? 0);
+    const actor = normalizeMemoryActor(input.actor ?? provenance.actor ?? 'cortex');
+    const labels = validateMemoryLabels(input.labels);
+    const namespace = normalizeMemoryNamespace(input.namespace);
+    const source = normalizeMemorySource(input.source);
+    const importance = normalizeMemoryRatio(input.importance, 'importance');
+    const confidence = normalizeMemoryRatio(input.confidence, 'confidence');
+    return {
+        version: 1,
+        id: createMemoryId({ kind, text, ts, actor }),
+        kind,
+        text,
+        labels,
+        namespace,
+        source,
+        importance,
+        confidence,
+        ts,
+        actor,
+        links: [],
+    };
+}
+export function normalizeMemoryKind(kind) {
+    return normalize(String(kind ?? '')).replace(/\s+/g, ' ').trim();
+}
+export function normalizeMemoryText(text) {
+    return String(text ?? '').trim();
+}
+export function normalizeMemoryNamespace(namespace) {
+    const normalized = normalizeMemoryLabel(namespace ?? '');
+    return normalized || undefined;
+}
+export function normalizeMemorySource(source) {
+    const normalized = normalize(String(source ?? '')).replace(/\s+/g, ' ').trim();
+    return normalized || undefined;
+}
+export function normalizeMemoryActor(actor) {
+    return String(actor ?? '').replace(/\s+/g, ' ').trim();
+}
+export function normalizeMemoryTimestamp(ts) {
+    const value = Number(ts);
+    if (!Number.isFinite(value)) {
+        throw new Error('Memory timestamp must be a finite number.');
+    }
+    return value;
+}
+function normalizeMemoryRatio(value, name) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Number.isFinite(value)) {
+        throw new Error(`Memory ${name} must be a finite number.`);
+    }
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}
+function normalizeMemoryTextForId(text) {
+    return normalize(String(text ?? '')).replace(/\s+/g, ' ').trim();
+}
+function hash64Hex(input) {
+    let hash = 0xcbf29ce484222325n;
+    const prime = 0x100000001b3n;
+    for (const char of input) {
+        hash ^= BigInt(char.codePointAt(0) ?? 0);
+        hash = (hash * prime) & 0xffffffffffffffffn;
+    }
+    return hash.toString(16).padStart(16, '0');
+}

package/dist/memory/graph_adapter.d.ts

@@ -0,0 +1,3 @@
+import type { ClaimOp } from '../graph/log.js';
+import type { MemoryEngramV1 } from './engram.js';
+export declare function memoryToClaimOps(memory: MemoryEngramV1): ClaimOp[];

package/dist/memory/graph_adapter.js

@@ -0,0 +1,65 @@
+import { computeEdgeId, computeNodeId, normalizeClaimLabel } from '../graph/claim_graph.js';
+import { validateMemoryLabels } from './label.js';
+export function memoryToClaimOps(memory) {
+    const nodeOps = new Map();
+    const edgeOps = new Map();
+    const memoryLabel = memoryNodeLabel(memory.id);
+    upsertNode(nodeOps, memoryLabel, memory.ts, memory.actor);
+    for (const label of validateMemoryLabels(memory.labels)) {
+        const entityLabel = normalizeClaimLabel(label);
+        if (!entityLabel)
+            continue;
+        upsertNode(nodeOps, entityLabel, memory.ts, memory.actor);
+        upsertEdge(edgeOps, memoryLabel, 'mentions', entityLabel, memory.ts, memory.actor);
+    }
+    for (const link of sortedLinks(memory.links)) {
+        const relation = normalizeClaimLabel(link.relation);
+        if (!relation)
+            continue;
+        const targetLabel = memoryNodeLabel(link.to);
+        upsertNode(nodeOps, targetLabel, link.ts, link.actor);
+        upsertEdge(edgeOps, memoryLabel, relation, targetLabel, link.ts, link.actor);
+    }
+    return [...nodeOps.values(), ...edgeOps.values()];
+}
+function memoryNodeLabel(id) {
+    return normalizeClaimLabel(`memory ${id}`);
+}
+function upsertNode(nodeOps, label, ts, actor) {
+    if (!label)
+        return;
+    const id = computeNodeId(label);
+    if (nodeOps.has(id))
+        return;
+    nodeOps.set(id, {
+        op: 'upsert_node',
+        id,
+        label,
+        ts,
+        actor,
+    });
+}
+function upsertEdge(edgeOps, fromLabel, relation, toLabel, ts, actor) {
+    if (!fromLabel || !relation || !toLabel)
+        return;
+    const from = computeNodeId(fromLabel);
+    const to = computeNodeId(toLabel);
+    const id = computeEdgeId(from, relation, to);
+    if (edgeOps.has(id))
+        return;
+    edgeOps.set(id, {
+        op: 'add_edge',
+        from,
+        p: relation,
+        to,
+        ts,
+        actor,
+    });
+}
+function sortedLinks(memoryLinks) {
+    return [...memoryLinks].sort((a, b) => a.ts - b.ts ||
+        a.actor.localeCompare(b.actor) ||
+        a.relation.localeCompare(b.relation) ||
+        a.to.localeCompare(b.to) ||
+        a.id.localeCompare(b.id));
+}

package/dist/memory/index.d.ts

@@ -0,0 +1,13 @@
+export { normalizeMemoryLabel, validateMemoryLabels, matchesMemoryLabels, normalizeMemoryLabelTokens, } from './label.js';
+export type { MemoryKind, MemoryLinkV1, MemoryLinkV1 as MemoryLink, MemoryEngramV1, MemoryEngramV1 as MemoryEngram, MemoryInputV1, MemoryInputV1 as MemoryInput, MemoryProvenanceV1, MemoryProvenanceV1 as MemoryProvenance, } from './engram.js';
+export { createMemoryId, normalizeMemoryInput, normalizeMemoryKind, normalizeMemoryText, normalizeMemoryNamespace, normalizeMemorySource, normalizeMemoryActor, normalizeMemoryTimestamp, } from './engram.js';
+export type { MemoryLogV1, MemoryOpV1 } from './log.js';
+export type { MemoryLogV1 as MemoryLog, MemoryOpV1 as MemoryOp, } from './log.js';
+export { createMemoryLog, appendMemoryOp, mergeMemoryLogs, serializeMemoryLog, deserializeMemoryLog, applyMemoryLog, } from './log.js';
+export type { CortexV1, CortexV1 as Cortex, CortexWriteResult, } from './cortex.js';
+export { createCortex, remember, forget, labelMemory, linkMemories } from './cortex.js';
+export type { RecallOptionsV1, RecallOptionsV1 as RecallOptions, MemoryRecallHitV1, MemoryRecallHitV1 as MemoryRecallHit, } from './recall.js';
+export { recall } from './recall.js';
+export type { ConsolidateMemoriesOptionsV1, ConsolidateMemoriesOptionsV1 as ConsolidateMemoriesOptions, } from './consolidate.js';
+export { consolidateMemories } from './consolidate.js';
+export { memoryToClaimOps } from './graph_adapter.js';

package/dist/memory/index.js

@@ -0,0 +1,7 @@
+export { normalizeMemoryLabel, validateMemoryLabels, matchesMemoryLabels, normalizeMemoryLabelTokens, } from './label.js';
+export { createMemoryId, normalizeMemoryInput, normalizeMemoryKind, normalizeMemoryText, normalizeMemoryNamespace, normalizeMemorySource, normalizeMemoryActor, normalizeMemoryTimestamp, } from './engram.js';
+export { createMemoryLog, appendMemoryOp, mergeMemoryLogs, serializeMemoryLog, deserializeMemoryLog, applyMemoryLog, } from './log.js';
+export { createCortex, remember, forget, labelMemory, linkMemories } from './cortex.js';
+export { recall } from './recall.js';
+export { consolidateMemories } from './consolidate.js';
+export { memoryToClaimOps } from './graph_adapter.js';

package/dist/memory/label.d.ts

@@ -0,0 +1,4 @@
+export declare function normalizeMemoryLabel(label: string): string;
+export declare function validateMemoryLabels(labels?: string | readonly string[] | null): string[];
+export declare function matchesMemoryLabels(memoryLabels?: string[] | string | null, requestedLabels?: string | readonly string[] | null): boolean;
+export declare function normalizeMemoryLabelTokens(label: string): string[];

package/dist/memory/label.js

@@ -0,0 +1,53 @@
+import { normalize } from '../tokenize.js';
+export function normalizeMemoryLabel(label) {
+    if (typeof label !== 'string')
+        return '';
+    const lowered = label.normalize('NFKD').replace(/\p{M}+/gu, '').toLowerCase().trim();
+    if (!lowered)
+        return '';
+    const dotted = lowered
+        .replace(/\s+/g, '.')
+        .replace(/[\u2010-\u2015/\\:;|>]+/gu, '.')
+        .replace(/[^\p{L}\p{N}._-]+/gu, '.')
+        .replace(/\.{2,}/g, '.')
+        .replace(/^\.|\.$/g, '');
+    return dotted
+        .split('.')
+        .map((segment) => segment.trim())
+        .filter(Boolean)
+        .join('.');
+}
+export function validateMemoryLabels(labels) {
+    if (labels === undefined || labels === null)
+        return [];
+    const values = typeof labels === 'string' ? [labels] : labels;
+    const seen = new Set();
+    const out = [];
+    for (const label of values) {
+        if (typeof label !== 'string') {
+            throw new Error('Memory labels must be strings.');
+        }
+        const normalized = normalizeMemoryLabel(label);
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        out.push(normalized);
+    }
+    out.sort((a, b) => a.localeCompare(b));
+    return out;
+}
+export function matchesMemoryLabels(memoryLabels, requestedLabels) {
+    const filters = validateMemoryLabels(requestedLabels);
+    if (filters.length === 0)
+        return true;
+    const labels = validateMemoryLabels(memoryLabels);
+    if (labels.length === 0)
+        return false;
+    return filters.some((filter) => labels.some((label) => label === filter || label.startsWith(`${filter}.`)));
+}
+export function normalizeMemoryLabelTokens(label) {
+    return normalizeMemoryLabel(label)
+        .split('.')
+        .map((part) => normalize(part).replace(/\s+/g, ' ').trim())
+        .filter(Boolean);
+}

package/dist/memory/log.d.ts

@@ -0,0 +1,36 @@
+import type { MemoryEngramV1 } from './engram.js';
+export type MemoryOpV1 = {
+    op: 'remember';
+    ts: number;
+    actor: string;
+    memory: MemoryEngramV1;
+} | {
+    op: 'forget';
+    ts: number;
+    actor: string;
+    id: string;
+} | {
+    op: 'label';
+    ts: number;
+    actor: string;
+    id: string;
+    labels: string[];
+} | {
+    op: 'link';
+    ts: number;
+    actor: string;
+    from: string;
+    to: string;
+    relation: string;
+    confidence?: number;
+};
+export type MemoryLogV1 = {
+    version: 1;
+    ops: MemoryOpV1[];
+};
+export declare function createMemoryLog(): MemoryLogV1;
+export declare function appendMemoryOp(log: MemoryLogV1, op: MemoryOpV1): MemoryLogV1;
+export declare function mergeMemoryLogs(a: MemoryLogV1, b: MemoryLogV1): MemoryLogV1;
+export declare function serializeMemoryLog(log: MemoryLogV1): Uint8Array;
+export declare function deserializeMemoryLog(data: Uint8Array): MemoryLogV1;
+export declare function applyMemoryLog(log: MemoryLogV1): MemoryEngramV1[];

package/dist/memory/log.js

@@ -0,0 +1,241 @@
+import { getTextDecoder, getTextEncoder } from '../utils/utf8.js';
+import { createMemoryId, normalizeMemoryActor, normalizeMemoryInput, normalizeMemoryKind, normalizeMemoryNamespace, normalizeMemorySource, normalizeMemoryTimestamp, } from './engram.js';
+import { matchesMemoryLabels, validateMemoryLabels } from './label.js';
+export function createMemoryLog() {
+    return { version: 1, ops: [] };
+}
+export function appendMemoryOp(log, op) {
+    return { version: 1, ops: [...log.ops, op] };
+}
+export function mergeMemoryLogs(a, b) {
+    return { version: 1, ops: [...a.ops, ...b.ops].sort(compareMemoryOps) };
+}
+export function serializeMemoryLog(log) {
+    const enc = getTextEncoder();
+    return enc.encode(JSON.stringify(normalizeMemoryLog(log)));
+}
+export function deserializeMemoryLog(data) {
+    const dec = getTextDecoder();
+    const parsed = JSON.parse(dec.decode(data));
+    if (!parsed || parsed.version !== 1 || !Array.isArray(parsed.ops)) {
+        throw new Error('Invalid MemoryLog payload');
+    }
+    return normalizeMemoryLog({ version: 1, ops: parsed.ops });
+}
+export function applyMemoryLog(log) {
+    const memories = new Map();
+    const tombstones = new Set();
+    const pendingLabels = new Map();
+    const pendingLinks = new Map();
+    for (const op of [...log.ops].sort(compareMemoryOps)) {
+        if (op.op === 'remember') {
+            if (tombstones.has(op.memory.id))
+                continue;
+            const memory = normalizeMemoryInput(op.memory, {
+                actor: op.actor,
+                ts: op.ts,
+            });
+            const mergedLabels = mergeLabels(memory.labels, pendingLabels.get(memory.id));
+            const mergedLinks = mergeLinks(memory.id, memory.links, pendingLinks.get(memory.id));
+            memories.set(memory.id, {
+                ...memory,
+                labels: mergedLabels,
+                links: mergedLinks,
+            });
+            pendingLabels.delete(memory.id);
+            pendingLinks.delete(memory.id);
+            continue;
+        }
+        if (op.op === 'forget') {
+            memories.delete(op.id);
+            tombstones.add(op.id);
+            pendingLabels.delete(op.id);
+            pendingLinks.delete(op.id);
+            continue;
+        }
+        if (op.op === 'label') {
+            if (tombstones.has(op.id))
+                continue;
+            const labels = validateMemoryLabels(op.labels);
+            const memory = memories.get(op.id);
+            if (memory) {
+                memories.set(op.id, {
+                    ...memory,
+                    labels: validateMemoryLabels([...memory.labels, ...labels]),
+                });
+            }
+            else if (labels.length > 0) {
+                const pending = pendingLabels.get(op.id) ?? new Set();
+                for (const label of labels)
+                    pending.add(label);
+                pendingLabels.set(op.id, pending);
+            }
+            continue;
+        }
+        if (tombstones.has(op.from))
+            continue;
+        const link = createLink(op);
+        const memory = memories.get(op.from);
+        if (memory) {
+            memories.set(op.from, {
+                ...memory,
+                links: mergeLinks(memory.id, memory.links, new Map([[link.id, link]])),
+            });
+        }
+        else {
+            const pending = pendingLinks.get(op.from) ?? new Map();
+            pending.set(link.id, link);
+            pendingLinks.set(op.from, pending);
+        }
+    }
+    return [...memories.values()]
+        .map((memory) => ({
+        ...memory,
+        labels: [...memory.labels].sort((a, b) => a.localeCompare(b)),
+        links: [...memory.links].sort((a, b) => a.id.localeCompare(b.id)),
+    }))
+        .sort((a, b) => a.ts - b.ts || a.id.localeCompare(b.id));
+}
+function normalizeMemoryLog(log) {
+    return {
+        version: 1,
+        ops: [...log.ops].sort(compareMemoryOps).map((op) => normalizeMemoryOp(op)),
+    };
+}
+function normalizeMemoryOp(op) {
+    if (op.op === 'remember') {
+        const memory = normalizeMemoryInput(op.memory, {
+            actor: op.actor,
+            ts: op.ts,
+        });
+        return {
+            op: 'remember',
+            ts: normalizeMemoryTimestamp(op.ts),
+            actor: normalizeMemoryActor(op.actor),
+            memory,
+        };
+    }
+    if (op.op === 'forget') {
+        return {
+            op: 'forget',
+            ts: normalizeMemoryTimestamp(op.ts),
+            actor: normalizeMemoryActor(op.actor),
+            id: String(op.id),
+        };
+    }
+    if (op.op === 'label') {
+        return {
+            op: 'label',
+            ts: normalizeMemoryTimestamp(op.ts),
+            actor: normalizeMemoryActor(op.actor),
+            id: String(op.id),
+            labels: validateMemoryLabels(op.labels),
+        };
+    }
+    return {
+        op: 'link',
+        ts: normalizeMemoryTimestamp(op.ts),
+        actor: normalizeMemoryActor(op.actor),
+        from: String(op.from),
+        to: String(op.to),
+        relation: normalizeMemoryKind(op.relation),
+        confidence: op.confidence === undefined ? undefined : clamp01(op.confidence),
+    };
+}
+function compareMemoryOps(a, b) {
+    const tsA = a.ts;
+    const tsB = b.ts;
+    if (tsA !== tsB)
+        return tsA - tsB;
+    const actorCmp = a.actor.localeCompare(b.actor);
+    if (actorCmp !== 0)
+        return actorCmp;
+    const rankA = memoryOpRank(a.op);
+    const rankB = memoryOpRank(b.op);
+    if (rankA !== rankB)
+        return rankA - rankB;
+    return stableSerializeMemoryOp(a).localeCompare(stableSerializeMemoryOp(b));
+}
+function memoryOpRank(op) {
+    switch (op) {
+        case 'remember':
+            return 0;
+        case 'label':
+            return 1;
+        case 'link':
+            return 2;
+        case 'forget':
+            return 3;
+    }
+}
+function stableSerializeMemoryOp(op) {
+    if (op.op === 'remember') {
+        const memory = op.memory;
+        return [
+            'remember',
+            memory.id,
+            memory.kind,
+            memory.text,
+            memory.labels.join(','),
+            memory.namespace ?? '',
+            memory.source ?? '',
+            memory.importance ?? '',
+            memory.confidence ?? '',
+        ].join('|');
+    }
+    if (op.op === 'forget') {
+        return ['forget', op.id].join('|');
+    }
+    if (op.op === 'label') {
+        return ['label', op.id, op.labels.join(',')].join('|');
+    }
+    return [
+        'link',
+        op.from,
+        op.to,
+        op.relation,
+        op.confidence ?? '',
+    ].join('|');
+}
+function mergeLabels(labels, pending) {
+    if (!pending || pending.size === 0)
+        return [...labels].sort((a, b) => a.localeCompare(b));
+    return validateMemoryLabels([...labels, ...pending]);
+}
+function mergeLinks(fromId, links, pending) {
+    const map = new Map(links.map((link) => [link.id, link]));
+    if (pending) {
+        for (const [id, link] of pending) {
+            if (link.from === fromId) {
+                map.set(id, link);
+            }
+        }
+    }
+    return [...map.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+function createLink(op) {
+    return {
+        version: 1,
+        id: createMemoryId({
+            kind: 'link',
+            text: [op.from, op.relation, op.to, op.confidence ?? ''].join('\u0001'),
+            ts: op.ts,
+            actor: op.actor,
+        }),
+        from: op.from,
+        to: op.to,
+        relation: op.relation,
+        ts: op.ts,
+        actor: op.actor,
+        confidence: op.confidence,
+    };
+}
+function clamp01(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}

package/dist/memory/recall.d.ts

@@ -0,0 +1,23 @@
+import type { CortexV1 } from './cortex.js';
+import type { MemoryEngramV1 } from './engram.js';
+export type RecallOptionsV1 = {
+    topK?: number;
+    kind?: string | readonly string[];
+    labels?: string | readonly string[];
+    namespace?: string | readonly string[];
+    source?: string | readonly string[];
+    since?: number;
+    until?: number;
+    minImportance?: number;
+    minConfidence?: number;
+};
+export type MemoryRecallHitV1 = MemoryEngramV1 & {
+    score: number;
+    lexicalScore: number;
+    metadataScore: number;
+    kindScore: number;
+    labelScore: number;
+    namespaceScore: number;
+    sourceScore: number;
+};
+export declare function recall(cortexOrMemories: CortexV1 | readonly MemoryEngramV1[], query: string, opts?: RecallOptionsV1): MemoryRecallHitV1[];

package/dist/memory/recall.js

@@ -0,0 +1,167 @@
+import { tokenize, normalize } from '../tokenize.js';
+import { matchesMemoryLabels, validateMemoryLabels } from './label.js';
+import { normalizeMemoryLabel } from './label.js';
+export function recall(cortexOrMemories, query, opts = {}) {
+    const memories = isCortex(cortexOrMemories)
+        ? cortexOrMemories.memories
+        : cortexOrMemories;
+    const queryTerms = tokenize(query).map((token) => token.term);
+    const hasQuery = queryTerms.length > 0;
+    const hasFilters = Boolean(opts.kind ||
+        opts.labels ||
+        opts.namespace ||
+        opts.source ||
+        opts.since !== undefined ||
+        opts.until !== undefined ||
+        opts.minImportance !== undefined ||
+        opts.minConfidence !== undefined);
+    if (!hasQuery && !hasFilters)
+        return [];
+    const kindFilters = normalizeKinds(opts.kind);
+    const namespaceFilters = normalizeHierarchicalFilters(opts.namespace);
+    const sourceFilters = normalizeSourceFilters(opts.source);
+    const labelFilters = validateMemoryLabels(opts.labels);
+    const hits = memories
+        .filter((memory) => passesFilters(memory, {
+        kindFilters,
+        labelFilters,
+        namespaceFilters,
+        sourceFilters,
+        since: opts.since,
+        until: opts.until,
+        minImportance: opts.minImportance,
+        minConfidence: opts.minConfidence,
+    }))
+        .map((memory) => scoreMemory(memory, queryTerms, {
+        kindFilters,
+        labelFilters,
+        namespaceFilters,
+        sourceFilters,
+    }))
+        .sort((a, b) => b.score - a.score || b.ts - a.ts || a.id.localeCompare(b.id));
+    const topK = Number.isInteger(opts.topK) && opts.topK > 0 ? opts.topK : 10;
+    const visibleHits = hasQuery ? hits.filter((hit) => hit.score > 0) : hits;
+    return visibleHits.slice(0, topK);
+}
+function passesFilters(memory, filters) {
+    if (filters.kindFilters.length > 0 && !filters.kindFilters.includes(normalizeKind(memory.kind))) {
+        return false;
+    }
+    if (filters.labelFilters.length > 0 && !matchesMemoryLabels(memory.labels, filters.labelFilters)) {
+        return false;
+    }
+    if (filters.namespaceFilters.length > 0 && !matchesHierarchicalValue(memory.namespace, filters.namespaceFilters)) {
+        return false;
+    }
+    if (filters.sourceFilters.length > 0 && !matchesSource(memory.source, filters.sourceFilters)) {
+        return false;
+    }
+    if (filters.since !== undefined && memory.ts < filters.since)
+        return false;
+    if (filters.until !== undefined && memory.ts > filters.until)
+        return false;
+    if (filters.minImportance !== undefined && valueOrDefault(memory.importance, 0.5) < filters.minImportance)
+        return false;
+    if (filters.minConfidence !== undefined && valueOrDefault(memory.confidence, 0.5) < filters.minConfidence)
+        return false;
+    return true;
+}
+function scoreMemory(memory, queryTerms, filters) {
+    const lexicalScore = scoreTokenOverlap(queryTerms, tokenize(memory.text).map((token) => token.term));
+    const kindScore = scoreKind(memory, queryTerms, filters.kindFilters);
+    const labelScore = scoreLabelSignal(memory, queryTerms, filters.labelFilters);
+    const namespaceScore = scoreNamespaceSignal(memory, queryTerms, filters.namespaceFilters);
+    const sourceScore = scoreSourceSignal(memory, queryTerms, filters.sourceFilters);
+    const metadataScore = kindScore * 0.2 + labelScore * 0.1 + namespaceScore * 0.15 + sourceScore * 0.1;
+    const score = lexicalScore * 0.45 + metadataScore;
+    return {
+        ...memory,
+        score,
+        lexicalScore,
+        metadataScore,
+        kindScore,
+        labelScore,
+        namespaceScore,
+        sourceScore,
+    };
+}
+function scoreKind(memory, queryTerms, kindFilters) {
+    const kind = normalizeKind(memory.kind);
+    if (kindFilters.length > 0) {
+        return kindFilters.includes(kind) ? 1 : 0;
+    }
+    return scoreTokenOverlap(queryTerms, tokenize(kind).map((token) => token.term));
+}
+function scoreLabelSignal(memory, queryTerms, labelFilters) {
+    if (labelFilters.length > 0) {
+        const matched = labelFilters.filter((filter) => memory.labels.some((label) => label === filter || label.startsWith(`${filter}.`)));
+        return matched.length / labelFilters.length;
+    }
+    return scoreTokenOverlap(queryTerms, tokenize(memory.labels.join(' ')).map((token) => token.term));
+}
+function scoreNamespaceSignal(memory, queryTerms, namespaceFilters) {
+    if (namespaceFilters.length > 0) {
+        return matchesHierarchicalValue(memory.namespace, namespaceFilters) ? 1 : 0;
+    }
+    return scoreTokenOverlap(queryTerms, tokenize(String(memory.namespace ?? '')).map((token) => token.term));
+}
+function scoreSourceSignal(memory, queryTerms, sourceFilters) {
+    if (sourceFilters.length > 0) {
+        return matchesSource(memory.source, sourceFilters) ? 1 : 0;
+    }
+    return scoreTokenOverlap(queryTerms, tokenize(String(memory.source ?? '')).map((token) => token.term));
+}
+function scoreTokenOverlap(queryTerms, fieldTerms) {
+    const q = new Set(queryTerms.filter(Boolean));
+    const f = new Set(fieldTerms.filter(Boolean));
+    if (q.size === 0 || f.size === 0)
+        return 0;
+    let matched = 0;
+    for (const term of q) {
+        if (f.has(term))
+            matched++;
+    }
+    return matched / q.size;
+}
+function normalizeKinds(kind) {
+    if (kind === undefined)
+        return [];
+    return uniqueSorted((Array.isArray(kind) ? kind : [kind]).map(normalizeKind).filter(Boolean));
+}
+function normalizeHierarchicalFilters(value) {
+    if (value === undefined)
+        return [];
+    return uniqueSorted((Array.isArray(value) ? value : [value]).map(normalizeMemoryLabel).filter(Boolean));
+}
+function normalizeSourceFilters(value) {
+    if (value === undefined)
+        return [];
+    return uniqueSorted((Array.isArray(value) ? value : [value]).map(normalizeSource).filter(Boolean));
+}
+function normalizeKind(kind) {
+    return normalize(kind).replace(/\s+/g, ' ').trim();
+}
+function normalizeSource(source) {
+    return normalize(String(source ?? '')).replace(/\s+/g, ' ').trim();
+}
+function matchesHierarchicalValue(value, filters) {
+    if (!value)
+        return false;
+    const normalized = normalizeMemoryLabel(value);
+    return filters.some((filter) => normalized === filter || normalized.startsWith(`${filter}.`));
+}
+function matchesSource(value, filters) {
+    if (!value)
+        return false;
+    const normalized = normalizeSource(value);
+    return filters.includes(normalized);
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((a, b) => a.localeCompare(b));
+}
+function valueOrDefault(value, fallback) {
+    return Number.isFinite(value) ? value : fallback;
+}
+function isCortex(input) {
+    return !Array.isArray(input) && typeof input === 'object' && input !== null && 'memories' in input;
+}

package/dist/query.js

@@ -181,7 +181,7 @@ export function query(pack, q, opts = {}) {
                 let pos = p[i++];
                 const positions = [];
                 while (pos !== 0) {
-                    positions.push(pos);
+                    positions.push(pos - 1);
                     pos = p[i++];
                 }
                 termDf++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knolo/core",
-  "version": "3.2.2",
+  "version": "3.2.4",
   "type": "module",
   "description": "Local-first knowledge packs for small LLMs.",
   "keywords": [
@@ -34,7 +34,7 @@
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build",
     "smoke": "node scripts/smoke.mjs",
-    "test": "npm run build && node scripts/check-runtime-no-node.mjs && node scripts/test.mjs",
+    "test": "npm run build && node scripts/check-runtime-no-node.mjs && node --test test/*.test.mjs && node scripts/test.mjs",
     "format": "prettier --write src/agent.ts src/pack.ts src/pack.runtime.ts src/pack.node.ts src/node.ts src/builder.ts src/index.ts scripts/test.mjs scripts/check-runtime-no-node.mjs ../../README.md README.md",
     "format:check": "prettier --check src/agent.ts src/pack.ts src/pack.runtime.ts src/pack.node.ts src/node.ts src/builder.ts src/index.ts scripts/test.mjs scripts/check-runtime-no-node.mjs ../../README.md README.md",
     "check:runtime-no-node": "node scripts/check-runtime-no-node.mjs"