@smyslenny/agent-memory 2.0.0 → 2.2.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { D as DbOptions, o as openDatabase } from './db-CMsKtBt0.js';
+export { D as DbOptions, i as isCountRow, o as openDatabase } from './db-DsY3zz8f.js';
 import Database from 'better-sqlite3';
 
 type MemoryType = "identity" | "emotion" | "knowledge" | "event";
@@ -59,6 +59,7 @@ declare function countMemories(db: Database.Database, agent_id?: string): {
 interface Path {
     id: string;
     memory_id: string;
+    agent_id: string;
     uri: string;
     alias: string | null;
     domain: string;
@@ -68,35 +69,36 @@ declare function parseUri(uri: string): {
     domain: string;
     path: string;
 };
-declare function createPath(db: Database.Database, memoryId: string, uri: string, alias?: string, validDomains?: Set<string>): Path;
+declare function createPath(db: Database.Database, memoryId: string, uri: string, alias?: string, validDomains?: Set<string>, agent_id?: string): Path;
 declare function getPath(db: Database.Database, id: string): Path | null;
-declare function getPathByUri(db: Database.Database, uri: string): Path | null;
+declare function getPathByUri(db: Database.Database, uri: string, agent_id?: string): Path | null;
 declare function getPathsByMemory(db: Database.Database, memoryId: string): Path[];
-declare function getPathsByDomain(db: Database.Database, domain: string): Path[];
-declare function getPathsByPrefix(db: Database.Database, prefix: string): Path[];
+declare function getPathsByDomain(db: Database.Database, domain: string, agent_id?: string): Path[];
+declare function getPathsByPrefix(db: Database.Database, prefix: string, agent_id?: string): Path[];
 declare function deletePath(db: Database.Database, id: string): boolean;
 
 type RelationType = "related" | "caused" | "reminds" | "evolved" | "contradicts";
 interface Link {
+    agent_id: string;
     source_id: string;
     target_id: string;
     relation: RelationType;
     weight: number;
     created_at: string;
 }
-declare function createLink(db: Database.Database, sourceId: string, targetId: string, relation: RelationType, weight?: number): Link;
-declare function getLinks(db: Database.Database, memoryId: string): Link[];
-declare function getOutgoingLinks(db: Database.Database, sourceId: string): Link[];
+declare function createLink(db: Database.Database, sourceId: string, targetId: string, relation: RelationType, weight?: number, agent_id?: string): Link;
+declare function getLinks(db: Database.Database, memoryId: string, agent_id?: string): Link[];
+declare function getOutgoingLinks(db: Database.Database, sourceId: string, agent_id?: string): Link[];
 /**
  * Multi-hop traversal: find all memories reachable within N hops
  * Inspired by PowerMem's knowledge graph traversal
  */
-declare function traverse(db: Database.Database, startId: string, maxHops?: number): Array<{
+declare function traverse(db: Database.Database, startId: string, maxHops?: number, agent_id?: string): Array<{
     id: string;
     hop: number;
     relation: string;
 }>;
-declare function deleteLink(db: Database.Database, sourceId: string, targetId: string): boolean;
+declare function deleteLink(db: Database.Database, sourceId: string, targetId: string, agent_id?: string): boolean;
 
 type SnapshotAction = "create" | "update" | "delete" | "merge";
 interface Snapshot {
@@ -133,13 +135,25 @@ interface GuardResult {
  * Pipeline:
  * 1. Hash dedup (exact content match → skip)
  * 2. URI conflict (URI exists → update path)
- * 3. BM25 similarity (>0.85 → conflict detection → merge or update)
- * 4. Four-criterion gate (for P0/P1 only)
+ * 3. BM25 similarity (dynamic threshold → merge or update)
+ * 4. Four-criterion gate: Specificity, Novelty, Relevance, Coherence
  */
 declare function guard(db: Database.Database, input: CreateMemoryInput & {
     uri?: string;
 }): GuardResult;
 
+interface ExportResult {
+    exported: number;
+    files: string[];
+}
+/**
+ * Export all memories to Markdown files in the given directory.
+ * Creates MEMORY.md for identity/emotion/knowledge and daily .md files for events.
+ */
+declare function exportMemories(db: Database.Database, dirPath: string, opts?: {
+    agent_id?: string;
+}): ExportResult;
+
 interface SearchResult {
     memory: Memory;
     score: number;
@@ -155,6 +169,14 @@ declare function searchBM25(db: Database.Database, query: string, opts?: {
     min_vitality?: number;
 }): SearchResult[];
 
+/**
+ * Tokenize text for FTS5 queries.
+ * - Latin/numeric words: split on whitespace, filter len > 1
+ * - CJK text: use jieba cutForSearch, fallback to unigram + bigram
+ * Returns deduplicated token array, max 30 tokens.
+ */
+declare function tokenize(text: string): string[];
+
 type SearchIntent = "factual" | "exploratory" | "temporal" | "causal";
 interface IntentResult {
     intent: SearchIntent;
@@ -162,7 +184,8 @@ interface IntentResult {
 }
 /**
  * Classify the intent of a search query.
- * Uses keyword scoring — no LLM needed.
+ * Uses keyword pattern matching + structural analysis.
+ * Enhanced for Chinese with jieba-aware token analysis.
  */
 declare function classifyIntent(query: string): IntentResult;
 /**
@@ -174,6 +197,27 @@ declare function getStrategy(intent: SearchIntent): {
     limit: number;
 };
 
+interface RerankResult {
+    index: number;
+    relevance_score: number;
+}
+interface RerankProvider {
+    id: string;
+    model: string;
+    rerank(query: string, documents: string[]): Promise<RerankResult[]>;
+}
+declare function getRerankerProviderFromEnv(): RerankProvider | null;
+declare function createOpenAIRerankProvider(opts: {
+    apiKey: string;
+    model: string;
+    baseUrl?: string;
+}): RerankProvider;
+
+/**
+ * Optionally rerank results using an external semantic reranker provider.
+ * Best-effort: on failure, returns original results unchanged.
+ */
+declare function rerankWithProvider(results: SearchResult[], query: string, provider: RerankProvider): Promise<SearchResult[]>;
 /**
  * Rerank search results based on intent strategy and priority weighting.
  */
@@ -184,13 +228,94 @@ declare function rerank(results: SearchResult[], opts: {
     limit: number;
 }): SearchResult[];
 
-declare function calculateVitality(stability: number, daysSinceCreation: number, priority: number): number;
+interface EmbeddingProvider {
+    id: string;
+    model: string;
+    dimension?: number;
+    instructionPrefix?: string | null;
+    embed(text: string): Promise<number[]>;
+    embedQuery?(query: string): Promise<number[]>;
+}
+declare function getDefaultInstruction(model: string): string | null;
+declare function getEmbeddingProviderFromEnv(): EmbeddingProvider | null;
+declare function createOpenAIProvider(opts: {
+    id?: string;
+    apiKey: string;
+    model: string;
+    baseUrl?: string;
+    instruction?: string | null;
+}): EmbeddingProvider;
+declare function createDashScopeProvider(opts: {
+    apiKey: string;
+    model: string;
+    baseUrl?: string;
+    instruction?: string | null;
+}): EmbeddingProvider;
+
+interface HybridSearchOptions {
+    agent_id?: string;
+    limit?: number;
+    bm25CandidateMultiplier?: number;
+    semanticCandidates?: number;
+    rrfK?: number;
+    embeddingProvider?: EmbeddingProvider | null;
+    embeddingModel?: string;
+}
+declare function searchHybrid(db: Database.Database, query: string, opts?: HybridSearchOptions): Promise<SearchResult[]>;
+
+interface StoredEmbedding {
+    agent_id: string;
+    memory_id: string;
+    model: string;
+    dim: number;
+    vector: Float32Array;
+    created_at: string;
+    updated_at: string;
+}
+declare function encodeEmbedding(vector: number[] | Float32Array): Buffer;
+declare function decodeEmbedding(buf: Buffer): Float32Array;
+declare function upsertEmbedding(db: Database.Database, input: {
+    agent_id: string;
+    memory_id: string;
+    model: string;
+    vector: number[] | Float32Array;
+}): void;
+declare function getEmbedding(db: Database.Database, agent_id: string, memory_id: string, model: string): StoredEmbedding | null;
+declare function listEmbeddings(db: Database.Database, agent_id: string, model: string): Array<{
+    memory_id: string;
+    vector: Float32Array;
+}>;
+
+declare function embedMemory(db: Database.Database, memoryId: string, provider: EmbeddingProvider, opts?: {
+    agent_id?: string;
+    model?: string;
+    maxChars?: number;
+}): Promise<boolean>;
+declare function embedMissingForAgent(db: Database.Database, provider: EmbeddingProvider, opts?: {
+    agent_id?: string;
+    model?: string;
+    limit?: number;
+    maxChars?: number;
+}): Promise<{
+    embedded: number;
+    scanned: number;
+}>;
+
+/**
+ * Calculate vitality using Ebbinghaus forgetting curve.
+ * @param stability - S parameter (higher = slower decay)
+ * @param daysSinceLastAccess - days since last recall (or creation if never accessed)
+ * @param priority - memory priority (0-3)
+ */
+declare function calculateVitality(stability: number, daysSinceLastAccess: number, priority: number): number;
 /**
  * Run decay on all memories.
  * Updates vitality based on Ebbinghaus curve.
  * Returns count of memories updated.
  */
-declare function runDecay(db: Database.Database): {
+declare function runDecay(db: Database.Database, opts?: {
+    agent_id?: string;
+}): {
     updated: number;
     decayed: number;
     belowThreshold: number;
@@ -199,7 +324,9 @@ declare function runDecay(db: Database.Database): {
  * Get memories that are candidates for cleanup (vitality < threshold).
  * Only P3 (event) memories can be fully cleaned.
  */
-declare function getDecayedMemories(db: Database.Database, threshold?: number): Array<{
+declare function getDecayedMemories(db: Database.Database, threshold?: number, opts?: {
+    agent_id?: string;
+}): Array<{
     id: string;
     content: string;
     vitality: number;
@@ -244,6 +371,7 @@ interface TidyResult {
 declare function runTidy(db: Database.Database, opts?: {
     vitalityThreshold?: number;
     maxSnapshotsPerMemory?: number;
+    agent_id?: string;
 }): TidyResult;
 
 interface GovernResult {
@@ -257,7 +385,9 @@ interface GovernResult {
  * 2. Remove orphan links (source or target missing)
  * 3. Remove empty memories (blank content)
  */
-declare function runGovern(db: Database.Database): GovernResult;
+declare function runGovern(db: Database.Database, opts?: {
+    agent_id?: string;
+}): GovernResult;
 
 interface BootResult {
     identityMemories: Memory[];
@@ -272,4 +402,4 @@ declare function boot(db: Database.Database, opts?: {
     corePaths?: string[];
 }): BootResult;
 
-export { type BootResult, type CreateMemoryInput, type GovernResult, type GuardAction, type GuardResult, type IntentResult, type Link, type Memory, type MemoryType, type Path, type Priority, type RelationType, type SearchIntent, type SearchResult, type Snapshot, type SnapshotAction, type SyncInput, type SyncResult, type TidyResult, type UpdateMemoryInput, boot, calculateVitality, classifyIntent, contentHash, countMemories, createLink, createMemory, createPath, createSnapshot, deleteLink, deleteMemory, deletePath, getDecayedMemories, getLinks, getMemory, getOutgoingLinks, getPath, getPathByUri, getPathsByDomain, getPathsByMemory, getPathsByPrefix, getSnapshot, getSnapshots, getStrategy, guard, listMemories, parseUri, recordAccess, rerank, rollback, runDecay, runGovern, runTidy, searchBM25, syncBatch, syncOne, traverse, updateMemory };
+export { type BootResult, type CreateMemoryInput, type EmbeddingProvider, type ExportResult, type GovernResult, type GuardAction, type GuardResult, type HybridSearchOptions, type IntentResult, type Link, type Memory, type MemoryType, type Path, type Priority, type RelationType, type RerankProvider, type RerankResult, type SearchIntent, type SearchResult, type Snapshot, type SnapshotAction, type StoredEmbedding, type SyncInput, type SyncResult, type TidyResult, type UpdateMemoryInput, boot, calculateVitality, classifyIntent, contentHash, countMemories, createDashScopeProvider, createLink, createMemory, createOpenAIProvider, createOpenAIRerankProvider, createPath, createSnapshot, decodeEmbedding, deleteLink, deleteMemory, deletePath, embedMemory, embedMissingForAgent, encodeEmbedding, exportMemories, getDecayedMemories, getDefaultInstruction, getEmbedding, getEmbeddingProviderFromEnv, getLinks, getMemory, getOutgoingLinks, getPath, getPathByUri, getPathsByDomain, getPathsByMemory, getPathsByPrefix, getRerankerProviderFromEnv, getSnapshot, getSnapshots, getStrategy, guard, listEmbeddings, listMemories, parseUri, recordAccess, rerank, rerankWithProvider, rollback, runDecay, runGovern, runTidy, searchBM25, searchHybrid, syncBatch, syncOne, tokenize, traverse, updateMemory, upsertEmbedding };