cogmem 3.6.2

package/dist/adapters/types.js

@@ -0,0 +1,185 @@
+import { createHash } from 'crypto';
+import { basename } from 'node:path';
+export function computeStableHash(parts) {
+    const hash = createHash('sha256');
+    for (const part of parts) {
+        hash.update(String(part ?? ''));
+        hash.update('\u241f');
+    }
+    return hash.digest('hex');
+}
+export function inferSourceTitle(sourcePath) {
+    return basename(sourcePath).replace(/\.md$/i, '');
+}
+export function normalizeMarkdownText(text) {
+    return text
+        .replace(/\r\n/g, '\n')
+        .replace(/\u00a0/g, ' ')
+        .trim();
+}
+export function parseLooseTimestamp(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const direct = Date.parse(raw);
+    if (!Number.isNaN(direct))
+        return direct;
+    const normalized = raw
+        .trim()
+        .replace(/\./g, '-')
+        .replace(/\//g, '-')
+        .replace(/\s+/g, ' ');
+    const retry = Date.parse(normalized);
+    if (!Number.isNaN(retry))
+        return retry;
+    return fallback;
+}
+const ROLE_ALIASES = {
+    user: 'user',
+    human: 'user',
+    customer: 'user',
+    client: 'user',
+    q: 'user',
+    question: 'user',
+    agent: 'agent',
+    assistant: 'agent',
+    ai: 'agent',
+    bot: 'agent',
+    model: 'agent',
+    a: 'agent',
+    answer: 'agent',
+    system: 'system',
+    sys: 'system',
+    narrator: 'narrator',
+    note: 'narrator',
+    notes: 'narrator',
+    memo: 'narrator'
+};
+export function parseMarkdownRoleLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    const patterns = [
+        /^(?:[-*]|\d+\.)?\s*(?:\[(?<timestamp>[^\]]+)\]|\((?<timestampAlt>[^)]+)\)|(?<timestampLead>(?:\d{4}[-/.]\d{1,2}[-/.]\d{1,2}(?:[ T]\d{1,2}:\d{2}(?::\d{2})?(?:\s*[+-]\d{2}:?\d{2})?)?|\d{1,2}:\d{2}(?::\d{2})?)))?\s*(?<role>[A-Za-z][A-Za-z _-]{0,24})\s*[:：\-]\s*(?<text>.*)\s*$/i,
+        /^(?<role>[A-Za-z][A-Za-z _-]{0,24})\s*(?:\[(?<timestamp>[^\]]+)\]|\((?<timestampAlt>[^)]+)\))?\s*[:：\-]\s*(?<text>.*)\s*$/i
+    ];
+    for (const pattern of patterns) {
+        const match = trimmed.match(pattern);
+        if (!match?.groups?.role || match.groups.text === undefined)
+            continue;
+        const rawRole = match.groups.role.trim().toLowerCase().replace(/\s+/g, ' ');
+        const role = ROLE_ALIASES[rawRole] || ROLE_ALIASES[rawRole.replace(/\s+/g, '')];
+        if (!role)
+            continue;
+        return {
+            role,
+            rawRole,
+            text: match.groups.text.trim(),
+            timestamp: match.groups.timestamp || match.groups.timestampAlt || match.groups.timestampLead
+        };
+    }
+    return null;
+}
+export function parseLooseDateHeading(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    if (/^(?:[-*]|\d+\.)\s/.test(trimmed))
+        return null;
+    const normalizedHeading = trimmed.replace(/^#{1,6}\s+/, '').trim();
+    const direct = normalizedHeading.match(/^(?:day\s*\d+\s*[:：-]?\s*)?(?<date>\d{4}[-/.]\d{1,2}[-/.]\d{1,2})$/i);
+    if (direct?.groups?.date)
+        return direct.groups.date.replace(/[/.]/g, '-');
+    const zh = normalizedHeading.match(/^(?<year>\d{4})年(?<month>\d{1,2})月(?<day>\d{1,2})日$/);
+    if (!zh?.groups)
+        return null;
+    return [
+        zh.groups.year,
+        zh.groups.month.padStart(2, '0'),
+        zh.groups.day.padStart(2, '0')
+    ].join('-');
+}
+export function resolveTimestampWithContext(raw, fallback, currentDateHint) {
+    if (!raw) {
+        if (!currentDateHint)
+            return fallback;
+        return parseLooseTimestamp(`${currentDateHint}T00:00:00`, fallback);
+    }
+    const trimmed = raw.trim();
+    if (currentDateHint) {
+        const timeOnly = trimmed.match(/^(?<hour>\d{1,2}):(?<minute>\d{2})(?::(?<second>\d{2}))?$/);
+        if (timeOnly?.groups) {
+            const hh = timeOnly.groups.hour.padStart(2, '0');
+            const mm = timeOnly.groups.minute;
+            const ss = (timeOnly.groups.second || '00').padStart(2, '0');
+            return parseLooseTimestamp(`${currentDateHint}T${hh}:${mm}:${ss}`, fallback);
+        }
+        const monthDay = trimmed.match(/^(?<month>\d{1,2})[-/.](?<day>\d{1,2})\s+(?<hour>\d{1,2}):(?<minute>\d{2})(?::(?<second>\d{2}))?$/);
+        if (monthDay?.groups) {
+            const year = currentDateHint.slice(0, 4);
+            const month = monthDay.groups.month.padStart(2, '0');
+            const day = monthDay.groups.day.padStart(2, '0');
+            const hh = monthDay.groups.hour.padStart(2, '0');
+            const mm = monthDay.groups.minute;
+            const ss = (monthDay.groups.second || '00').padStart(2, '0');
+            return parseLooseTimestamp(`${year}-${month}-${day}T${hh}:${mm}:${ss}`, fallback);
+        }
+    }
+    return parseLooseTimestamp(trimmed, fallback);
+}
+export function buildEpisodeEnvelope(source, record) {
+    const type = record.kind === 'raw_utterance' || record.kind === 'conversation_message' ? 'chat' : 'doc';
+    const sourceRef = buildSourceRef(source, record);
+    return {
+        record,
+        ingestInput: {
+            content: record.text,
+            projectId: source.projectId,
+            filePath: source.sourcePath,
+            type,
+            createdAt: record.timestamp,
+            updatedAt: record.timestamp,
+            sourceType: record.sourceTypeHint,
+            sourceRefs: [sourceRef],
+            tags: Array.from(new Set([
+                ...(source.tags || []),
+                ...record.tags,
+                `source:${record.provenance.sourceType}`,
+                `reliability:${record.provenance.reliabilityClass}`,
+                `role:${record.role || 'narrator'}`,
+                `record:${record.kind}`
+            ]))
+        }
+    };
+}
+function buildSourceRef(source, record) {
+    const sourceOffset = numberField(record.metadata?.sourceOffset) ?? record.provenance.sourceOffset;
+    const threadSeq = numberField(record.metadata?.threadSeq) ?? sourceOffset;
+    return {
+        sourceId: record.provenance.sourceId,
+        sourcePath: record.provenance.sourcePath,
+        sourceType: record.provenance.sourceType,
+        recordId: record.recordId,
+        contentHash: record.provenance.recordHash,
+        threadId: stringField(record.metadata?.threadId) ?? stringField(source.metadata?.threadId) ?? source.sourceId,
+        sessionId: stringField(record.metadata?.sessionId) ?? stringField(source.metadata?.sessionId),
+        turnId: record.turnId,
+        role: record.role === 'agent' ? 'assistant' : record.role,
+        threadSeq,
+        turnSeq: numberField(record.metadata?.turnSeq) ?? numberField(record.metadata?.turnIndex),
+        eventOrdinal: numberField(record.metadata?.eventOrdinal),
+        sourceOffset,
+        lineStart: numberField(record.metadata?.lineStart) ?? numberField(record.metadata?.lineNumber) ?? record.provenance.lineStart,
+        lineEnd: numberField(record.metadata?.lineEnd) ?? numberField(record.metadata?.lineNumber) ?? record.provenance.lineEnd,
+        charStart: numberField(record.metadata?.charStart) ?? record.provenance.charStart,
+        charEnd: numberField(record.metadata?.charEnd) ?? record.provenance.charEnd,
+        orderingConfidence: (stringField(record.metadata?.orderingConfidence)
+            ?? record.provenance.orderingConfidence
+            ?? 'low'),
+    };
+}
+function numberField(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function stringField(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/dist/agent/AgentMemoryBackend.d.ts

@@ -0,0 +1,291 @@
+import type { MemoryKernel, MemoryKernelNavigationResult } from '../factory.js';
+import { type MemoryEventCharRange, type MemoryEventSourceRange, type SourceContextWindowMetadata } from '../recall/SourceContextMetadata.js';
+import type { BeliefRecord, MemoryEvent } from '../types/index.js';
+import type { StrategyRetrievalPolicy } from '../strategy/StrategyCapsule.js';
+import { type AgentRecallIntent, type AgentRecallQueryPlan } from './AgentRecallQueryCompiler.js';
+export type AgentTurnIngestMode = 'immediate_compile' | 'selective_compile' | 'raw_archive_only' | 'raw_then_dream';
+export type AgentTurnCompileReason = 'immediate_compile' | 'durable_signal_detected' | 'low_signal_turn' | 'raw_archive_only' | 'raw_then_dream';
+export interface AgentTurnMemory {
+    agentId: string;
+    projectId: string;
+    collection?: string;
+    workspaceId?: string;
+    sessionId: string;
+    threadId?: string;
+    turnId?: string;
+    turnSeq?: number;
+    userText: string;
+    assistantText?: string;
+    timestamp?: number;
+    ingestMode?: AgentTurnIngestMode;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentTurnMemoryResult {
+    mode: AgentTurnIngestMode;
+    reason: AgentTurnCompileReason;
+    compiled: boolean;
+    rawEventIds: string[];
+    compiledNeuronId?: string;
+}
+export interface AgentRecallQuery {
+    agentId: string;
+    projectId: string;
+    collection?: string;
+    query: string;
+    workspaceId?: string;
+    sessionId?: string;
+    threadId?: string;
+    excludeSessionId?: string;
+    intent?: AgentRecallIntent;
+    anchorEventId?: string;
+    anchorText?: string;
+    limit?: number;
+    startTime?: number;
+    endTime?: number;
+    retrievalPolicy?: StrategyRetrievalPolicy;
+}
+export interface AgentRecallSourceAnchor {
+    eventId?: string;
+    threadId?: string;
+    sessionId?: string;
+    turnId?: string;
+    role?: MemoryEvent['role'];
+    threadSeq?: number;
+    turnSeq?: number;
+    eventOrdinal?: number;
+    parentEventId?: string;
+    prevEventId?: string;
+    nextEventId?: string;
+    causalityType?: MemoryEvent['causalityType'];
+    orderingConfidence?: MemoryEvent['orderingConfidence'];
+}
+export interface AgentRecallSourceContextEvent {
+    eventId: string;
+    label: string;
+    role?: MemoryEvent['role'];
+    rawEventType?: MemoryEvent['rawEventType'];
+    eventType?: MemoryEvent['eventType'];
+    projectId?: string;
+    workspaceId?: string;
+    threadId?: string;
+    sessionId?: string;
+    turnId?: string;
+    threadSeq?: number;
+    turnSeq?: number;
+    eventOrdinal?: number;
+    occurredAt: number;
+    localDate?: string;
+    charRange?: MemoryEventCharRange;
+    sourceRange?: MemoryEventSourceRange;
+    textLength: number;
+    text: string;
+}
+export interface AgentRecallSourceContext {
+    event: AgentRecallSourceContextEvent;
+    before: AgentRecallSourceContextEvent[];
+    after: AgentRecallSourceContextEvent[];
+    parent?: AgentRecallSourceContextEvent;
+    children: AgentRecallSourceContextEvent[];
+    window: SourceContextWindowMetadata;
+    locator: {
+        eventId: string;
+        command: string;
+        threadId?: string;
+        sessionId?: string;
+        localDate?: string;
+    };
+}
+export interface AgentToolCallMemory {
+    agentId: string;
+    projectId: string;
+    workspaceId?: string;
+    sessionId: string;
+    threadId?: string;
+    turnId?: string;
+    turnSeq?: number;
+    assistantEventId?: string;
+    toolCallId?: string;
+    toolName: string;
+    input?: unknown;
+    eventOrdinal?: number;
+    timestamp?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentToolObservationMemory {
+    agentId: string;
+    projectId: string;
+    workspaceId?: string;
+    sessionId: string;
+    threadId?: string;
+    turnId?: string;
+    turnSeq?: number;
+    toolCallEventId: string;
+    toolCallId?: string;
+    toolName: string;
+    output: string;
+    eventOrdinal?: number;
+    timestamp?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentTaskEventMemory {
+    agentId: string;
+    projectId: string;
+    workspaceId?: string;
+    sessionId: string;
+    threadId?: string;
+    turnId?: string;
+    turnSeq?: number;
+    parentEventId?: string;
+    taskId?: string;
+    title?: string;
+    content: string;
+    eventOrdinal?: number;
+    timestamp?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentRecallItem {
+    id: string;
+    text: string;
+    projectId?: string;
+    topicPath?: string;
+    tags: string[];
+    source?: string;
+    sourceType?: 'compiled_memory' | 'imported_summary' | 'raw_ledger' | 'raw_ledger_session';
+    sourceAnchor?: AgentRecallSourceAnchor;
+    sourceContext?: AgentRecallSourceContext;
+    confidence?: number;
+    whyMatched?: string;
+    canAnswerExactQuote?: boolean;
+}
+export interface AgentRecallResult {
+    recallMode: MemoryKernelNavigationResult['recallMode'] | 'raw_ledger_fallback';
+    items: AgentRecallItem[];
+    narrative?: NonNullable<MemoryKernelNavigationResult['navigation']>['narrative'];
+    pulseTrace?: NonNullable<MemoryKernelNavigationResult['navigation']>['pulse']['trace'];
+    temporalTraversal?: NonNullable<MemoryKernelNavigationResult['navigation']>['branchSearch']['temporalTraversal'];
+    runtime?: NonNullable<MemoryKernelNavigationResult['navigation']>['runtime'];
+    fallbackUsed: boolean;
+    queryPlan?: AgentRecallQueryPlan;
+    /** Present on all kernel-produced results. Optional for source compatibility with external result mocks. */
+    decisionTrace?: AgentRecallDecisionTrace;
+}
+export interface AgentRecallDecisionTrace {
+    version: 'agent_recall_decision.v1';
+    selectedLane: 'graph' | 'compiled' | 'brain_fallback' | 'raw_ledger' | 'mixed' | 'none';
+    reason: 'previous_session' | 'forensic_quote' | 'graph_selected' | 'raw_cue_match_preferred' | 'compiled_cue_match' | 'brain_fallback_selected' | 'raw_ledger_only' | 'no_recall_evidence';
+    candidateCounts: {
+        graph: number;
+        navigation: number;
+        scopedNavigation: number;
+        brainFallback: number;
+        rawLedger: number;
+    };
+    selectedCount: number;
+}
+export interface AgentRecallEntityCard {
+    entityId: string;
+    canonicalName: string;
+    type: string;
+    aliases: string[];
+    attributes: Array<{
+        key: string;
+        value: string;
+        updatedAt: number;
+    }>;
+    recentMentions: Array<{
+        neuronId?: string;
+        projectId?: string;
+        mentionType: string;
+        createdAt: number;
+    }>;
+}
+export interface AgentRecallBeliefTouch {
+    beliefId: string;
+    subject: string;
+    predicate: string;
+    objectValue: string;
+    confidence: number;
+    trustScore: number;
+    status: BeliefRecord['status'];
+    supportCount: number;
+    conflictCount: number;
+    explanation?: string;
+}
+export interface AgentRecallPackSlots {
+    direct: AgentRecallItem[];
+    associative: AgentRecallItem[];
+    entityCards: AgentRecallEntityCard[];
+    beliefTouches: AgentRecallBeliefTouch[];
+}
+export interface AgentRecallPackResult extends AgentRecallResult {
+    collection?: string;
+    generatedAt: number;
+    slots: AgentRecallPackSlots;
+    chargeVector: {
+        direct: number;
+        associative: number;
+        entityCards: number;
+        beliefTouches: number;
+        activationHotspots: number;
+    };
+}
+export declare class KernelAgentMemoryBackend {
+    private readonly kernel;
+    constructor(kernel: MemoryKernel);
+    rememberTurn(turn: AgentTurnMemory): Promise<void>;
+    rememberTurnWithResult(turn: AgentTurnMemory): Promise<AgentTurnMemoryResult>;
+    ingestToolCall(call: AgentToolCallMemory): Promise<MemoryEvent>;
+    ingestToolObservation(observation: AgentToolObservationMemory): Promise<MemoryEvent>;
+    ingestTaskEvent(task: AgentTaskEventMemory): Promise<MemoryEvent>;
+    private tryAppendAuxiliaryEvent;
+    recall(query: AgentRecallQuery): AgentRecallResult;
+    recallPack(query: AgentRecallQuery): AgentRecallPackResult;
+    private recallPreviousSession;
+    private recallForensicQuote;
+    private recallForensicAnchor;
+    private searchRawEventsByQueryPlan;
+    private rawLedgerFallbackItemsForQuery;
+    private memoryBindingGraphItemsForQuery;
+    private graphRecallTextScore;
+    private shouldPreferRawLedgerFallback;
+    private itemsContainRecallCue;
+    private recallCueTerms;
+    private itemSearchableText;
+    private mergeRecallItems;
+    private dedupeRawEventsByTurnPreferUser;
+    private expandRawSearchTexts;
+    private findPreviousSessionId;
+    private getSessionEvents;
+    private dedupeRawEventsByTurnPreferCue;
+    private rawEventCueScore;
+    private rawEventTextLength;
+    private rawEventText;
+    private filterAgentEvidence;
+    private toAgentRecallItem;
+    private isAgentRawEvent;
+    private isOperationalNoiseRawEvent;
+    private isAllowedSession;
+    private hasReadableEventText;
+    private quoteEventPriority;
+    private isQuoteSourceEvent;
+    private toAgentRawRecallItem;
+    private preferredRawSourceEventId;
+    private toAgentSourceContext;
+    private toAgentSourceContextEvent;
+    private toAgentSourceAnchorFromContextEvent;
+    private toAgentSourceAnchor;
+    private toSourceRef;
+    private eventText;
+    private buildAssociativeItems;
+    private buildEntityCards;
+    private buildBeliefTouches;
+    private entityLookupCandidates;
+    private metadataWithCollection;
+    private collectionTags;
+    private normalizeCollection;
+    private isAllowedRawEventCollection;
+    private isAllowedCollectionTags;
+    private shouldCompileTurn;
+    private hasDurableTurnSignal;
+}
+//# sourceMappingURL=AgentMemoryBackend.d.ts.map