mem0-mcp 0.2.0

package/dist/test/sqlite-memory-store.test.js

@@ -0,0 +1,110 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { SqliteMem0Adapter } from '../index.js';
+const stubEmbedder = {
+    async embedText() {
+        return [1, 0, 0];
+    },
+    async healthCheck() {
+        return {
+            ok: true,
+            modelAvailable: true,
+        };
+    },
+};
+test('storeMemory dedupes exact duplicates while keeping latest provenance', async () => {
+    const tempDir = mkdtempSync(join(tmpdir(), 'mem0-sqlite-dedupe-'));
+    const adapter = new SqliteMem0Adapter({
+        storePath: tempDir,
+        ollamaBaseUrl: 'http://127.0.0.1:11434',
+        embedModel: 'stub',
+        ollamaTimeoutMs: 1_000,
+    }, stubEmbedder);
+    try {
+        const scope = { workspace: 'workspace-1', project: 'project-1', task: 'task-1' };
+        const metadata = { source: 'agentic-loop' };
+        const first = (await adapter.storeMemory({
+            kind: 'note',
+            content: 'Remember this exact note.',
+            scope,
+            provenance: {
+                checkpointId: 'checkpoint-1',
+                artifactIds: [],
+            },
+            metadata,
+        }));
+        const second = (await adapter.storeMemory({
+            kind: 'note',
+            content: 'Remember this exact note.',
+            scope,
+            provenance: {
+                checkpointId: 'checkpoint-2',
+                artifactIds: ['artifact-2'],
+            },
+            metadata,
+        }));
+        assert.equal(second.id, first.id);
+        assert.equal(second.provenance.checkpointId, 'checkpoint-2');
+        assert.deepEqual(second.provenance.artifactIds, ['artifact-2']);
+        const recalled = (await adapter.recallMemory({
+            memoryId: first.id,
+            scope,
+        }));
+        assert.equal(recalled?.content, 'Remember this exact note.');
+        assert.equal(recalled?.provenance.checkpointId, 'checkpoint-2');
+    }
+    finally {
+        rmSync(tempDir, { recursive: true, force: true });
+    }
+});
+test('storeMemory does not collapse different memories that share the same embedding vector', async () => {
+    const tempDir = mkdtempSync(join(tmpdir(), 'mem0-sqlite-distinct-'));
+    const adapter = new SqliteMem0Adapter({
+        storePath: tempDir,
+        ollamaBaseUrl: 'http://127.0.0.1:11434',
+        embedModel: 'stub',
+        ollamaTimeoutMs: 1_000,
+    }, stubEmbedder);
+    try {
+        const scope = { workspace: 'workspace-1', project: 'project-1', task: 'task-1' };
+        const first = (await adapter.storeMemory({
+            kind: 'note',
+            content: 'First memory content',
+            scope,
+            provenance: {
+                checkpointId: 'checkpoint-1',
+                artifactIds: [],
+            },
+            metadata: { phase: 'one' },
+        }));
+        const second = (await adapter.storeMemory({
+            kind: 'note',
+            content: 'Second memory content',
+            scope,
+            provenance: {
+                checkpointId: 'checkpoint-2',
+                artifactIds: [],
+            },
+            metadata: { phase: 'two' },
+        }));
+        assert.notEqual(second.id, first.id);
+        assert.equal(second.content, 'Second memory content');
+        assert.equal(second.metadata.phase, 'two');
+        const recalledFirst = (await adapter.recallMemory({
+            memoryId: first.id,
+            scope,
+        }));
+        const recalledSecond = (await adapter.recallMemory({
+            memoryId: second.id,
+            scope,
+        }));
+        assert.equal(recalledFirst?.content, 'First memory content');
+        assert.equal(recalledSecond?.content, 'Second memory content');
+    }
+    finally {
+        rmSync(tempDir, { recursive: true, force: true });
+    }
+});

package/dist/transport/jsonrpc-stdio.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Minimal JSON-RPC 2.0 over stdio transport.
+ *
+ * Self-contained — no external dependencies.
+ * Supports both Content-Length framed and bare JSON-line (jsonl) formats,
+ * auto-detecting the peer's output style and mirroring it.
+ */
+export type JsonRpcId = number | string | null;
+export interface JsonRpcMessage {
+    jsonrpc: '2.0';
+    id?: JsonRpcId;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcErrorPayload {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface JsonRpcSuccessResponse {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    result: unknown;
+}
+export interface JsonRpcErrorResponse {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    error: JsonRpcErrorPayload;
+}
+export type JsonRpcEnvelope = JsonRpcMessage | JsonRpcSuccessResponse | JsonRpcErrorResponse;
+export declare function isJsonRpcSuccessResponse(message: JsonRpcEnvelope): message is JsonRpcSuccessResponse;
+export declare function isJsonRpcErrorResponse(message: JsonRpcEnvelope): message is JsonRpcErrorResponse;
+export type JsonRpcOutputMode = 'framed' | 'jsonl';
+export declare class JsonRpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    constructor(code: number, message: string, data?: unknown | undefined);
+}
+interface JsonRpcStreamEndpoints {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+}
+export declare class JsonRpcStreamTransport {
+    private readonly onMessage;
+    private readonly endpoints;
+    private buffer;
+    private chain;
+    private listening;
+    private outputMode;
+    constructor(onMessage: (message: JsonRpcEnvelope) => Promise<void>, endpoints: JsonRpcStreamEndpoints, options?: {
+        initialOutputMode?: JsonRpcOutputMode;
+    });
+    start(): void;
+    stop(): void;
+    sendRequest(id: JsonRpcId, method: string, params?: unknown): void;
+    sendNotification(method: string, params?: unknown): void;
+    sendResult(id: JsonRpcId, result: unknown): void;
+    sendError(id: JsonRpcId, error: JsonRpcErrorPayload): void;
+    private readonly handleChunk;
+    private drainBuffer;
+    private writeEnvelope;
+}
+export declare class StdioJsonRpcTransport {
+    private readonly onMessageHandler?;
+    private readonly transport;
+    constructor(onMessageHandler?: ((message: JsonRpcMessage) => Promise<void>) | undefined);
+    start(): void;
+    stop(): void;
+    sendNotification(method: string, params?: unknown): void;
+    sendResult(id: JsonRpcId, result: unknown): void;
+    sendError(id: JsonRpcId, error: JsonRpcErrorPayload): void;
+}
+export {};

package/dist/transport/jsonrpc-stdio.js

@@ -0,0 +1,230 @@
+/**
+ * Minimal JSON-RPC 2.0 over stdio transport.
+ *
+ * Self-contained — no external dependencies.
+ * Supports both Content-Length framed and bare JSON-line (jsonl) formats,
+ * auto-detecting the peer's output style and mirroring it.
+ */
+export function isJsonRpcSuccessResponse(message) {
+    return 'result' in message;
+}
+export function isJsonRpcErrorResponse(message) {
+    return 'error' in message;
+}
+// ─── Error ──────────────────────────────────────────────────────────
+export class JsonRpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+    }
+}
+export class JsonRpcStreamTransport {
+    onMessage;
+    endpoints;
+    buffer = Buffer.alloc(0);
+    chain = Promise.resolve();
+    listening = false;
+    outputMode;
+    constructor(onMessage, endpoints, options = {}) {
+        this.onMessage = onMessage;
+        this.endpoints = endpoints;
+        this.outputMode = options.initialOutputMode ?? 'jsonl';
+    }
+    start() {
+        if (this.listening)
+            return;
+        this.endpoints.input.on('data', this.handleChunk);
+        this.listening = true;
+        const readable = this.endpoints.input;
+        readable.resume?.();
+    }
+    stop() {
+        if (!this.listening)
+            return;
+        const readable = this.endpoints.input;
+        if (typeof readable.off === 'function') {
+            readable.off('data', this.handleChunk);
+        }
+        else {
+            readable.removeListener?.('data', this.handleChunk);
+        }
+        this.listening = false;
+    }
+    sendRequest(id, method, params) {
+        const message = { jsonrpc: '2.0', id, method };
+        if (params !== undefined)
+            message.params = params;
+        this.writeEnvelope(message);
+    }
+    sendNotification(method, params) {
+        const message = { jsonrpc: '2.0', method };
+        if (params !== undefined)
+            message.params = params;
+        this.writeEnvelope(message);
+    }
+    sendResult(id, result) {
+        this.writeEnvelope({ jsonrpc: '2.0', id, result });
+    }
+    sendError(id, error) {
+        this.writeEnvelope({ jsonrpc: '2.0', id, error });
+    }
+    // ── Private ─────────────────────────────────────────────────────
+    handleChunk = (chunk) => {
+        const chunkBuffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        this.buffer = Buffer.concat([this.buffer, chunkBuffer]);
+        this.drainBuffer();
+    };
+    drainBuffer() {
+        while (true) {
+            const framedEnvelope = extractFramedEnvelope(this.buffer);
+            let body;
+            if (framedEnvelope !== null) {
+                this.outputMode = 'framed';
+                body = framedEnvelope.body;
+                this.buffer = this.buffer.subarray(framedEnvelope.nextOffset);
+            }
+            else {
+                const bareEnvelope = extractBareJsonEnvelope(this.buffer);
+                if (bareEnvelope === null)
+                    return;
+                this.outputMode = 'jsonl';
+                body = bareEnvelope.body;
+                this.buffer = this.buffer.subarray(bareEnvelope.nextOffset);
+            }
+            let message;
+            try {
+                message = JSON.parse(body);
+            }
+            catch (error) {
+                console.error(`Failed to parse JSON-RPC message: ${getErrorMessage(error)}`);
+                continue;
+            }
+            this.chain = this.chain
+                .then(() => this.onMessage(message))
+                .catch((error) => {
+                console.error(getErrorMessage(error));
+            });
+        }
+    }
+    writeEnvelope(message) {
+        const body = JSON.stringify(message);
+        if (this.outputMode === 'jsonl') {
+            this.endpoints.output.write(`${body}\n`);
+            return;
+        }
+        const header = `Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n`;
+        this.endpoints.output.write(header);
+        this.endpoints.output.write(body);
+    }
+}
+// ─── Stdio Server Transport ─────────────────────────────────────────
+export class StdioJsonRpcTransport {
+    onMessageHandler;
+    transport;
+    constructor(onMessageHandler) {
+        this.onMessageHandler = onMessageHandler;
+        this.transport = new JsonRpcStreamTransport(async (message) => {
+            if (!('method' in message)) {
+                console.error(`Unexpected JSON-RPC response envelope on stdio server input: ${JSON.stringify(message)}`);
+                return;
+            }
+            if (this.onMessageHandler) {
+                await this.onMessageHandler(message);
+            }
+        }, { input: process.stdin, output: process.stdout });
+    }
+    start() {
+        this.transport.start();
+    }
+    stop() {
+        this.transport.stop();
+    }
+    sendNotification(method, params) {
+        this.transport.sendNotification(method, params);
+    }
+    sendResult(id, result) {
+        this.transport.sendResult(id, result);
+    }
+    sendError(id, error) {
+        this.transport.sendError(id, error);
+    }
+}
+// ─── Helpers ────────────────────────────────────────────────────────
+function findHeaderBoundary(buffer) {
+    const crlfBoundary = buffer.indexOf('\r\n\r\n');
+    if (crlfBoundary !== -1)
+        return { headerEnd: crlfBoundary, separatorLength: 4 };
+    const lfBoundary = buffer.indexOf('\n\n');
+    if (lfBoundary !== -1)
+        return { headerEnd: lfBoundary, separatorLength: 2 };
+    return null;
+}
+function extractFramedEnvelope(buffer) {
+    const headerBoundary = findHeaderBoundary(buffer);
+    if (headerBoundary === null)
+        return null;
+    const { headerEnd, separatorLength } = headerBoundary;
+    const header = buffer.subarray(0, headerEnd).toString('utf8');
+    const match = header.match(/Content-Length:\s*(\d+)/i);
+    if (match === null)
+        return null;
+    const contentLength = Number.parseInt(match[1], 10);
+    const messageEnd = headerEnd + separatorLength + contentLength;
+    if (buffer.length < messageEnd)
+        return null;
+    return {
+        body: buffer.subarray(headerEnd + separatorLength, messageEnd).toString('utf8'),
+        nextOffset: messageEnd,
+    };
+}
+function extractBareJsonEnvelope(buffer) {
+    const source = buffer.toString('utf8');
+    const leadingWhitespace = source.match(/^\s*/)?.[0].length ?? 0;
+    if (leadingWhitespace >= source.length)
+        return null;
+    const firstCharacter = source[leadingWhitespace];
+    if (firstCharacter !== '{' && firstCharacter !== '[')
+        return null;
+    let depth = 0;
+    let inString = false;
+    let escaping = false;
+    for (let index = leadingWhitespace; index < source.length; index += 1) {
+        const character = source[index];
+        if (escaping) {
+            escaping = false;
+            continue;
+        }
+        if (inString) {
+            if (character === '\\')
+                escaping = true;
+            else if (character === '"')
+                inString = false;
+            continue;
+        }
+        if (character === '"') {
+            inString = true;
+            continue;
+        }
+        if (character === '{' || character === '[') {
+            depth += 1;
+            continue;
+        }
+        if (character === '}' || character === ']') {
+            depth -= 1;
+            if (depth === 0) {
+                const endIndex = index + 1;
+                return {
+                    body: source.slice(leadingWhitespace, endIndex),
+                    nextOffset: Buffer.byteLength(source.slice(0, endIndex), 'utf8'),
+                };
+            }
+        }
+    }
+    return null;
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/transport/mcp-server.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Generic MCP Server — tool registry + JSON-RPC dispatch.
+ * Zero business logic: tools are registered externally.
+ */
+import { StdioJsonRpcTransport } from './jsonrpc-stdio.js';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: unknown) => Promise<unknown>;
+}
+export interface McpServerOptions {
+    protocolVersion?: string;
+    serverInfo?: {
+        name: string;
+        version: string;
+    };
+    instructions?: string;
+    transport?: StdioJsonRpcTransport;
+}
+export declare class McpServer {
+    private readonly transport;
+    private readonly tools;
+    private resourceListHandler?;
+    private readonly protocolVersion;
+    private readonly serverInfo;
+    private readonly instructions?;
+    constructor(options?: McpServerOptions);
+    registerTool(tool: ToolDefinition): void;
+    registerResourceListHandler(handler: () => Promise<{
+        resources: unknown[];
+    }>): void;
+    start(): void;
+    private handleMessage;
+    private buildInitializeResult;
+    private callTool;
+    private requireId;
+}

package/dist/transport/mcp-server.js

@@ -0,0 +1,156 @@
+/**
+ * Generic MCP Server — tool registry + JSON-RPC dispatch.
+ * Zero business logic: tools are registered externally.
+ */
+import { z } from 'zod';
+import { getErrorMessage } from '../domain/errors.js';
+import { JsonRpcError, StdioJsonRpcTransport, } from './jsonrpc-stdio.js';
+const initializeParamsSchema = z
+    .object({ protocolVersion: z.string().optional() })
+    .passthrough();
+const toolCallParamsSchema = z
+    .object({ name: z.string().min(1), arguments: z.unknown().optional() })
+    .passthrough();
+export class McpServer {
+    transport;
+    tools = new Map();
+    resourceListHandler;
+    protocolVersion;
+    serverInfo;
+    instructions;
+    constructor(options = {}) {
+        this.transport =
+            options.transport ??
+                new StdioJsonRpcTransport((msg) => this.handleMessage(msg));
+        this.protocolVersion = options.protocolVersion ?? '2024-11-05';
+        this.serverInfo = options.serverInfo ?? {
+            name: 'mcp-server',
+            version: '0.0.0',
+        };
+        this.instructions = options.instructions;
+    }
+    registerTool(tool) {
+        this.tools.set(tool.name, tool);
+    }
+    registerResourceListHandler(handler) {
+        this.resourceListHandler = handler;
+    }
+    start() {
+        this.transport.start();
+    }
+    // ─── Private ──────────────────────────────────────────────────────
+    async handleMessage(message) {
+        const id = 'id' in message ? (message.id ?? null) : undefined;
+        try {
+            switch (message.method) {
+                case 'initialize':
+                    this.requireId(id, message.method);
+                    this.transport.sendResult(id, this.buildInitializeResult(message.params));
+                    return;
+                case 'notifications/initialized':
+                case '$/cancelRequest':
+                case '$/setTrace':
+                    return;
+                case 'ping':
+                    if (id !== undefined)
+                        this.transport.sendResult(id, {});
+                    return;
+                case 'tools/list':
+                    this.requireId(id, message.method);
+                    this.transport.sendResult(id, {
+                        tools: [...this.tools.values()].map(({ name, description, inputSchema }) => ({
+                            name, description, inputSchema,
+                        })),
+                    });
+                    return;
+                case 'tools/call':
+                    this.requireId(id, message.method);
+                    this.transport.sendResult(id, await this.callTool(message.params));
+                    return;
+                case 'resources/list':
+                    this.requireId(id, message.method);
+                    if (this.resourceListHandler) {
+                        try {
+                            this.transport.sendResult(id, await this.resourceListHandler());
+                        }
+                        catch {
+                            this.transport.sendResult(id, { resources: [] });
+                        }
+                    }
+                    else {
+                        this.transport.sendResult(id, { resources: [] });
+                    }
+                    return;
+                case 'prompts/list':
+                    this.requireId(id, message.method);
+                    this.transport.sendResult(id, { prompts: [] });
+                    return;
+                case 'shutdown':
+                    this.requireId(id, message.method);
+                    this.transport.sendResult(id, {});
+                    return;
+                case 'exit':
+                    process.exit(0);
+                default:
+                    throw new JsonRpcError(-32601, `Method not found: ${message.method}`);
+            }
+        }
+        catch (error) {
+            if (id === undefined) {
+                console.error(getErrorMessage(error));
+                return;
+            }
+            this.transport.sendError(id, toJsonRpcErrorPayload(error));
+        }
+    }
+    buildInitializeResult(params) {
+        const parsed = initializeParamsSchema.safeParse(params);
+        const protocolVersion = parsed.success && parsed.data.protocolVersion !== undefined
+            ? parsed.data.protocolVersion
+            : this.protocolVersion;
+        return {
+            protocolVersion,
+            capabilities: { tools: { listChanged: false } },
+            serverInfo: this.serverInfo,
+            ...(this.instructions ? { instructions: this.instructions } : {}),
+        };
+    }
+    async callTool(params) {
+        const parsed = toolCallParamsSchema.parse(params);
+        const tool = this.tools.get(parsed.name);
+        if (tool === undefined) {
+            throw new JsonRpcError(-32602, `Unknown tool: ${parsed.name}`);
+        }
+        try {
+            const payload = await tool.handler(parsed.arguments);
+            return toToolResult(payload, false);
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                return toToolResult({ error: `Invalid arguments for ${parsed.name}`, issues: error.issues }, true);
+            }
+            return toToolResult({ error: getErrorMessage(error) }, true);
+        }
+    }
+    requireId(id, method) {
+        if (id === undefined) {
+            throw new JsonRpcError(-32600, `Method ${method} must be called as a request with an id`);
+        }
+    }
+}
+function toToolResult(payload, isError) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+        isError,
+    };
+}
+function toJsonRpcErrorPayload(error) {
+    if (error instanceof JsonRpcError) {
+        return { code: error.code, message: error.message, data: error.data };
+    }
+    if (error instanceof z.ZodError) {
+        return { code: -32602, message: 'Invalid params', data: error.issues };
+    }
+    return { code: -32603, message: getErrorMessage(error) };
+}

package/dist/transport/tools/health.tool.d.ts

@@ -0,0 +1,3 @@
+import type { MemoryStorePort } from '../../ports/memory-store.port.js';
+import type { ToolDefinition } from '../mcp-server.js';
+export declare function createHealthTool(store: MemoryStorePort): ToolDefinition;

package/dist/transport/tools/health.tool.js

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+const emptyInput = z.object({}).passthrough();
+export function createHealthTool(store) {
+    return {
+        name: 'health',
+        description: 'Check the mem0-mcp server state, local store path, configured embedding model, and Ollama availability.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        handler: async (args) => {
+            emptyInput.parse(args ?? {});
+            return await store.healthCheck();
+        },
+    };
+}

package/dist/transport/tools/memory-forget.tool.d.ts

@@ -0,0 +1,3 @@
+import type { MemoryStorePort } from '../../ports/memory-store.port.js';
+import type { ToolDefinition } from '../mcp-server.js';
+export declare function createMemoryForgetTool(store: MemoryStorePort): ToolDefinition;

package/dist/transport/tools/memory-forget.tool.js

@@ -0,0 +1,22 @@
+import { memoryForgetInputSchema } from '../../domain/memory.types.js';
+import { scopeJsonSchema } from './shared-schemas.js';
+export function createMemoryForgetTool(store) {
+    return {
+        name: 'memory_forget',
+        description: 'Delete a memory from the store.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                memoryId: { type: 'string', format: 'uuid' },
+                scope: scopeJsonSchema,
+            },
+            required: ['memoryId', 'scope'],
+            additionalProperties: false,
+        },
+        handler: async (args) => {
+            const input = memoryForgetInputSchema.parse(args);
+            await store.deleteMemory(input);
+            return { success: true };
+        },
+    };
+}

package/dist/transport/tools/memory-recall.tool.d.ts

@@ -0,0 +1,3 @@
+import type { MemoryStorePort } from '../../ports/memory-store.port.js';
+import type { ToolDefinition } from '../mcp-server.js';
+export declare function createMemoryRecallTool(store: MemoryStorePort): ToolDefinition;

package/dist/transport/tools/memory-recall.tool.js

@@ -0,0 +1,22 @@
+import { memoryRecallInputSchema } from '../../domain/memory.types.js';
+import { scopeJsonSchema } from './shared-schemas.js';
+export function createMemoryRecallTool(store) {
+    return {
+        name: 'memory_recall',
+        description: 'Recall a single persisted memory by ID within the provided canonical scope.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                memoryId: { type: 'string', format: 'uuid' },
+                scope: scopeJsonSchema,
+            },
+            required: ['memoryId', 'scope'],
+            additionalProperties: false,
+        },
+        handler: async (args) => {
+            const input = memoryRecallInputSchema.parse(args);
+            const memory = await store.recallMemory(input);
+            return { memory };
+        },
+    };
+}

package/dist/transport/tools/memory-search.tool.d.ts

@@ -0,0 +1,3 @@
+import type { MemoryStorePort } from '../../ports/memory-store.port.js';
+import type { ToolDefinition } from '../mcp-server.js';
+export declare function createMemorySearchTool(store: MemoryStorePort): ToolDefinition;