cogmem 3.6.2

package/dist/prospective/ProspectiveMemoryService.js

@@ -0,0 +1,258 @@
+import { randomUUID } from 'node:crypto';
+const PROSPECTIVE_MEMORY_TYPES = ['intention', 'commitment', 'reminder', 'open_loop', 'plan'];
+const PROSPECTIVE_MEMORY_STATUSES = ['pending', 'confirmed', 'deferred', 'rejected', 'completed', 'expired'];
+const PROSPECTIVE_MEMORY_PROPOSERS = ['deterministic', 'model_candidate', 'operator'];
+const TERMINAL_PROSPECTIVE_MEMORY_STATUSES = ['rejected', 'completed', 'expired'];
+export class ProspectiveMemoryService {
+    db;
+    findEvidence;
+    constructor(db, findEvidence) {
+        this.db = db;
+        this.findEvidence = findEvidence;
+        this.initializeSchema();
+    }
+    propose(input) {
+        return this.db.transaction(() => this.proposeInTransaction(input)).immediate();
+    }
+    proposeInTransaction(input) {
+        const projectId = requireProjectId(input.projectId);
+        if (!PROSPECTIVE_MEMORY_TYPES.includes(input.candidateType))
+            throw new Error('invalid_prospective_memory_type');
+        if (!PROSPECTIVE_MEMORY_PROPOSERS.includes(input.proposedBy))
+            throw new Error('invalid_prospective_memory_proposer');
+        const canonicalKey = input.canonicalKey.trim().toLowerCase();
+        const title = input.title.trim();
+        if (!canonicalKey || !title)
+            throw new Error('prospective_key_and_title_required');
+        if (input.dueAt !== undefined && (!Number.isFinite(input.dueAt) || input.dueAt < 0))
+            throw new Error('invalid_due_at');
+        if (input.evidenceEventIds.length === 0)
+            throw new Error('missing_evidence');
+        const evidence = input.evidenceEventIds.map((eventId) => this.findEvidence(eventId));
+        if (evidence.some((item) => !item))
+            throw new Error('unknown_evidence');
+        if (evidence.some((item) => item?.projectId !== projectId))
+            throw new Error('project_boundary_violation');
+        const evidenceIds = [...new Set(input.evidenceEventIds)].sort();
+        const latest = this.getLatest(projectId, canonicalKey);
+        if (latest && JSON.stringify([...latest.evidenceEventIds].sort()) === JSON.stringify(evidenceIds))
+            return latest;
+        const now = Date.now();
+        const candidateId = `prospective-${randomUUID()}`;
+        const version = (latest?.version ?? 0) + 1;
+        this.db.prepare(`
+      INSERT INTO prospective_memories (
+        candidate_id, project_id, candidate_type, canonical_key, title, details, status,
+        proposed_by, evidence_event_ids_json, confirmation_evidence_event_id, due_at,
+        deferred_until, version, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, 'pending', ?, ?, NULL, ?, NULL, ?, ?, ?)
+    `).run(candidateId, projectId, input.candidateType, canonicalKey, title, input.details ?? null, input.proposedBy, JSON.stringify(evidenceIds), input.dueAt ?? null, version, now, now);
+        this.recordTransition(candidateId, undefined, 'pending', 'proposed', input.evidenceEventIds[0], now);
+        return this.get(candidateId, projectId);
+    }
+    resolve(candidateId, input, projectId) {
+        return this.db.transaction(() => this.resolveInTransaction(candidateId, input, projectId)).immediate();
+    }
+    resolveInTransaction(candidateId, input, projectId) {
+        projectId = requireProjectId(projectId);
+        const current = this.getUnscoped(candidateId);
+        if (!current)
+            throw new Error('prospective_memory_not_found');
+        if (current.projectId !== projectId)
+            throw new Error('project_boundary_violation');
+        if (TERMINAL_PROSPECTIVE_MEMORY_STATUSES.includes(current.status)) {
+            throw new Error('terminal_prospective_memory_cannot_transition');
+        }
+        const now = Date.now();
+        let status;
+        let confirmationEvidenceEventId = current.confirmationEvidenceEventId;
+        let deferredUntil = current.deferredUntil;
+        switch (input.action) {
+            case 'confirm': {
+                if (current.status === 'confirmed')
+                    return current;
+                const evidence = this.findEvidence(input.confirmationEvidenceEventId);
+                if (!evidence)
+                    throw new Error('unknown_confirmation_evidence');
+                if (evidence.projectId !== current.projectId)
+                    throw new Error('project_boundary_violation');
+                if (evidence.role !== 'user')
+                    throw new Error('confirmation_requires_user_evidence');
+                if (current.evidenceEventIds.includes(input.confirmationEvidenceEventId)) {
+                    throw new Error('confirmation_requires_distinct_user_evidence');
+                }
+                const proposalEvidence = current.evidenceEventIds.map((eventId) => this.findEvidence(eventId));
+                const proposalSequences = proposalEvidence.map((item) => item?.globalSeq).filter((value) => Number.isFinite(value));
+                if (evidence.globalSeq === undefined || proposalSequences.length !== current.evidenceEventIds.length
+                    || evidence.globalSeq <= Math.max(...proposalSequences)) {
+                    throw new Error('confirmation_must_follow_proposal_evidence');
+                }
+                if (!isExplicitProspectiveConfirmation(evidence.content)) {
+                    throw new Error('confirmation_requires_explicit_affirmation');
+                }
+                const priorUse = this.db.prepare(`
+          SELECT candidate_id FROM prospective_memories
+          WHERE project_id = ? AND confirmation_evidence_event_id = ? AND candidate_id <> ?
+          LIMIT 1
+        `).get(current.projectId, input.confirmationEvidenceEventId, candidateId);
+                if (priorUse)
+                    throw new Error('confirmation_evidence_already_used');
+                status = 'confirmed';
+                confirmationEvidenceEventId = input.confirmationEvidenceEventId;
+                deferredUntil = undefined;
+                break;
+            }
+            case 'reject':
+                status = 'rejected';
+                break;
+            case 'defer':
+                if (current.status !== 'confirmed')
+                    throw new Error('only_confirmed_memory_can_be_deferred');
+                if (!Number.isFinite(input.deferredUntil) || input.deferredUntil <= now)
+                    throw new Error('invalid_deferred_until');
+                status = 'deferred';
+                deferredUntil = input.deferredUntil;
+                break;
+            case 'complete':
+                if (current.status !== 'confirmed')
+                    throw new Error('only_confirmed_memory_can_be_completed');
+                status = 'completed';
+                break;
+            case 'expire':
+                status = 'expired';
+                break;
+        }
+        this.db.prepare(`
+      UPDATE prospective_memories
+      SET status = ?, confirmation_evidence_event_id = ?, deferred_until = ?, updated_at = ?
+      WHERE candidate_id = ?
+    `).run(status, confirmationEvidenceEventId ?? null, deferredUntil ?? null, now, candidateId);
+        this.recordTransition(candidateId, current.status, status, input.action, confirmationEvidenceEventId, now);
+        return this.get(candidateId, projectId);
+    }
+    get(candidateId, projectId) {
+        projectId = requireProjectId(projectId);
+        const row = this.db.prepare(`
+      SELECT * FROM prospective_memories WHERE candidate_id = ? AND project_id = ?
+    `).get(candidateId, projectId);
+        return row ? this.mapRow(row) : null;
+    }
+    list(options) {
+        const projectId = requireProjectId(options.projectId);
+        const statuses = options.statuses ?? ['pending', 'confirmed', 'deferred'];
+        if (statuses.length === 0)
+            return [];
+        if (statuses.some((status) => !PROSPECTIVE_MEMORY_STATUSES.includes(status))) {
+            throw new Error('invalid_prospective_memory_status');
+        }
+        const rows = this.db.prepare(`
+      SELECT * FROM prospective_memories
+      WHERE project_id = ? AND status IN (${statuses.map(() => '?').join(', ')})
+      ORDER BY COALESCE(deferred_until, due_at, updated_at) ASC, updated_at DESC
+      LIMIT ?
+    `).all(projectId, ...statuses, boundedLimit(options.limit, 100, 500));
+        return rows.map((row) => this.mapRow(row));
+    }
+    listDue(input) {
+        const projectId = requireProjectId(input.projectId);
+        const atTime = input.atTime ?? Date.now();
+        if (!Number.isFinite(atTime) || atTime < 0)
+            throw new Error('invalid_at_time');
+        const rows = this.db.prepare(`
+      SELECT * FROM prospective_memories
+      WHERE project_id = ? AND (
+        (status = 'confirmed' AND due_at IS NOT NULL AND due_at <= ?)
+        OR (status = 'deferred' AND deferred_until IS NOT NULL AND deferred_until <= ?)
+      )
+      ORDER BY COALESCE(deferred_until, due_at) ASC, updated_at ASC LIMIT ?
+    `).all(projectId, atTime, atTime, boundedLimit(input.limit, 20, 100));
+        return rows.map((row) => this.mapRow(row));
+    }
+    getLatest(projectId, canonicalKey) {
+        const row = this.db.prepare(`
+      SELECT * FROM prospective_memories WHERE project_id = ? AND canonical_key = ?
+      ORDER BY version DESC LIMIT 1
+    `).get(projectId, canonicalKey);
+        return row ? this.mapRow(row) : null;
+    }
+    getUnscoped(candidateId) {
+        const row = this.db.prepare(`SELECT * FROM prospective_memories WHERE candidate_id = ?`)
+            .get(candidateId);
+        return row ? this.mapRow(row) : null;
+    }
+    recordTransition(candidateId, from, to, action, eventId, now) {
+        this.db.prepare(`
+      INSERT INTO prospective_memory_transitions (
+        transition_id, candidate_id, from_status, to_status, action, evidence_event_id, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(`transition-${randomUUID()}`, candidateId, from ?? null, to, action, eventId ?? null, now);
+    }
+    mapRow(row) {
+        return {
+            candidateId: String(row.candidate_id),
+            projectId: String(row.project_id),
+            candidateType: row.candidate_type,
+            canonicalKey: String(row.canonical_key),
+            title: String(row.title),
+            details: row.details == null ? undefined : String(row.details),
+            status: row.status,
+            proposedBy: row.proposed_by,
+            evidenceEventIds: JSON.parse(String(row.evidence_event_ids_json)),
+            confirmationEvidenceEventId: row.confirmation_evidence_event_id == null ? undefined : String(row.confirmation_evidence_event_id),
+            dueAt: row.due_at == null ? undefined : Number(row.due_at),
+            deferredUntil: row.deferred_until == null ? undefined : Number(row.deferred_until),
+            version: Number(row.version),
+            createdAt: Number(row.created_at),
+            updatedAt: Number(row.updated_at),
+        };
+    }
+    initializeSchema() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS prospective_memories (
+        candidate_id TEXT PRIMARY KEY, project_id TEXT NOT NULL, candidate_type TEXT NOT NULL,
+        canonical_key TEXT NOT NULL, title TEXT NOT NULL, details TEXT, status TEXT NOT NULL,
+        proposed_by TEXT NOT NULL, evidence_event_ids_json TEXT NOT NULL,
+        confirmation_evidence_event_id TEXT, due_at INTEGER, deferred_until INTEGER,
+        version INTEGER NOT NULL DEFAULT 1, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_prospective_project_status_due
+        ON prospective_memories(project_id, status, due_at, updated_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_prospective_project_status_deferred
+        ON prospective_memories(project_id, status, deferred_until, updated_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_prospective_project_key_version
+        ON prospective_memories(project_id, canonical_key, version DESC);
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_prospective_project_key_version_unique
+        ON prospective_memories(project_id, canonical_key, version);
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_prospective_confirmation_evidence_unique
+        ON prospective_memories(project_id, confirmation_evidence_event_id)
+        WHERE confirmation_evidence_event_id IS NOT NULL;
+      CREATE TABLE IF NOT EXISTS prospective_memory_transitions (
+        transition_id TEXT PRIMARY KEY, candidate_id TEXT NOT NULL, from_status TEXT,
+        to_status TEXT NOT NULL, action TEXT NOT NULL, evidence_event_id TEXT, created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_prospective_transitions_candidate
+        ON prospective_memory_transitions(candidate_id, created_at DESC);
+    `);
+    }
+}
+function isExplicitProspectiveConfirmation(content) {
+    const text = content?.trim();
+    if (!text)
+        return false;
+    if (/\b(?:no|not|don['’]?t|cancel|reject|deny|decline|abort)\b|(?:不要|不确认|取消|拒绝|否认|いいえ|キャンセル|拒否)/iu.test(text)) {
+        return false;
+    }
+    return /\b(?:yes|confirm|approve|authorize|proceed)\b|(?:确认|同意|批准|没错|是的|はい|確認|承認)/iu.test(text);
+}
+function requireProjectId(projectId) {
+    const normalized = projectId.trim();
+    if (!normalized)
+        throw new Error('project_id_required');
+    return normalized;
+}
+function boundedLimit(value, fallback, maximum) {
+    const limit = value ?? fallback;
+    if (!Number.isInteger(limit) || limit <= 0)
+        throw new Error('invalid_limit');
+    return Math.min(maximum, limit);
+}

package/dist/prospective/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ProspectiveMemoryService.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/prospective/index.js

@@ -0,0 +1 @@
+export * from './ProspectiveMemoryService.js';

package/dist/public.d.ts

@@ -0,0 +1,160 @@
+/**
+ * cogmem — public API surface for v2.0+
+ *
+ * Stability tiers (see SEMVER.md for full policy):
+ *   @stable      — covered by SemVer; no breaking changes within a major
+ *   @beta        — available for integration; may change before next stable minor
+ *   @experimental — no stability promise; can change or be removed at any time
+ *
+ * Only explicitly listed symbols are part of the public entrypoint. Internal
+ * implementation modules stay importable inside the source tree, but are not
+ * exported for third-party packages.
+ */
+/**
+ * Primary entry point and kernel lifecycle.
+ * @stable @since 1.0.0
+ */
+export { MemoryKernel, createMemoryKernel, createMemoryKernelFromConfig, } from './factory.js';
+export type { ForgetUserResult, GovernanceAuditRecord, DreamCandidateListOptions, DreamCandidateRecord, DreamCandidateStatus, DreamCuratorRunOptions, DreamCuratorRunResult, DreamTickOptions, DreamTickResult, EpisodeClosureReceipt, EpisodeDreamStatus, EpisodeListOptions, EpisodeMessageInput, EpisodeMessageResult, EpisodeRepairInput, EpisodeRepairResult, MemoryEpisode, MaintenanceSuggestedAction, MaintenanceTickOptions, MaintenanceTickResult, MemoryDataLane, MemoryBindingBackfillOptions, MemoryBindingBackfillResult, MemoryKernelFromConfigOptions, MemoryKernelNavigationOptions, MemoryKernelNavigationResult, MemoryKernelOptions, MemoryMapOptions, MemoryMapSection, MemorySelfMap, RawEventSearchOptions, RawMemoryEventInput, TaskMemoryEventInput, ToolCallMemoryEventInput, ToolResultMemoryEventInput, } from './factory.js';
+export { EpisodeAssembler, EpisodeStore, classifyAssistantRelation, classifyTurnRelation, classifyTurnRelationHybrid, createStableImportIdentityFactory, summarizeEpisode, type EpisodeCandidateType, type EpisodeClosureMode, type EpisodeClosureReasonCode, type EpisodeDreamState, type EpisodeDreamStatusValue, type EpisodeEventLink, type EpisodeSemanticSummary, type EpisodeStatus, type EpisodeType, type StableImportIdentityInput, type TurnClassificationContext, type TurnRelation, type TurnRelationAdvisoryReviewer, type TurnRelationDecision, } from './episode/index.js';
+export { DreamScheduler, type DreamTickMode, type SelectedDreamMode } from './dream/index.js';
+export { MEMORY_ONTOLOGY_CLASSES, isMemoryOntologyClass, type MemoryOntologyClass } from './ontology/MemoryOntology.js';
+export { TopicAliasRegistry, TopicGovernance, TopicPathRegistry as UserTopicPathRegistry, TopicRelationGraph, type TopicAliasRecord, type TopicCreatedBy, type TopicNode, type TopicOperationInput, type TopicOperationRecord, type TopicOperationType, type TopicRelationRecord, type TopicStatus, } from './topic/index.js';
+/**
+ * Cogmem runtime home and structured configuration helpers.
+ * @stable @since 2.0.0
+ */
+export { defaultCogmemConfigPath, defaultCogmemHome, loadCogmemConfig, resolveCogmemConfigPath, } from './config/CogmemConfig.js';
+export type { CogmemConfigResolution, CogmemConfigResolutionOptions, LoadedCogmemConfig, LoadCogmemConfigOptions, } from './config/CogmemConfig.js';
+export type { MemoryBindingListOptions, MemoryBindingRecord, MemoryBindingSource, MemoryBindingStats, MemoryBindingType, MemoryBindingAction, MemoryClusterListOptions, MemoryClusterRecord, MemoryClusterStatus, MemoryEdgeListOptions, MemoryEdgeRecord, MemoryEdgeRelation, MemoryEntityRecord, MemoryEntityType, MemoryGraphRecallAnchor, MemoryTopicRecord, } from './binding/index.js';
+export { BeliefGovernanceService, type ApplyBeliefInput, type BeliefEvidenceLookup, type BeliefEvidenceRecord, type BeliefOwnership, type BeliefRelation, type GovernedBeliefRecord, type GovernedBeliefStatus, type GovernedBeliefType, } from './belief/BeliefGovernanceService.js';
+export { TemporalMemoryService, type RecordTimelineEntryInput, type TemporalBeliefRecord, type TimelineEntryRecord, type TimelineEntryType, type TimelineListOptions, } from './temporal/index.js';
+export { ContextCortex, type ContextActivationPlan, type ContextActivationReceipt, type ContextCandidate, type ContextIntent, type ContextLayer, type ContextPlanInput, type ContextSuppressionReason, } from './context/index.js';
+export { ProspectiveMemoryService, type ProposeProspectiveMemoryInput, type ProspectiveEvidenceLookup, type ProspectiveEvidenceRecord, type ProspectiveMemoryListOptions, type ProspectiveMemoryProposer, type ProspectiveMemoryRecord, type ProspectiveMemoryStatus, type ProspectiveMemoryType, type ResolveProspectiveMemoryInput, } from './prospective/index.js';
+export { BrainEvalRunner, type BrainEvalMetrics, type BrainEvalReport, type BrainEvalSample, } from './benchmark/BrainEval.js';
+export { StrategyConditionedCandidateBuilder, StrategyCortex, StrategyTemplateRegistry, formatStrategyContext, type RetrievalLane, type StrategyCapsule, type StrategyPlanInput, type StrategyReplanDecision, type StrategyReplanObservation, type StrategyReplanReason, type StrategyRetrievalPolicy, type StrategySourcePolicy, type StrategyTemplate, type StrategyTemplateId, } from './strategy/index.js';
+export { ContextOutcomeStore, ContextPolicyScorer, MemoryUseJudge, StrategyDiversitySelector, StrategyRolloutEvaluator, type ContextPolicyScore, type JudgedMemorySelection, type MemoryUseJudgeInput, type MemoryUseViolation, type StrategyRolloutOutcome, type StrategyRolloutReport, type StrategyVectorCandidate, } from './eval/strategy/index.js';
+/**
+ * Agent framework integration facade.
+ * @stable @since 2.0.0
+ */
+export { compileAgentRecallQuery, COGMEM_RECALL_BLOCK_RE, createMemoryUsageReceipt, formatMemoryUsageBridge, formatSessionWorkingState, inferAgentRecallIntent, KernelAgentMemoryBackend, shouldInjectMemoryUsageBridge, stripCogmemRecallBlocks, updateSessionWorkingState, type AgentRecallBeliefTouch, type AgentRecallEntityCard, type AgentRecallIntent, type AgentRecallItem, type AgentRecallPackResult, type AgentRecallPackSlots, type AgentRecallQuery, type AgentRecallQueryPlan, type AgentRecallResult, type AgentRecallSourceAnchor, type AgentRecallSourceContext, type AgentRecallSourceContextEvent, type AgentTaskEventMemory, type AgentToolCallMemory, type AgentToolObservationMemory, type AgentTurnCompileReason, type AgentTurnIngestMode, type AgentTurnMemory, type AgentTurnMemoryResult, type CreateMemoryUsageReceiptInput, type MemoryUsageReceipt, type MemoryUsageReceiptSourceAnchor, type SessionWorkingState, type StripCogmemRecallBlocksResult, type UpdateSessionWorkingStateInput, } from './agent/index.js';
+/**
+ * Core recall pipeline.
+ * @stable @since 1.0.0
+ */
+export { BrainRecall } from './recall/BrainRecall.js';
+export type { BrainRecallOptions } from './recall/BrainRecall.js';
+export type { BrainRecallResult } from './types/BrainRecallResult.js';
+/**
+ * Neuron types — the fundamental memory unit.
+ * @stable @since 1.0.0
+ */
+export type { MemoryEvent, MemoryEventContext, MemoryEventCausalityType, MemoryRawEventType, MemoryEventRole, MemorySourceRef, Neuron, NeuronType, OrderingConfidence, } from './types/index.js';
+export type { ImportanceLevel } from './core/ImportanceLevels.js';
+/**
+ * Extension point interfaces for host runtimes and third-party adapters.
+ * @stable @since 1.9.6
+ */
+export type { AutonomyContext, IAuditLedger, ILLMClarifier, IProceduralBridge, ISkillDiscovery, ISkillMemoryStore, SkillCandidateLike, } from './types/ExtensionPoints.js';
+/**
+ * Cross-device snapshot: export / import / error types.
+ * @stable @since 1.9.7
+ */
+export { ChecksumError, DimensionMismatchError, KernelRunningError, SnapshotExporter, SnapshotImporter, SnapshotTargetExistsError, SnapshotVersionError, } from './snapshot/index.js';
+export type { ImportOptions, ImportResult, SnapshotHeader, SnapshotMeta } from './snapshot/index.js';
+/**
+ * Security: AES-256-GCM encryption provider and PII redaction.
+ * @stable @since 1.14.0
+ */
+export { AesGcmEncryptionProvider, isEncryptedPayload } from './encryption/index.js';
+export type { EncryptionProvider } from './encryption/index.js';
+export { MemoryGovernanceExecutor, MemoryGovernanceStore, MemoryGovernanceValidator, PiiRedactor, } from './governance/index.js';
+export type { MemoryEvidenceRole, MemoryGovernanceAuditEntry, MemoryGovernanceExecutionResult, MemoryGovernanceIssue, MemoryGovernanceOperation, MemoryGovernanceOperationType, MemoryGovernancePlan, MemoryGovernanceValidationResult, MemoryOwnership, PiiFinding, RedactionPolicy, RedactionResult, } from './governance/index.js';
+/**
+ * Embedding provider interface and utilities.
+ * @beta @since 1.9.5
+ */
+export type { EmbeddingProvider } from './embedding/EmbeddingProvider.js';
+export { EmbeddingUnavailableError, embedOne } from './embedding/EmbeddingProvider.js';
+/**
+ * Re-embedding status for observability.
+ * @beta @since 1.9.8
+ */
+export type { ReEmbeddingStatus } from './embedding/ReEmbeddingStatus.js';
+/**
+ * Dream curator scheduling helpers. They describe host-owned schedules; core
+ * never starts a hidden daemon.
+ * @beta @since 2.0.0
+ */
+export { describeDreamCuratorWorkflow, nextDreamCuratorRunAt, } from './engine/DreamCuratorSchedule.js';
+export type { DreamCuratorScheduleConfig, DreamCuratorScheduleMode, DreamCuratorWorkflowDescription, } from './engine/DreamCuratorSchedule.js';
+export { ReEmbeddingPipeline } from './embedding/ReEmbeddingPipeline.js';
+export { EntityGovernanceService } from './entity/index.js';
+export type { EntityMergeCandidate, EntityMergeCandidateStatus, ProposeEntityMergeInput } from './entity/index.js';
+/**
+ * Vector store backends — choose between durable sqlite-vec (recommended)
+ * and the legacy in-process hnswlib backend.
+ * @beta @since 1.12.0
+ */
+export { SqliteVecStore } from './store/SqliteVecStore.js';
+export { HnswlibVectorStore } from './store/HnswlibVectorStore.js';
+export { ActivationStore } from './store/ActivationStore.js';
+export { MemoryBindingStore } from './store/MemoryBindingStore.js';
+/** @deprecated Use HnswlibVectorStore. Will be removed in v3.0. */
+export { VectorStore } from './store/VectorStore.js';
+export type { ActivationDecayOptions, ActivationDecayResult, ActivationHotspot, ActivationTouchInput } from './store/ActivationStore.js';
+export type { UpsertMemoryEntityInput, UpsertMemoryTopicInput } from './store/MemoryBindingStore.js';
+export type { IVectorStore, VectorBackend, VectorSearchResult, VectorStoreStats } from './store/IVectorStore.js';
+/**
+ * Offline consolidation — advanced use only.
+ * @beta @since 1.9.0
+ */
+export { OfflineConsolidationPipeline } from './engine/OfflineConsolidationPipeline.js';
+/**
+ * MemoryGraph — low-level neuron graph. Prefer MemoryKernel for most use cases.
+ * @beta @since 1.0.0
+ */
+export { MemoryGraph } from './core/MemoryGraph.js';
+/**
+ * Source adapters and first-party external-agent profiles.
+ * @beta @since 2.0.0
+ */
+export { ConversationMarkdownAdapter, HermesWorkspaceProfile, MarkdownSourceLoader, OpenClawDailyMemoryAdapter, OpenClawMemoryIndexAdapter, OpenClawPersonaAdapter, OpenClawSessionAdapter, OpenClawUserProfileAdapter, OpenClawWorkspaceProfile, SoulMarkdownAdapter, } from './adapters/index.js';
+export type { AdaptedSource, HermesWorkspaceSourceOptions, OpenClawClassifiedPath, OpenClawWorkspaceSelection, OpenClawWorkspaceSelectionDiagnostic, OpenClawWorkspaceSourceOptions, SourceAdapter, SourceAdapterDiagnostic, SourceAdapterKind, SourceAdapterRecord, SourceDefinition, } from './adapters/index.js';
+/**
+ * Pulse/universe recall orchestration. Agent backends use this by default;
+ * advanced integrations can inspect or compose these pieces directly.
+ * @beta @since 2.0.0
+ */
+export { QueryCompiler } from './retrieval/QueryCompiler.js';
+export type { CompiledQuery } from './retrieval/QueryCompiler.js';
+export { RetrievalPlanner } from './retrieval/RetrievalPlanner.js';
+export type { RetrievalExecutionPlan, RetrievalIntent } from './retrieval/RetrievalPlanner.js';
+export { TemporalBranchSearch } from './retrieval/TemporalBranchSearch.js';
+export type { TemporalBranchSearchResult, TemporalTraversalSegment } from './retrieval/TemporalBranchSearch.js';
+export { PulseRetrievalEngine } from './retrieval/PulseRetrievalEngine.js';
+export type { PulseRetrievalResult } from './retrieval/PulseRetrievalEngine.js';
+export { NarrativeRecallAssembler } from './retrieval/NarrativeRecallAssembler.js';
+export type { NarrativeRecallSummary } from './retrieval/NarrativeRecallAssembler.js';
+export { UniverseNavigator } from './retrieval/UniverseNavigator.js';
+export type { UniverseNavigationResult } from './retrieval/UniverseNavigator.js';
+export { UniverseTraversalExecutor } from './retrieval/UniverseTraversalExecutor.js';
+export type { UniverseTraversalExecution, UniverseTraversalSegment } from './retrieval/UniverseTraversalExecutor.js';
+/**
+ * Recall explainability and MCP bridge helpers.
+ * @beta @since 2.0.0
+ */
+export { explainRecallWithKernel } from './recall/RecallExplanation.js';
+export type { RecallExplanation, RecallExplanationEvidence, RecallExplanationOptions, RecallExplanationSourceAnchor, } from './recall/RecallExplanation.js';
+export { callCogmemMcpTool, listCogmemMcpTools } from './mcp/CoreMcpTools.js';
+export type { CogmemMcpCallResult, CogmemMcpRuntime, CogmemMcpTool } from './mcp/CoreMcpTools.js';
+export type { DreamBacklogStatus } from './store/DreamLedgerStore.js';
+export * from './atlas/index.js';
+/**
+ * Chinese-language lexicons for entity hints, stopwords, and topic classification.
+ * @experimental @since 1.13.0
+ */
+export { ZH_ENTITY_HINTS, ZH_STOPWORDS, ZH_TOPIC_LEXICON } from './lexicon/zh/index.js';
+export type { ChineseTopicLexiconEntry } from './lexicon/zh/index.js';
+//# sourceMappingURL=public.d.ts.map

package/dist/public.js

@@ -0,0 +1,115 @@
+/**
+ * cogmem — public API surface for v2.0+
+ *
+ * Stability tiers (see SEMVER.md for full policy):
+ *   @stable      — covered by SemVer; no breaking changes within a major
+ *   @beta        — available for integration; may change before next stable minor
+ *   @experimental — no stability promise; can change or be removed at any time
+ *
+ * Only explicitly listed symbols are part of the public entrypoint. Internal
+ * implementation modules stay importable inside the source tree, but are not
+ * exported for third-party packages.
+ */
+// ─── @stable ─────────────────────────────────────────────────────────────────
+/**
+ * Primary entry point and kernel lifecycle.
+ * @stable @since 1.0.0
+ */
+export { MemoryKernel, createMemoryKernel, createMemoryKernelFromConfig, } from './factory.js';
+export { EpisodeAssembler, EpisodeStore, classifyAssistantRelation, classifyTurnRelation, classifyTurnRelationHybrid, createStableImportIdentityFactory, summarizeEpisode, } from './episode/index.js';
+export { DreamScheduler } from './dream/index.js';
+export { MEMORY_ONTOLOGY_CLASSES, isMemoryOntologyClass } from './ontology/MemoryOntology.js';
+export { TopicAliasRegistry, TopicGovernance, TopicPathRegistry as UserTopicPathRegistry, TopicRelationGraph, } from './topic/index.js';
+/**
+ * Cogmem runtime home and structured configuration helpers.
+ * @stable @since 2.0.0
+ */
+export { defaultCogmemConfigPath, defaultCogmemHome, loadCogmemConfig, resolveCogmemConfigPath, } from './config/CogmemConfig.js';
+export { BeliefGovernanceService, } from './belief/BeliefGovernanceService.js';
+export { TemporalMemoryService, } from './temporal/index.js';
+export { ContextCortex, } from './context/index.js';
+export { ProspectiveMemoryService, } from './prospective/index.js';
+export { BrainEvalRunner, } from './benchmark/BrainEval.js';
+export { StrategyConditionedCandidateBuilder, StrategyCortex, StrategyTemplateRegistry, formatStrategyContext, } from './strategy/index.js';
+export { ContextOutcomeStore, ContextPolicyScorer, MemoryUseJudge, StrategyDiversitySelector, StrategyRolloutEvaluator, } from './eval/strategy/index.js';
+/**
+ * Agent framework integration facade.
+ * @stable @since 2.0.0
+ */
+export { compileAgentRecallQuery, COGMEM_RECALL_BLOCK_RE, createMemoryUsageReceipt, formatMemoryUsageBridge, formatSessionWorkingState, inferAgentRecallIntent, KernelAgentMemoryBackend, shouldInjectMemoryUsageBridge, stripCogmemRecallBlocks, updateSessionWorkingState, } from './agent/index.js';
+/**
+ * Core recall pipeline.
+ * @stable @since 1.0.0
+ */
+export { BrainRecall } from './recall/BrainRecall.js';
+/**
+ * Cross-device snapshot: export / import / error types.
+ * @stable @since 1.9.7
+ */
+export { ChecksumError, DimensionMismatchError, KernelRunningError, SnapshotExporter, SnapshotImporter, SnapshotTargetExistsError, SnapshotVersionError, } from './snapshot/index.js';
+/**
+ * Security: AES-256-GCM encryption provider and PII redaction.
+ * @stable @since 1.14.0
+ */
+export { AesGcmEncryptionProvider, isEncryptedPayload } from './encryption/index.js';
+export { MemoryGovernanceExecutor, MemoryGovernanceStore, MemoryGovernanceValidator, PiiRedactor, } from './governance/index.js';
+export { EmbeddingUnavailableError, embedOne } from './embedding/EmbeddingProvider.js';
+/**
+ * Dream curator scheduling helpers. They describe host-owned schedules; core
+ * never starts a hidden daemon.
+ * @beta @since 2.0.0
+ */
+export { describeDreamCuratorWorkflow, nextDreamCuratorRunAt, } from './engine/DreamCuratorSchedule.js';
+export { ReEmbeddingPipeline } from './embedding/ReEmbeddingPipeline.js';
+export { EntityGovernanceService } from './entity/index.js';
+/**
+ * Vector store backends — choose between durable sqlite-vec (recommended)
+ * and the legacy in-process hnswlib backend.
+ * @beta @since 1.12.0
+ */
+export { SqliteVecStore } from './store/SqliteVecStore.js';
+export { HnswlibVectorStore } from './store/HnswlibVectorStore.js';
+export { ActivationStore } from './store/ActivationStore.js';
+export { MemoryBindingStore } from './store/MemoryBindingStore.js';
+/** @deprecated Use HnswlibVectorStore. Will be removed in v3.0. */
+export { VectorStore } from './store/VectorStore.js';
+/**
+ * Offline consolidation — advanced use only.
+ * @beta @since 1.9.0
+ */
+export { OfflineConsolidationPipeline } from './engine/OfflineConsolidationPipeline.js';
+/**
+ * MemoryGraph — low-level neuron graph. Prefer MemoryKernel for most use cases.
+ * @beta @since 1.0.0
+ */
+export { MemoryGraph } from './core/MemoryGraph.js';
+/**
+ * Source adapters and first-party external-agent profiles.
+ * @beta @since 2.0.0
+ */
+export { ConversationMarkdownAdapter, HermesWorkspaceProfile, MarkdownSourceLoader, OpenClawDailyMemoryAdapter, OpenClawMemoryIndexAdapter, OpenClawPersonaAdapter, OpenClawSessionAdapter, OpenClawUserProfileAdapter, OpenClawWorkspaceProfile, SoulMarkdownAdapter, } from './adapters/index.js';
+/**
+ * Pulse/universe recall orchestration. Agent backends use this by default;
+ * advanced integrations can inspect or compose these pieces directly.
+ * @beta @since 2.0.0
+ */
+export { QueryCompiler } from './retrieval/QueryCompiler.js';
+export { RetrievalPlanner } from './retrieval/RetrievalPlanner.js';
+export { TemporalBranchSearch } from './retrieval/TemporalBranchSearch.js';
+export { PulseRetrievalEngine } from './retrieval/PulseRetrievalEngine.js';
+export { NarrativeRecallAssembler } from './retrieval/NarrativeRecallAssembler.js';
+export { UniverseNavigator } from './retrieval/UniverseNavigator.js';
+export { UniverseTraversalExecutor } from './retrieval/UniverseTraversalExecutor.js';
+/**
+ * Recall explainability and MCP bridge helpers.
+ * @beta @since 2.0.0
+ */
+export { explainRecallWithKernel } from './recall/RecallExplanation.js';
+export { callCogmemMcpTool, listCogmemMcpTools } from './mcp/CoreMcpTools.js';
+export * from './atlas/index.js';
+// ─── @experimental ───────────────────────────────────────────────────────────
+/**
+ * Chinese-language lexicons for entity hints, stopwords, and topic classification.
+ * @experimental @since 1.13.0
+ */
+export { ZH_ENTITY_HINTS, ZH_STOPWORDS, ZH_TOPIC_LEXICON } from './lexicon/zh/index.js';

package/dist/recall/BrainRecall.d.ts

@@ -0,0 +1,96 @@
+import type { FactStore } from '../store/FactStore.js';
+import type { EntityStore } from '../store/EntityStore.js';
+import type { BeliefStore } from '../belief/BeliefStore.js';
+import type { MemoryGraph } from '../core/MemoryGraph.js';
+import type { IngestionCursorStore } from '../batch/IngestionCursorStore.js';
+import type { SummaryStore } from '../store/SummaryStore.js';
+import type { FileChunkStore } from '../assets/index.js';
+import type { BrainRecallResult } from '../types/BrainRecallResult.js';
+import type { GraphEdgeStoreLike, ISkillDiscovery } from '../types/ExtensionPoints.js';
+import type { VectorCandidateFilter } from './VectorCandidateFilter.js';
+import type { HierarchicalRecallRouter } from './HierarchicalRecallRouter.js';
+import type { TopicSummaryBoard } from './TopicSummaryBoard.js';
+import type { GraphCommunityEngine } from '../engine/GraphCommunityEngine.js';
+import type { EmbeddingProvider } from '../embedding/EmbeddingProvider.js';
+import type { NeuronEmbeddingStore } from '../embedding/NeuronEmbeddingStore.js';
+export type { BrainRecallResult } from '../types/BrainRecallResult.js';
+export interface BrainRecallOptions {
+    projectId?: string;
+    limit?: number;
+    includeRawEvidence?: boolean;
+    includeUnprocessedFallback?: boolean;
+    /** Enable 1-hop persistent_gain graph edge expansion. Defaults to true. */
+    enablePersistentGainEdges?: boolean;
+    /** Enable opt-in deep-write relation/causal graph edges. Defaults to false. */
+    enableDeepWriteEdges?: boolean;
+    /** CPU-controlled topic namespace hint for hierarchical recall. */
+    topicPath?: string;
+}
+export interface BrainRecallDependencies {
+    memoryGraph: MemoryGraph;
+    factStore: FactStore;
+    entityStore: EntityStore;
+    beliefStore: BeliefStore;
+    cursorStore: IngestionCursorStore;
+    graphEdgeStore?: GraphEdgeStoreLike;
+    summaryStore?: SummaryStore;
+    fileChunkStore?: FileChunkStore;
+    skillDiscoveryEngine?: ISkillDiscovery;
+    /**
+     * v1.1: Optional vector semantic search function.
+     * Called with the query string; returns an ordered list of neuron IDs.
+     */
+    vectorSearchFn?: (query: string, projectId: string | undefined, limit: number) => string[];
+    vectorCandidateFilter?: VectorCandidateFilter;
+    hierarchicalRouter?: HierarchicalRecallRouter;
+    topicSummaryBoard?: TopicSummaryBoard;
+    graphCommunityEngine?: GraphCommunityEngine;
+    embeddingProvider?: EmbeddingProvider;
+    neuronEmbeddingStore?: NeuronEmbeddingStore;
+}
+export declare class BrainRecall {
+    private readonly deps;
+    private readonly semanticCompiler;
+    private readonly loader;
+    private readonly adapters;
+    constructor(deps: BrainRecallDependencies);
+    recall(query: string, options?: BrainRecallOptions): BrainRecallResult;
+    recallAsync(query: string, options?: BrainRecallOptions): Promise<BrainRecallResult>;
+    private prepareRecallCandidates;
+    private finishRecall;
+    private _prependSemanticConsolidations;
+    private _prependCrossDomainPrinciples;
+    private findDurableNeuronsByType;
+    private _expandByCommunity;
+    private routeByTopic;
+    private withSkillCandidates;
+    private withFileEvidence;
+    private expandEntityIdsViaPersistentGainEdges;
+    private withSummaries;
+    private detectPersistentGainAmbiguity;
+    private collectProfileSignals;
+    private collectFallbackSnippets;
+    private collectProfileSurface;
+    private rankFacts;
+    private rankEvents;
+    private scoreRecord;
+    private scoreText;
+    private extractProfileFacets;
+    private normalizeProfileLabel;
+    private extractTokens;
+    /**
+     * v1.1: Appends vector semantic search results to candidateNeuronIds when the
+     * existing FTS5 results are sparse (below vectorFallbackThreshold).
+     *
+     * @returns true if vector search was triggered and produced results.
+     */
+    private appendVectorResults;
+    private appendVectorResultsAsync;
+    private appendVectorResultIds;
+    private toRecallableNeurons;
+    private retainRecallableNeuronIds;
+    private filterRecallableNeuronIds;
+    private isRecallableNeuronId;
+    private isRecallableNeuron;
+}
+//# sourceMappingURL=BrainRecall.d.ts.map