engram-sdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,204 @@
+import { z } from 'zod';
+export declare const MemoryType: z.ZodEnum<["episodic", "semantic", "procedural"]>;
+export type MemoryType = z.infer<typeof MemoryType>;
+export declare const SourceType: z.ZodEnum<["conversation", "observation", "inference", "consolidation", "external", "manual"]>;
+export type SourceType = z.infer<typeof SourceType>;
+export declare const EdgeType: z.ZodEnum<["supports", "contradicts", "elaborates", "supersedes", "causes", "caused_by", "part_of", "instance_of", "associated_with", "temporal_next", "derived_from"]>;
+export type EdgeType = z.infer<typeof EdgeType>;
+export declare const MemoryStatus: z.ZodEnum<["active", "pending", "fulfilled", "superseded", "archived"]>;
+export type MemoryStatus = z.infer<typeof MemoryStatus>;
+export declare const Visibility: z.ZodEnum<["private", "owner_agents", "shared", "public"]>;
+export type Visibility = z.infer<typeof Visibility>;
+export interface Memory {
+    id: string;
+    type: MemoryType;
+    content: string;
+    summary: string;
+    source: {
+        type: SourceType;
+        sessionId?: string;
+        agentId?: string;
+        evidence?: string[];
+        timestamp: string;
+    };
+    createdAt: string;
+    lastAccessedAt: string;
+    lastModifiedAt: string;
+    accessCount: number;
+    expiresAt?: string;
+    salience: number;
+    confidence: number;
+    stability: number;
+    entities: string[];
+    topics: string[];
+    status: MemoryStatus;
+    visibility: Visibility;
+    embedding?: number[];
+}
+export interface Edge {
+    id: string;
+    sourceId: string;
+    targetId: string;
+    type: EdgeType;
+    strength: number;
+    createdAt: string;
+}
+export interface Entity {
+    id: string;
+    name: string;
+    type: string;
+    aliases: string[];
+    properties: Record<string, unknown>;
+    firstSeen: string;
+    lastSeen: string;
+    memoryCount: number;
+    importance: number;
+}
+export declare const RememberInputSchema: z.ZodObject<{
+    content: z.ZodString;
+    type: z.ZodDefault<z.ZodEnum<["episodic", "semantic", "procedural"]>>;
+    summary: z.ZodOptional<z.ZodString>;
+    entities: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    topics: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    salience: z.ZodDefault<z.ZodNumber>;
+    confidence: z.ZodDefault<z.ZodNumber>;
+    status: z.ZodDefault<z.ZodEnum<["active", "pending", "fulfilled", "superseded", "archived"]>>;
+    visibility: z.ZodDefault<z.ZodEnum<["private", "owner_agents", "shared", "public"]>>;
+    source: z.ZodOptional<z.ZodObject<{
+        type: z.ZodDefault<z.ZodEnum<["conversation", "observation", "inference", "consolidation", "external", "manual"]>>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        agentId: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        type: "conversation" | "observation" | "inference" | "consolidation" | "external" | "manual";
+        sessionId?: string | undefined;
+        agentId?: string | undefined;
+        evidence?: string[] | undefined;
+    }, {
+        sessionId?: string | undefined;
+        type?: "conversation" | "observation" | "inference" | "consolidation" | "external" | "manual" | undefined;
+        agentId?: string | undefined;
+        evidence?: string[] | undefined;
+    }>>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "episodic" | "semantic" | "procedural";
+    status: "active" | "pending" | "fulfilled" | "superseded" | "archived";
+    content: string;
+    entities: string[];
+    topics: string[];
+    salience: number;
+    confidence: number;
+    visibility: "private" | "owner_agents" | "shared" | "public";
+    summary?: string | undefined;
+    source?: {
+        type: "conversation" | "observation" | "inference" | "consolidation" | "external" | "manual";
+        sessionId?: string | undefined;
+        agentId?: string | undefined;
+        evidence?: string[] | undefined;
+    } | undefined;
+    expiresAt?: string | undefined;
+}, {
+    content: string;
+    type?: "episodic" | "semantic" | "procedural" | undefined;
+    status?: "active" | "pending" | "fulfilled" | "superseded" | "archived" | undefined;
+    summary?: string | undefined;
+    entities?: string[] | undefined;
+    topics?: string[] | undefined;
+    salience?: number | undefined;
+    confidence?: number | undefined;
+    visibility?: "private" | "owner_agents" | "shared" | "public" | undefined;
+    source?: {
+        sessionId?: string | undefined;
+        type?: "conversation" | "observation" | "inference" | "consolidation" | "external" | "manual" | undefined;
+        agentId?: string | undefined;
+        evidence?: string[] | undefined;
+    } | undefined;
+    expiresAt?: string | undefined;
+}>;
+export type RememberInput = z.input<typeof RememberInputSchema>;
+export type RememberParsed = z.output<typeof RememberInputSchema>;
+export declare const RecallInputSchema: z.ZodObject<{
+    context: z.ZodString;
+    entities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    topics: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    types: z.ZodOptional<z.ZodArray<z.ZodEnum<["episodic", "semantic", "procedural"]>, "many">>;
+    temporalFocus: z.ZodDefault<z.ZodEnum<["recent", "upcoming", "all"]>>;
+    minSalience: z.ZodDefault<z.ZodNumber>;
+    minConfidence: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    spread: z.ZodDefault<z.ZodBoolean>;
+    spreadHops: z.ZodDefault<z.ZodNumber>;
+    spreadDecay: z.ZodDefault<z.ZodNumber>;
+    spreadMinActivation: z.ZodDefault<z.ZodNumber>;
+    spreadEntityHops: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    context: string;
+    temporalFocus: "recent" | "upcoming" | "all";
+    minSalience: number;
+    minConfidence: number;
+    limit: number;
+    spread: boolean;
+    spreadHops: number;
+    spreadDecay: number;
+    spreadMinActivation: number;
+    spreadEntityHops: boolean;
+    entities?: string[] | undefined;
+    topics?: string[] | undefined;
+    types?: ("episodic" | "semantic" | "procedural")[] | undefined;
+}, {
+    context: string;
+    entities?: string[] | undefined;
+    topics?: string[] | undefined;
+    types?: ("episodic" | "semantic" | "procedural")[] | undefined;
+    temporalFocus?: "recent" | "upcoming" | "all" | undefined;
+    minSalience?: number | undefined;
+    minConfidence?: number | undefined;
+    limit?: number | undefined;
+    spread?: boolean | undefined;
+    spreadHops?: number | undefined;
+    spreadDecay?: number | undefined;
+    spreadMinActivation?: number | undefined;
+    spreadEntityHops?: boolean | undefined;
+}>;
+export type RecallInput = z.input<typeof RecallInputSchema>;
+export type RecallParsed = z.output<typeof RecallInputSchema>;
+export interface ConsolidationReport {
+    startedAt: string;
+    completedAt: string;
+    episodesProcessed: number;
+    semanticMemoriesCreated: number;
+    semanticMemoriesUpdated: number;
+    entitiesDiscovered: number;
+    connectionsFormed: number;
+    contradictionsFound: number;
+    memoriesDecayed: number;
+    memoriesArchived: number;
+}
+export interface VaultConfig {
+    /** Unique owner identifier */
+    owner: string;
+    /** Path to SQLite database file (default: ./engram.db) */
+    dbPath?: string;
+    /** Agent ID for source tracking */
+    agentId?: string;
+    /** Session ID for source tracking */
+    sessionId?: string;
+    /** LLM provider for consolidation and embeddings */
+    llm?: {
+        provider: 'anthropic' | 'openai' | 'gemini';
+        apiKey: string;
+        model?: string;
+        embeddingModel?: string;
+    };
+    /** Decay settings */
+    decay?: {
+        /** Base half-life in hours for new memories (default: 168 = 1 week) */
+        halfLifeHours?: number;
+        /** Retrievability threshold below which memories are archived (default: 0.05) */
+        archiveThreshold?: number;
+        /** Salience weight factor for stability (default: 2.0) */
+        salienceWeight?: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+// ============================================================
+// Memory Types — The core data model for Engram
+// ============================================================
+export const MemoryType = z.enum(['episodic', 'semantic', 'procedural']);
+export const SourceType = z.enum([
+    'conversation', // From a chat/interaction
+    'observation', // Agent observed something
+    'inference', // Derived from other memories
+    'consolidation', // Created during consolidation
+    'external', // Imported from external source
+    'manual', // Explicitly created by human
+]);
+export const EdgeType = z.enum([
+    'supports', // This memory supports another
+    'contradicts', // This memory contradicts another
+    'elaborates', // This memory adds detail to another
+    'supersedes', // This memory replaces another
+    'causes', // This memory describes a cause
+    'caused_by', // This memory describes an effect
+    'part_of', // This memory is part of a larger concept
+    'instance_of', // This is a specific instance of a general pattern
+    'associated_with', // General association
+    'temporal_next', // This happened after another memory
+    'derived_from', // Created from this memory during consolidation
+]);
+export const MemoryStatus = z.enum([
+    'active', // Current, valid memory
+    'pending', // Commitment/plan not yet fulfilled
+    'fulfilled', // Commitment completed
+    'superseded', // Replaced by newer information
+    'archived', // Decayed beyond usefulness
+]);
+export const Visibility = z.enum([
+    'private', // Only the creating agent
+    'owner_agents', // All of the owner's agents
+    'shared', // Specific principals
+    'public', // Anyone
+]);
+// ============================================================
+// API Input Types
+// ============================================================
+export const RememberInputSchema = z.object({
+    content: z.string().min(1),
+    type: MemoryType.default('episodic'),
+    summary: z.string().optional(),
+    entities: z.array(z.string()).default([]),
+    topics: z.array(z.string()).default([]),
+    salience: z.number().min(0).max(1).default(0.5),
+    confidence: z.number().min(0).max(1).default(0.8),
+    status: MemoryStatus.default('active'),
+    visibility: Visibility.default('owner_agents'),
+    source: z.object({
+        type: SourceType.default('conversation'),
+        sessionId: z.string().optional(),
+        agentId: z.string().optional(),
+        evidence: z.array(z.string()).optional(),
+    }).optional(),
+    expiresAt: z.string().optional(),
+});
+export const RecallInputSchema = z.object({
+    context: z.string().min(1),
+    entities: z.array(z.string()).optional(),
+    topics: z.array(z.string()).optional(),
+    types: z.array(MemoryType).optional(),
+    temporalFocus: z.enum(['recent', 'upcoming', 'all']).default('all'),
+    minSalience: z.number().min(0).max(1).default(0),
+    minConfidence: z.number().min(0).max(1).default(0),
+    limit: z.number().int().min(1).max(100).default(20),
+    // Spreading activation parameters
+    spread: z.boolean().default(true), // Enable spreading activation (default ON)
+    spreadHops: z.number().int().min(0).max(5).default(2), // Max graph hops
+    spreadDecay: z.number().min(0).max(1).default(0.5), // Activation decay per hop
+    spreadMinActivation: z.number().min(0).max(1).default(0.1), // Stop spreading below this
+    spreadEntityHops: z.boolean().default(true), // Also spread via shared entities (not just edges)
+});
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+DAA+D;AAC/D,gDAAgD;AAChD,+DAA+D;AAE/D,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC;AAGzE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC;IAC/B,cAAc,EAAI,0BAA0B;IAC5C,aAAa,EAAK,2BAA2B;IAC7C,WAAW,EAAO,8BAA8B;IAChD,eAAe,EAAG,+BAA+B;IACjD,UAAU,EAAQ,gCAAgC;IAClD,QAAQ,EAAU,8BAA8B;CACjD,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC;IAC7B,UAAU,EAAU,+BAA+B;IACnD,aAAa,EAAO,kCAAkC;IACtD,YAAY,EAAQ,qCAAqC;IACzD,YAAY,EAAQ,+BAA+B;IACnD,QAAQ,EAAY,gCAAgC;IACpD,WAAW,EAAS,kCAAkC;IACtD,SAAS,EAAW,0CAA0C;IAC9D,aAAa,EAAO,mDAAmD;IACvE,iBAAiB,EAAG,sBAAsB;IAC1C,eAAe,EAAK,qCAAqC;IACzD,cAAc,EAAM,gDAAgD;CACrE,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,IAAI,CAAC;IACjC,QAAQ,EAAQ,wBAAwB;IACxC,SAAS,EAAO,oCAAoC;IACpD,WAAW,EAAK,uBAAuB;IACvC,YAAY,EAAI,gCAAgC;IAChD,UAAU,EAAM,4BAA4B;CAC7C,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC;IAC/B,SAAS,EAAS,0BAA0B;IAC5C,cAAc,EAAI,4BAA4B;IAC9C,QAAQ,EAAU,sBAAsB;IACxC,QAAQ,EAAU,SAAS;CAC5B,CAAC,CAAC;AA6EH,+DAA+D;AAC/D,kBAAkB;AAClB,+DAA+D;AAE/D,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC;IACpC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACzC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACvC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;IAC/C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;IACjD,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,QAAQ,CAAC;IACtC,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC;IAC9C,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC;QACxC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAChC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC9B,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;KACzC,CAAC,CAAC,QAAQ,EAAE;IACb,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACxC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACtC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,QAAQ,EAAE;IACrC,aAAa,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACnE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAChD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAClD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAEnD,kCAAkC;IAClC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAgB,2CAA2C;IAC5F,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAG,iBAAiB;IACzE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAM,2BAA2B;IACnF,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,4BAA4B;IACxF,gBAAgB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAM,mDAAmD;CACrG,CAAC,CAAC"}

package/dist/vault.d.ts

@@ -0,0 +1,116 @@
+import type { Memory, Edge, Entity, RememberInput, RecallInput, ConsolidationReport, VaultConfig } from './types.js';
+import type { EmbeddingProvider } from './embeddings.js';
+export declare class Vault {
+    private store;
+    private config;
+    private embedder;
+    /** Track all in-flight embedding computations so close() can await them */
+    private pendingEmbeddings;
+    constructor(config: VaultConfig, embedder?: EmbeddingProvider);
+    remember(input: RememberInput | string): Memory;
+    /**
+     * Dedup: after storing a memory and its embedding, check if a near-identical
+     * memory already exists. If so, keep the better one (higher salience/confidence,
+     * or newer if semantic) and supersede the other.
+     *
+     * Threshold: cosine distance <= 0.08 (similarity >= 0.92) = near-duplicate.
+     * Only dedup within the same type (don't merge episodic into semantic).
+     */
+    private dedup;
+    /** Compute embedding and store it — can be awaited if needed */
+    computeAndStoreEmbedding(memoryId: string, content: string): Promise<void>;
+    /** Batch compute embeddings for all memories missing them */
+    backfillEmbeddings(): Promise<number>;
+    recall(input: RecallInput | string): Promise<Memory[]>;
+    private spreadActivation;
+    private edgeTypeWeight;
+    forget(id: string, hard?: boolean): void;
+    connect(sourceId: string, targetId: string, type: Edge['type'], strength?: number): Edge;
+    neighbors(memoryId: string, depth?: number): Memory[];
+    consolidate(): Promise<ConsolidationReport>;
+    briefing(context?: string, limit?: number): Promise<{
+        summary: string;
+        keyFacts: Array<{
+            content: string;
+            salience: number;
+            entities: string[];
+        }>;
+        activeCommitments: Array<{
+            content: string;
+            status: string;
+            entities: string[];
+        }>;
+        recentActivity: Array<{
+            content: string;
+            when: string;
+        }>;
+        topEntities: Array<{
+            name: string;
+            type: string;
+            memoryCount: number;
+        }>;
+        contradictions: Array<{
+            a: string;
+            b: string;
+        }>;
+        stats: ReturnType<Vault['stats']>;
+    }>;
+    contradictions(limit?: number): Array<{
+        memoryA: Memory;
+        memoryB: Memory;
+        type: 'explicit_edge' | 'superseded_conflict' | 'entity_conflict';
+        description: string;
+    }>;
+    surface(input: {
+        context: string;
+        /** Currently active entities (people, projects in the conversation) */
+        activeEntities?: string[];
+        /** Currently active topics */
+        activeTopics?: string[];
+        /** Memory IDs the agent has already seen this session (don't re-surface) */
+        seen?: string[];
+        /** Minimum salience to surface (default: 0.4 — only important stuff) */
+        minSalience?: number;
+        /** Minimum hours since last accessed (default: 1 — don't repeat recent) */
+        minHoursSinceAccess?: number;
+        /** Maximum results (default: 3 — keep it focused) */
+        limit?: number;
+        /** Relevance threshold 0-1 (default: 0.3 — must be genuinely relevant) */
+        relevanceThreshold?: number;
+    }): Promise<Array<{
+        memory: Memory;
+        reason: string;
+        relevance: number;
+        activationPath: string;
+    }>>;
+    /** Classify why a memory is being proactively surfaced */
+    private classifySurfaceReason;
+    /** Trace how a memory was activated (simplified path description) */
+    private traceActivationPath;
+    /** Composite ranking score for proactive surfacing */
+    private surfaceRankScore;
+    stats(): {
+        total: number;
+        episodic: number;
+        semantic: number;
+        procedural: number;
+        entities: number;
+    };
+    entities(): Entity[];
+    export(): {
+        memories: Memory[];
+        edges: Edge[];
+        entities: Entity[];
+    };
+    close(): Promise<void>;
+    /** Flush all pending embedding computations without closing */
+    flush(): Promise<number>;
+    private extractWithLLM;
+    private ruleBasedConsolidate;
+    private llmConsolidate;
+    private callLLM;
+    private keywordSearch;
+    private extractKeywords;
+    private addCandidate;
+}
+//# sourceMappingURL=vault.d.ts.map

package/dist/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":"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"}