cogmem 3.6.2

package/dist/atlas/MemoryAtlasIndexer.js

@@ -0,0 +1,74 @@
+import { backfillAtlasDocuments, installAtlasProjectionDirtyTriggers } from '../migrations/0025_memory_atlas.js';
+import { ActionFrameExtractor } from './ActionFrameExtractor.js';
+export class MemoryAtlasIndexer {
+    db;
+    store;
+    actions;
+    constructor(db, eventStore, store) {
+        this.db = db;
+        this.store = store;
+        installAtlasProjectionDirtyTriggers(db);
+        this.actions = new ActionFrameExtractor(db, eventStore, store);
+    }
+    rebuild(options = {}) {
+        const projectId = options.projectId;
+        let actions = 0;
+        try {
+            this.db.transaction(() => {
+                if (projectId) {
+                    this.db.prepare(`DELETE FROM memory_atlas_documents WHERE project_id=? AND node_type IN ('project','entity','topic','cluster','episode','belief')`).run(projectId);
+                }
+                else {
+                    this.db.exec(`DELETE FROM memory_atlas_documents WHERE node_type IN ('project','entity','topic','cluster','episode','belief');`);
+                }
+                backfillAtlasDocuments(this.db, projectId);
+                const projects = projectId
+                    ? [projectId]
+                    : this.db.prepare(`SELECT DISTINCT project_id FROM memory_atlas_documents WHERE project_id<>''`).all().map((row) => row.project_id);
+                for (const id of projects)
+                    this.store.upsertDocument({
+                        id: `project:${id}`, projectId: id, nodeType: 'project', sourceId: id, label: id,
+                        confidence: 1, supportCount: this.store.countDocuments(id), status: 'active', evidenceEventIds: [],
+                        metadata: { projection: 'memory_atlas.v1' },
+                    });
+                actions = this.actions.rebuild(projectId);
+                if (projectId) {
+                    this.store.markProjectionClean(projectId, { actions });
+                }
+                else {
+                    for (const id of projects)
+                        this.store.markProjectionClean(id, { actions });
+                }
+            })();
+        }
+        catch (error) {
+            this.store.markProjectionFailed(projectId || '__global__', error instanceof Error ? error.message : String(error));
+            throw error;
+        }
+        return { documents: this.store.countDocuments(projectId), actions };
+    }
+    ensureFresh(options) {
+        if (!this.store.projectionNeedsRefresh(options.projectId)) {
+            return { documents: this.store.countDocuments(options.projectId), actions: 0, refreshed: false };
+        }
+        return { ...this.rebuild(options), refreshed: true };
+    }
+    ensureAllFresh() {
+        let documents = 0;
+        let actions = 0;
+        let refreshed = false;
+        const errors = [];
+        for (const projectId of this.store.listKnownProjectIds()) {
+            try {
+                const result = this.ensureFresh({ projectId });
+                documents += result.documents;
+                actions += result.actions;
+                refreshed ||= result.refreshed;
+            }
+            catch (error) {
+                errors.push({ projectId, error: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        return { documents, actions, refreshed, errors };
+    }
+}

package/dist/atlas/MemoryAtlasQueryCompiler.d.ts

@@ -0,0 +1,23 @@
+export interface CompiledAtlasQuery {
+    text: string;
+    tokens: string[];
+    keywords: string[];
+    target?: string;
+    actionIntent: boolean;
+    range?: {
+        from: number;
+        to: number;
+        label: string;
+    };
+    memoryKinds: string[];
+}
+export declare function compileAtlasQuery(query: string, now?: number): CompiledAtlasQuery;
+export declare function actionMarker(value: string): {
+    frameType: string;
+    action: string;
+} | undefined;
+export declare function actionMarkers(value: string): Array<{
+    frameType: string;
+    action: string;
+}>;
+//# sourceMappingURL=MemoryAtlasQueryCompiler.d.ts.map

package/dist/atlas/MemoryAtlasQueryCompiler.js

@@ -0,0 +1,55 @@
+const STOP_WORDS = new Set(['我', '你', '让', '对', '的', '年', '做过', '什么', '去年', '今年', 'the', 'a', 'an', 'what', 'did', 'do', 'to', 'last', 'year']);
+const ACTION_MARKERS = /配置|连接|安装|修复|更新|升级|比较|操作|设置|调试|configure|connect|install|repair|fix|update|upgrade|compare|setup|debug/iu;
+const MEMORY_KIND_MARKERS = [
+    [/决策|决定|decision/iu, 'decision'], [/修正|纠正|correction/iu, 'correction'],
+    [/目标|goal/iu, 'goal'], [/偏好|preference/iu, 'preference'], [/计划|plan/iu, 'plan'],
+    [/事件|经历|event/iu, 'event'], [/证据|原文|evidence/iu, 'evidence'],
+    [/人物|person/iu, 'person'], [/地点|place/iu, 'place'], [/项目|project/iu, 'project'],
+    [ACTION_MARKERS, 'action'],
+];
+export function compileAtlasQuery(query, now = Date.now()) {
+    const text = String(query || '').trim().slice(0, 1000);
+    const tokens = Array.from(new Set((text.match(/[\p{L}\p{N}_-]+/gu) || [])
+        .map((item) => item.trim())
+        .filter((item) => item.length > 1 && !STOP_WORDS.has(item.toLowerCase())))).slice(0, 24);
+    const explicitYear = text.match(/(?:^|\D)((?:19|20)\d{2})(?:\D|$)/u)?.[1];
+    let range;
+    if (explicitYear) {
+        const year = Number(explicitYear);
+        range = { from: Date.UTC(year, 0, 1), to: Date.UTC(year + 1, 0, 1), label: explicitYear };
+    }
+    else if (/去年|last year/iu.test(text)) {
+        const year = new Date(now).getUTCFullYear() - 1;
+        range = { from: Date.UTC(year, 0, 1), to: Date.UTC(year + 1, 0, 1), label: String(year) };
+    }
+    const target = tokens.find((token) => /^[A-Z][\p{L}\p{N}_.-]*$/u.test(token))
+        ?? tokens.find((token) => !/^\d{4}$/u.test(token)
+            && !ACTION_MARKERS.test(token)
+            && !MEMORY_KIND_MARKERS.some(([pattern]) => pattern.test(token)));
+    const memoryKinds = MEMORY_KIND_MARKERS.filter(([pattern]) => pattern.test(text)).map(([, kind]) => kind);
+    const keywords = tokens.filter((token) => token !== target
+        && token !== explicitYear
+        && !ACTION_MARKERS.test(token)
+        && !MEMORY_KIND_MARKERS.some(([pattern]) => pattern.test(token)));
+    return { text, tokens, keywords, target, actionIntent: ACTION_MARKERS.test(text), range, memoryKinds };
+}
+export function actionMarker(value) {
+    return actionMarkers(value)[0];
+}
+export function actionMarkers(value) {
+    const matches = value.match(new RegExp(ACTION_MARKERS.source, 'giu')) || [];
+    return Array.from(new Set(matches.map((match) => match.toLocaleLowerCase()))).map((action) => ({
+        frameType: frameTypeForAction(action),
+        action,
+    }));
+}
+function frameTypeForAction(lower) {
+    const frameType = /修复|fix|repair|调试|debug/u.test(lower) ? 'repair'
+        : /安装|install/u.test(lower) ? 'install'
+            : /连接|connect/u.test(lower) ? 'connect'
+                : /更新|升级|update|upgrade/u.test(lower) ? 'update'
+                    : /比较|compare/u.test(lower) ? 'compare'
+                        : /配置|设置|configure|setup/u.test(lower) ? 'configuration'
+                            : 'operation';
+    return frameType;
+}

package/dist/atlas/MemoryAtlasService.d.ts

@@ -0,0 +1,25 @@
+import type { EventStore } from '../store/EventStore.js';
+import type { MemoryAtlasStore } from '../store/MemoryAtlasStore.js';
+import type { MemoryAtlasNodeDetail, MemoryAtlasPathResult, MemoryAtlasQueryOptions, MemoryAtlasSlice, MemoryAtlasTimelineResult } from './MemoryAtlasTypes.js';
+export declare class MemoryAtlasService {
+    private store;
+    private eventStore;
+    constructor(store: MemoryAtlasStore, eventStore: EventStore);
+    overview(options: MemoryAtlasQueryOptions): MemoryAtlasSlice;
+    search(query: string, options: MemoryAtlasQueryOptions): MemoryAtlasSlice;
+    explore(query: string, options: MemoryAtlasQueryOptions): MemoryAtlasSlice;
+    node(nodeId: string, options: MemoryAtlasQueryOptions): MemoryAtlasNodeDetail | null;
+    neighbors(nodeId: string, options: MemoryAtlasQueryOptions & {
+        hops?: number;
+    }): MemoryAtlasSlice;
+    path(from: string, to: string, options: MemoryAtlasQueryOptions & {
+        maxHops?: number;
+    }): MemoryAtlasPathResult;
+    timeline(query: string, options: MemoryAtlasQueryOptions): MemoryAtlasTimelineResult;
+    private evidence;
+    private edgesFor;
+    private safeEdges;
+    private adjacentEdges;
+    private directEdgesToTarget;
+}
+//# sourceMappingURL=MemoryAtlasService.d.ts.map

package/dist/atlas/MemoryAtlasService.js

@@ -0,0 +1,216 @@
+import { eventTextForMemory } from '../episode/CogmemBlockStripper.js';
+import { compileAtlasQuery } from './MemoryAtlasQueryCompiler.js';
+export class MemoryAtlasService {
+    store;
+    eventStore;
+    constructor(store, eventStore) {
+        this.store = store;
+        this.eventStore = eventStore;
+    }
+    overview(options) {
+        const limit = boundedLimit(options.limit);
+        const nodes = this.store.listNodes(requiredProject(options.projectId), limit);
+        return slice(options.projectId, nodes, this.edgesFor(nodes, options.projectId));
+    }
+    search(query, options) {
+        const projectId = requiredProject(options.projectId);
+        const nodes = this.store.search(boundedQuery(query), projectId, boundedLimit(options.limit));
+        return slice(projectId, nodes, this.edgesFor(nodes, projectId), query);
+    }
+    explore(query, options) {
+        const projectId = requiredProject(options.projectId);
+        const limit = boundedLimit(options.limit);
+        const compiled = compileAtlasQuery(boundedQuery(query), options.now);
+        const target = this.store.resolveTargetNodeIds(projectId, compiled.text);
+        let nodes = this.store.searchFaceted(query, projectId, limit, {
+            from: compiled.range?.from, to: compiled.range?.to, memoryKinds: compiled.memoryKinds,
+            keywords: target.nodeIds.length ? compiled.keywords : compiled.tokens,
+            targetNodeIds: target.nodeIds.length ? target.nodeIds : undefined,
+        });
+        if (compiled.actionIntent) {
+            const actions = this.store.listActions(projectId, { target: compiled.target, targetEntityIds: target.entitySourceIds,
+                from: compiled.range?.from, to: compiled.range?.to, limit });
+            nodes = uniqueNodes([...actions.map((action) => this.store.getNode(action.id, projectId)).filter((node) => Boolean(node)), ...nodes]).slice(0, limit);
+        }
+        const edges = this.edgesFor(nodes, projectId);
+        const result = slice(projectId, nodes, edges, query);
+        result.facets = { time: compiled.range, target: target.labels.join(', ') || compiled.target, memoryKinds: compiled.memoryKinds, keywords: compiled.keywords };
+        const hasFacet = Boolean(compiled.range || compiled.target || compiled.memoryKinds.length || compiled.tokens.length);
+        result.coldMemoryResurrected = hasFacet && nodes.some((node) => node.activation <= 0.1);
+        return result;
+    }
+    node(nodeId, options) {
+        const projectId = requiredProject(options.projectId);
+        const node = this.store.getNode(boundedId(nodeId), projectId);
+        if (!node)
+            return null;
+        const evidence = this.evidence(node.id, projectId, options.evidenceLimit, options.includeEvidence);
+        const neighbors = this.safeEdges(this.store.listEdgesForNodes(projectId, [node.id], 30), projectId);
+        const evidenceTotal = this.store.evidenceTotal(node.id, projectId);
+        return { ...node, evidenceCount: evidenceTotal, evidenceTotal, evidenceReturned: evidence.length, evidence, neighbors };
+    }
+    neighbors(nodeId, options) {
+        const projectId = requiredProject(options.projectId);
+        const hops = options.hops ?? 1;
+        if (!Number.isInteger(hops) || hops < 1 || hops > 2)
+            throw new Error('hops must be between 1 and 2');
+        const limit = boundedLimit(options.limit);
+        const seen = new Set([boundedId(nodeId)]);
+        let frontier = [...seen];
+        const selectedEdges = [];
+        for (let depth = 0; depth < hops; depth += 1) {
+            const next = [];
+            const adjacentEdges = this.store.listEdgesForNodes(projectId, frontier, Math.max(60, limit * 20));
+            for (const edge of adjacentEdges)
+                if (frontier.includes(edge.source) || frontier.includes(edge.target)) {
+                    selectedEdges.push(edge);
+                    const other = frontier.includes(edge.source) ? edge.target : edge.source;
+                    if (!seen.has(other) && seen.size < limit) {
+                        seen.add(other);
+                        next.push(other);
+                    }
+                }
+            frontier = next;
+        }
+        const nodes = Array.from(seen).map((id) => this.store.getNode(id, projectId)).filter((node) => Boolean(node)).slice(0, limit);
+        return slice(projectId, nodes, this.safeEdges(selectedEdges.filter((edge) => seen.has(edge.source) && seen.has(edge.target)).slice(0, 60), projectId));
+    }
+    path(from, to, options) {
+        const projectId = requiredProject(options.projectId);
+        const maxHops = Math.max(1, Math.min(options.maxHops ?? 6, 6));
+        const start = boundedId(from);
+        const target = boundedId(to);
+        const parents = new Map();
+        const best = new Map([[start, 0]]);
+        const queue = [{ id: start, cost: 0, hops: 0 }];
+        const expanded = new Set();
+        let found = start === target;
+        while (queue.length && expanded.size < 2000) {
+            queue.sort((left, right) => left.cost - right.cost || left.hops - right.hops);
+            const current = queue.shift();
+            if (current.cost !== best.get(current.id))
+                continue;
+            if (current.id === target) {
+                found = true;
+                break;
+            }
+            if (current.hops >= maxHops)
+                continue;
+            expanded.add(current.id);
+            const adjacent = uniqueEdges([
+                ...this.adjacentEdges(projectId, [current.id], 4000),
+                ...this.directEdgesToTarget(projectId, [current.id], target),
+            ]);
+            for (const edge of adjacent) {
+                const next = edge.source === current.id ? edge.target : edge.target === current.id ? edge.source : undefined;
+                if (!next)
+                    continue;
+                if (next !== target && !this.store.getNode(next, projectId))
+                    continue;
+                const nextCost = current.cost + edgeTraversalCost(edge);
+                if (nextCost >= (best.get(next) ?? Number.POSITIVE_INFINITY))
+                    continue;
+                best.set(next, nextCost);
+                parents.set(next, { previous: current.id, edge });
+                queue.push({ id: next, cost: nextCost, hops: current.hops + 1 });
+            }
+        }
+        const pathIds = [];
+        const pathEdges = [];
+        if (found) {
+            let current = target;
+            pathIds.push(current);
+            while (current !== start) {
+                const parent = parents.get(current);
+                if (!parent)
+                    break;
+                pathEdges.push(parent.edge);
+                current = parent.previous;
+                pathIds.push(current);
+            }
+            pathIds.reverse();
+            pathEdges.reverse();
+        }
+        const path = found ? pathIds.map((id) => this.store.getNode(id, projectId)).filter((node) => Boolean(node)) : [];
+        return { version: 'memory_atlas.v1', projectId, from: start, to: target, path,
+            edges: found ? this.safeEdges(pathEdges, projectId) : [], truncated: expanded.size >= 2000 };
+    }
+    timeline(query, options) {
+        const projectId = requiredProject(options.projectId);
+        const compiled = compileAtlasQuery(boundedQuery(query), options.now);
+        const limit = boundedLimit(options.limit);
+        const target = this.store.resolveTargetNodeIds(projectId, compiled.text);
+        const nodes = this.store.searchFaceted(query, projectId, limit, {
+            from: compiled.range?.from, to: compiled.range?.to, memoryKinds: compiled.memoryKinds,
+            keywords: target.nodeIds.length ? compiled.keywords : compiled.tokens,
+            targetNodeIds: target.nodeIds.length ? target.nodeIds : undefined,
+        }).sort((left, right) => Number(right.occurredAt || 0) - Number(left.occurredAt || 0)).map((node) => {
+            const evidence = this.evidence(node.id, projectId, options.evidenceLimit, options.includeEvidence);
+            const evidenceTotal = this.store.evidenceTotal(node.id, projectId);
+            return { ...node, evidenceCount: evidenceTotal, evidenceTotal, evidenceReturned: evidence.length, evidence, neighbors: [] };
+        });
+        const actions = this.store.listActions(projectId, { target: compiled.target, targetEntityIds: target.entitySourceIds,
+            from: compiled.range?.from, to: compiled.range?.to, limit: boundedLimit(options.limit) })
+            .map((action) => ({ ...action, evidence: this.evidence(action.id, projectId, options.evidenceLimit, options.includeEvidence) }));
+        return { version: 'memory_atlas.v1', projectId, query, range: compiled.range,
+            temporalResurrection: Boolean(compiled.range && [...nodes, ...actions].length), nodes, actions, warnings: [] };
+    }
+    evidence(nodeId, projectId, requested, includeExcerpt) {
+        const limit = Math.max(1, Math.min(requested ?? 2, 10));
+        return this.store.evidenceIds(nodeId, projectId, limit).flatMap((eventId) => {
+            const event = this.eventStore.getEvent(eventId);
+            if (!event || event.projectId !== projectId)
+                return [];
+            return [{ eventId, drilldown: `cogmem memory show --event ${eventId} --project ${projectId} --json`,
+                    excerpt: includeExcerpt ? eventTextForMemory(event).slice(0, 500) : undefined }];
+        });
+    }
+    edgesFor(nodes, projectId) {
+        const ids = new Set(nodes.map((node) => node.id));
+        return this.safeEdges(this.store.listEdgesForNodes(projectId, [...ids], 60)
+            .filter((edge) => ids.has(edge.source) && ids.has(edge.target)).slice(0, 60), projectId);
+    }
+    safeEdges(edges, projectId) {
+        return edges.map((edge) => ({ ...edge, evidenceEventIds: edge.evidenceEventIds.filter((eventId) => {
+                const event = this.eventStore.getEvent(eventId);
+                return Boolean(event && event.projectId === projectId);
+            }) }));
+    }
+    adjacentEdges(projectId, nodeIds, limit) {
+        const chunks = chunked(nodeIds, 30);
+        const perChunk = Math.max(60, Math.ceil(limit / Math.max(1, chunks.length)));
+        const edges = chunks.flatMap((chunk) => this.store.listEdgesForNodes(projectId, chunk, perChunk));
+        return uniqueEdges(edges).slice(0, limit);
+    }
+    directEdgesToTarget(projectId, nodeIds, target) {
+        return uniqueEdges(chunked(nodeIds, 30)
+            .flatMap((chunk) => this.store.findEdgesFromNodesToTarget(projectId, chunk, target)));
+    }
+}
+function requiredProject(value) { if (!value?.trim())
+    throw new Error('projectId is required for Memory Atlas queries'); return value.trim(); }
+function boundedLimit(value) { if (value !== undefined && (!Number.isFinite(value) || value < 1))
+    throw new Error('limit must be a positive number'); return Math.min(Math.floor(value ?? 8), 30); }
+function boundedQuery(value) { const query = String(value || '').trim(); if (!query)
+    throw new Error('query is required'); if (query.length > 1000)
+    throw new Error('query exceeds 1000 characters'); return query; }
+function boundedId(value) { const id = String(value || '').trim(); if (!id || id.length > 500)
+    throw new Error('invalid node id'); return id; }
+function uniqueNodes(nodes) { return Array.from(new Map(nodes.map((node) => [node.id, node])).values()); }
+function uniqueIds(ids) { return Array.from(new Set(ids)); }
+function uniqueEdges(edges) {
+    return Array.from(new Map(edges.map((edge) => [`${edge.source}\0${edge.relation}\0${edge.target}`, edge])).values());
+}
+function edgeTraversalCost(edge) {
+    const confidence = Math.max(0.01, Math.min(1, edge.confidence));
+    const relationPenalty = /^(EVIDENCED_BY|DERIVED_FROM|TARGETS|OCCURRED_IN|SUPPORTS|ABOUT|MENTIONS)$/u.test(edge.relation)
+        ? 0 : /^(CONTRADICTS|CORRECTS)$/u.test(edge.relation) ? 0.2 : 0.1;
+    return -Math.log(confidence) + 0.12 + relationPenalty;
+}
+function chunked(values, size) {
+    const chunks = [];
+    for (let index = 0; index < values.length; index += size)
+        chunks.push(values.slice(index, index + size));
+    return chunks;
+}
+function slice(projectId, nodes, edges, query) { return { version: 'memory_atlas.v1', projectId, query, nodes, edges, nextActions: nodes.slice(0, 5).map((node) => ({ label: `Inspect ${node.label}`, tool: 'cogmem_graph_node', args: { id: node.id, projectId } })), warnings: [] }; }

package/dist/atlas/MemoryAtlasTypes.d.ts

@@ -0,0 +1,107 @@
+export type MemoryAtlasNodeType = 'project' | 'topic' | 'entity' | 'cluster' | 'episode' | 'belief' | 'action' | 'time' | 'event';
+export interface MemoryAtlasEvidence {
+    eventId: string;
+    drilldown: string;
+    excerpt?: string;
+}
+export interface MemoryAtlasNode {
+    id: string;
+    projectId: string;
+    nodeType: MemoryAtlasNodeType;
+    memoryKind?: string;
+    sourceId: string;
+    label: string;
+    summary?: string;
+    topicPath?: string;
+    confidence: number;
+    supportCount: number;
+    status: string;
+    occurredAt?: number;
+    activation: number;
+    score: number;
+    evidenceCount: number;
+    /** Total source evidence known for this node. */
+    evidenceTotal: number;
+    /** Number of evidence records returned in this response. */
+    evidenceReturned?: number;
+}
+export interface MemoryAtlasEdge {
+    source: string;
+    relation: string;
+    target: string;
+    confidence: number;
+    evidenceEventIds: string[];
+}
+export interface MemoryAtlasNextAction {
+    label: string;
+    tool: string;
+    args: Record<string, unknown>;
+}
+export interface MemoryAtlasSlice {
+    version: 'memory_atlas.v1';
+    projectId: string;
+    query?: string;
+    nodes: MemoryAtlasNode[];
+    edges: MemoryAtlasEdge[];
+    nextActions: MemoryAtlasNextAction[];
+    warnings: string[];
+    facets?: {
+        time?: {
+            from: number;
+            to: number;
+            label: string;
+        };
+        target?: string;
+        memoryKinds: string[];
+        keywords: string[];
+    };
+    coldMemoryResurrected?: boolean;
+}
+export interface MemoryAtlasNodeDetail extends MemoryAtlasNode {
+    evidence: MemoryAtlasEvidence[];
+    neighbors: MemoryAtlasEdge[];
+}
+export interface MemoryAtlasAction {
+    id: string;
+    frameType: string;
+    action: string;
+    targetLabel?: string;
+    topicPath?: string;
+    episodeId?: string;
+    occurredAt: number;
+    confidence: number;
+    evidence: MemoryAtlasEvidence[];
+}
+export interface MemoryAtlasTimelineResult {
+    version: 'memory_atlas.v1';
+    projectId: string;
+    query: string;
+    range?: {
+        from: number;
+        to: number;
+        label: string;
+    };
+    temporalResurrection: boolean;
+    nodes: MemoryAtlasNodeDetail[];
+    actions: MemoryAtlasAction[];
+    warnings: string[];
+}
+export interface MemoryAtlasPathResult {
+    version: 'memory_atlas.v1';
+    projectId: string;
+    from: string;
+    to: string;
+    path: MemoryAtlasNode[];
+    edges: MemoryAtlasEdge[];
+    truncated: boolean;
+}
+export interface MemoryAtlasQueryOptions {
+    projectId: string;
+    limit?: number;
+    includeEvidence?: boolean;
+    evidenceLimit?: number;
+    now?: number;
+    refresh?: boolean;
+    staleOk?: boolean;
+}
+//# sourceMappingURL=MemoryAtlasTypes.d.ts.map

package/dist/atlas/MemoryAtlasTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/atlas/index.d.ts

@@ -0,0 +1,6 @@
+export * from './MemoryAtlasTypes.js';
+export * from './MemoryAtlasQueryCompiler.js';
+export * from './MemoryAtlasIndexer.js';
+export * from './MemoryAtlasService.js';
+export * from './ActionFrameExtractor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/atlas/index.js

@@ -0,0 +1,5 @@
+export * from './MemoryAtlasTypes.js';
+export * from './MemoryAtlasQueryCompiler.js';
+export * from './MemoryAtlasIndexer.js';
+export * from './MemoryAtlasService.js';
+export * from './ActionFrameExtractor.js';

package/dist/backend/SemanticBackend.d.ts

@@ -0,0 +1,40 @@
+export type SemanticBackendMode = 'deterministic_local' | 'rule_only' | 'model_backed' | 'hybrid';
+export type SemanticBackendProviderId = 'deterministic-local' | 'rule-only' | 'gemma4-e4b-local' | 'hybrid-rule-plus-gemma4-e4b';
+export type SemanticBackendTask = 'offline_deep_consolidation' | 'async_low_confidence_enrichment' | 'optional_semantic_task';
+export interface SemanticBackendConfig {
+    mode: SemanticBackendMode;
+    providerId: SemanticBackendProviderId;
+    modelPath?: string;
+    readinessFile: string;
+    requireReady: boolean;
+}
+export interface SemanticBackendStatus {
+    mode: SemanticBackendMode;
+    providerId: SemanticBackendProviderId;
+    ready: boolean;
+    requiresExplicitSetup: boolean;
+    modelPath?: string;
+    readinessFile: string;
+    eligibleTasks: SemanticBackendTask[];
+    failureBehavior: 'no_effect' | 'rule_only_fallback' | 'explicit_failure';
+    fallbackBackend: 'rule_only' | null;
+    reason: string;
+}
+export interface SemanticBackendInvocation {
+    task: SemanticBackendTask;
+    selectedBackend: SemanticBackendProviderId | 'rule-only-fallback';
+    fallbackUsed: boolean;
+    ready: boolean;
+    reason: string;
+}
+export declare function resolveSemanticBackendConfig(): SemanticBackendConfig;
+export declare class SemanticBackendRuntime {
+    private readonly config;
+    constructor(config?: SemanticBackendConfig);
+    getStatus(): SemanticBackendStatus;
+    warmup(): SemanticBackendStatus;
+    prepare(task: SemanticBackendTask): SemanticBackendInvocation;
+    private isReady;
+    private explainNotReady;
+}
+//# sourceMappingURL=SemanticBackend.d.ts.map

package/dist/backend/SemanticBackend.js

@@ -0,0 +1,107 @@
+// @ts-nocheck
+import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+const DEFAULT_CACHE_ROOT = resolve(`${process.env.HOME || '/tmp'}/.cache/cogmem`);
+const DEFAULT_READY_FILE = join(DEFAULT_CACHE_ROOT, 'semantic-backends', 'gemma4-e4b-ready.json');
+export function resolveSemanticBackendConfig() {
+    return {
+        mode: 'rule_only',
+        providerId: 'rule-only',
+        readinessFile: DEFAULT_READY_FILE,
+        requireReady: false
+    };
+}
+export class SemanticBackendRuntime {
+    config;
+    constructor(config = resolveSemanticBackendConfig()) {
+        this.config = config;
+    }
+    getStatus() {
+        const ready = this.isReady();
+        const eligibleTasks = this.config.mode === 'rule_only' || this.config.mode === 'deterministic_local'
+            ? []
+            : ['offline_deep_consolidation', 'async_low_confidence_enrichment', 'optional_semantic_task'];
+        const failureBehavior = this.config.mode === 'model_backed'
+            ? (this.config.requireReady ? 'explicit_failure' : 'rule_only_fallback')
+            : this.config.mode === 'hybrid'
+                ? 'rule_only_fallback'
+                : 'no_effect';
+        return {
+            mode: this.config.mode,
+            providerId: this.config.providerId,
+            ready,
+            requiresExplicitSetup: this.config.mode === 'model_backed' || this.config.mode === 'hybrid',
+            modelPath: this.config.modelPath,
+            readinessFile: this.config.readinessFile,
+            eligibleTasks,
+            failureBehavior,
+            fallbackBackend: failureBehavior === 'rule_only_fallback' ? 'rule_only' : null,
+            reason: ready ? 'ready' : this.explainNotReady()
+        };
+    }
+    warmup() {
+        const status = this.getStatus();
+        if (!status.requiresExplicitSetup)
+            return status;
+        if (!this.config.modelPath || !existsSync(this.config.modelPath))
+            return status;
+        if (!statSync(this.config.modelPath).isDirectory())
+            return status;
+        mkdirSync(dirname(this.config.readinessFile), { recursive: true });
+        writeFileSync(this.config.readinessFile, JSON.stringify({
+            providerId: this.config.providerId,
+            modelPath: this.config.modelPath,
+            warmedAt: new Date().toISOString()
+        }, null, 2));
+        return this.getStatus();
+    }
+    prepare(task) {
+        const status = this.getStatus();
+        if (status.mode === 'rule_only' || status.mode === 'deterministic_local') {
+            return {
+                task,
+                selectedBackend: status.providerId,
+                fallbackUsed: false,
+                ready: true,
+                reason: 'default_no_download_backend'
+            };
+        }
+        if (status.ready) {
+            return {
+                task,
+                selectedBackend: status.providerId,
+                fallbackUsed: false,
+                ready: true,
+                reason: 'explicit_model_backend_ready'
+            };
+        }
+        if (status.failureBehavior === 'explicit_failure') {
+            throw new Error(`Semantic backend ${status.providerId} is not ready: ${status.reason}`);
+        }
+        return {
+            task,
+            selectedBackend: 'rule-only-fallback',
+            fallbackUsed: true,
+            ready: false,
+            reason: status.reason
+        };
+    }
+    isReady() {
+        if (this.config.mode === 'rule_only' || this.config.mode === 'deterministic_local')
+            return true;
+        if (!this.config.modelPath || !existsSync(this.config.modelPath))
+            return false;
+        return existsSync(this.config.readinessFile);
+    }
+    explainNotReady() {
+        if (this.config.mode === 'rule_only' || this.config.mode === 'deterministic_local')
+            return 'no_model_required';
+        if (!this.config.modelPath)
+            return 'missing_model_path';
+        if (!existsSync(this.config.modelPath))
+            return 'missing_local_model';
+        if (!existsSync(this.config.readinessFile))
+            return 'setup_not_run';
+        return 'not_ready';
+    }
+}