@smyslenny/agent-memory 5.0.1 → 5.1.0

package/dist/index.d.ts

@@ -72,6 +72,46 @@ declare function createMemory(db: Database.Database, input: CreateMemoryInput):
 declare function getMemory(db: Database.Database, id: string): Memory | null;
 declare function updateMemory(db: Database.Database, id: string, input: UpdateMemoryInput): Memory | null;
 declare function deleteMemory(db: Database.Database, id: string): boolean;
+interface ArchivedMemory {
+    id: string;
+    content: string;
+    type: string;
+    priority: number;
+    emotion_val: number;
+    vitality: number;
+    stability: number;
+    access_count: number;
+    last_accessed: string | null;
+    created_at: string;
+    updated_at: string;
+    archived_at: string;
+    archive_reason: string;
+    source: string | null;
+    agent_id: string;
+    hash: string | null;
+    emotion_tag: string | null;
+    source_session: string | null;
+    source_context: string | null;
+    observed_at: string | null;
+}
+/**
+ * Archive a memory to memory_archive, then delete from memories.
+ * If minVitality is set (default 0.1), memories below that threshold
+ * are directly deleted without archiving — they're decayed noise.
+ * Returns "archived" if actually archived, "deleted" if skipped to direct delete,
+ * or false if memory not found.
+ */
+declare function archiveMemory(db: Database.Database, id: string, reason?: string, opts?: {
+    minVitality?: number;
+}): "archived" | "deleted" | false;
+declare function restoreMemory(db: Database.Database, id: string): Memory | null;
+declare function listArchivedMemories(db: Database.Database, opts?: {
+    agent_id?: string;
+    limit?: number;
+}): ArchivedMemory[];
+declare function purgeArchive(db: Database.Database, opts?: {
+    agent_id?: string;
+}): number;
 declare function listMemories(db: Database.Database, opts?: {
     agent_id?: string;
     type?: MemoryType;
@@ -330,6 +370,16 @@ declare function fusionScore(input: {
     recency_boost?: number;
 }): number;
 declare function fuseHybridResults(lexical: SearchResult[], vector: VectorSearchResult[], limit: number, recency_boost?: number): HybridRecallResult[];
+interface RelatedLink {
+    memory: Memory;
+    sourceId: string;
+    weight: number;
+}
+/**
+ * Fetch related memories from the links table for a set of source memory IDs.
+ * Shared by both recall and surface expansion paths.
+ */
+declare function fetchRelatedLinks(db: Database.Database, sourceIds: string[], agentId: string, excludeIds: Set<string>, maxPerSource?: number): RelatedLink[];
 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>;
@@ -410,6 +460,8 @@ interface SurfaceResult {
     lexical_rank?: number;
     semantic_rank?: number;
     semantic_similarity?: number;
+    related_source_id?: string;
+    match_type?: "direct" | "related";
 }
 interface SurfaceResponse {
     count: number;
@@ -505,6 +557,10 @@ interface ReflectInput {
 }
 declare function reflectMemories(db: Database.Database, input: ReflectInput): Promise<ReflectRunResult>;
 
+interface CapacityInfo {
+    count: number;
+    limit: number | null;
+}
 interface StatusResult {
     total: number;
     by_type: Record<string, number>;
@@ -513,6 +569,7 @@ interface StatusResult {
     low_vitality: number;
     feedback_events: number;
     agent_id: string;
+    capacity: Record<string, CapacityInfo>;
 }
 declare function getMemoryStatus(db: Database.Database, input?: {
     agent_id?: string;
@@ -752,6 +809,8 @@ interface GovernResult {
     orphanPaths: number;
     emptyMemories: number;
     evicted: number;
+    archived: number;
+    evictedByType: Record<string, number>;
 }
 interface EvictionCandidate {
     memory: Memory;
@@ -771,13 +830,28 @@ declare function computeEvictionScore(input: {
 declare function rankEvictionCandidates(db: Database.Database, opts?: {
     agent_id?: string;
 }): EvictionCandidate[];
+interface TieredCapacity {
+    identity: number | null;
+    emotion: number | null;
+    knowledge: number | null;
+    event: number | null;
+    total: number;
+}
+declare function getTieredCapacity(opts?: {
+    maxMemories?: number;
+}): TieredCapacity;
 /**
  * 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
+ * 3. Evict low-value memories when over capacity using tiered + global eviction
+ *
+ * Tiered capacity can be set via env vars:
+ *   AGENT_MEMORY_MAX_IDENTITY, AGENT_MEMORY_MAX_EMOTION,
+ *   AGENT_MEMORY_MAX_KNOWLEDGE, AGENT_MEMORY_MAX_EVENT,
+ *   AGENT_MEMORY_MAX_MEMORIES (global cap, default 350)
  *
- * maxMemories can be set via AGENT_MEMORY_MAX_MEMORIES env var (default: 200).
+ * Evicted memories are archived to memory_archive before deletion.
  */
 declare function runGovern(db: Database.Database, opts?: {
     agent_id?: string;
@@ -831,4 +905,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 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 };
+export { type AgentMemoryHttpServer, type ReflectInput as AppReflectInput, type ReflectProgressEvent as AppReflectProgressEvent, type ArchivedMemory, type AutoIngestWatcher, type AutoIngestWatcherOptions, type BootResult, type CapacityInfo, 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 RelatedLink, type RememberInput, type SearchResult, type StatusResult, type StoredEmbedding, type SurfaceInput, type SurfaceIntent, type SurfaceResponse, type SurfaceResult, type SyncInput, type SyncResult, type TidyResult, type TieredCapacity, type UpdateMemoryInput, type VectorSearchResult, type WarmBootOptions, type WarmBootResult, archiveMemory, 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, fetchRelatedLinks, findResumableMaintenanceJob, formatNarrativeBoot, formatRelativeDate, fuseHybridResults, fusionScore, getConfiguredEmbeddingProviderId, getDecayedMemories, getEmbedding, getEmbeddingProvider, getEmbeddingProviderConfigFromEnv, getEmbeddingProviderFromEnv, getFeedbackScore, getFeedbackSummary, getMaintenanceJob, getMemory, getMemoryStatus, getPath, getPathByUri, getPathsByDomain, getPathsByMemory, getPathsByPrefix, getTieredCapacity, guard, healthcheckEmbeddingProvider, ingestText, isStaleContent, listArchivedMemories, listMemories, listPendingEmbeddings, loadWarmBootLayers, markAllEmbeddingsPending, markEmbeddingFailed, markMemoryEmbeddingPending, parseUri, priorityPrior, purgeArchive, rankEvictionCandidates, rebuildBm25Index, recallMemories, recallMemory, recordAccess, recordFeedbackEvent, recordPassiveFeedback, reflectMemories, reindexEmbeddings, reindexMemories, reindexMemorySearch, rememberMemory, restoreMemory, runAutoIngestWatcher, runDecay, runGovern, runReflectOrchestrator, runTidy, searchBM25, searchByVector, slugify, splitIngestBlocks, startHttpServer, surfaceMemories, syncBatch, syncOne, tokenize, updateMaintenanceCheckpoint, updateMemory, upsertReadyEmbedding };