ai-memory-layer 2.0.0

package/dist/core/knowledge-lifecycle.js

@@ -0,0 +1,103 @@
+import { DEFAULT_MAINTENANCE_POLICY } from '../contracts/policy.js';
+function daysToSeconds(days) {
+    return Math.max(0, Math.floor(days * 24 * 60 * 60));
+}
+export function resolveMaintenancePolicy(policy) {
+    return {
+        ...DEFAULT_MAINTENANCE_POLICY,
+        ...policy,
+        classRetentionOverrides: {
+            ...DEFAULT_MAINTENANCE_POLICY.classRetentionOverrides,
+            ...(policy?.classRetentionOverrides ?? {}),
+        },
+    };
+}
+export function isTrustedCoreKnowledge(knowledge) {
+    return (knowledge.knowledge_state === 'trusted' &&
+        ['identity', 'preference', 'constraint'].includes(knowledge.knowledge_class));
+}
+function outcomeRetentionBonusDays(knowledge) {
+    if (knowledge.knowledge_class === 'strategy') {
+        return Math.min(180, knowledge.successful_use_count * 30);
+    }
+    if (knowledge.knowledge_class === 'anti_pattern') {
+        return Math.min(365, knowledge.failed_use_count * 45);
+    }
+    if (knowledge.knowledge_class === 'procedure') {
+        return Math.min(90, knowledge.successful_use_count * 15);
+    }
+    return 0;
+}
+export function getKnowledgeRetentionDays(knowledge, policy) {
+    if (knowledge.knowledge_state === 'provisional') {
+        return policy.provisionalRetentionDays;
+    }
+    if (knowledge.knowledge_state === 'disputed') {
+        return policy.disputedRetentionDays;
+    }
+    if (isTrustedCoreKnowledge(knowledge)) {
+        return Math.max(policy.trustedCoreRetentionDays, policy.classRetentionOverrides[knowledge.knowledge_class] ?? policy.trustedCoreRetentionDays);
+    }
+    return ((policy.classRetentionOverrides[knowledge.knowledge_class] ?? policy.knowledgeStaleAfterSeconds / 86400) +
+        outcomeRetentionBonusDays(knowledge));
+}
+export function getLifecycleReferenceTime(knowledge) {
+    return Math.max(knowledge.last_confirmed_at ?? 0, knowledge.last_verified_at ?? 0, knowledge.last_accessed_at ?? 0, knowledge.created_at);
+}
+export function computeNextReverificationAt(knowledge, policy) {
+    if (knowledge.knowledge_state === 'retired' || knowledge.knowledge_state === 'superseded') {
+        return null;
+    }
+    const cadence = isTrustedCoreKnowledge(knowledge)
+        ? daysToSeconds(policy.trustedCoreRetentionDays)
+        : daysToSeconds(policy.reverificationCadenceDays);
+    const anchor = knowledge.last_confirmed_at ??
+        knowledge.last_verified_at ??
+        knowledge.created_at;
+    return anchor + cadence;
+}
+export function evaluateKnowledgeLifecycle(knowledge, policy, now) {
+    const retentionSeconds = daysToSeconds(getKnowledgeRetentionDays(knowledge, policy));
+    const ageSeconds = Math.max(0, now - getLifecycleReferenceTime(knowledge));
+    const dueAt = computeNextReverificationAt(knowledge, policy);
+    if (knowledge.knowledge_state === 'provisional') {
+        return {
+            retire: ageSeconds > retentionSeconds && knowledge.access_count <= policy.minKnowledgeAccessCount,
+            demote: false,
+            nextReverificationAt: dueAt,
+        };
+    }
+    if (knowledge.knowledge_state === 'disputed') {
+        return {
+            retire: ageSeconds > retentionSeconds && knowledge.access_count <= policy.minKnowledgeAccessCount,
+            demote: false,
+            nextReverificationAt: dueAt,
+        };
+    }
+    const staleAndWeak = ageSeconds > retentionSeconds && knowledge.access_count <= policy.minKnowledgeAccessCount;
+    const shouldDemoteProjectFact = knowledge.knowledge_state === 'trusted' &&
+        knowledge.knowledge_class === 'project_fact' &&
+        policy.requireReconfirmationForProjectFacts &&
+        dueAt !== null &&
+        dueAt <= now &&
+        knowledge.confirmation_count === 0;
+    return {
+        retire: !isTrustedCoreKnowledge(knowledge) &&
+            !shouldDemoteProjectFact &&
+            staleAndWeak &&
+            ['project_fact', 'episodic_fact', 'procedure'].includes(knowledge.knowledge_class),
+        demote: shouldDemoteProjectFact,
+        nextReverificationAt: dueAt,
+    };
+}
+export function getDueReverificationKnowledge(knowledge, policy, now) {
+    return knowledge
+        .filter((item) => {
+        const dueAt = item.next_reverification_at ?? computeNextReverificationAt(item, policy);
+        return dueAt !== null && dueAt <= now && item.retired_at === null && item.superseded_by_id === null;
+    })
+        .sort((a, b) => (a.next_reverification_at ?? computeNextReverificationAt(a, policy) ?? Number.MAX_SAFE_INTEGER) -
+        (b.next_reverification_at ?? computeNextReverificationAt(b, policy) ?? Number.MAX_SAFE_INTEGER) ||
+        a.created_at - b.created_at);
+}
+//# sourceMappingURL=knowledge-lifecycle.js.map

package/dist/core/knowledge-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-lifecycle.js","sourceRoot":"","sources":["../../src/core/knowledge-lifecycle.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AASpE,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,MAA0B;IACjE,OAAO;QACL,GAAG,0BAA0B;QAC7B,GAAG,MAAM;QACT,uBAAuB,EAAE;YACvB,GAAG,0BAA0B,CAAC,uBAAuB;YACrD,GAAG,CAAC,MAAM,EAAE,uBAAuB,IAAI,EAAE,CAAC;SAC3C;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,SAA0B;IAC/D,OAAO,CACL,SAAS,CAAC,eAAe,KAAK,SAAS;QACvC,CAAC,UAAU,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,eAAe,CAAC,CAC7E,CAAC;AACJ,CAAC;AAED,SAAS,yBAAyB,CAAC,SAA0B;IAC3D,IAAI,SAAS,CAAC,eAAe,KAAK,UAAU,EAAE,CAAC;QAC7C,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,oBAAoB,GAAG,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,SAAS,CAAC,eAAe,KAAK,cAAc,EAAE,CAAC;QACjD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,gBAAgB,GAAG,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,IAAI,SAAS,CAAC,eAAe,KAAK,WAAW,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,CAAC,oBAAoB,GAAG,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,SAA0B,EAC1B,MAAmC;IAEnC,IAAI,SAAS,CAAC,eAAe,KAAK,aAAa,EAAE,CAAC;QAChD,OAAO,MAAM,CAAC,wBAAwB,CAAC;IACzC,CAAC;IACD,IAAI,SAAS,CAAC,eAAe,KAAK,UAAU,EAAE,CAAC;QAC7C,OAAO,MAAM,CAAC,qBAAqB,CAAC;IACtC,CAAC;IACD,IAAI,sBAAsB,CAAC,SAAS,CAAC,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC,GAAG,CACb,MAAM,CAAC,wBAAwB,EAC/B,MAAM,CAAC,uBAAuB,CAAC,SAAS,CAAC,eAAe,CAAC,IAAI,MAAM,CAAC,wBAAwB,CAC7F,CAAC;IACJ,CAAC;IACD,OAAO,CACL,CAAC,MAAM,CAAC,uBAAuB,CAAC,SAAS,CAAC,eAAe,CAAC,IAAI,MAAM,CAAC,0BAA0B,GAAG,KAAK,CAAC;QACxG,yBAAyB,CAAC,SAAS,CAAC,CACrC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,SAA0B;IAClE,OAAO,IAAI,CAAC,GAAG,CACb,SAAS,CAAC,iBAAiB,IAAI,CAAC,EAChC,SAAS,CAAC,gBAAgB,IAAI,CAAC,EAC/B,SAAS,CAAC,gBAAgB,IAAI,CAAC,EAC/B,SAAS,CAAC,UAAU,CACrB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,2BAA2B,CACzC,SAA0B,EAC1B,MAAmC;IAEnC,IAAI,SAAS,CAAC,eAAe,KAAK,SAAS,IAAI,SAAS,CAAC,eAAe,KAAK,YAAY,EAAE,CAAC;QAC1F,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,OAAO,GAAG,sBAAsB,CAAC,SAAS,CAAC;QAC/C,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,wBAAwB,CAAC;QAChD,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,yBAAyB,CAAC,CAAC;IACpD,MAAM,MAAM,GACV,SAAS,CAAC,iBAAiB;QAC3B,SAAS,CAAC,gBAAgB;QAC1B,SAAS,CAAC,UAAU,CAAC;IACvB,OAAO,MAAM,GAAG,OAAO,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,SAA0B,EAC1B,MAAmC,EACnC,GAAW;IAEX,MAAM,gBAAgB,GAAG,aAAa,CAAC,yBAAyB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;IACrF,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,yBAAyB,CAAC,SAAS,CAAC,CAAC,CAAC;IAC3E,MAAM,KAAK,GAAG,2BAA2B,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAE7D,IAAI,SAAS,CAAC,eAAe,KAAK,aAAa,EAAE,CAAC;QAChD,OAAO;YACL,MAAM,EAAE,UAAU,GAAG,gBAAgB,IAAI,SAAS,CAAC,YAAY,IAAI,MAAM,CAAC,uBAAuB;YACjG,MAAM,EAAE,KAAK;YACb,oBAAoB,EAAE,KAAK;SAC5B,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,CAAC,eAAe,KAAK,UAAU,EAAE,CAAC;QAC7C,OAAO;YACL,MAAM,EAAE,UAAU,GAAG,gBAAgB,IAAI,SAAS,CAAC,YAAY,IAAI,MAAM,CAAC,uBAAuB;YACjG,MAAM,EAAE,KAAK;YACb,oBAAoB,EAAE,KAAK;SAC5B,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAG,UAAU,GAAG,gBAAgB,IAAI,SAAS,CAAC,YAAY,IAAI,MAAM,CAAC,uBAAuB,CAAC;IAC/G,MAAM,uBAAuB,GAC3B,SAAS,CAAC,eAAe,KAAK,SAAS;QACvC,SAAS,CAAC,eAAe,KAAK,cAAc;QAC5C,MAAM,CAAC,oCAAoC;QAC3C,KAAK,KAAK,IAAI;QACd,KAAK,IAAI,GAAG;QACZ,SAAS,CAAC,kBAAkB,KAAK,CAAC,CAAC;IAErC,OAAO;QACL,MAAM,EACJ,CAAC,sBAAsB,CAAC,SAAS,CAAC;YAClC,CAAC,uBAAuB;YACxB,YAAY;YACZ,CAAC,cAAc,EAAE,eAAe,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,eAAe,CAAC;QACpF,MAAM,EAAE,uBAAuB;QAC/B,oBAAoB,EAAE,KAAK;KAC5B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,SAA4B,EAC5B,MAAmC,EACnC,GAAW;IAEX,OAAO,SAAS;SACb,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QACf,MAAM,KAAK,GAAG,IAAI,CAAC,sBAAsB,IAAI,2BAA2B,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACvF,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,IAAI,GAAG,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI,IAAI,IAAI,CAAC,gBAAgB,KAAK,IAAI,CAAC;IACtG,CAAC,CAAC;SACD,IAAI,CACH,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,CAAC,CAAC,CAAC,sBAAsB,IAAI,2BAA2B,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,gBAAgB,CAAC;QAC7F,CAAC,CAAC,CAAC,sBAAsB,IAAI,2BAA2B,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,gBAAgB,CAAC;QACjG,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAC9B,CAAC;AACN,CAAC"}

package/dist/core/maintenance.d.ts

@@ -0,0 +1,13 @@
+import type { MemoryScope } from '../contracts/identity.js';
+import type { MaintenancePolicy } from '../contracts/policy.js';
+import type { AsyncStorageAdapter } from '../contracts/async-storage.js';
+export interface MaintenanceReport {
+    expiredWorkingMemoryIds: number[];
+    retiredKnowledgeIds: number[];
+    deletedWorkItemIds: number[];
+    reverifiedKnowledgeIds: number[];
+    demotedKnowledgeIds: number[];
+    expiredCandidateIds: number[];
+}
+export declare function runMaintenance(adapter: AsyncStorageAdapter, scope: MemoryScope, policy?: MaintenancePolicy): Promise<MaintenanceReport>;
+//# sourceMappingURL=maintenance.d.ts.map

package/dist/core/maintenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../../src/core/maintenance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AASzE,MAAM,WAAW,iBAAiB;IAChC,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAClC,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,WAAW,EAClB,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CA4G5B"}

package/dist/core/maintenance.js

@@ -0,0 +1,102 @@
+import { nowSeconds } from './validation.js';
+import { evaluateKnowledgeLifecycle, getDueReverificationKnowledge, isTrustedCoreKnowledge, resolveMaintenancePolicy, } from './knowledge-lifecycle.js';
+export async function runMaintenance(adapter, scope, policy = {}) {
+    const resolved = resolveMaintenancePolicy(policy);
+    const now = nowSeconds();
+    const expiredWorkingMemoryIds = [];
+    const retiredKnowledgeIds = [];
+    const deletedWorkItemIds = [];
+    const reverifiedKnowledgeIds = [];
+    const demotedKnowledgeIds = [];
+    const expiredCandidateIds = [];
+    const staleWorkingMemory = await adapter.getWorkingMemoryByTimeRange(scope, {
+        end_at: now - resolved.workingMemoryTtlSeconds,
+    });
+    for (const item of staleWorkingMemory) {
+        if (item.expires_at === null || item.expires_at > now) {
+            await adapter.expireWorkingMemory(item.id);
+            expiredWorkingMemoryIds.push(item.id);
+        }
+    }
+    const activeKnowledge = await adapter.getActiveKnowledgeMemory(scope);
+    const dueReverification = getDueReverificationKnowledge(activeKnowledge, resolved, now);
+    for (const item of dueReverification) {
+        await adapter.updateKnowledgeMemory(item.id, {
+            next_reverification_at: item.next_reverification_at ?? now,
+        });
+    }
+    for (const item of activeKnowledge) {
+        const decision = evaluateKnowledgeLifecycle(item, resolved, now);
+        if (decision.demote) {
+            await adapter.updateKnowledgeMemory(item.id, {
+                knowledge_state: 'provisional',
+                verification_status: 'unverified',
+                verification_notes: 'maintenance_demoted_pending_reconfirmation',
+                trust_score: Math.min(item.trust_score, 0.55),
+                next_reverification_at: decision.nextReverificationAt,
+            });
+            demotedKnowledgeIds.push(item.id);
+            continue;
+        }
+        if (decision.retire) {
+            await adapter.retireKnowledgeMemory(item.id, now);
+            retiredKnowledgeIds.push(item.id);
+            continue;
+        }
+        if (decision.nextReverificationAt !== item.next_reverification_at) {
+            await adapter.updateKnowledgeMemory(item.id, {
+                next_reverification_at: decision.nextReverificationAt,
+            });
+        }
+    }
+    if (activeKnowledge.length > resolved.maxActiveKnowledgeItems) {
+        const overflow = [...activeKnowledge]
+            .filter((item) => !isTrustedCoreKnowledge(item))
+            .sort((a, b) => a.access_count - b.access_count || a.last_accessed_at - b.last_accessed_at)
+            .slice(0, activeKnowledge.length - resolved.maxActiveKnowledgeItems);
+        for (const item of overflow) {
+            if (item.retired_at === null) {
+                await adapter.retireKnowledgeMemory(item.id, now);
+                retiredKnowledgeIds.push(item.id);
+            }
+        }
+    }
+    if (resolved.consolidateKnowledge) {
+        const bySlot = new Map();
+        for (const item of activeKnowledge) {
+            if (!item.slot_key)
+                continue;
+            bySlot.set(item.slot_key, [...(bySlot.get(item.slot_key) ?? []), item]);
+        }
+        for (const group of bySlot.values()) {
+            if (group.length < 2)
+                continue;
+            const [winner, ...duplicates] = [...group].sort((a, b) => b.confidence_score - a.confidence_score ||
+                b.access_count - a.access_count ||
+                b.last_accessed_at - a.last_accessed_at);
+            void winner;
+            for (const duplicate of duplicates) {
+                if (duplicate.retired_at === null) {
+                    await adapter.retireKnowledgeMemory(duplicate.id, now);
+                    retiredKnowledgeIds.push(duplicate.id);
+                }
+            }
+        }
+    }
+    const completedWorkItems = (await adapter.getWorkItemsByTimeRange(scope, {
+        end_at: now - resolved.completedWorkItemTtlSeconds,
+    })).filter((item) => item.status === 'done');
+    for (const item of completedWorkItems) {
+        await adapter.deleteWorkItem(item.id);
+        deletedWorkItemIds.push(item.id);
+    }
+    return {
+        expiredWorkingMemoryIds,
+        retiredKnowledgeIds,
+        deletedWorkItemIds,
+        reverifiedKnowledgeIds,
+        demotedKnowledgeIds,
+        expiredCandidateIds,
+    };
+}
+//# sourceMappingURL=maintenance.js.map

package/dist/core/maintenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance.js","sourceRoot":"","sources":["../../src/core/maintenance.ts"],"names":[],"mappings":"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"}

package/dist/core/manager.d.ts

@@ -0,0 +1,110 @@
+import type { EmbeddingAdapter, EmbeddingGenerator } from '../contracts/embedding.js';
+import type { MemoryScope, ScopeLevel } from '../contracts/identity.js';
+import type { EventHook, Logger } from '../contracts/observability.js';
+import type { ContextPolicy, ExtractionPolicy, MaintenancePolicy, MonitorPolicy } from '../contracts/policy.js';
+import type { StorageAdapter } from '../contracts/storage.js';
+import type { AsyncStorageAdapter } from '../contracts/async-storage.js';
+import type { CompactionLog, ContextMonitor, FactConfidence, FactType, KnowledgeEvidence, KnowledgeMemory, KnowledgeMemoryAudit, KnowledgeTrustAssessment, PaginationOptions, PaginatedResult, SearchOptions, SearchResult, TimeRange, Turn, TurnRole, WorkItem, WorkingMemory } from '../contracts/types.js';
+import { type MemoryContext } from './context.js';
+import type { MemoryEventEmitter } from './events.js';
+import type { Extractor } from './extractor.js';
+import type { SessionBootstrap } from './formatter.js';
+import { type CompactionResult, type Summarizer } from './orchestrator.js';
+import { type MaintenanceReport } from './maintenance.js';
+import { type TokenEstimator } from './tokens.js';
+import { type CircuitBreakerOptions } from './circuit-breaker.js';
+export interface MemoryManagerConfig {
+    /** Synchronous storage adapter (SQLite, in-memory). Mutually exclusive with asyncAdapter. */
+    adapter?: StorageAdapter;
+    /** Async storage adapter (PostgreSQL, remote). Mutually exclusive with adapter. */
+    asyncAdapter?: AsyncStorageAdapter;
+    scope: MemoryScope;
+    sessionId: string;
+    summarizer: Summarizer;
+    extractor?: Extractor;
+    embeddingAdapter?: EmbeddingAdapter;
+    embeddingGenerator?: EmbeddingGenerator;
+    logger?: Logger;
+    onEvent?: EventHook;
+    eventEmitter?: MemoryEventEmitter;
+    monitorPolicy?: MonitorPolicy;
+    extractionPolicy?: ExtractionPolicy;
+    contextPolicy?: ContextPolicy;
+    maintenancePolicy?: MaintenancePolicy;
+    crossScopeLevel?: ScopeLevel;
+    tokenEstimator?: TokenEstimator;
+    autoCompact?: boolean;
+    autoExtract?: boolean;
+    failurePolicy?: {
+        summarizer?: 'throw' | 'retry_once' | 'log_and_continue';
+        extractor?: 'throw' | 'retry_once' | 'log_and_continue' | 'disable_auto_extract';
+    };
+    circuitBreaker?: {
+        summarizer?: CircuitBreakerOptions;
+        extractor?: CircuitBreakerOptions;
+        embeddings?: CircuitBreakerOptions;
+    };
+    redactText?: (input: {
+        kind: 'turn' | 'fact' | 'work_item';
+        text: string;
+    }) => string;
+}
+export interface MemoryManager {
+    processTurn(role: TurnRole, content: string, actor?: string): Promise<Turn>;
+    processExchange(userContent: string, assistantContent: string, actors?: {
+        user?: string;
+        assistant?: string;
+    }): Promise<{
+        userTurn: Turn;
+        assistantTurn: Turn;
+        compactionResult: CompactionResult | null;
+    }>;
+    getContext(relevanceQuery?: string): Promise<MemoryContext>;
+    getContextAt(asOf: number, relevanceQuery?: string): Promise<MemoryContext>;
+    getSessionBootstrap(relevanceQuery?: string): Promise<SessionBootstrap>;
+    recall(timeRange: TimeRange): Promise<{
+        turns: Turn[];
+        workingMemory: WorkingMemory[];
+        knowledge: KnowledgeMemory[];
+        workItems: WorkItem[];
+    }>;
+    search(query: string, options?: SearchOptions): Promise<{
+        turns: SearchResult<Turn>[];
+        knowledge: SearchResult<KnowledgeMemory>[];
+    }>;
+    searchCrossScope(query: string, level: ScopeLevel, options?: SearchOptions): Promise<{
+        knowledge: SearchResult<KnowledgeMemory>[];
+    }>;
+    pollForChanges(since: Date, options?: {
+        scopeLevel?: ScopeLevel;
+    }): Promise<KnowledgeMemory[]>;
+    forceCompact(): Promise<CompactionResult | null>;
+    learnFact(fact: string, factType: FactType, confidence?: FactConfidence): Promise<KnowledgeMemory>;
+    trackWorkItem(title: string, kind?: WorkItem['kind'], status?: WorkItem['status'], detail?: string): Promise<WorkItem>;
+    inspectKnowledge(id: number): Promise<{
+        knowledge: KnowledgeMemory | null;
+        evidence: KnowledgeEvidence[];
+        audits: KnowledgeMemoryAudit[];
+    }>;
+    listKnowledge(options?: PaginationOptions): Promise<PaginatedResult<KnowledgeMemory>>;
+    getKnowledgeAudits(options?: {
+        knowledgeId?: number;
+        limit?: number;
+    }): Promise<KnowledgeMemoryAudit[]>;
+    getContextMonitor(): Promise<ContextMonitor | null>;
+    getRecentCompactionLogs(limit?: number): Promise<CompactionLog[]>;
+    getDueReverification(options?: {
+        limit?: number;
+    }): Promise<KnowledgeMemory[]>;
+    reverifyKnowledge(id: number): Promise<KnowledgeTrustAssessment>;
+    runReverification(options?: {
+        limit?: number;
+    }): Promise<{
+        reverifiedKnowledgeIds: number[];
+        demotedKnowledgeIds: number[];
+    }>;
+    runMaintenance(policy?: MaintenancePolicy): Promise<MaintenanceReport>;
+    close(): Promise<void>;
+}
+export declare function createMemoryManager(config: MemoryManagerConfig): MemoryManager;
+//# sourceMappingURL=manager.d.ts.map

package/dist/core/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/core/manager.ts"],"names":[],"mappings":"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"}