@knolo/core 3.2.1 → 3.2.4

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.d.ts

@@ -1,4 +1,5 @@
 import type { Pack } from "./pack.js";
+import type { RetrievalEvidence, SemanticSidecar } from "./semantic/types.js";
 export type QueryOptions = {
     topK?: number;
     minScore?: number;
@@ -28,6 +29,14 @@ export type QueryOptions = {
             wSem?: number;
         };
         queryEmbedding?: Float32Array;
+        sidecar?: SemanticSidecar;
+        provider?: {
+            type: "ollama";
+            modelId: string;
+            endpoint?: string;
+        };
+        sidecarPath?: string;
+        minSemanticScore?: number;
         force?: boolean;
     };
 };
@@ -39,6 +48,7 @@ export type Hit = {
     text: string;
     source?: string;
     namespace?: string;
+    evidence?: RetrievalEvidence;
 };
 export declare function query(pack: Pack, q: string, opts?: QueryOptions): Hit[];
 export declare function lexConfidence(hits: Array<{