memtrails 0.4.3 → 0.5.1

package/CHANGELOG.md

@@ -5,6 +5,21 @@ versions follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.1] — 2026-11-05
+
+- Rust: the MCP server and the command line, as in TypeScript and Python — `cargo install memtrails`, then
+  `memtrails mcp`, `add`, `search`; `memtrails::mcp::serve_mcp` from code, held to the same answers
+  (`conformance/fixtures/mcp.json`). The TypeScript and Python versions are released at the same version, unchanged.
+
+## [0.5.0] — 2026-11-05
+
+- An MCP server and a command line: `npx memtrails mcp` serves a memory to Claude Desktop, Claude Code, Cursor and any
+  MCP client (`memory_search`, `memory_open`, `memory_explore`, and `memory_save` unless `--read-only`), opening it at
+  the first tool call and closing it when idle; `memtrails add` fills it from folders, mail, JSONL, a Slack export or
+  git; `memtrails search` asks it. `serveMcp` serves one from code. The same in Python (`uvx memtrails mcp`,
+  `serve_mcp`), held to the same answers (`conformance/fixtures/mcp.json`). The Rust version has the same library at
+  this version, without the server and command line for now: its `Memory::tools()` serve an MCP server of your own.
+
 ## [0.4.3] — 2026-11-05
 
 - Fixes: the first start no longer fails with "Qdrant exited (101) while starting" where the system has no CA

package/README.md

@@ -45,8 +45,8 @@ await memory.close();
   answer an independent audit found wrong. [Benchmarks](docs/BENCHMARKS.md).
 - **Explorable.** A concept graph links what records share — people, places, systems, names — so an agent can walk
   from what it found to what a search for the words does not find.
-- **Built for agents.** `memory.tools()` gives `memory_search`, `memory_open` and `memory_explore` with zod and JSON
-  schemas, ready for an MCP server or any function-calling API.
+- **Built for agents.** `npx memtrails mcp` gives Claude, Cursor or any MCP app a memory it can search and save to;
+  `memory.tools()` gives the same tools with zod and JSON schemas, for your own server or any function-calling API.
 
 ## Install
 
@@ -69,6 +69,33 @@ pip install memtrails          # Python 3.10–3.13, asyncio — see python/READ
 cargo add memtrails            # Rust 1.88+, tokio — see rust/README.md
 ```
 
+## Memory for Claude, Cursor and other MCP apps
+
+One line gives an MCP client a long-term memory on your machine: `memory_search`, `memory_open`, `memory_explore`,
+and `memory_save` for what the agent should remember.
+
+```bash
+claude mcp add memory -- npx -y memtrails mcp                                  # Claude Code
+```
+
+```json
+{ "mcpServers": { "memory": { "command": "npx", "args": ["-y", "memtrails", "mcp"] } } }
+```
+
+The second is for Claude Desktop (`claude_desktop_config.json`), Cursor (`.cursor/mcp.json`) and most other clients.
+The same server comes with the Python and Rust versions: `uvx memtrails mcp`, or `cargo install memtrails` and then
+`memtrails mcp`. Fill the memory from the command line, and try it:
+
+```bash
+npx memtrails add ~/notes ~/mail/archive.mbox ./slack-export      # notes and documents, mail, a Slack export
+npx memtrails add --git ~/code/my-repo                             # commit messages and changed files
+npx memtrails search "why did the certificate stop renewing?"
+```
+
+The memory lives in `~/.memtrails` (`--home` or `MEMTRAILS_HOME` for another). The server opens it at the first tool
+call and closes it after five minutes without one (`--idle`), so `add` can run in between; `--read-only` leaves out
+`memory_save`. From code: `serveMcp({ open: () => openMemory({ home }), version })`.
+
 ## Adding data
 
 A **record** is anything with text. Only `id` and `text` are required.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * memtrails on the command line: `mcp` serves a memory to an MCP client, `add` fills it from files, mail, Slack or
+ * git, `search` asks it. The memory is MEMTRAILS_HOME, or ~/.memtrails, unless --home names another.
+ */
+import { existsSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { extname, join, resolve } from 'node:path';
+import { fromEml, fromFiles, fromGit, fromJsonl, fromMbox, fromSlackExport } from './importers/index.js';
+import { serveMcp } from './mcp.js';
+import { openMemory } from './memory.js';
+const VERSION = createRequire(import.meta.url)('../package.json').version;
+const USAGE = `memtrails ${VERSION} — local memory for agents
+
+  memtrails mcp [--read-only] [--idle MINUTES]   serve the memory to an MCP client over stdio
+  memtrails add PATH... [--git REPO] [--collection NAME]
+                                                 add folders of notes and documents, .mbox/.eml mail,
+                                                 .jsonl records, a Slack export folder, a git history
+  memtrails search QUERY... [--limit N]          search, best first
+
+  --home DIR   the memory (default: MEMTRAILS_HOME, or ~/.memtrails)
+
+MCP client configuration (Claude Desktop, Cursor, …):
+  { "mcpServers": { "memory": { "command": "npx", "args": ["-y", "memtrails", "mcp"] } } }
+Claude Code:
+  claude mcp add memory -- npx -y memtrails mcp
+`;
+const VALUED = new Set(['--home', '--git', '--collection', '--limit', '--idle']);
+const SWITCHES = new Set(['--read-only', '--help', '-h', '--version', '-v']);
+function parse(argv) {
+    const flags = new Map();
+    const switches = new Set();
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const eq = a.indexOf('=');
+        const name = a.startsWith('--') && eq > 0 ? a.slice(0, eq) : a;
+        if (VALUED.has(name)) {
+            const value = eq > 0 && a.startsWith('--') ? a.slice(eq + 1) : argv[++i];
+            if (value === undefined)
+                throw new Error(`${name} needs a value`);
+            flags.set(name, [...(flags.get(name) ?? []), value]);
+        }
+        else if (SWITCHES.has(a)) {
+            switches.add(a);
+        }
+        else if (a.startsWith('-') && a !== '-') {
+            throw new Error(`unknown option ${a}`);
+        }
+        else {
+            rest.push(a);
+        }
+    }
+    return { command: rest.shift() ?? '', rest, flags, switches };
+}
+const one = (a, name) => a.flags.get(name)?.at(-1);
+const homeOf = (a) => resolve(one(a, '--home') ?? process.env.MEMTRAILS_HOME ?? join(homedir(), '.memtrails'));
+const say = (line) => { process.stderr.write(`${line}\n`); };
+function number(a, name, fallback, min) {
+    const raw = one(a, name);
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < min)
+        throw new Error(`${name} must be a number of at least ${min}`);
+    return n;
+}
+/** What a path holds, as records: the importer its kind calls for. */
+function importerFor(path, collection) {
+    if (!existsSync(path))
+        throw new Error(`${path}: not found`);
+    if (statSync(path).isDirectory()) {
+        if (existsSync(join(path, 'channels.json')) && existsSync(join(path, 'users.json')))
+            return fromSlackExport(path, { collection });
+        return fromFiles(path, { collection, onSkip: (p, why) => say(`  skipped ${p}: ${why}`) });
+    }
+    switch (extname(path).toLowerCase()) {
+        case '.mbox': return fromMbox(path, { collection });
+        case '.eml': return fromEml(path, { collection });
+        case '.jsonl': return fromJsonl(path, { collection, onSkip: (_line, why, n) => say(`  skipped line ${n}: ${why}`) });
+        default: throw new Error(`${path}: give a folder of notes or documents, an .mbox or .eml file, a .jsonl file, or a Slack export folder`);
+    }
+}
+async function withMemory(a, f) {
+    const memory = await openMemory({ home: homeOf(a), log: say });
+    try {
+        return await f(memory);
+    }
+    finally {
+        await memory.close();
+    }
+}
+async function add(a) {
+    const collection = one(a, '--collection');
+    const sources = [
+        ...a.rest.map((p) => [p, importerFor(resolve(p), collection)]),
+        ...(a.flags.get('--git') ?? []).map((p) => [`${p} (git)`, fromGit(resolve(p), { collection })]),
+    ];
+    if (!sources.length)
+        throw new Error('add what? give one or more paths, or --git REPO');
+    await withMemory(a, async (m) => {
+        for (const [name, records] of sources) {
+            say(`adding ${name}`);
+            const r = await m.import(records, { onProgress: (n) => say(`  ${n} records`) });
+            say(`  ${r.added} added, ${r.unchanged} unchanged`);
+        }
+        const s = m.stats();
+        say(`${homeOf(a)}: ${s.records} records`);
+    });
+}
+async function search(a) {
+    const query = a.rest.join(' ').trim();
+    if (!query)
+        throw new Error('search for what? give the question as words');
+    const limit = number(a, '--limit', 10, 1);
+    await withMemory(a, async (m) => { process.stdout.write(`${await m.searchText({ query, limit })}\n`); });
+}
+async function mcp(a) {
+    const home = homeOf(a);
+    await serveMcp({
+        version: VERSION,
+        readOnly: a.switches.has('--read-only'),
+        idleMs: number(a, '--idle', 5, 0) * 60_000,
+        open: () => openMemory({ home, log: say }),
+    });
+}
+async function main() {
+    const a = parse(process.argv.slice(2));
+    if (a.switches.has('--version') || a.switches.has('-v'))
+        return void process.stdout.write(`${VERSION}\n`);
+    if (!a.command || a.command === 'help' || a.switches.has('--help') || a.switches.has('-h'))
+        return void process.stdout.write(USAGE);
+    switch (a.command) {
+        case 'mcp': return mcp(a);
+        case 'add': return add(a);
+        case 'search': return search(a);
+        default: throw new Error(`unknown command ${a.command}; try memtrails --help`);
+    }
+}
+// Ends on its own, never by process.exit: exiting while ONNX Runtime's threads are still there aborts the process.
+main().catch((e) => {
+    say(`memtrails: ${e instanceof Error ? e.message : String(e)}`);
+    process.exitCode = 1;
+});

package/dist/index.d.ts

@@ -26,3 +26,4 @@ export type { RerankRoute } from './core/reranker.js';
 export { sentenceRoom, sentenceSpans } from './core/room.js';
 export { maxSim, packWords, WordStore, WORD_LIMIT, type WordEncoder, type WordVectors, type PackedWords } from './core/words.js';
 export { cacheDir } from './core/paths.js';
+export { serveMcp, MCP_PROTOCOL_VERSIONS, type McpServerOptions } from './mcp.js';

package/dist/index.js

@@ -20,3 +20,4 @@ export { ensureQdrant, QDRANT_VERSION } from './core/qdrant-binary.js';
 export { sentenceRoom, sentenceSpans } from './core/room.js';
 export { maxSim, packWords, WordStore, WORD_LIMIT } from './core/words.js';
 export { cacheDir } from './core/paths.js';
+export { serveMcp, MCP_PROTOCOL_VERSIONS } from './mcp.js';

package/dist/mcp.d.ts

@@ -0,0 +1,19 @@
+import type { Readable, Writable } from 'node:stream';
+import type { Memory } from './memory.js';
+/** The protocol versions this server speaks, newest first; a client asking for another gets the newest. */
+export declare const MCP_PROTOCOL_VERSIONS: string[];
+export interface McpServerOptions {
+    /** Opens the memory; called at the first tool call, and again after an idle close. */
+    open: () => Promise<Memory>;
+    /** Without memory_save. */
+    readOnly?: boolean;
+    /** Close the memory after this long without a tool call (default 5 minutes; 0 keeps it open). */
+    idleMs?: number;
+    /** The server's version, as clients show it. */
+    version: string;
+    input?: Readable;
+    output?: Writable;
+    log?: (line: string) => void;
+}
+/** Serves until the input ends, then closes the memory. Resolves when it is closed. */
+export declare function serveMcp(o: McpServerOptions): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,184 @@
+/**
+ * A memory as an MCP server over stdio (newline-delimited JSON-RPC), for Claude Desktop, Claude Code, Cursor and any
+ * other MCP client: the agent tools (memory_search, memory_open, memory_explore) and, unless read-only, memory_save.
+ *
+ * The memory is opened at the first tool call and closed again after `idleMs` without one, so the home is free in
+ * between: for `memtrails add`, or another client on the same memory. A memory another process holds is a tool error
+ * that says which process, not a server that will not start.
+ */
+import { randomBytes } from 'node:crypto';
+import { createInterface } from 'node:readline';
+import { z } from 'zod';
+import { buildAgentTools } from './tools/agent-tools.js';
+/** The protocol versions this server speaks, newest first; a client asking for another gets the newest. */
+export const MCP_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+const INSTRUCTIONS = 'Long-term memory: what this person or team worked on, wrote, decided and said, and what was learned '
+    + 'from it. Search it before answering about past work, people, decisions or dates, and open a result to read it whole. '
+    + 'Save what is worth remembering later: a decision and why, a preference, a fact about a person or a system.';
+const SAVE_DESCRIPTION = 'Save something to memory, to be found later by memory_search: a decision and why, a preference, '
+    + 'a fact about a person, a project or a system, what was learned. Write it to be understood on its own, later, by '
+    + 'someone who was not here: name who and what, and the date when it matters.';
+const READ_ONLY = { readOnlyHint: true, openWorldHint: false };
+/** Serves until the input ends, then closes the memory. Resolves when it is closed. */
+export async function serveMcp(o) {
+    const input = o.input ?? process.stdin;
+    const output = o.output ?? process.stdout;
+    const log = o.log ?? ((line) => process.stderr.write(`${line}\n`));
+    const idleMs = o.idleMs ?? 5 * 60_000;
+    let memory = null;
+    let busy = 0;
+    let idle = null;
+    const send = (message) => { output.write(`${JSON.stringify(message)}\n`); };
+    const closeMemory = async () => {
+        const m = memory;
+        memory = null;
+        if (m)
+            await m.then((x) => x.close(), () => undefined);
+    };
+    const touch = () => {
+        if (idle)
+            clearTimeout(idle);
+        idle = null;
+        if (idleMs > 0 && busy === 0 && memory) {
+            idle = setTimeout(() => { if (busy === 0)
+                void closeMemory().catch((e) => log(`[memtrails] close: ${String(e)}`)); }, idleMs);
+            idle.unref();
+        }
+    };
+    const withMemory = async (f) => {
+        busy++;
+        if (idle)
+            clearTimeout(idle);
+        try {
+            if (!memory) {
+                memory = o.open();
+                memory.catch(() => { memory = null; }); // the next call tries again
+            }
+            return await f(await memory);
+        }
+        finally {
+            busy--;
+            touch();
+        }
+    };
+    // The tools' definitions do not need an open memory: they are listed before any call.
+    const definitions = toolDefinitions(o.readOnly ?? false);
+    const call = async (name, args) => {
+        const d = definitions.find((t) => t.name === name);
+        if (!d)
+            return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+        try {
+            return await withMemory((m) => d.run(m, args));
+        }
+        catch (e) {
+            return { content: [{ type: 'text', text: e instanceof Error ? e.message : String(e) }], isError: true };
+        }
+    };
+    const handle = async (r) => {
+        const isCall = r.id !== undefined;
+        if (r.jsonrpc !== '2.0' || typeof r.method !== 'string') {
+            return isCall ? { jsonrpc: '2.0', id: r.id ?? null, error: { code: -32600, message: 'Invalid request' } } : undefined;
+        }
+        const ok = (result) => ({ jsonrpc: '2.0', id: r.id, result });
+        switch (r.method) {
+            case 'initialize': {
+                const asked = r.params?.protocolVersion;
+                const protocolVersion = typeof asked === 'string' && MCP_PROTOCOL_VERSIONS.includes(asked) ? asked : MCP_PROTOCOL_VERSIONS[0];
+                return ok({ protocolVersion, capabilities: { tools: {} }, serverInfo: { name: 'memtrails', version: o.version }, instructions: INSTRUCTIONS });
+            }
+            case 'ping':
+                return isCall ? ok({}) : undefined;
+            case 'tools/list':
+                return ok({ tools: definitions.map(({ name, description, inputSchema, annotations }) => ({ name, description, inputSchema, annotations })) });
+            case 'tools/call': {
+                const name = r.params?.name;
+                if (typeof name !== 'string')
+                    return { jsonrpc: '2.0', id: r.id, error: { code: -32602, message: 'tools/call needs a tool name' } };
+                return ok(await call(name, r.params?.arguments ?? {}));
+            }
+            default:
+                // Notifications (initialized, cancelled, …) need no answer; an unknown request does.
+                return isCall ? { jsonrpc: '2.0', id: r.id, error: { code: -32601, message: `Method not found: ${r.method}` } } : undefined;
+        }
+    };
+    const pending = new Set();
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    for await (const line of lines) {
+        if (!line.trim())
+            continue;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+            continue;
+        }
+        // Answered as each finishes: a slow search does not hold up a ping.
+        const p = (async () => {
+            if (Array.isArray(message)) {
+                const answers = (await Promise.all(message.map((m) => handle(asRequest(m))))).filter((a) => a !== undefined);
+                if (answers.length)
+                    send(answers);
+            }
+            else {
+                const answer = await handle(asRequest(message));
+                if (answer !== undefined)
+                    send(answer);
+            }
+        })().catch((e) => log(`[memtrails] mcp: ${String(e)}`));
+        pending.add(p);
+        void p.finally(() => pending.delete(p));
+    }
+    await Promise.all(pending);
+    if (idle)
+        clearTimeout(idle);
+    await closeMemory();
+}
+function asRequest(m) {
+    return m && typeof m === 'object' && !Array.isArray(m) ? m : {};
+}
+const saveInput = z.object({
+    text: z.string().min(1).describe('What to remember, written to be understood on its own.'),
+    title: z.string().max(200).optional().describe('A short title (default: the start of the text).'),
+});
+function toolDefinitions(readOnly) {
+    // The agent tools' names, texts and schemas, from a memory that is never searched: listing needs no open memory.
+    const shapes = toolShapes();
+    const defs = shapes.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.jsonSchema,
+        annotations: READ_ONLY,
+        run: (m, args) => {
+            const live = m.tools().find((x) => x.name === t.name);
+            if (!live)
+                return Promise.resolve({ content: [{ type: 'text', text: `Unknown tool: ${t.name}` }], isError: true });
+            return live.handler(args);
+        },
+    }));
+    if (!readOnly) {
+        defs.push({
+            name: 'memory_save',
+            description: SAVE_DESCRIPTION,
+            inputSchema: z.toJSONSchema(saveInput),
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+            run: async (m, args) => {
+                const got = saveInput.safeParse(args ?? {});
+                if (!got.success) {
+                    return { content: [{ type: 'text', text: `Invalid arguments: ${got.error.issues.map((i) => `${i.path.join('.') || 'input'}: ${i.message}`).join('; ')}` }], isError: true };
+                }
+                const now = new Date();
+                const id = `${now.toISOString()}-${randomBytes(4).toString('hex')}`;
+                await m.add({ id, source: 'mcp', kind: 'note', title: got.data.title, text: got.data.text, at: now.toISOString() });
+                return { content: [{ type: 'text', text: `Saved (${now.toISOString().slice(0, 10)}, id ${id}).` }] };
+            },
+        });
+    }
+    return defs;
+}
+let shapesCache = null;
+function toolShapes() {
+    const never = () => { throw new Error('not a memory'); };
+    return (shapesCache ??= buildAgentTools({ search: never, open: never, explore: never }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrails",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "Retrieval and exploration for any text — e-mail, chat, notes, documents, news, commits, conversations. Searchable at once, on your own machine, in any language; optional consolidation into typed knowledge with a language model.",
   "keywords": [
     "retrieval",
@@ -43,6 +43,9 @@
     },
     "./package.json": "./package.json"
   },
+  "bin": {
+    "memtrails": "dist/cli.js"
+  },
   "files": [
     "dist",
     "README.md",
@@ -68,6 +71,7 @@
     "onnxruntime-node": "1.23.2"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
     "@types/node": "^22.10.0",
     "esbuild": "^0.25.12",
     "tsx": "^4.20.6",