minimem 0.0.3 → 0.0.4

package/dist/index.d.ts

@@ -1,3 +1,61 @@
+import { DatabaseSync } from 'node:sqlite';
+import { DebugFn, MemoryFileEntry, MemoryChunk } from './internal.js';
+export { buildFileEntry, chunkMarkdown, cosineSimilarity, extractChunkMetadata, hashText, isMemoryPath, listMemoryFiles, stripPrivateContent } from './internal.js';
+export { KnowledgeLink, KnowledgeSource, MemoryFrontmatter, SessionContext, addFrontmatter, addSessionToContent, extractSession, parseFrontmatter, serializeFrontmatter } from './session.js';
+
+/**
+ * A knowledge graph link between two nodes
+ */
+type GraphLink = {
+    fromId: string;
+    toId: string;
+    relation: string;
+    layer: string | null;
+    weight: number;
+    sourcePath: string | null;
+};
+/**
+ * A neighbor node discovered during graph traversal
+ */
+type GraphNeighbor = {
+    id: string;
+    depth: number;
+    link: GraphLink;
+};
+/**
+ * Get all outgoing links from a node.
+ */
+declare function getLinksFrom(db: DatabaseSync, fromId: string, opts?: {
+    relation?: string;
+    layer?: string;
+}): GraphLink[];
+/**
+ * Get all incoming links to a node.
+ */
+declare function getLinksTo(db: DatabaseSync, toId: string, opts?: {
+    relation?: string;
+    layer?: string;
+}): GraphLink[];
+/**
+ * BFS traversal to find neighbors up to a given depth.
+ *
+ * @param db - Database handle
+ * @param startId - The starting node ID
+ * @param depth - Maximum traversal depth (default: 1)
+ * @param opts - Optional filters for relation and layer
+ * @returns Array of neighbor nodes with their depth and connecting link
+ */
+declare function getNeighbors(db: DatabaseSync, startId: string, depth?: number, opts?: {
+    relation?: string;
+    layer?: string;
+}): GraphNeighbor[];
+/**
+ * BFS shortest path between two nodes, max depth 3.
+ *
+ * @returns Array of links forming the path, or empty if no path found.
+ */
+declare function getPathBetween(db: DatabaseSync, fromId: string, toId: string, maxDepth?: number): GraphLink[];
+
 type EmbeddingProvider = {
     id: string;
     model: string;
@@ -6,8 +64,8 @@ type EmbeddingProvider = {
 };
 type EmbeddingProviderResult = {
     provider: EmbeddingProvider;
-    requestedProvider: "openai" | "local" | "gemini" | "auto";
-    fallbackFrom?: "openai" | "local" | "gemini";
+    requestedProvider: "openai" | "local" | "gemini" | "auto" | "none";
+    fallbackFrom?: "openai" | "local" | "gemini" | "auto";
     fallbackReason?: string;
     openAi?: OpenAiEmbeddingClient;
     gemini?: GeminiEmbeddingClient;
@@ -148,6 +206,7 @@ declare class Minimem {
     private closed;
     private dirty;
     private syncing;
+    private syncLock;
     private embeddingOptions;
     private constructor();
     static create(config: MinimemConfig): Promise<Minimem>;
@@ -166,6 +225,7 @@ declare class Minimem {
     search(query: string, opts?: {
         maxResults?: number;
         minScore?: number;
+        type?: string;
     }): Promise<MinimemSearchResult[]>;
     sync(opts?: {
         reason?: string;
@@ -228,68 +288,39 @@ declare class Minimem {
         chunkCount: number;
         cacheCount: number;
     }>;
+    /**
+     * Search with knowledge metadata filters (domain, entities, confidence, type).
+     * Runs a standard search then post-filters by knowledge columns.
+     */
+    knowledgeSearch(query: string, opts?: {
+        maxResults?: number;
+        minScore?: number;
+        domain?: string[];
+        entities?: string[];
+        minConfidence?: number;
+        knowledgeType?: string;
+    }): Promise<MinimemSearchResult[]>;
+    /**
+     * Get knowledge graph links from or to a node.
+     */
+    getLinks(nodeId: string, direction?: "from" | "to", opts?: {
+        relation?: string;
+        layer?: string;
+    }): GraphLink[];
+    /**
+     * Get neighbor nodes via BFS traversal.
+     */
+    getGraphNeighbors(nodeId: string, depth?: number, opts?: {
+        relation?: string;
+        layer?: string;
+    }): GraphNeighbor[];
+    /**
+     * Find shortest path between two knowledge nodes.
+     */
+    getGraphPath(fromId: string, toId: string, maxDepth?: number): GraphLink[];
     close(): void;
 }
 
-type MemoryFileEntry = {
-    path: string;
-    absPath: string;
-    mtimeMs: number;
-    size: number;
-    hash: string;
-};
-type MemoryChunk = {
-    startLine: number;
-    endLine: number;
-    text: string;
-    hash: string;
-};
-declare function normalizeRelPath(value: string): string;
-declare function isMemoryPath(relPath: string): boolean;
-declare function listMemoryFiles(memoryDir: string): Promise<string[]>;
-declare function hashText(value: string): string;
-declare function buildFileEntry(absPath: string, memoryDir: string): Promise<MemoryFileEntry>;
-declare function chunkMarkdown(content: string, chunking: {
-    tokens: number;
-    overlap: number;
-}): MemoryChunk[];
-declare function cosineSimilarity(a: number[], b: number[]): number;
-
-type HybridSource = string;
-type HybridVectorResult = {
-    id: string;
-    path: string;
-    startLine: number;
-    endLine: number;
-    source: HybridSource;
-    snippet: string;
-    vectorScore: number;
-};
-type HybridKeywordResult = {
-    id: string;
-    path: string;
-    startLine: number;
-    endLine: number;
-    source: HybridSource;
-    snippet: string;
-    textScore: number;
-};
-declare function buildFtsQuery(raw: string): string | null;
-declare function bm25RankToScore(rank: number): number;
-declare function mergeHybridResults(params: {
-    vector: HybridVectorResult[];
-    keyword: HybridKeywordResult[];
-    vectorWeight: number;
-    textWeight: number;
-}): Array<{
-    path: string;
-    startLine: number;
-    endLine: number;
-    score: number;
-    snippet: string;
-    source: HybridSource;
-}>;
-
 type OpenAiBatchRequest = {
     custom_id: string;
     method: "POST";
@@ -384,8 +415,59 @@ type MemorySearchParams = {
     maxResults?: number;
     minScore?: number;
     directories?: string[];
+    /** "compact" returns lightweight index; "full" returns complete snippets (default: "compact") */
+    detail?: "compact" | "full";
+    /** Filter by observation type (e.g., "decision", "bugfix", "feature", "discovery") */
+    type?: string;
+};
+/**
+ * Memory get details tool parameters
+ */
+type MemoryGetDetailsParams = {
+    results: Array<{
+        path: string;
+        startLine: number;
+        endLine: number;
+    }>;
+    directories?: string[];
+};
+/**
+ * Knowledge search tool parameters
+ */
+type KnowledgeSearchParams = {
+    query: string;
+    domain?: string[];
+    entities?: string[];
+    minConfidence?: number;
+    knowledgeType?: string;
+    maxResults?: number;
+    minScore?: number;
+    directories?: string[];
+};
+/**
+ * Knowledge graph traversal parameters
+ */
+type KnowledgeGraphParams = {
+    nodeId: string;
+    depth?: number;
+    relation?: string;
+    layer?: string;
+    directories?: string[];
+};
+/**
+ * Knowledge path parameters
+ */
+type KnowledgePathParams = {
+    fromId: string;
+    toId: string;
+    maxDepth?: number;
+    directories?: string[];
 };
 declare const MEMORY_SEARCH_TOOL: ToolDefinition;
+declare const MEMORY_GET_DETAILS_TOOL: ToolDefinition;
+declare const KNOWLEDGE_SEARCH_TOOL: ToolDefinition;
+declare const KNOWLEDGE_GRAPH_TOOL: ToolDefinition;
+declare const KNOWLEDGE_PATH_TOOL: ToolDefinition;
 /**
  * All available memory tools
  */
@@ -416,7 +498,17 @@ declare class MemoryToolExecutor {
      * Execute a tool by name with given parameters
      */
     execute(toolName: string, params: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * Filter instances by directory names/paths
+     */
+    private filterInstances;
     private memorySearch;
+    private formatCompactResults;
+    private formatFullResults;
+    private memoryGetDetails;
+    private knowledgeSearch;
+    private knowledgeGraph;
+    private knowledgePath;
 }
 /**
  * Create a tool executor for the given Minimem instance(s)
@@ -527,66 +619,240 @@ declare function generateMcpConfig(opts: {
 }): McpServerConfig;
 
 /**
- * Session tracking for memory entries
- *
- * Captures context about the originating session (Claude Code, VS Code, etc.)
- * and stores it as YAML frontmatter in memory files.
+ * Options for filtering search results by knowledge metadata
  */
-/**
- * Session metadata for memory entries
- */
-type SessionContext = {
-    /** Session identifier (e.g., Claude Code session ID) */
-    id?: string;
-    /** Source application (claude-code, vscode, cursor, etc.) */
-    source?: string;
-    /** Project directory path */
-    project?: string;
-    /** Path to session transcript/log file */
-    transcript?: string;
+type KnowledgeSearchOptions = {
+    /** Filter to chunks matching any of these domains */
+    domain?: string[];
+    /** Filter to chunks referencing any of these entities */
+    entities?: string[];
+    /** Minimum confidence threshold */
+    minConfidence?: number;
+    /** Filter to a specific knowledge type */
+    knowledgeType?: string;
 };
 /**
- * Frontmatter structure for memory files
+ * Build SQL WHERE clause fragments for knowledge filters.
+ * Uses json_each() for array column filtering.
  */
-type MemoryFrontmatter = {
-    session?: SessionContext;
-    created?: string;
-    updated?: string;
-    tags?: string[];
+declare function buildKnowledgeFilterSql(opts: KnowledgeSearchOptions): {
+    sql: string;
+    params: (string | number)[];
 };
+
 /**
- * Parse YAML frontmatter from content
+ * MemoryIndexer - Handles file indexing and embedding management
  *
- * Frontmatter is delimited by --- at the start and end:
- * ```
- * ---
- * session:
- *   id: abc123
- *   source: claude-code
- * created: 2024-01-27T14:30:00Z
- * ---
- * Actual content here...
- * ```
- */
-declare function parseFrontmatter(content: string): {
-    frontmatter: MemoryFrontmatter | undefined;
-    body: string;
-};
-/**
- * Serialize frontmatter to YAML string
+ * Responsible for:
+ * - Processing memory files into chunks
+ * - Computing and caching embeddings
+ * - Managing file records in the database
+ * - Detecting stale content
  */
-declare function serializeFrontmatter(frontmatter: MemoryFrontmatter): string;
+
+type IndexerConfig = {
+    memoryDir: string;
+    chunking: {
+        tokens: number;
+        overlap: number;
+    };
+    cache: {
+        enabled: boolean;
+        maxEntries: number;
+    };
+    batch: {
+        enabled: boolean;
+        wait: boolean;
+        concurrency: number;
+        pollIntervalMs: number;
+        timeoutMs: number;
+    };
+    ftsEnabled: boolean;
+    debug?: DebugFn;
+};
+type MemoryIndexMeta = {
+    model: string;
+    provider: string;
+    providerKey?: string;
+    chunkTokens: number;
+    chunkOverlap: number;
+    vectorDims?: number;
+};
+type IndexStats = {
+    filesProcessed: number;
+    chunksCreated: number;
+    staleRemoved: number;
+};
 /**
- * Add or update frontmatter in content
+ * MemoryIndexer handles file indexing, chunking, and embedding management
  */
-declare function addFrontmatter(content: string, frontmatter: MemoryFrontmatter): string;
+declare class MemoryIndexer {
+    private readonly config;
+    private readonly db;
+    private readonly provider;
+    private readonly providerKey;
+    private readonly openAi?;
+    private readonly gemini?;
+    private vectorState;
+    private ftsAvailable;
+    constructor(db: DatabaseSync, provider: EmbeddingProvider, config: IndexerConfig, options?: {
+        openAi?: OpenAiEmbeddingClient;
+        gemini?: GeminiEmbeddingClient;
+        vectorState?: {
+            available: boolean;
+            dims?: number;
+        };
+        ftsAvailable?: boolean;
+    });
+    /**
+     * Update vector/FTS availability (called by parent when extensions load)
+     */
+    setVectorState(state: {
+        available: boolean;
+        dims?: number;
+    }): void;
+    setFtsAvailable(available: boolean): void;
+    getVectorDims(): number | undefined;
+    /**
+     * Compute a unique key for the current provider configuration
+     */
+    private computeProviderKey;
+    /**
+     * Read index metadata from database
+     */
+    readMeta(): MemoryIndexMeta | null;
+    /**
+     * Write index metadata to database
+     */
+    writeMeta(meta: MemoryIndexMeta): void;
+    /**
+     * Check if the index is stale by comparing file mtimes
+     */
+    isStale(): Promise<boolean>;
+    /**
+     * Check if a full reindex is needed based on configuration changes
+     */
+    needsFullReindex(force?: boolean): boolean;
+    /**
+     * Index all memory files, returns stats
+     */
+    indexAll(force?: boolean): Promise<IndexStats>;
+    /**
+     * Index a single file
+     */
+    indexFile(entry: MemoryFileEntry): Promise<number>;
+    /**
+     * Delete all chunks for a file
+     */
+    private deleteChunksForFile;
+    /**
+     * Insert a chunk into the database
+     */
+    private insertChunk;
+    /**
+     * Remove stale file entries that no longer exist
+     */
+    private removeStaleEntries;
+    /**
+     * Create vector table with the given dimensions
+     */
+    ensureVectorTable(dimensions: number): void;
+    /**
+     * Get embeddings for chunks, using cache when available
+     */
+    embedChunks(chunks: MemoryChunk[]): Promise<number[][]>;
+    /**
+     * Embed texts with retry logic
+     */
+    private embedBatchWithRetry;
+    /**
+     * Use batch API for large embedding jobs
+     */
+    private embedWithBatchApi;
+    /**
+     * Load embeddings from cache
+     */
+    private loadEmbeddingCache;
+    /**
+     * Save embedding to cache
+     */
+    private upsertEmbeddingCache;
+    /**
+     * Prune old cache entries if over limit
+     */
+    private pruneEmbeddingCacheIfNeeded;
+}
+
 /**
- * Add session context as frontmatter to content
+ * MemorySearcher - Handles search operations
+ *
+ * Responsible for:
+ * - Executing vector searches
+ * - Executing keyword (FTS) searches
+ * - Merging results with hybrid scoring
  */
-declare function addSessionToContent(content: string, session: SessionContext): string;
+
+type SearchConfig = {
+    hybrid: {
+        enabled: boolean;
+        vectorWeight: number;
+        textWeight: number;
+        candidateMultiplier: number;
+    };
+    query: {
+        maxResults: number;
+        minScore: number;
+    };
+    debug?: DebugFn;
+};
+type SearchResult = {
+    path: string;
+    startLine: number;
+    endLine: number;
+    score: number;
+    snippet: string;
+};
 /**
- * Extract session context from file content
+ * MemorySearcher handles search queries against the indexed memory
  */
-declare function extractSession(content: string): SessionContext | undefined;
+declare class MemorySearcher {
+    private readonly db;
+    private readonly provider;
+    private readonly config;
+    private vectorState;
+    private ftsAvailable;
+    private ensureVectorReadyFn?;
+    constructor(db: DatabaseSync, provider: EmbeddingProvider, config: SearchConfig, options?: {
+        vectorState?: {
+            available: boolean;
+            dims?: number;
+        };
+        ftsAvailable?: boolean;
+        ensureVectorReady?: (dims?: number) => Promise<boolean>;
+    });
+    /**
+     * Update vector/FTS availability (called by parent when extensions load)
+     */
+    setVectorState(state: {
+        available: boolean;
+        dims?: number;
+    }): void;
+    setFtsAvailable(available: boolean): void;
+    /**
+     * Execute a search query
+     */
+    search(query: string, opts?: {
+        maxResults?: number;
+        minScore?: number;
+    }): Promise<SearchResult[]>;
+    /**
+     * Embed a query string with timeout
+     */
+    private embedQueryWithTimeout;
+    /**
+     * Ensure vector extension is ready
+     */
+    private ensureVectorReady;
+}
 
-export { type EmbeddingProvider, type EmbeddingProviderOptions, type EmbeddingProviderResult, type GeminiBatchRequest, type GeminiEmbeddingClient, MEMORY_SEARCH_TOOL, MEMORY_TOOLS, McpServer, type McpServerConfig, type MemoryChunk, type MemoryFileEntry, type MemoryFrontmatter, type MemoryInstance, type MemorySearchParams, MemoryToolExecutor, Minimem, type MinimemConfig, type MinimemSearchResult, type OpenAiBatchRequest, type OpenAiEmbeddingClient, type SessionContext, type ToolDefinition, type ToolInputSchema, type ToolResult, addFrontmatter, addSessionToContent, bm25RankToScore, buildFileEntry, buildFtsQuery, chunkMarkdown, cosineSimilarity, createEmbeddingProvider, createGeminiEmbeddingProvider, createMcpServer, createOpenAiEmbeddingProvider, createToolExecutor, extractSession, generateMcpConfig, getToolDefinitions, hashText, isMemoryPath, listMemoryFiles, mergeHybridResults, normalizeRelPath, parseFrontmatter, runGeminiEmbeddingBatches, runMcpServer, runOpenAiEmbeddingBatches, serializeFrontmatter };
+export { type SearchResult as CoreSearchResult, DebugFn, type EmbeddingProvider, type EmbeddingProviderOptions, type EmbeddingProviderResult, type GeminiBatchRequest, type GeminiEmbeddingClient, type GraphLink, type GraphNeighbor, type IndexStats, type IndexerConfig, KNOWLEDGE_GRAPH_TOOL, KNOWLEDGE_PATH_TOOL, KNOWLEDGE_SEARCH_TOOL, type KnowledgeGraphParams, type KnowledgePathParams, type KnowledgeSearchOptions, type KnowledgeSearchParams, MEMORY_GET_DETAILS_TOOL, MEMORY_SEARCH_TOOL, MEMORY_TOOLS, McpServer, type McpServerConfig, MemoryChunk, MemoryFileEntry, type MemoryGetDetailsParams, type MemoryIndexMeta, MemoryIndexer, type MemoryInstance, type MemorySearchParams, MemorySearcher, MemoryToolExecutor, Minimem, type MinimemConfig, type MinimemSearchResult, type OpenAiBatchRequest, type OpenAiEmbeddingClient, type SearchConfig, type MinimemSearchResult as SearchResult, type ToolDefinition, type ToolInputSchema, type ToolResult, buildKnowledgeFilterSql, createEmbeddingProvider, createGeminiEmbeddingProvider, createMcpServer, createOpenAiEmbeddingProvider, createToolExecutor, generateMcpConfig, getLinksFrom, getLinksTo, getNeighbors, getPathBetween, getToolDefinitions, runGeminiEmbeddingBatches, runMcpServer, runOpenAiEmbeddingBatches };