@smyslenny/agent-memory 3.1.0 → 4.1.0-alpha.1

package/dist/index.d.ts

@@ -1,5 +1,25 @@
-export { D as DbOptions, i as isCountRow, o as openDatabase } from './db-DsY3zz8f.js';
 import Database from 'better-sqlite3';
+import http from 'node:http';
+export { D as DbOptions, i as isCountRow, o as openDatabase } from './db-DsY3zz8f.js';
+
+interface EmbeddingProvider {
+    id: string;
+    model: string;
+    dimension: number;
+    embed(texts: string[]): Promise<number[][]>;
+    healthcheck?(): Promise<void>;
+}
+interface EmbeddingProviderOptions {
+    baseUrl: string;
+    model: string;
+    dimension: number;
+    apiKey?: string;
+    endpoint?: string;
+    headers?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+}
+declare function createOpenAICompatibleEmbeddingProvider(opts: EmbeddingProviderOptions): EmbeddingProvider;
+declare function createLocalHttpEmbeddingProvider(opts: EmbeddingProviderOptions): EmbeddingProvider;
 
 type MemoryType = "identity" | "emotion" | "knowledge" | "event";
 type Priority = 0 | 1 | 2 | 3;
@@ -18,6 +38,7 @@ interface Memory {
     source: string | null;
     agent_id: string;
     hash: string | null;
+    emotion_tag: string | null;
 }
 interface CreateMemoryInput {
     content: string;
@@ -26,6 +47,8 @@ interface CreateMemoryInput {
     emotion_val?: number;
     source?: string;
     agent_id?: string;
+    embedding_provider_id?: string | null;
+    emotion_tag?: string;
 }
 interface UpdateMemoryInput {
     content?: string;
@@ -35,6 +58,8 @@ interface UpdateMemoryInput {
     vitality?: number;
     stability?: number;
     source?: string;
+    embedding_provider_id?: string | null;
+    emotion_tag?: string | null;
 }
 declare function contentHash(content: string): string;
 declare function createMemory(db: Database.Database, input: CreateMemoryInput): Memory | null;
@@ -48,6 +73,7 @@ declare function listMemories(db: Database.Database, opts?: {
     min_vitality?: number;
     limit?: number;
     offset?: number;
+    emotion_tag?: string;
 }): Memory[];
 declare function recordAccess(db: Database.Database, id: string, growthFactor?: number): void;
 declare function countMemories(db: Database.Database, agent_id?: string): {
@@ -56,6 +82,400 @@ declare function countMemories(db: Database.Database, agent_id?: string): {
     by_priority: Record<string, number>;
 };
 
+interface SyncInput {
+    content: string;
+    type?: CreateMemoryInput["type"];
+    priority?: CreateMemoryInput["priority"];
+    emotion_val?: number;
+    uri?: string;
+    source?: string;
+    agent_id?: string;
+    provider?: EmbeddingProvider | null;
+    conservative?: boolean;
+    emotion_tag?: string;
+}
+interface SyncResult {
+    action: "added" | "updated" | "merged" | "skipped";
+    memoryId?: string;
+    reason: string;
+}
+/**
+ * Sync a single piece of information into memory.
+ * Runs full Write Guard pipeline before writing.
+ */
+declare function syncOne(db: Database.Database, input: SyncInput): Promise<SyncResult>;
+/**
+ * Sync multiple items in a batch.
+ * Semantic guard may require async provider calls, so batch writes are serialized.
+ */
+declare function syncBatch(db: Database.Database, inputs: SyncInput[]): Promise<SyncResult[]>;
+
+interface RememberInput {
+    content: string;
+    type?: MemoryType;
+    priority?: Priority;
+    emotion_val?: number;
+    uri?: string;
+    source?: string;
+    agent_id?: string;
+    provider?: EmbeddingProvider | null;
+    conservative?: boolean;
+    emotion_tag?: string;
+}
+declare function rememberMemory(db: Database.Database, input: RememberInput): Promise<SyncResult>;
+
+interface SearchResult {
+    memory: Memory;
+    score: number;
+    rank: number;
+    matchReason: string;
+}
+/**
+ * BM25 search using SQLite FTS5.
+ * Returns memories ranked by relevance.
+ */
+declare function searchBM25(db: Database.Database, query: string, opts?: {
+    agent_id?: string;
+    limit?: number;
+    min_vitality?: number;
+}): SearchResult[];
+/**
+ * Build FTS5 query from natural language.
+ * Uses jieba for Chinese word segmentation, falls back to bigram splitting.
+ */
+declare function buildFtsQuery(text: string): string | null;
+declare function rebuildBm25Index(db: Database.Database, opts?: {
+    agent_id?: string;
+}): {
+    reindexed: number;
+};
+
+type EmbeddingStatus = "pending" | "ready" | "failed";
+interface StoredEmbedding {
+    id: string;
+    memory_id: string;
+    provider_id: string;
+    vector: Buffer | null;
+    content_hash: string;
+    status: EmbeddingStatus;
+    created_at: string;
+}
+interface VectorSearchResult {
+    memory: Memory;
+    similarity: number;
+    rank: number;
+    provider_id: string;
+}
+interface PendingEmbeddingRecord {
+    embeddingId: string;
+    memoryId: string;
+    content: string;
+    contentHash: string;
+    providerId: string;
+    status: EmbeddingStatus;
+}
+declare function encodeVector(vector: ArrayLike<number>): Buffer;
+declare function decodeVector(blob: Uint8Array | ArrayBuffer): number[];
+declare function cosineSimilarity(a: ArrayLike<number>, b: ArrayLike<number>): number;
+declare function getEmbedding(db: Database.Database, memoryId: string, providerId: string): StoredEmbedding | null;
+declare function markMemoryEmbeddingPending(db: Database.Database, memoryId: string, providerId: string, contentHash: string): void;
+declare function markAllEmbeddingsPending(db: Database.Database, memoryId: string, contentHash: string): number;
+declare function upsertReadyEmbedding(input: {
+    db: Database.Database;
+    memoryId: string;
+    providerId: string;
+    vector: ArrayLike<number>;
+    contentHash: string;
+}): void;
+declare function markEmbeddingFailed(db: Database.Database, memoryId: string, providerId: string, contentHash: string): void;
+declare function listPendingEmbeddings(db: Database.Database, opts: {
+    providerId: string;
+    agent_id?: string;
+    limit?: number;
+    includeFailed?: boolean;
+}): PendingEmbeddingRecord[];
+declare function searchByVector(db: Database.Database, queryVector: ArrayLike<number>, opts: {
+    providerId: string;
+    agent_id?: string;
+    limit?: number;
+    min_vitality?: number;
+}): VectorSearchResult[];
+
+interface HybridRecallResult {
+    memory: Memory;
+    score: number;
+    bm25_rank?: number;
+    vector_rank?: number;
+    bm25_score?: number;
+    vector_score?: number;
+}
+interface HybridRecallResponse {
+    mode: "bm25-only" | "vector-only" | "dual-path";
+    providerId: string | null;
+    usedVectorSearch: boolean;
+    results: HybridRecallResult[];
+}
+interface RecallOptions {
+    agent_id?: string;
+    limit?: number;
+    min_vitality?: number;
+    lexicalLimit?: number;
+    vectorLimit?: number;
+    provider?: EmbeddingProvider | null;
+    recordAccess?: boolean;
+}
+interface ReindexOptions {
+    agent_id?: string;
+    provider?: EmbeddingProvider | null;
+    force?: boolean;
+    batchSize?: number;
+}
+interface ReindexEmbeddingsResult {
+    enabled: boolean;
+    providerId: string | null;
+    scanned: number;
+    pending: number;
+    embedded: number;
+    failed: number;
+}
+interface ReindexSearchResult {
+    fts: {
+        reindexed: number;
+    };
+    embeddings: ReindexEmbeddingsResult;
+}
+declare function priorityPrior(priority: number): number;
+declare function fusionScore(input: {
+    memory: Memory;
+    bm25Rank?: number;
+    vectorRank?: number;
+}): number;
+declare function fuseHybridResults(lexical: SearchResult[], vector: VectorSearchResult[], limit: number): HybridRecallResult[];
+declare function recallMemories(db: Database.Database, query: string, opts?: RecallOptions): Promise<HybridRecallResponse>;
+declare function reindexEmbeddings(db: Database.Database, opts?: ReindexOptions): Promise<ReindexEmbeddingsResult>;
+declare function reindexMemorySearch(db: Database.Database, opts?: ReindexOptions): Promise<ReindexSearchResult>;
+
+interface RecallInput {
+    query: string;
+    limit?: number;
+    agent_id?: string;
+    min_vitality?: number;
+    lexicalLimit?: number;
+    vectorLimit?: number;
+    provider?: EmbeddingProvider | null;
+    recordAccess?: boolean;
+    emotion_tag?: string;
+}
+declare function recallMemory(db: Database.Database, input: RecallInput): Promise<HybridRecallResponse>;
+
+type FeedbackSource = "recall" | "surface";
+interface FeedbackEventInput {
+    memory_id: string;
+    source: FeedbackSource;
+    useful: boolean;
+    agent_id?: string;
+}
+interface FeedbackEventRecord extends FeedbackEventInput {
+    id: string;
+    created_at: string;
+    value: number;
+}
+interface FeedbackSummary {
+    total: number;
+    useful: number;
+    not_useful: number;
+    score: number;
+}
+declare function recordFeedbackEvent(db: Database.Database, input: FeedbackEventInput): FeedbackEventRecord;
+declare function getFeedbackSummary(db: Database.Database, memoryId: string, agentId?: string): FeedbackSummary;
+declare function getFeedbackScore(db: Database.Database, memoryId: string, agentId?: string): number;
+
+type SurfaceIntent = "factual" | "preference" | "temporal" | "planning" | "design";
+interface SurfaceInput {
+    query?: string;
+    task?: string;
+    recent_turns?: string[];
+    intent?: SurfaceIntent;
+    types?: MemoryType[];
+    limit?: number;
+    agent_id?: string;
+    provider?: EmbeddingProvider | null;
+    min_vitality?: number;
+    emotion_tag?: string;
+}
+interface SurfaceResult {
+    memory: Memory;
+    score: number;
+    semantic_score: number;
+    lexical_score: number;
+    task_match: number;
+    vitality: number;
+    priority_prior: number;
+    feedback_score: number;
+    feedback_summary: FeedbackSummary;
+    reason_codes: string[];
+    lexical_rank?: number;
+    semantic_rank?: number;
+    semantic_similarity?: number;
+}
+interface SurfaceResponse {
+    count: number;
+    query?: string;
+    task?: string;
+    intent?: SurfaceIntent;
+    results: SurfaceResult[];
+}
+declare function surfaceMemories(db: Database.Database, input: SurfaceInput): Promise<SurfaceResponse>;
+
+type MaintenancePhase = "decay" | "tidy" | "govern" | "all";
+type MaintenanceStatus = "running" | "completed" | "failed";
+type ReflectStep = Exclude<MaintenancePhase, "all">;
+interface ReflectCheckpoint {
+    requestedPhase: MaintenancePhase;
+    nextPhase: ReflectStep | null;
+    completedPhases: ReflectStep[];
+    phaseResults: Partial<Record<ReflectStep, unknown>>;
+}
+interface MaintenanceJob {
+    job_id: string;
+    phase: MaintenancePhase;
+    status: MaintenanceStatus;
+    checkpoint: ReflectCheckpoint | null;
+    error: string | null;
+    started_at: string;
+    finished_at: string | null;
+}
+declare function createInitialCheckpoint(phase: MaintenancePhase): ReflectCheckpoint;
+declare function createMaintenanceJob(db: Database.Database, phase: MaintenancePhase, checkpoint?: ReflectCheckpoint): MaintenanceJob;
+declare function getMaintenanceJob(db: Database.Database, jobId: string): MaintenanceJob | null;
+declare function findResumableMaintenanceJob(db: Database.Database, phase: MaintenancePhase): MaintenanceJob | null;
+declare function updateMaintenanceCheckpoint(db: Database.Database, jobId: string, checkpoint: ReflectCheckpoint): MaintenanceJob | null;
+declare function failMaintenanceJob(db: Database.Database, jobId: string, error: string, checkpoint?: ReflectCheckpoint | null): MaintenanceJob | null;
+declare function completeMaintenanceJob(db: Database.Database, jobId: string, checkpoint?: ReflectCheckpoint | null): MaintenanceJob | null;
+
+interface ReflectStats {
+    total: number;
+    avgVitality: number;
+}
+interface ReflectRunners {
+    decay: (db: Database.Database, opts?: {
+        agent_id?: string;
+    }) => unknown | Promise<unknown>;
+    tidy: (db: Database.Database, opts?: {
+        agent_id?: string;
+    }) => unknown | Promise<unknown>;
+    govern: (db: Database.Database, opts?: {
+        agent_id?: string;
+    }) => unknown | Promise<unknown>;
+}
+interface ReflectProgressEvent$1 {
+    status: "started" | "phase-completed" | "completed" | "failed";
+    phase: MaintenancePhase | ReflectStep;
+    progress: number;
+    jobId?: string;
+    detail?: unknown;
+}
+interface ReflectOptions {
+    phase: MaintenancePhase;
+    agent_id?: string;
+    jobId?: string;
+    resume?: boolean;
+    runners?: Partial<ReflectRunners>;
+    onProgress?: (event: ReflectProgressEvent$1) => void;
+}
+interface ReflectRunResult {
+    job: MaintenanceJob;
+    jobId: string;
+    phase: MaintenancePhase;
+    resumed: boolean;
+    checkpoint: ReflectCheckpoint;
+    results: Partial<Record<ReflectStep, unknown>>;
+    before: ReflectStats;
+    after: ReflectStats;
+}
+declare function runReflectOrchestrator(db: Database.Database, opts: ReflectOptions): Promise<ReflectRunResult>;
+
+interface ReflectProgressEvent {
+    status: "started" | "phase-completed" | "completed" | "failed";
+    phase: MaintenancePhase | ReflectStep;
+    progress: number;
+    jobId?: string;
+    detail?: unknown;
+}
+interface ReflectInput {
+    phase: MaintenancePhase;
+    agent_id?: string;
+    jobId?: string;
+    resume?: boolean;
+    runners?: Partial<ReflectRunners>;
+    onProgress?: (event: ReflectProgressEvent) => void;
+}
+declare function reflectMemories(db: Database.Database, input: ReflectInput): Promise<ReflectRunResult>;
+
+interface StatusResult {
+    total: number;
+    by_type: Record<string, number>;
+    by_priority: Record<string, number>;
+    paths: number;
+    low_vitality: number;
+    feedback_events: number;
+    agent_id: string;
+}
+declare function getMemoryStatus(db: Database.Database, input?: {
+    agent_id?: string;
+}): StatusResult;
+
+interface ReindexProgressEvent {
+    status: "started" | "stage-completed" | "completed" | "failed";
+    stage: "fts" | "embeddings" | "done";
+    progress: number;
+    detail?: unknown;
+}
+interface ReindexInput {
+    agent_id?: string;
+    provider?: EmbeddingProvider | null;
+    force?: boolean;
+    batchSize?: number;
+    onProgress?: (event: ReindexProgressEvent) => void;
+}
+declare function reindexMemories(db: Database.Database, input?: ReindexInput): Promise<ReindexSearchResult>;
+
+interface HttpJobStatus {
+    id: string;
+    kind: "reflect" | "reindex";
+    status: "running" | "completed" | "failed";
+    stage: string;
+    progress: number;
+    agent_id: string;
+    started_at: string;
+    finished_at: string | null;
+    backend_job_id?: string;
+    error?: string;
+    result?: unknown;
+}
+interface HttpServerOptions {
+    db?: Database.Database;
+    dbPath?: string;
+    agentId?: string;
+    provider?: EmbeddingProvider | null;
+    reflectRunners?: Partial<ReflectRunners>;
+}
+interface AgentMemoryHttpServer {
+    server: http.Server;
+    db: Database.Database;
+    jobs: Map<string, HttpJobStatus>;
+    listen: (port?: number, host?: string) => Promise<{
+        port: number;
+        host: string;
+    }>;
+    close: () => Promise<void>;
+}
+declare function createHttpServer(options?: HttpServerOptions): AgentMemoryHttpServer;
+declare function startHttpServer(options?: HttpServerOptions & {
+    port?: number;
+    host?: string;
+}): Promise<AgentMemoryHttpServer>;
+
 interface Path {
     id: string;
     memory_id: string;
@@ -77,25 +497,46 @@ declare function getPathsByDomain(db: Database.Database, domain: string, agent_i
 declare function getPathsByPrefix(db: Database.Database, prefix: string, agent_id?: string): Path[];
 declare function deletePath(db: Database.Database, id: string): boolean;
 
+interface MergePlan {
+    strategy: "replace" | "append_evidence" | "synthesize" | "compact_timeline";
+    content: string;
+    aliases?: string[];
+    notes?: string[];
+}
+interface MergeContext {
+    existing: Memory;
+    incoming: Pick<CreateMemoryInput, "content" | "type" | "source"> & {
+        observed_at?: string | null;
+    };
+}
+declare function buildMergePlan(context: MergeContext): MergePlan;
+
 type GuardAction = "add" | "update" | "skip" | "merge";
+interface DedupScoreBreakdown {
+    semantic_similarity: number;
+    lexical_overlap: number;
+    uri_scope_match: number;
+    entity_overlap: number;
+    time_proximity: number;
+    dedup_score: number;
+}
 interface GuardResult {
     action: GuardAction;
     reason: string;
     existingId?: string;
+    updatedContent?: string;
     mergedContent?: string;
+    mergePlan?: MergePlan;
+    score?: DedupScoreBreakdown;
 }
-/**
- * Write Guard — decides whether to add, update, skip, or merge a memory.
- *
- * Pipeline:
- * 1. Hash dedup (exact content match → skip)
- * 2. URI conflict (URI exists → update path)
- * 3. BM25 similarity (dynamic threshold → merge or update)
- * 4. Four-criterion gate: Specificity, Novelty, Relevance, Coherence
- */
-declare function guard(db: Database.Database, input: CreateMemoryInput & {
+interface GuardInput extends CreateMemoryInput {
     uri?: string;
-}): GuardResult;
+    provider?: EmbeddingProvider | null;
+    candidateLimit?: number;
+    conservative?: boolean;
+    now?: string;
+}
+declare function guard(db: Database.Database, input: GuardInput): Promise<GuardResult>;
 
 interface ExportResult {
     exported: number;
@@ -109,20 +550,33 @@ declare function exportMemories(db: Database.Database, dirPath: string, opts?: {
     agent_id?: string;
 }): ExportResult;
 
-interface SearchResult {
-    memory: Memory;
-    score: number;
-    matchReason: string;
+type EmbeddingProviderKind = "openai-compatible" | "local-http";
+interface EmbeddingProviderConfig {
+    provider: EmbeddingProviderKind;
+    baseUrl: string;
+    model: string;
+    dimension: number;
+    apiKey?: string;
 }
-/**
- * BM25 search using SQLite FTS5.
- * Returns memories ranked by relevance.
- */
-declare function searchBM25(db: Database.Database, query: string, opts?: {
-    agent_id?: string;
-    limit?: number;
-    min_vitality?: number;
-}): SearchResult[];
+interface EmbeddingProviderFactoryOptions {
+    config?: Partial<EmbeddingProviderConfig>;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+}
+declare function getEmbeddingProviderConfigFromEnv(env?: NodeJS.ProcessEnv): EmbeddingProviderConfig | null;
+declare function createEmbeddingProvider(input: EmbeddingProviderConfig, opts?: {
+    fetchImpl?: typeof fetch;
+}): EmbeddingProvider;
+declare function getEmbeddingProvider(opts?: EmbeddingProviderFactoryOptions): EmbeddingProvider | null;
+declare function getEmbeddingProviderFromEnv(env?: NodeJS.ProcessEnv): EmbeddingProvider | null;
+declare function getConfiguredEmbeddingProviderId(opts?: {
+    config?: Partial<EmbeddingProviderConfig>;
+    env?: NodeJS.ProcessEnv;
+}): string | null;
+declare function healthcheckEmbeddingProvider(provider: EmbeddingProvider | null): Promise<{
+    enabled: boolean;
+    providerId?: string;
+}>;
 
 /**
  * Tokenize text for FTS5 queries.
@@ -132,29 +586,25 @@ declare function searchBM25(db: Database.Database, query: string, opts?: {
  */
 declare function tokenize(text: string): string[];
 
-interface IngestBlock {
-    title: string;
-    content: string;
-}
 interface IngestExtractedItem {
     index: number;
-    title: string;
-    content: string;
     type: MemoryType;
-    uri: string;
+    uri?: string;
+    content: string;
 }
-interface IngestDryRunDetail {
-    index: number;
-    type: MemoryType;
-    uri: string;
-    preview: string;
+interface IngestRunOptions {
+    text: string;
+    source?: string;
+    dryRun?: boolean;
+    agentId?: string;
 }
 interface IngestWriteDetail {
     index: number;
     type: MemoryType;
-    uri: string;
-    action: "added" | "updated" | "merged" | "skipped";
-    reason: string;
+    uri?: string;
+    preview?: string;
+    action?: "added" | "updated" | "merged" | "skipped";
+    reason?: string;
     memoryId?: string;
 }
 interface IngestResult {
@@ -162,19 +612,16 @@ interface IngestResult {
     written: number;
     skipped: number;
     dry_run: boolean;
-    details: Array<IngestDryRunDetail | IngestWriteDetail>;
-}
-interface IngestRunOptions {
-    text: string;
-    source?: string;
-    dryRun?: boolean;
-    agentId?: string;
+    details: IngestWriteDetail[];
 }
 declare function slugify(input: string): string;
-declare function classifyIngestType(text: string): MemoryType;
-declare function splitIngestBlocks(text: string): IngestBlock[];
+declare function classifyIngestType(title: string): MemoryType;
+declare function splitIngestBlocks(text: string): Array<{
+    title: string;
+    body: string;
+}>;
 declare function extractIngestItems(text: string, source?: string): IngestExtractedItem[];
-declare function ingestText(db: Database.Database, options: IngestRunOptions): IngestResult;
+declare function ingestText(db: Database.Database, options: IngestRunOptions): Promise<IngestResult>;
 
 interface AutoIngestWatcherOptions {
     db: Database.Database;
@@ -221,30 +668,6 @@ declare function getDecayedMemories(db: Database.Database, threshold?: number, o
     priority: number;
 }>;
 
-interface SyncInput {
-    content: string;
-    type?: CreateMemoryInput["type"];
-    priority?: CreateMemoryInput["priority"];
-    emotion_val?: number;
-    uri?: string;
-    source?: string;
-    agent_id?: string;
-}
-interface SyncResult {
-    action: "added" | "updated" | "merged" | "skipped";
-    memoryId?: string;
-    reason: string;
-}
-/**
- * Sync a single piece of information into memory.
- * Runs full Write Guard pipeline before writing.
- */
-declare function syncOne(db: Database.Database, input: SyncInput): SyncResult;
-/**
- * Sync multiple items in a batch (within a transaction).
- */
-declare function syncBatch(db: Database.Database, inputs: SyncInput[]): SyncResult[];
-
 interface TidyResult {
     archived: number;
     orphansCleaned: number;
@@ -252,7 +675,8 @@ interface TidyResult {
 /**
  * Run the tidy (deep sleep) cycle:
  * 1. Archive decayed P3 memories (vitality < threshold)
- * 2. Clean orphan paths (paths with no memory)
+ *
+ * Path/orphan cleanup moved to govern.ts in Phase 2.
  */
 declare function runTidy(db: Database.Database, opts?: {
     vitalityThreshold?: number;
@@ -262,27 +686,82 @@ declare function runTidy(db: Database.Database, opts?: {
 interface GovernResult {
     orphanPaths: number;
     emptyMemories: number;
+    evicted: number;
 }
+interface EvictionCandidate {
+    memory: Memory;
+    redundancy_score: number;
+    age_score: number;
+    low_feedback_penalty: number;
+    low_priority_penalty: number;
+    eviction_score: number;
+}
+declare function computeEvictionScore(input: {
+    vitality: number;
+    redundancy_score: number;
+    age_score: number;
+    low_feedback_penalty: number;
+    low_priority_penalty: number;
+}): number;
+declare function rankEvictionCandidates(db: Database.Database, opts?: {
+    agent_id?: string;
+}): EvictionCandidate[];
 /**
  * Run governance checks and cleanup:
  * 1. Remove orphan paths (no parent memory)
  * 2. Remove empty memories (blank content)
+ * 3. Evict low-value memories when over capacity using eviction_score
  */
 declare function runGovern(db: Database.Database, opts?: {
     agent_id?: string;
+    maxMemories?: number;
 }): GovernResult;
 
 interface BootResult {
     identityMemories: Memory[];
     bootPaths: string[];
 }
+interface WarmBootOptions {
+    agent_id?: string;
+    corePaths?: string[];
+    format?: "json" | "narrative";
+    agent_name?: string;
+}
+interface WarmBootResult extends BootResult {
+    narrative?: string;
+    layers?: {
+        identity: Memory[];
+        emotion: Memory[];
+        event: Memory[];
+        knowledge: Memory[];
+    };
+}
+/**
+ * Format a relative time string from an ISO date.
+ */
+declare function formatRelativeDate(isoDate: string): string;
 /**
- * Load core identity memories at startup.
+ * Load layered memories for warm boot.
+ */
+declare function loadWarmBootLayers(db: Database.Database, agentId: string): {
+    identity: Memory[];
+    emotion: Memory[];
+    event: Memory[];
+    knowledge: Memory[];
+};
+/**
+ * Format layered memories as narrative Markdown.
+ */
+declare function formatNarrativeBoot(layers: {
+    identity: Memory[];
+    emotion: Memory[];
+    event: Memory[];
+    knowledge: Memory[];
+}, agentName: string): string;
+/**
+ * Load core identity memories at startup (legacy JSON format).
  * Returns all P0 (identity) memories + any memories referenced by system://boot.
  */
-declare function boot(db: Database.Database, opts?: {
-    agent_id?: string;
-    corePaths?: string[];
-}): BootResult;
+declare function boot(db: Database.Database, opts?: WarmBootOptions): WarmBootResult;
 
-export { type AutoIngestWatcher, type AutoIngestWatcherOptions, type BootResult, type CreateMemoryInput, type ExportResult, type GovernResult, type GuardAction, type GuardResult, type IngestExtractedItem, type IngestResult, type IngestRunOptions, type Memory, type MemoryType, type Path, type Priority, type SearchResult, type SyncInput, type SyncResult, type TidyResult, type UpdateMemoryInput, boot, calculateVitality, classifyIngestType, contentHash, countMemories, createMemory, createPath, deleteMemory, deletePath, exportMemories, extractIngestItems, getDecayedMemories, getMemory, getPath, getPathByUri, getPathsByDomain, getPathsByMemory, getPathsByPrefix, guard, ingestText, listMemories, parseUri, recordAccess, runAutoIngestWatcher, runDecay, runGovern, runTidy, searchBM25, slugify, splitIngestBlocks, syncBatch, syncOne, tokenize, updateMemory };
+export { type AgentMemoryHttpServer, type ReflectInput as AppReflectInput, type ReflectProgressEvent as AppReflectProgressEvent, type AutoIngestWatcher, type AutoIngestWatcherOptions, type BootResult, type CreateMemoryInput, type DedupScoreBreakdown, type EmbeddingProvider, type EmbeddingProviderConfig, type EmbeddingProviderKind, type EmbeddingProviderOptions, type EmbeddingStatus, type EvictionCandidate, type ExportResult, type FeedbackEventInput, type FeedbackEventRecord, type FeedbackSource, type FeedbackSummary, type GovernResult, type GuardAction, type GuardInput, type GuardResult, type HttpJobStatus, type HttpServerOptions, type HybridRecallResponse, type HybridRecallResult, type IngestExtractedItem, type IngestResult, type IngestRunOptions, type MaintenanceJob, type MaintenancePhase, type MaintenanceStatus, type Memory, type MemoryType, type MergeContext, type MergePlan, type Path, type PendingEmbeddingRecord, type Priority, type RecallInput, type ReflectCheckpoint, type ReflectOptions, type ReflectProgressEvent$1 as ReflectProgressEvent, type ReflectRunResult, type ReflectRunners, type ReflectStats, type ReflectStep, type ReindexEmbeddingsResult, type ReindexInput, type ReindexProgressEvent, type ReindexSearchResult, type RememberInput, type SearchResult, type StatusResult, type StoredEmbedding, type SurfaceInput, type SurfaceIntent, type SurfaceResponse, type SurfaceResult, type SyncInput, type SyncResult, type TidyResult, type UpdateMemoryInput, type VectorSearchResult, type WarmBootOptions, type WarmBootResult, boot, buildFtsQuery, buildMergePlan, calculateVitality, classifyIngestType, completeMaintenanceJob, computeEvictionScore, contentHash, cosineSimilarity, countMemories, createEmbeddingProvider, createHttpServer, createInitialCheckpoint, createLocalHttpEmbeddingProvider, createMaintenanceJob, createMemory, createOpenAICompatibleEmbeddingProvider, createPath, decodeVector, deleteMemory, deletePath, encodeVector, exportMemories, extractIngestItems, failMaintenanceJob, findResumableMaintenanceJob, formatNarrativeBoot, formatRelativeDate, fuseHybridResults, fusionScore, getConfiguredEmbeddingProviderId, getDecayedMemories, getEmbedding, getEmbeddingProvider, getEmbeddingProviderConfigFromEnv, getEmbeddingProviderFromEnv, getFeedbackScore, getFeedbackSummary, getMaintenanceJob, getMemory, getMemoryStatus, getPath, getPathByUri, getPathsByDomain, getPathsByMemory, getPathsByPrefix, guard, healthcheckEmbeddingProvider, ingestText, listMemories, listPendingEmbeddings, loadWarmBootLayers, markAllEmbeddingsPending, markEmbeddingFailed, markMemoryEmbeddingPending, parseUri, priorityPrior, rankEvictionCandidates, rebuildBm25Index, recallMemories, recallMemory, recordAccess, recordFeedbackEvent, reflectMemories, reindexEmbeddings, reindexMemories, reindexMemorySearch, rememberMemory, runAutoIngestWatcher, runDecay, runGovern, runReflectOrchestrator, runTidy, searchBM25, searchByVector, slugify, splitIngestBlocks, startHttpServer, surfaceMemories, syncBatch, syncOne, tokenize, updateMaintenanceCheckpoint, updateMemory, upsertReadyEmbedding };