cogmem 3.6.4 → 3.7.0

package/dist/atlas/MemoryAtlasService.js

@@ -1,8 +1,11 @@
+import { MEMORY_ATLAS_PROJECTION_NAME } from '../store/MemoryAtlasStore.js';
 import { eventTextForMemory } from '../episode/CogmemBlockStripper.js';
+import { FacetQueryPlanner } from './FacetQueryPlanner.js';
 import { compileAtlasQuery } from './MemoryAtlasQueryCompiler.js';
 export class MemoryAtlasService {
     store;
     eventStore;
+    facetPlanner = new FacetQueryPlanner();
     constructor(store, eventStore) {
         this.store = store;
         this.eventStore = eventStore;
@@ -14,12 +17,29 @@ export class MemoryAtlasService {
     }
     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);
+        const limit = boundedLimit(options.limit);
+        const facetResult = this.searchFacetCardsWithRelaxation(query, projectId, limit, options);
+        const cards = facetResult.cards;
+        let nodes = this.store.search(boundedQuery(query), projectId, limit);
+        if (cards.length) {
+            const cardNodes = cards.map((card) => this.store.getNode(card.canonicalId, projectId)).filter((node) => Boolean(node));
+            nodes = uniqueNodes([...cardNodes, ...nodes]).slice(0, limit);
+        }
+        const withEvidence = this.attachEvidence(nodes, projectId, options);
+        const result = slice(projectId, withEvidence, this.edgesFor(withEvidence, projectId), query);
+        result.facets = facetsForPlan(facetResult.plan);
+        result.matchedFacets = cards.flatMap((card) => card.matchedFacets);
+        if (cards.length)
+            result.cards = this.attachCardEvidence(cards, projectId, options);
+        if (facetResult.relaxationTrace.length)
+            result.relaxationTrace = facetResult.relaxationTrace;
+        return result;
     }
     explore(query, options) {
         const projectId = requiredProject(options.projectId);
         const limit = boundedLimit(options.limit);
+        const facetResult = this.searchFacetCardsWithRelaxation(query, projectId, limit, options);
+        const cards = facetResult.cards;
         const compiled = compileAtlasQuery(boundedQuery(query), options.now);
         const target = this.store.resolveTargetNodeIds(projectId, compiled.text);
         let nodes = this.store.searchFaceted(query, projectId, limit, {
@@ -27,14 +47,27 @@ export class MemoryAtlasService {
             keywords: target.nodeIds.length ? compiled.keywords : compiled.tokens,
             targetNodeIds: target.nodeIds.length ? target.nodeIds : undefined,
         });
+        if (cards.length) {
+            const cardNodes = cards.map((card) => this.store.getNode(card.canonicalId, projectId)).filter((node) => Boolean(node));
+            nodes = uniqueNodes([...cardNodes, ...nodes]).slice(0, limit);
+        }
         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 nodesWithEvidence = this.attachEvidence(nodes, projectId, options);
+        const edges = this.edgesFor(nodesWithEvidence, projectId);
+        const result = slice(projectId, nodesWithEvidence, edges, query);
+        result.facets = {
+            ...facetsForPlan(facetResult.plan),
+            legacy: { time: compiled.range, target: target.labels.join(', ') || compiled.target, memoryKinds: compiled.memoryKinds, keywords: compiled.keywords },
+        };
+        result.matchedFacets = cards.flatMap((card) => card.matchedFacets);
+        if (cards.length)
+            result.cards = this.attachCardEvidence(cards, projectId, options);
+        if (facetResult.relaxationTrace.length)
+            result.relaxationTrace = facetResult.relaxationTrace;
         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;
@@ -132,19 +165,22 @@ export class MemoryAtlasService {
             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,
+        return { version: MEMORY_ATLAS_PROJECTION_NAME, 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 facetResult = this.searchFacetCardsWithRelaxation(query, projectId, limit, options);
+        const cards = this.attachCardEvidence(facetResult.cards, projectId, options)
+            .sort((left, right) => dateKey(left) - dateKey(right) || left.displayTitle.localeCompare(right.displayTitle));
         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) => {
+        }).sort((left, right) => Number(left.occurredAt || 0) - Number(right.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: [] };
@@ -152,8 +188,46 @@ export class MemoryAtlasService {
         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: [] };
+        return { version: MEMORY_ATLAS_PROJECTION_NAME, projectId, query, range: compiled.range,
+            temporalResurrection: Boolean((compiled.range || facetResult.plan.temporalIntent) && [...nodes, ...actions, ...cards].length),
+            nodes, actions, cards,
+            groupedByIssue: groupCardsByIssue(cards),
+            relaxationTrace: facetResult.relaxationTrace.length ? facetResult.relaxationTrace : undefined,
+            facets: facetsForPlan(facetResult.plan),
+            matchedFacets: cards.flatMap((card) => card.matchedFacets),
+            warnings: [] };
+    }
+    searchFacetCardsWithRelaxation(query, projectId, limit, options) {
+        let plan = this.facetPlanner.plan(boundedQuery(query), { projectId, now: options.now });
+        const relaxationTrace = [];
+        let cards = plan.facets.length ? this.store.searchCanonicalEpisodeCards(projectId, plan, limit) : [];
+        if (!cards.length && plan.facets.length) {
+            const relaxed = relaxFacetPlan(plan);
+            if (relaxed) {
+                plan = relaxed.plan;
+                cards = this.store.searchCanonicalEpisodeCards(projectId, relaxed.plan, limit);
+                relaxationTrace.push(...relaxed.trace);
+            }
+        }
+        return { plan, cards, relaxationTrace };
+    }
+    attachEvidence(nodes, projectId, options) {
+        return nodes.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 };
+        });
+    }
+    attachCardEvidence(cards, projectId, options) {
+        return cards.map((card) => {
+            const evidence = this.evidence(card.canonicalId, projectId, options.evidenceLimit, options.includeEvidence);
+            return {
+                ...card,
+                sourceLocator: evidence[0]?.sourceLocator ?? card.sourceLocator,
+                evidenceTotal: Math.max(card.evidenceTotal, this.store.evidenceTotal(card.canonicalId, projectId)),
+                evidenceReturned: evidence.length,
+            };
+        });
     }
     evidence(nodeId, projectId, requested, includeExcerpt) {
         const limit = Math.max(1, Math.min(requested ?? 2, 10));
@@ -161,8 +235,15 @@ export class MemoryAtlasService {
             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 }];
+            const sourceLocator = atlasSourceLocator(event, projectId);
+            return [{
+                    eventId,
+                    globalSeq: event.globalSeq,
+                    projectId,
+                    drilldown: sourceLocator.command,
+                    sourceLocator,
+                    excerpt: includeExcerpt ? eventTextForMemory(event).slice(0, 500) : undefined,
+                }];
         });
     }
     edgesFor(nodes, projectId) {
@@ -213,4 +294,76 @@ function chunked(values, 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: [] }; }
+function slice(projectId, nodes, edges, query) { return { version: MEMORY_ATLAS_PROJECTION_NAME, 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: [] }; }
+function facetsForPlan(plan) {
+    return {
+        planner: {
+            intent: plan.intent,
+            operator: plan.operator,
+            temporalIntent: plan.temporalIntent,
+            groupBy: plan.groupBy,
+            exactness: plan.exactness,
+            keywords: plan.keywords,
+            facets: plan.facets.map((facet) => ({
+                type: facet.type,
+                value: facet.value,
+                label: facet.label,
+                nodeId: facet.nodeId || `${facet.type}:${facet.value}`,
+                relation: facet.relation || 'MATCHES',
+            })),
+        },
+    };
+}
+function dateKey(card) {
+    if (card.localDate && /^\d{4}-\d{2}-\d{2}$/u.test(card.localDate)) {
+        return Date.parse(`${card.localDate}T00:00:00.000Z`);
+    }
+    return Number.POSITIVE_INFINITY;
+}
+function groupCardsByIssue(cards) {
+    const groups = new Map();
+    for (const card of cards) {
+        const key = card.issueType || 'unclassified';
+        groups.set(key, [...(groups.get(key) || []), card]);
+    }
+    return Array.from(groups.entries()).map(([issueType, group]) => ({ issueType, cards: group }));
+}
+function relaxFacetPlan(plan) {
+    const dayFacet = plan.facets.find((facet) => facet.type === 'time' && facet.granularity === 'day');
+    if (!dayFacet)
+        return null;
+    const monthValue = dayFacet.value.slice(0, 7);
+    return {
+        plan: {
+            ...plan,
+            exactness: 'relaxed',
+            facets: plan.facets.map((facet) => facet === dayFacet ? {
+                ...facet,
+                value: monthValue,
+                label: monthValue,
+                nodeId: facet.nodeId?.replace(dayFacet.value, monthValue),
+                relation: 'OCCURRED_IN',
+                granularity: 'month',
+            } : facet),
+        },
+        trace: [{ from: dayFacet.value, to: monthValue, reason: 'exact day facet had no canonical episode match; relaxed to parent month' }],
+    };
+}
+function atlasSourceLocator(event, projectId) {
+    const project = projectId || event.projectId;
+    const projectArg = project ? ` --project ${cliArg(project)}` : '';
+    const base = `cogmem memory show --event ${cliArg(event.eventId)}${projectArg}`;
+    return {
+        eventId: event.eventId,
+        globalSeq: event.globalSeq,
+        projectId: project,
+        threadId: event.threadId,
+        sessionId: event.sessionId,
+        localDate: event.localDate,
+        command: `${base} --before 2 --after 2 --json`,
+        contextCommand: `${base} --before 3 --after 3 --json`,
+    };
+}
+function cliArg(value) {
+    return /^[A-Za-z0-9._:/=@+-]+$/u.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/dist/atlas/MemoryAtlasTypes.d.ts

@@ -1,7 +1,19 @@
-export type MemoryAtlasNodeType = 'project' | 'topic' | 'entity' | 'cluster' | 'episode' | 'belief' | 'action' | 'time' | 'event';
+export type MemoryAtlasNodeType = 'project' | 'topic' | 'issue' | 'entity' | 'session' | 'thread' | 'memoryKind' | 'actionKind' | 'cluster' | 'episode' | 'raw_event' | 'belief' | 'action' | 'time' | 'event' | 'decision' | 'correction';
 export interface MemoryAtlasEvidence {
     eventId: string;
+    globalSeq?: number;
+    projectId?: string;
     drilldown: string;
+    sourceLocator?: {
+        eventId: string;
+        globalSeq?: number;
+        projectId?: string;
+        threadId?: string;
+        sessionId?: string;
+        localDate?: string;
+        command: string;
+        contextCommand: string;
+    };
     excerpt?: string;
 }
 export interface MemoryAtlasNode {
@@ -24,6 +36,50 @@ export interface MemoryAtlasNode {
     evidenceTotal: number;
     /** Number of evidence records returned in this response. */
     evidenceReturned?: number;
+    /** Bounded first-hop raw evidence locators for agent-facing graph search/explore responses. */
+    evidence?: MemoryAtlasEvidence[];
+}
+export interface MemoryAtlasMatchedFacet {
+    type: 'time' | 'topic' | 'issue' | 'entity' | 'session' | 'thread' | 'memoryKind' | 'actionKind';
+    value: string;
+    label: string;
+    nodeId: string;
+    relation: string;
+}
+export interface MemoryAtlasMatchedPath {
+    facet: MemoryAtlasMatchedFacet;
+    via: string[];
+    relation: string;
+    confidence: number;
+}
+export interface MemoryAtlasRelatedCard {
+    canonicalId: string;
+    displayTitle: string;
+    reason: string;
+    matchedFacets?: MemoryAtlasMatchedFacet[];
+}
+export interface MemoryAtlasCard {
+    canonicalId: string;
+    nodeType: MemoryAtlasNodeType;
+    displayTitle: string;
+    oneLineSummary?: string;
+    matchedFacets: MemoryAtlasMatchedFacet[];
+    matchedPaths: MemoryAtlasMatchedPath[];
+    parentTopics: string[];
+    issueType?: string;
+    eventKind?: string;
+    localDate?: string;
+    whyMatched: string;
+    relatedButNotSelected: MemoryAtlasRelatedCard[];
+    sourceLocator?: MemoryAtlasEvidence['sourceLocator'];
+    evidenceEventIds: string[];
+    evidenceTotal: number;
+    evidenceReturned: number;
+}
+export interface MemoryAtlasRelaxationStep {
+    from: string;
+    to: string;
+    reason: string;
 }
 export interface MemoryAtlasEdge {
     source: string;
@@ -38,7 +94,7 @@ export interface MemoryAtlasNextAction {
     args: Record<string, unknown>;
 }
 export interface MemoryAtlasSlice {
-    version: 'memory_atlas.v1';
+    version: 'memory_atlas.v2';
     projectId: string;
     query?: string;
     nodes: MemoryAtlasNode[];
@@ -46,15 +102,29 @@ export interface MemoryAtlasSlice {
     nextActions: MemoryAtlasNextAction[];
     warnings: string[];
     facets?: {
-        time?: {
-            from: number;
-            to: number;
-            label: string;
+        planner?: {
+            intent: string;
+            operator: string;
+            temporalIntent?: string;
+            groupBy?: string;
+            exactness: string;
+            facets: MemoryAtlasMatchedFacet[];
+            keywords: string[];
+        };
+        legacy?: {
+            time?: {
+                from: number;
+                to: number;
+                label: string;
+            };
+            target?: string;
+            memoryKinds: string[];
+            keywords: string[];
         };
-        target?: string;
-        memoryKinds: string[];
-        keywords: string[];
     };
+    matchedFacets?: MemoryAtlasMatchedFacet[];
+    cards?: MemoryAtlasCard[];
+    relaxationTrace?: MemoryAtlasRelaxationStep[];
     coldMemoryResurrected?: boolean;
 }
 export interface MemoryAtlasNodeDetail extends MemoryAtlasNode {
@@ -73,7 +143,7 @@ export interface MemoryAtlasAction {
     evidence: MemoryAtlasEvidence[];
 }
 export interface MemoryAtlasTimelineResult {
-    version: 'memory_atlas.v1';
+    version: 'memory_atlas.v2';
     projectId: string;
     query: string;
     range?: {
@@ -84,10 +154,18 @@ export interface MemoryAtlasTimelineResult {
     temporalResurrection: boolean;
     nodes: MemoryAtlasNodeDetail[];
     actions: MemoryAtlasAction[];
+    cards?: MemoryAtlasCard[];
+    groupedByIssue?: Array<{
+        issueType: string;
+        cards: MemoryAtlasCard[];
+    }>;
+    relaxationTrace?: MemoryAtlasRelaxationStep[];
+    facets?: MemoryAtlasSlice['facets'];
+    matchedFacets?: MemoryAtlasMatchedFacet[];
     warnings: string[];
 }
 export interface MemoryAtlasPathResult {
-    version: 'memory_atlas.v1';
+    version: 'memory_atlas.v2';
     projectId: string;
     from: string;
     to: string;

package/dist/bin/connect.js

@@ -90,21 +90,92 @@ function defaultSkillPath(agent, workspaceRoot) {
     return join(process.env.HOME || homedir(), '.hermes', 'skills', 'cogmem-memory', 'SKILL.md');
 }
 function nextCommands(agent) {
+    return nextSteps(agent)
+        .filter((step) => step.safeForAutomation && step.actor === 'agent')
+        .map((step) => step.command);
+}
+function nextSteps(agent) {
+    const project = agent === 'openclaw' ? 'openclaw' : 'hermes';
+    const importCommand = agent === 'openclaw' ? 'import-openclaw' : 'import-hermes';
+    const steps = [
+        {
+            id: 'doctor',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: './node_modules/.bin/cogmem doctor',
+            when: 'after installation or update',
+            purpose: 'verify package, config, and database access',
+        },
+        {
+            id: 'import_dry_run',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: `./node_modules/.bin/cogmem ${importCommand} --workspace . --project ${project} --dry-run --json`,
+            when: 'before importing legacy memory',
+            purpose: 'preview source discovery and import counts',
+        },
+        {
+            id: 'import_apply',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: `./node_modules/.bin/cogmem ${importCommand} --workspace . --project ${project} --json`,
+            when: 'after dry-run looks correct',
+            purpose: 'idempotently import legacy memory into Cogmem',
+        },
+        {
+            id: 'memory_plan',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: `./node_modules/.bin/cogmem memory plan --project ${project} --json`,
+            when: 'after import, update, or user asks for governance progress',
+            purpose: 'read agent-safe next actions instead of guessing from raw counters',
+        },
+        {
+            id: 'memory_status',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: `./node_modules/.bin/cogmem memory status --project ${project} --json`,
+            when: 'for read-only health checks',
+            purpose: 'inspect raw ledger, vector fallback, dream backlog, and queue summary',
+        },
+        {
+            id: 'interactive_init',
+            actor: 'operator',
+            safeForAutomation: false,
+            command: `./node_modules/.bin/cogmem init --agent ${agent} --scope project`,
+            when: 'only if no Cogmem config exists and a human operator is present',
+            purpose: 'interactive first-time config wizard; agents must not run this unattended',
+        },
+    ];
     if (agent === 'openclaw') {
-        return [
-            './node_modules/.bin/cogmem doctor',
-            './node_modules/.bin/cogmem openclaw diagnose --workspace . --json',
-            './node_modules/.bin/cogmem import-openclaw --workspace . --project openclaw --dry-run',
-            './node_modules/.bin/cogmem import-openclaw --workspace . --project openclaw',
-            './node_modules/.bin/cogmem memory status --project openclaw --json',
-        ];
+        steps.splice(1, 0, {
+            id: 'openclaw_diagnose',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: './node_modules/.bin/cogmem openclaw diagnose --workspace . --json',
+            when: 'after connect --auto --force or before investigating injection failures',
+            purpose: 'verify generated plugin files, audit log, queue lock, and hook diagnostics',
+        });
+        steps.push({
+            id: 'restart_gateway',
+            actor: 'host',
+            safeForAutomation: false,
+            command: 'openclaw gateway restart',
+            when: 'after plugin files or OpenClaw config changed',
+            purpose: 'reload OpenClaw hooks so the refreshed Cogmem plugin is active',
+        });
     }
-    return [
-        './node_modules/.bin/cogmem doctor',
-        './node_modules/.bin/cogmem import-hermes --workspace . --project hermes --dry-run',
-        './node_modules/.bin/cogmem import-hermes --workspace . --project hermes',
-        './node_modules/.bin/cogmem memory status --project hermes --json',
-    ];
+    else {
+        steps.push({
+            id: 'reload_hermes',
+            actor: 'host',
+            safeForAutomation: false,
+            command: 'restart or reload Hermes MCP server',
+            when: 'after Hermes MCP config changed',
+            purpose: 'reload the cogmem MCP server entry',
+        });
+    }
+    return steps;
 }
 function usage() {
     return [
@@ -238,6 +309,7 @@ function installSkill(args) {
         installed: !args.dryRun && !alreadyCurrent,
         alreadyCurrent,
         nextCommands: nextCommands(args.agent),
+        nextSteps: nextSteps(args.agent),
         hostConfigSnippet: hostConfigSnippet(args.agent, args.workspaceRoot, args.auto),
         autoMemory,
         hermesMcp,