@memvid/sdk 2.0.113

package/dist/adapters/crewai.d.ts

@@ -0,0 +1,23 @@
+/**
+ * CrewAI adapter exposing Memvid core methods as CrewAI-compatible tools.
+ *
+ * CrewAI.js tools follow the OpenAI function calling format. This adapter
+ * provides three tools compatible with CrewAI's agent system:
+ * - memvid_put: Store documents in memory
+ * - memvid_find: Search for relevant documents
+ * - memvid_ask: Query with RAG-style answer synthesis
+ *
+ * Usage:
+ *    import { use } from "memvid-sdk";
+ *
+ *    const mem = await use("crewai", "knowledge.mv2");
+ *
+ *    // Access tools for CrewAI agents
+ *    const tools = mem.tools; // Array of tool definitions
+ *
+ *    // Use with CrewAI (tools follow OpenAI function calling format)
+ *    // Tools can be used with any agent framework supporting this format
+ *
+ * Note: CrewAI for Node.js uses OpenAI-compatible tool definitions.
+ */
+export {};

package/dist/adapters/crewai.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * CrewAI adapter exposing Memvid core methods as CrewAI-compatible tools.
+ *
+ * CrewAI.js tools follow the OpenAI function calling format. This adapter
+ * provides three tools compatible with CrewAI's agent system:
+ * - memvid_put: Store documents in memory
+ * - memvid_find: Search for relevant documents
+ * - memvid_ask: Query with RAG-style answer synthesis
+ *
+ * Usage:
+ *    import { use } from "memvid-sdk";
+ *
+ *    const mem = await use("crewai", "knowledge.mv2");
+ *
+ *    // Access tools for CrewAI agents
+ *    const tools = mem.tools; // Array of tool definitions
+ *
+ *    // Use with CrewAI (tools follow OpenAI function calling format)
+ *    // Tools can be used with any agent framework supporting this format
+ *
+ * Note: CrewAI for Node.js uses OpenAI-compatible tool definitions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const noop_1 = require("../noop");
+const registry_1 = require("../registry");
+const KIND = "crewai";
+(0, registry_1.register)(KIND, async (core, _apiKey) => {
+    // CrewAI uses OpenAI-compatible tool definitions
+    // No external imports needed - we create the tool structure directly
+    // Define the memvid_put tool
+    const memvidPutTool = {
+        type: "function",
+        function: {
+            name: "memvid_put",
+            description: "Store a document in Memvid memory. Use this to save information " +
+                "that should be retrievable later. Returns the frame ID of the stored document.",
+            parameters: {
+                type: "object",
+                properties: {
+                    title: {
+                        type: "string",
+                        description: "Title of the document",
+                    },
+                    label: {
+                        type: "string",
+                        description: "Category or label for the document",
+                    },
+                    text: {
+                        type: "string",
+                        description: "Text content to store",
+                    },
+                    metadata: {
+                        type: "object",
+                        description: "Optional key-value metadata",
+                        additionalProperties: true,
+                    },
+                },
+                required: ["title", "label", "text"],
+            },
+        },
+        execute: async (args) => {
+            const frameId = await core.put({
+                title: args.title,
+                label: args.label,
+                text: args.text,
+                metadata: args.metadata ?? {},
+                enable_embedding: true,
+                auto_tag: true,
+                extract_dates: true,
+            });
+            return `Document stored with frame_id: ${frameId}`;
+        },
+    };
+    // Define the memvid_find tool
+    const memvidFindTool = {
+        type: "function",
+        function: {
+            name: "memvid_find",
+            description: "Search Memvid memory for documents matching a query. " +
+                "Returns the most relevant documents with snippets and metadata.",
+            parameters: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "Search query string",
+                    },
+                    top_k: {
+                        type: "number",
+                        description: "Number of results to return (default: 5)",
+                    },
+                },
+                required: ["query"],
+            },
+        },
+        execute: async (args) => {
+            const query = args.query;
+            const topK = args.top_k ?? 5;
+            const response = (await core.find(query, { k: topK }));
+            const hits = response.hits ?? [];
+            if (hits.length === 0) {
+                return `No results found for query: '${query}'`;
+            }
+            const results = [];
+            for (let i = 0; i < hits.length; i++) {
+                const hit = hits[i];
+                const title = hit.title ?? "Untitled";
+                const snippet = (hit.text ?? hit.snippet ?? "").slice(0, 200);
+                const score = hit.score ?? 0;
+                results.push(`${i + 1}. [${title}] (score: ${score.toFixed(2)}): ${snippet}...`);
+            }
+            return `Found ${hits.length} results:\n${results.join("\n")}`;
+        },
+    };
+    // Define the memvid_ask tool
+    const memvidAskTool = {
+        type: "function",
+        function: {
+            name: "memvid_ask",
+            description: "Ask a question and get an answer synthesized from Memvid memory. " +
+                "Uses retrieval-augmented generation to find relevant context and generate a response.",
+            parameters: {
+                type: "object",
+                properties: {
+                    question: {
+                        type: "string",
+                        description: "Question to answer",
+                    },
+                    mode: {
+                        type: "string",
+                        enum: ["auto", "lex", "sem"],
+                        description: "Search mode: 'auto' (hybrid), 'lex' (keyword), or 'sem' (semantic)",
+                    },
+                },
+                required: ["question"],
+            },
+        },
+        execute: async (args) => {
+            const question = args.question;
+            const mode = args.mode ?? "auto";
+            const response = (await core.ask(question, { mode }));
+            const answer = response.answer ?? "No answer generated";
+            const sources = response.sources ?? [];
+            let result = `Answer: ${answer}`;
+            if (sources.length > 0) {
+                const sourceTitles = sources.slice(0, 3).map((s) => s.title ?? "Unknown");
+                result += `\n\nSources: ${sourceTitles.join(", ")}`;
+            }
+            return result;
+        },
+    };
+    const tools = [memvidPutTool, memvidFindTool, memvidAskTool];
+    return {
+        tools,
+        functions: [],
+        nodes: (0, noop_1.createNoOp)("crewai adapter nodes not provided", "memvid.adapters.crewai.nodes"),
+        asQueryEngine: null,
+    };
+});

package/dist/adapters/google_adk.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Google ADK (Agent Development Kit) adapter exposing Memvid core methods as ADK function tools.
+ *
+ * This adapter provides tools formatted for Google's Agent Development Kit.
+ * The tools can be used directly with ADK agents and the Gemini API.
+ *
+ * Usage:
+ *    import { use } from "memvid-sdk";
+ *
+ *    const mem = await use("google-adk", "knowledge.mv2");
+ *
+ *    // Access tools for Google ADK
+ *    const tools = mem.tools; // Array of ADK function declarations
+ *    const executors = mem.functions; // Function executors
+ *
+ *    // Use with Gemini API or ADK TypeScript
+ *    import { GoogleGenerativeAI } from "@google/generative-ai";
+ *
+ *    const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);
+ *    const model = genAI.getGenerativeModel({
+ *      model: "gemini-2.0-flash",
+ *      tools: [{ functionDeclarations: mem.tools }],
+ *    });
+ */
+export {};

package/dist/adapters/google_adk.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * Google ADK (Agent Development Kit) adapter exposing Memvid core methods as ADK function tools.
+ *
+ * This adapter provides tools formatted for Google's Agent Development Kit.
+ * The tools can be used directly with ADK agents and the Gemini API.
+ *
+ * Usage:
+ *    import { use } from "memvid-sdk";
+ *
+ *    const mem = await use("google-adk", "knowledge.mv2");
+ *
+ *    // Access tools for Google ADK
+ *    const tools = mem.tools; // Array of ADK function declarations
+ *    const executors = mem.functions; // Function executors
+ *
+ *    // Use with Gemini API or ADK TypeScript
+ *    import { GoogleGenerativeAI } from "@google/generative-ai";
+ *
+ *    const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);
+ *    const model = genAI.getGenerativeModel({
+ *      model: "gemini-2.0-flash",
+ *      tools: [{ functionDeclarations: mem.tools }],
+ *    });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const noop_1 = require("../noop");
+const registry_1 = require("../registry");
+const KIND = "google-adk";
+(0, registry_1.register)(KIND, async (core, apiKey) => {
+    // Set up API key if provided
+    const key = apiKey?.google ?? apiKey?.default;
+    if (key && !process.env.GOOGLE_API_KEY) {
+        process.env.GOOGLE_API_KEY = key;
+    }
+    // Define Google ADK function declarations
+    const functionDeclarations = [
+        {
+            name: "memvid_put",
+            description: "Store a document in Memvid memory for later retrieval. " +
+                "Use this to save information that should be searchable later.",
+            parameters: {
+                type: "object",
+                properties: {
+                    title: {
+                        type: "string",
+                        description: "Title of the document",
+                    },
+                    label: {
+                        type: "string",
+                        description: "Category or label for the document",
+                    },
+                    text: {
+                        type: "string",
+                        description: "Text content to store",
+                    },
+                    metadata: {
+                        type: "object",
+                        description: "Optional key-value metadata",
+                    },
+                },
+                required: ["title", "label", "text"],
+            },
+        },
+        {
+            name: "memvid_find",
+            description: "Search Memvid memory for documents matching a query. " +
+                "Returns the most relevant documents with snippets and scores.",
+            parameters: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "Search query string",
+                    },
+                    top_k: {
+                        type: "number",
+                        description: "Number of results to return (default: 5)",
+                    },
+                },
+                required: ["query"],
+            },
+        },
+        {
+            name: "memvid_ask",
+            description: "Ask a question and get an answer synthesized from Memvid memory " +
+                "using retrieval-augmented generation.",
+            parameters: {
+                type: "object",
+                properties: {
+                    question: {
+                        type: "string",
+                        description: "Question to answer",
+                    },
+                    mode: {
+                        type: "string",
+                        enum: ["auto", "lex", "sem"],
+                        description: "Search mode: 'auto' (hybrid), 'lex' (keyword), or 'sem' (semantic)",
+                    },
+                },
+                required: ["question"],
+            },
+        },
+    ];
+    // Create executor functions for each tool
+    const executors = {
+        memvid_put: async (args) => {
+            const frameId = await core.put({
+                title: args.title,
+                label: args.label,
+                text: args.text,
+                metadata: args.metadata ?? {},
+                enable_embedding: true,
+                auto_tag: true,
+                extract_dates: true,
+            });
+            return `Document stored with frame_id: ${frameId}`;
+        },
+        memvid_find: async (args) => {
+            const query = args.query;
+            const topK = args.top_k ?? 5;
+            const response = (await core.find(query, { k: topK }));
+            const hits = response.hits ?? [];
+            if (hits.length === 0) {
+                return `No results found for query: '${query}'`;
+            }
+            const results = [];
+            for (let i = 0; i < hits.length; i++) {
+                const hit = hits[i];
+                const title = hit.title ?? "Untitled";
+                const snippet = (hit.text ?? hit.snippet ?? "").slice(0, 200);
+                const score = hit.score ?? 0;
+                results.push(`${i + 1}. [${title}] (score: ${score.toFixed(2)}): ${snippet}...`);
+            }
+            return `Found ${hits.length} results:\n${results.join("\n")}`;
+        },
+        memvid_ask: async (args) => {
+            const question = args.question;
+            const mode = args.mode ?? "auto";
+            const response = (await core.ask(question, { mode }));
+            const answer = response.answer ?? "No answer generated";
+            const sources = response.sources ?? [];
+            let result = `Answer: ${answer}`;
+            if (sources.length > 0) {
+                const sourceTitles = sources.slice(0, 3).map((s) => s.title ?? "Unknown");
+                result += `\n\nSources: ${sourceTitles.join(", ")}`;
+            }
+            return result;
+        },
+    };
+    // Return tools in Google ADK format
+    return {
+        tools: functionDeclarations, // FunctionDeclaration array for Gemini/ADK
+        functions: executors, // Executors keyed by function name
+        nodes: (0, noop_1.createNoOp)("google-adk adapter does not provide nodes", "memvid.adapters.google-adk.nodes"),
+        asQueryEngine: null,
+    };
+});

package/dist/adapters/haystack.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapters/haystack.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const noop_1 = require("../noop");
+const registry_1 = require("../registry");
+const KIND = "haystack";
+(0, registry_1.register)(KIND, async () => ({
+    tools: (0, noop_1.createNoOp)("haystack adapter unavailable; install 'haystack-ai' to enable", "memvid.adapters.haystack.tools"),
+    functions: [],
+    nodes: (0, noop_1.createNoOp)("haystack adapter nodes unavailable", "memvid.adapters.haystack.nodes"),
+    asQueryEngine: null,
+}));

package/dist/adapters/langchain.d.ts

@@ -0,0 +1,28 @@
+/**
+ * LangChain adapter exposing Memvid core methods as tools.
+ *
+ * LangChain.js tools are created using the DynamicStructuredTool class or
+ * by implementing the StructuredTool interface. This adapter provides three tools:
+ * - memvid_put: Store documents in memory
+ * - memvid_find: Search for relevant documents
+ * - memvid_ask: Query with RAG-style answer synthesis
+ *
+ * Usage:
+ *    import { use } from "memvid-sdk";
+ *
+ *    const mem = await use("langchain", "knowledge.mv2");
+ *
+ *    // Access tools for LangChain agents
+ *    const tools = mem.tools; // Array of DynamicStructuredTool objects
+ *
+ *    // Use with LangChain agent
+ *    import { ChatOpenAI } from "@langchain/openai";
+ *    import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
+ *
+ *    const llm = new ChatOpenAI({ model: "gpt-4" });
+ *    const agent = createToolCallingAgent({ llm, tools: mem.tools, prompt });
+ *    const executor = AgentExecutor.fromAgentAndTools({ agent, tools: mem.tools });
+ *
+ * Note: Requires @langchain/core package to be installed.
+ */
+export {};

package/dist/adapters/langchain.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * LangChain adapter exposing Memvid core methods as tools.
+ *
+ * LangChain.js tools are created using the DynamicStructuredTool class or
+ * by implementing the StructuredTool interface. This adapter provides three tools:
+ * - memvid_put: Store documents in memory
+ * - memvid_find: Search for relevant documents
+ * - memvid_ask: Query with RAG-style answer synthesis
+ *
+ * Usage:
+ *    import { use } from "memvid-sdk";
+ *
+ *    const mem = await use("langchain", "knowledge.mv2");
+ *
+ *    // Access tools for LangChain agents
+ *    const tools = mem.tools; // Array of DynamicStructuredTool objects
+ *
+ *    // Use with LangChain agent
+ *    import { ChatOpenAI } from "@langchain/openai";
+ *    import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
+ *
+ *    const llm = new ChatOpenAI({ model: "gpt-4" });
+ *    const agent = createToolCallingAgent({ llm, tools: mem.tools, prompt });
+ *    const executor = AgentExecutor.fromAgentAndTools({ agent, tools: mem.tools });
+ *
+ * Note: Requires @langchain/core package to be installed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const noop_1 = require("../noop");
+const registry_1 = require("../registry");
+const KIND = "langchain";
+// Dynamic import helper to avoid TypeScript module resolution issues
+async function tryImportLangChain() {
+    try {
+        // Use require for better compatibility with npm module resolution
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const toolsModule = require("@langchain/core/tools");
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const zodModule = require("zod");
+        return {
+            tool: toolsModule.tool,
+            z: zodModule.z,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+(0, registry_1.register)(KIND, async (core, _apiKey) => {
+    // Try to import LangChain
+    const imports = await tryImportLangChain();
+    if (!imports) {
+        return {
+            tools: (0, noop_1.createNoOp)("langchain adapter unavailable; install '@langchain/core' and 'zod' to enable", "memvid.adapters.langchain.tools"),
+            functions: [],
+            nodes: (0, noop_1.createNoOp)("langchain adapter does not provide nodes", "memvid.adapters.langchain.nodes"),
+            asQueryEngine: null,
+        };
+    }
+    const { tool, z } = imports;
+    // Define the memvid_put tool using the `tool` function (compatible with createReactAgent)
+    const memvidPut = tool(async (params) => {
+        const frameId = await core.put({
+            title: params.title,
+            label: params.label,
+            text: params.text,
+            metadata: params.metadata ?? {},
+            enable_embedding: true,
+            auto_tag: true,
+            extract_dates: true,
+        });
+        return `Document stored with frame_id: ${frameId}`;
+    }, {
+        name: "memvid_put",
+        description: "Store a document in Memvid memory for later retrieval. " +
+            "Use this tool to save information that should be searchable later. " +
+            "The document will be indexed for both keyword and semantic search.",
+        schema: z.object({
+            title: z.string().describe("Title of the document"),
+            label: z.string().describe("Category or label for the document"),
+            text: z.string().describe("Text content to store"),
+            metadata: z
+                .record(z.unknown())
+                .optional()
+                .describe("Optional key-value metadata"),
+        }),
+    });
+    // Define the memvid_find tool
+    const memvidFind = tool(async (params) => {
+        const response = (await core.find(params.query, {
+            k: params.top_k ?? 5,
+        }));
+        const hits = response.hits ?? [];
+        if (hits.length === 0) {
+            return `No results found for query: '${params.query}'`;
+        }
+        const results = [];
+        for (let i = 0; i < hits.length; i++) {
+            const hit = hits[i];
+            const title = hit.title ?? "Untitled";
+            const snippet = (hit.text ?? hit.snippet ?? "").slice(0, 200);
+            const score = hit.score ?? 0;
+            results.push(`${i + 1}. [${title}] (score: ${score.toFixed(2)}): ${snippet}...`);
+        }
+        return `Found ${hits.length} results:\n${results.join("\n")}`;
+    }, {
+        name: "memvid_find",
+        description: "Search Memvid memory for documents matching a query. " +
+            "Returns the most relevant documents with snippets and metadata. " +
+            "Use this when you need to find specific information in stored documents.",
+        schema: z.object({
+            query: z.string().describe("Search query string"),
+            top_k: z
+                .number()
+                .optional()
+                .default(5)
+                .describe("Number of results to return (default: 5)"),
+        }),
+    });
+    // Define the memvid_ask tool
+    const memvidAsk = tool(async (params) => {
+        const response = (await core.ask(params.question, {
+            mode: params.mode ?? "auto",
+        }));
+        const answer = response.answer ?? "No answer generated";
+        const sources = response.sources ?? [];
+        let result = `Answer: ${answer}`;
+        if (sources.length > 0) {
+            const sourceTitles = sources.slice(0, 3).map((s) => s.title ?? "Unknown");
+            result += `\n\nSources: ${sourceTitles.join(", ")}`;
+        }
+        return result;
+    }, {
+        name: "memvid_ask",
+        description: "Ask a question and get an answer synthesized from Memvid memory. " +
+            "Uses retrieval-augmented generation to find relevant context " +
+            "and generate a comprehensive response. Best for complex questions " +
+            "that require synthesizing information from multiple sources.",
+        schema: z.object({
+            question: z.string().describe("Question to answer"),
+            mode: z
+                .enum(["auto", "lex", "sem"])
+                .optional()
+                .default("auto")
+                .describe("Search mode: 'auto' (hybrid), 'lex' (keyword), or 'sem' (semantic)"),
+        }),
+    });
+    const tools = [memvidPut, memvidFind, memvidAsk];
+    return {
+        tools,
+        functions: [],
+        nodes: (0, noop_1.createNoOp)("langchain adapter does not provide nodes", "memvid.adapters.langchain.nodes"),
+        asQueryEngine: null,
+    };
+});

package/dist/adapters/langgraph.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapters/langgraph.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const noop_1 = require("../noop");
+const registry_1 = require("../registry");
+const KIND = "langgraph";
+(0, registry_1.register)(KIND, async () => ({
+    tools: (0, noop_1.createNoOp)("langgraph adapter unavailable; install 'langgraph' to enable", "memvid.adapters.langgraph.tools"),
+    functions: [],
+    nodes: (0, noop_1.createNoOp)("langgraph adapter nodes unavailable", "memvid.adapters.langgraph.nodes"),
+    asQueryEngine: null,
+}));

package/dist/adapters/llamaindex.d.ts

@@ -0,0 +1,33 @@
+/**
+ * LlamaIndex adapter exposing Memvid helpers as FunctionTool and QueryEngineTool.
+ *
+ * LlamaIndex.TS uses FunctionTool for wrapping functions and QueryEngineTool
+ * for wrapping query engines. This adapter provides:
+ * - memvid_put: Store documents in memory
+ * - memvid_find: Search for relevant documents
+ * - memvid_ask: Query with RAG-style answer synthesis
+ * - asQueryEngine(): Factory for creating a LlamaIndex QueryEngine
+ *
+ * Usage:
+ *    import { use } from "memvid-sdk";
+ *
+ *    const mem = await use("llamaindex", "knowledge.mv2");
+ *
+ *    // Access tools for LlamaIndex agents
+ *    const tools = mem.tools; // Array of FunctionTool objects
+ *
+ *    // Use with LlamaIndex agent
+ *    import { OpenAIAgent } from "llamaindex";
+ *
+ *    const agent = new OpenAIAgent({
+ *      tools: mem.tools,
+ *    });
+ *    const response = await agent.chat({ message: "What do you know about X?" });
+ *
+ *    // Or use as a QueryEngine
+ *    const queryEngine = mem.asQueryEngine();
+ *    const result = await queryEngine.query({ query: "Summarize the key points" });
+ *
+ * Note: Requires llamaindex package to be installed.
+ */
+export {};