@smyslenny/agent-memory 4.3.1 → 5.0.1

package/dist/index.d.ts

@@ -39,6 +39,9 @@ interface Memory {
     agent_id: string;
     hash: string | null;
     emotion_tag: string | null;
+    source_session: string | null;
+    source_context: string | null;
+    observed_at: string | null;
 }
 interface CreateMemoryInput {
     content: string;
@@ -49,6 +52,9 @@ interface CreateMemoryInput {
     agent_id?: string;
     embedding_provider_id?: string | null;
     emotion_tag?: string;
+    source_session?: string;
+    source_context?: string;
+    observed_at?: string;
 }
 interface UpdateMemoryInput {
     content?: string;
@@ -82,6 +88,61 @@ declare function countMemories(db: Database.Database, agent_id?: string): {
     by_priority: Record<string, number>;
 };
 
+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";
+type ConflictType = "negation" | "value" | "status";
+interface ConflictInfo {
+    memoryId: string;
+    content: string;
+    conflict_score: number;
+    conflict_type: ConflictType;
+    detail: string;
+}
+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;
+    candidates?: Array<{
+        memoryId: string;
+        dedup_score: number;
+    }>;
+    conflicts?: ConflictInfo[];
+}
+interface GuardInput extends CreateMemoryInput {
+    uri?: string;
+    provider?: EmbeddingProvider | null;
+    candidateLimit?: number;
+    conservative?: boolean;
+    now?: string;
+    observed_at?: string;
+}
+declare function guard(db: Database.Database, input: GuardInput): Promise<GuardResult>;
+
 interface SyncInput {
     content: string;
     type?: CreateMemoryInput["type"];
@@ -93,11 +154,15 @@ interface SyncInput {
     provider?: EmbeddingProvider | null;
     conservative?: boolean;
     emotion_tag?: string;
+    source_session?: string;
+    source_context?: string;
+    observed_at?: string;
 }
 interface SyncResult {
     action: "added" | "updated" | "merged" | "skipped";
     memoryId?: string;
     reason: string;
+    conflicts?: ConflictInfo[];
 }
 /**
  * Sync a single piece of information into memory.
@@ -121,6 +186,9 @@ interface RememberInput {
     provider?: EmbeddingProvider | null;
     conservative?: boolean;
     emotion_tag?: string;
+    source_session?: string;
+    source_context?: string;
+    observed_at?: string;
 }
 declare function rememberMemory(db: Database.Database, input: RememberInput): Promise<SyncResult>;
 
@@ -138,6 +206,8 @@ declare function searchBM25(db: Database.Database, query: string, opts?: {
     agent_id?: string;
     limit?: number;
     min_vitality?: number;
+    after?: string;
+    before?: string;
 }): SearchResult[];
 /**
  * Build FTS5 query from natural language.
@@ -199,6 +269,8 @@ declare function searchByVector(db: Database.Database, queryVector: ArrayLike<nu
     agent_id?: string;
     limit?: number;
     min_vitality?: number;
+    after?: string;
+    before?: string;
 }): VectorSearchResult[];
 
 interface HybridRecallResult {
@@ -208,6 +280,8 @@ interface HybridRecallResult {
     vector_rank?: number;
     bm25_score?: number;
     vector_score?: number;
+    related_source_id?: string;
+    match_type?: "direct" | "related";
 }
 interface HybridRecallResponse {
     mode: "bm25-only" | "vector-only" | "dual-path";
@@ -223,6 +297,10 @@ interface RecallOptions {
     vectorLimit?: number;
     provider?: EmbeddingProvider | null;
     recordAccess?: boolean;
+    related?: boolean;
+    after?: string;
+    before?: string;
+    recency_boost?: number;
 }
 interface ReindexOptions {
     agent_id?: string;
@@ -249,8 +327,9 @@ declare function fusionScore(input: {
     memory: Memory;
     bm25Rank?: number;
     vectorRank?: number;
+    recency_boost?: number;
 }): number;
-declare function fuseHybridResults(lexical: SearchResult[], vector: VectorSearchResult[], limit: number): HybridRecallResult[];
+declare function fuseHybridResults(lexical: SearchResult[], vector: VectorSearchResult[], limit: number, recency_boost?: 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>;
@@ -265,10 +344,14 @@ interface RecallInput {
     provider?: EmbeddingProvider | null;
     recordAccess?: boolean;
     emotion_tag?: string;
+    related?: boolean;
+    after?: string;
+    before?: string;
+    recency_boost?: number;
 }
 declare function recallMemory(db: Database.Database, input: RecallInput): Promise<HybridRecallResponse>;
 
-type FeedbackSource = "recall" | "surface";
+type FeedbackSource = "recall" | "surface" | "passive";
 interface FeedbackEventInput {
     memory_id: string;
     source: FeedbackSource;
@@ -289,6 +372,12 @@ interface FeedbackSummary {
 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;
+/**
+ * Record passive feedback for multiple memories.
+ * 24h dedup: each memory can receive at most 3 passive feedbacks per 24h window.
+ * Uses batch query to avoid N+1.
+ */
+declare function recordPassiveFeedback(db: Database.Database, memoryIds: string[], agentId?: string): number;
 
 type SurfaceIntent = "factual" | "preference" | "temporal" | "planning" | "design";
 interface SurfaceInput {
@@ -302,6 +391,10 @@ interface SurfaceInput {
     provider?: EmbeddingProvider | null;
     min_vitality?: number;
     emotion_tag?: string;
+    related?: boolean;
+    after?: string;
+    before?: string;
+    recency_boost?: number;
 }
 interface SurfaceResult {
     memory: Memory;
@@ -497,47 +590,6 @@ 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;
-}
-interface GuardInput extends CreateMemoryInput {
-    uri?: string;
-    provider?: EmbeddingProvider | null;
-    candidateLimit?: number;
-    conservative?: boolean;
-    now?: string;
-}
-declare function guard(db: Database.Database, input: GuardInput): Promise<GuardResult>;
-
 interface ExportResult {
     exported: number;
     files: string[];
@@ -672,10 +724,22 @@ declare function getDecayedMemories(db: Database.Database, threshold?: number, o
 interface TidyResult {
     archived: number;
     orphansCleaned: number;
+    staleDecayed: number;
+}
+interface StaleDetectionResult {
+    stale: boolean;
+    reason: string;
+    decay_factor: number;
 }
+/**
+ * Detect if memory content is stale based on patterns.
+ * identity and emotion types never participate in semantic decay.
+ */
+declare function isStaleContent(content: string, type: MemoryType): StaleDetectionResult;
 /**
  * Run the tidy (deep sleep) cycle:
  * 1. Archive decayed P3 memories (vitality < threshold)
+ * 2. Apply semantic decay to stale content
  *
  * Path/orphan cleanup moved to govern.ts in Phase 2.
  */
@@ -767,4 +831,4 @@ declare function formatNarrativeBoot(layers: {
  */
 declare function boot(db: Database.Database, opts?: WarmBootOptions): WarmBootResult;
 
-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 };
+export { type AgentMemoryHttpServer, type ReflectInput as AppReflectInput, type ReflectProgressEvent as AppReflectProgressEvent, type AutoIngestWatcher, type AutoIngestWatcherOptions, type BootResult, type ConflictInfo, type ConflictType, 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, isStaleContent, listMemories, listPendingEmbeddings, loadWarmBootLayers, markAllEmbeddingsPending, markEmbeddingFailed, markMemoryEmbeddingPending, parseUri, priorityPrior, rankEvictionCandidates, rebuildBm25Index, recallMemories, recallMemory, recordAccess, recordFeedbackEvent, recordPassiveFeedback, reflectMemories, reindexEmbeddings, reindexMemories, reindexMemorySearch, rememberMemory, runAutoIngestWatcher, runDecay, runGovern, runReflectOrchestrator, runTidy, searchBM25, searchByVector, slugify, splitIngestBlocks, startHttpServer, surfaceMemories, syncBatch, syncOne, tokenize, updateMaintenanceCheckpoint, updateMemory, upsertReadyEmbedding };