@vortex-os/memory-extended 0.5.1

package/dist/mcp/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `mcp` namespace — exposes recall to MCP-capable hosts (Claude Desktop,
+ * chatbots, other agents).
+ *   - Slice 1: the `recall` tool, stdio transport (server.ts / recall-tool.ts).
+ *   - Slice 2: one-line install into the host's config (install.ts) — the bin's
+ *     `install` subcommand merges our server entry without clobbering others.
+ *   - Slice 3: read-only companion tools `list_memories` / `get_memory`
+ *     (memory-tools.ts).
+ *   - Slice 4: document tools `suggest_document` / `write_document` /
+ *     `decline_document` (document-tools.ts) — a propose-then-write pair so the
+ *     only write surface is gated behind an explicit second call. Operational
+ *     records stay auto-kept; formal knowledge docs are proposed, then written
+ *     only on acceptance ("auto the plumbing, propose the prose").
+ *
+ * Packaging: this lives INSIDE memory-extended (not a separate package) so that
+ * installing the memory extension also installs its MCP surface — the recall
+ * tool is a memory feature, so it ships with memory. The MCP SDK itself is an
+ * OPTIONAL dependency, loaded at runtime only when {@link createRecallServer}
+ * runs (mirrors the optional `@huggingface/transformers` embedder dependency).
+ *
+ * Run the stdio server via the `vortex-mcp-recall` bin (scripts/mcp-stdio.mjs);
+ * register it with `vortex-mcp-recall install --data-dir <path>`.
+ */
+export { createRecallServer } from "./server.js";
+export type { RecallServerOptions } from "./server.js";
+export { RECALL_TOOL_NAME, recallToolDefinition, runRecall } from "./recall-tool.js";
+export type { RunRecallArgs, RunRecallDeps } from "./recall-tool.js";
+export { LIST_MEMORIES_TOOL_NAME, GET_MEMORY_TOOL_NAME, listMemoriesToolDefinition, getMemoryToolDefinition, runListMemories, runGetMemory, } from "./memory-tools.js";
+export type { RunListArgs, RunGetArgs, RunMemoryToolDeps, MemorySummary, ListResult, GetResult, } from "./memory-tools.js";
+export { SUGGEST_DOCUMENT_TOOL_NAME, WRITE_DOCUMENT_TOOL_NAME, DECLINE_DOCUMENT_TOOL_NAME, suggestDocumentToolDefinition, writeDocumentToolDefinition, declineDocumentToolDefinition, runSuggestDocument, runWriteDocument, runDeclineDocument, renderDocumentBody, documentFingerprint, } from "./document-tools.js";
+export type { DocumentArgs, DocumentToolDeps, SuggestResult, WriteResult, DeclineResult, } from "./document-tools.js";
+export { DEFAULT_SERVER_KEY, claudeDesktopConfigPath, buildRecallServerEntry, mergeServerEntry, parseExistingConfig, serializeConfig, } from "./install.js";
+export type { InstallEnv, McpServerEntry, BuildEntryOptions, McpConfig, MergeResult, } from "./install.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACrF,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,uBAAuB,EACvB,eAAe,EACf,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,SAAS,GACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,0BAA0B,EAC1B,6BAA6B,EAC7B,2BAA2B,EAC3B,6BAA6B,EAC7B,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,EACtB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,SAAS,EACT,WAAW,GACZ,MAAM,cAAc,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,29 @@
+/**
+ * `mcp` namespace — exposes recall to MCP-capable hosts (Claude Desktop,
+ * chatbots, other agents).
+ *   - Slice 1: the `recall` tool, stdio transport (server.ts / recall-tool.ts).
+ *   - Slice 2: one-line install into the host's config (install.ts) — the bin's
+ *     `install` subcommand merges our server entry without clobbering others.
+ *   - Slice 3: read-only companion tools `list_memories` / `get_memory`
+ *     (memory-tools.ts).
+ *   - Slice 4: document tools `suggest_document` / `write_document` /
+ *     `decline_document` (document-tools.ts) — a propose-then-write pair so the
+ *     only write surface is gated behind an explicit second call. Operational
+ *     records stay auto-kept; formal knowledge docs are proposed, then written
+ *     only on acceptance ("auto the plumbing, propose the prose").
+ *
+ * Packaging: this lives INSIDE memory-extended (not a separate package) so that
+ * installing the memory extension also installs its MCP surface — the recall
+ * tool is a memory feature, so it ships with memory. The MCP SDK itself is an
+ * OPTIONAL dependency, loaded at runtime only when {@link createRecallServer}
+ * runs (mirrors the optional `@huggingface/transformers` embedder dependency).
+ *
+ * Run the stdio server via the `vortex-mcp-recall` bin (scripts/mcp-stdio.mjs);
+ * register it with `vortex-mcp-recall install --data-dir <path>`.
+ */
+export { createRecallServer } from "./server.js";
+export { RECALL_TOOL_NAME, recallToolDefinition, runRecall } from "./recall-tool.js";
+export { LIST_MEMORIES_TOOL_NAME, GET_MEMORY_TOOL_NAME, listMemoriesToolDefinition, getMemoryToolDefinition, runListMemories, runGetMemory, } from "./memory-tools.js";
+export { SUGGEST_DOCUMENT_TOOL_NAME, WRITE_DOCUMENT_TOOL_NAME, DECLINE_DOCUMENT_TOOL_NAME, suggestDocumentToolDefinition, writeDocumentToolDefinition, declineDocumentToolDefinition, runSuggestDocument, runWriteDocument, runDeclineDocument, renderDocumentBody, documentFingerprint, } from "./document-tools.js";
+export { DEFAULT_SERVER_KEY, claudeDesktopConfigPath, buildRecallServerEntry, mergeServerEntry, parseExistingConfig, serializeConfig, } from "./install.js";
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAErF,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,uBAAuB,EACvB,eAAe,EACf,YAAY,GACb,MAAM,mBAAmB,CAAC;AAS3B,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,0BAA0B,EAC1B,6BAA6B,EAC7B,2BAA2B,EAC3B,6BAA6B,EAC7B,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAQ7B,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,EACtB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,GAChB,MAAM,cAAc,CAAC"}

package/dist/mcp/install.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Install helpers for registering the `vortex-mcp-recall` stdio server in an MCP
+ * host's config (slice 2). Everything here is PURE — path resolution, entry
+ * construction, and config merging are deterministic and unit-testable. The bin
+ * (scripts/mcp-stdio.mjs) does the actual file read/backup/write around them.
+ *
+ * Design rule: NEVER overwrite the user's whole config. We read the existing
+ * config, merge in (or update) only our one server entry under a stable key,
+ * and preserve every other server and top-level field untouched.
+ */
+export declare const DEFAULT_SERVER_KEY = "vortex-recall";
+export interface InstallEnv {
+    readonly platform?: NodeJS.Platform;
+    readonly home?: string;
+    readonly appData?: string;
+}
+/**
+ * Resolve the Claude Desktop config file path per documented OS locations:
+ *   - macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
+ *   - Windows: %APPDATA%/Claude/claude_desktop_config.json
+ *   - Linux:   ~/.config/Claude/claude_desktop_config.json  (unofficial)
+ */
+export declare function claudeDesktopConfigPath(env?: InstallEnv): string;
+/** A single MCP server entry as Claude Desktop expects it. */
+export interface McpServerEntry {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+}
+export interface BuildEntryOptions {
+    /** Absolute path to the instance data dir (passed to the server via --data-dir). */
+    readonly dataDir: string;
+    /**
+     * Launcher command. Default "npx" runs the published bin without a global
+     * install; pass "node" + an explicit script path for a local checkout.
+     */
+    readonly command?: string;
+    /** Override the args entirely (advanced; e.g. node + absolute bin path). */
+    readonly args?: readonly string[];
+}
+/**
+ * Build the server entry that launches `vortex-mcp-recall` with the given data
+ * dir. Default form: `npx vortex-mcp-recall --data-dir <dataDir>`.
+ */
+export declare function buildRecallServerEntry(options: BuildEntryOptions): McpServerEntry;
+export type McpConfig = {
+    mcpServers?: Record<string, McpServerEntry>;
+    [key: string]: unknown;
+};
+export interface MergeResult {
+    readonly config: McpConfig;
+    /** "added" if the key was new, "updated" if it replaced an existing entry. */
+    readonly action: "added" | "updated";
+    /** Server keys preserved untouched alongside ours (excludes our key). */
+    readonly preservedKeys: readonly string[];
+}
+/**
+ * Merge our server entry into an existing config object WITHOUT mutating the
+ * input. Every other `mcpServers` entry and every other top-level field is
+ * carried over verbatim. If our key already exists, it is replaced (idempotent
+ * re-install) and `action` is "updated".
+ */
+export declare function mergeServerEntry(existing: McpConfig | null | undefined, entry: McpServerEntry, key?: string): MergeResult;
+/**
+ * Parse an existing config file's text. Returns `{}` for empty/whitespace
+ * content (a fresh install). Throws on malformed JSON so the caller can abort
+ * rather than clobber a file the user hand-edited into an invalid state.
+ */
+export declare function parseExistingConfig(text: string | null | undefined): McpConfig;
+/** Serialize a config object the way Claude Desktop writes it (2-space, trailing newline). */
+export declare function serializeConfig(config: McpConfig): string;
+//# sourceMappingURL=install.d.ts.map

package/dist/mcp/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/mcp/install.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,UAAe,GAAG,MAAM,CAYpE;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,iBAAiB;IAChC,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAQjF;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC5C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,EACtC,KAAK,EAAE,cAAc,EACrB,GAAG,GAAE,MAA2B,GAC/B,WAAW,CAcb;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,CAiB9E;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAEzD"}

package/dist/mcp/install.js

@@ -0,0 +1,92 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Install helpers for registering the `vortex-mcp-recall` stdio server in an MCP
+ * host's config (slice 2). Everything here is PURE — path resolution, entry
+ * construction, and config merging are deterministic and unit-testable. The bin
+ * (scripts/mcp-stdio.mjs) does the actual file read/backup/write around them.
+ *
+ * Design rule: NEVER overwrite the user's whole config. We read the existing
+ * config, merge in (or update) only our one server entry under a stable key,
+ * and preserve every other server and top-level field untouched.
+ */
+export const DEFAULT_SERVER_KEY = "vortex-recall";
+/**
+ * Resolve the Claude Desktop config file path per documented OS locations:
+ *   - macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
+ *   - Windows: %APPDATA%/Claude/claude_desktop_config.json
+ *   - Linux:   ~/.config/Claude/claude_desktop_config.json  (unofficial)
+ */
+export function claudeDesktopConfigPath(env = {}) {
+    const platform = env.platform ?? process.platform;
+    const home = env.home ?? homedir();
+    const file = "claude_desktop_config.json";
+    if (platform === "darwin") {
+        return join(home, "Library", "Application Support", "Claude", file);
+    }
+    if (platform === "win32") {
+        const appData = env.appData ?? process.env.APPDATA ?? join(home, "AppData", "Roaming");
+        return join(appData, "Claude", file);
+    }
+    return join(home, ".config", "Claude", file);
+}
+/**
+ * Build the server entry that launches `vortex-mcp-recall` with the given data
+ * dir. Default form: `npx vortex-mcp-recall --data-dir <dataDir>`.
+ */
+export function buildRecallServerEntry(options) {
+    const dataDir = options.dataDir?.trim();
+    if (!dataDir) {
+        throw new Error("buildRecallServerEntry: dataDir is required");
+    }
+    const command = options.command ?? "npx";
+    const args = options.args ?? ["vortex-mcp-recall", "--data-dir", dataDir];
+    return { command, args };
+}
+/**
+ * Merge our server entry into an existing config object WITHOUT mutating the
+ * input. Every other `mcpServers` entry and every other top-level field is
+ * carried over verbatim. If our key already exists, it is replaced (idempotent
+ * re-install) and `action` is "updated".
+ */
+export function mergeServerEntry(existing, entry, key = DEFAULT_SERVER_KEY) {
+    const base = existing && typeof existing === "object" ? existing : {};
+    const existingServers = base.mcpServers && typeof base.mcpServers === "object" ? base.mcpServers : {};
+    const action = key in existingServers ? "updated" : "added";
+    const preservedKeys = Object.keys(existingServers).filter((k) => k !== key);
+    const config = {
+        ...base,
+        mcpServers: {
+            ...existingServers,
+            [key]: entry,
+        },
+    };
+    return { config, action, preservedKeys };
+}
+/**
+ * Parse an existing config file's text. Returns `{}` for empty/whitespace
+ * content (a fresh install). Throws on malformed JSON so the caller can abort
+ * rather than clobber a file the user hand-edited into an invalid state.
+ */
+export function parseExistingConfig(text) {
+    const trimmed = (text ?? "").trim();
+    if (trimmed.length === 0) {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch (e) {
+        throw new Error(`existing config is not valid JSON — refusing to overwrite. Fix or remove it first. (${e.message})`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("existing config is not a JSON object — refusing to overwrite.");
+    }
+    return parsed;
+}
+/** Serialize a config object the way Claude Desktop writes it (2-space, trailing newline). */
+export function serializeConfig(config) {
+    return JSON.stringify(config, null, 2) + "\n";
+}
+//# sourceMappingURL=install.js.map

package/dist/mcp/install.js.map

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

package/dist/mcp/memory-tools.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Read-only MCP tools alongside `recall` (slice 3): structured listing and
+ * full-entry reads over the memory sqlite index. Neither writes — keeping the
+ * MCP surface read-only honors "auto the plumbing, propose the prose": memory
+ * writes stay a proposal flow, not a directly-callable external tool.
+ *
+ * Unlike recall, these need no embedder — only the sqlite store — so they are
+ * cheap and never trigger a model load.
+ */
+export declare const LIST_MEMORIES_TOOL_NAME = "list_memories";
+export declare const GET_MEMORY_TOOL_NAME = "get_memory";
+export declare const listMemoriesToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            type: {
+                type: string;
+                description: string;
+            };
+            tag: {
+                type: string;
+                description: string;
+            };
+            privacy: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+};
+export declare const getMemoryToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            id: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export interface RunListArgs {
+    readonly type?: string;
+    readonly tag?: string;
+    readonly privacy?: string;
+    readonly limit?: number;
+}
+export interface RunGetArgs {
+    readonly id: string;
+}
+/** Both read tools need only the sqlite index path — no embedder. */
+export interface RunMemoryToolDeps {
+    /** Absolute path to <dataDir>/_indexes/memory.sqlite. */
+    readonly dbPath: string;
+    readonly defaultLimit?: number;
+}
+export interface MemorySummary {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly type: string;
+    readonly tags: readonly string[];
+    readonly updated: string | null;
+}
+export interface ListResult {
+    readonly count: number;
+    readonly memories: readonly MemorySummary[];
+}
+export interface GetResult {
+    readonly found: boolean;
+    readonly memory?: {
+        readonly id: string;
+        readonly name: string;
+        readonly description: string;
+        readonly type: string;
+        readonly privacy: string;
+        readonly created: string | null;
+        readonly updated: string | null;
+        readonly tags: readonly string[];
+        readonly body: string;
+    };
+}
+/**
+ * List memories, optionally filtered. With no filter, lists all (capped by
+ * limit). Opens + closes the sqlite store per call (releases the file lock —
+ * matters on Windows).
+ */
+export declare function runListMemories(args: RunListArgs, deps: RunMemoryToolDeps): Promise<ListResult>;
+/** Read one memory in full by id. Returns `{ found: false }` for empty id or miss. */
+export declare function runGetMemory(args: RunGetArgs, deps: RunMemoryToolDeps): Promise<GetResult>;
+//# sourceMappingURL=memory-tools.d.ts.map

package/dist/mcp/memory-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-tools.d.ts","sourceRoot":"","sources":["../../src/mcp/memory-tools.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,eAAO,MAAM,uBAAuB,kBAAkB,CAAC;AACvD,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;CAiBtC,CAAC;AAEF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;CAanC,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;QACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAsBrG;AAED,sFAAsF;AACtF,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CA4BhG"}

package/dist/mcp/memory-tools.js

@@ -0,0 +1,105 @@
+import { MemorySqliteStore } from "../sqlite/store.js";
+/**
+ * Read-only MCP tools alongside `recall` (slice 3): structured listing and
+ * full-entry reads over the memory sqlite index. Neither writes — keeping the
+ * MCP surface read-only honors "auto the plumbing, propose the prose": memory
+ * writes stay a proposal flow, not a directly-callable external tool.
+ *
+ * Unlike recall, these need no embedder — only the sqlite store — so they are
+ * cheap and never trigger a model load.
+ */
+export const LIST_MEMORIES_TOOL_NAME = "list_memories";
+export const GET_MEMORY_TOOL_NAME = "get_memory";
+export const listMemoriesToolDefinition = {
+    name: LIST_MEMORIES_TOOL_NAME,
+    description: "List the user's stored memories, optionally filtered by type, tag, or privacy. " +
+        "Returns lightweight summaries (id, name, description, type, tags, updated) WITHOUT " +
+        "full bodies — call get_memory for a full entry. Use this to browse what the user has " +
+        "stored before recalling or answering.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            type: { type: "string", description: "Filter to one memory type (e.g. feedback, project, reference)." },
+            tag: { type: "string", description: "Filter to memories carrying this tag." },
+            privacy: { type: "string", description: "Filter by privacy level (public, internal, personal)." },
+            limit: { type: "number", description: "Max entries to return (default 50)." },
+        },
+        required: [],
+    },
+};
+export const getMemoryToolDefinition = {
+    name: GET_MEMORY_TOOL_NAME,
+    description: "Read one memory in full by its id (the filename stem, e.g. 'feedback_response_concise'). " +
+        "Returns name, description, type, tags, dates, and the full markdown body. Use after " +
+        "list_memories or recall surfaces an id you want to read in full.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            id: { type: "string", description: "Memory id — the filename stem without the .md extension." },
+        },
+        required: ["id"],
+    },
+};
+/**
+ * List memories, optionally filtered. With no filter, lists all (capped by
+ * limit). Opens + closes the sqlite store per call (releases the file lock —
+ * matters on Windows).
+ */
+export async function runListMemories(args, deps) {
+    const q = {};
+    if (args.type?.trim())
+        q.type = [args.type.trim()];
+    if (args.tag?.trim())
+        q.tags = [args.tag.trim()];
+    if (args.privacy?.trim())
+        q.privacy = [args.privacy.trim()];
+    const limit = args.limit && args.limit > 0 ? args.limit : deps.defaultLimit ?? 50;
+    const store = new MemorySqliteStore(deps.dbPath);
+    try {
+        const rows = Object.keys(q).length > 0 ? store.query(q) : store.listAll();
+        const memories = rows.slice(0, limit).map((r) => ({
+            id: r.id,
+            name: r.name,
+            description: r.description,
+            type: r.type,
+            tags: r.tags,
+            updated: r.updated,
+        }));
+        return { count: memories.length, memories };
+    }
+    finally {
+        store.close();
+    }
+}
+/** Read one memory in full by id. Returns `{ found: false }` for empty id or miss. */
+export async function runGetMemory(args, deps) {
+    const id = (args.id ?? "").trim();
+    if (id.length === 0) {
+        return { found: false };
+    }
+    const store = new MemorySqliteStore(deps.dbPath);
+    try {
+        const row = store.getById(id);
+        if (!row) {
+            return { found: false };
+        }
+        return {
+            found: true,
+            memory: {
+                id: row.id,
+                name: row.name,
+                description: row.description,
+                type: row.type,
+                privacy: row.privacy,
+                created: row.created,
+                updated: row.updated,
+                tags: row.tags,
+                body: row.body,
+            },
+        };
+    }
+    finally {
+        store.close();
+    }
+}
+//# sourceMappingURL=memory-tools.js.map

package/dist/mcp/memory-tools.js.map

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

package/dist/mcp/recall-tool.d.ts

@@ -0,0 +1,52 @@
+import type { RecallResult } from "../recall/types.js";
+import type { EmbedFn, VectorSource } from "../vector/types.js";
+export declare const RECALL_TOOL_NAME = "recall";
+/**
+ * MCP tool descriptor for `recall`, as plain JSON (no MCP SDK types at build
+ * time — the SDK is an optional, runtime-resolved dependency). The low-level
+ * MCP Server validates the request envelope; arguments are read defensively in
+ * {@link runRecall} and the server handler.
+ */
+export declare const recallToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            k: {
+                type: string;
+                description: string;
+            };
+            source: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export interface RunRecallArgs {
+    readonly query: string;
+    readonly k?: number;
+    readonly source?: VectorSource;
+    readonly noHardFilter?: boolean;
+}
+export interface RunRecallDeps {
+    /** Embedding function — supply a warm embedder once and reuse it across calls. */
+    readonly embed: EmbedFn;
+    /** Absolute path to the memory SQLite index (e.g. <dataDir>/_indexes/memory.sqlite). */
+    readonly dbPath: string;
+    readonly defaultK?: number;
+}
+/**
+ * Open the recall stores, run a hybrid recall query, and always close the stores
+ * (releasing the SQLite file lock — critical on Windows). The embedder is injected,
+ * not opened here, so its one-time model load is amortised across the server's life.
+ */
+export declare function runRecall(args: RunRecallArgs, deps: RunRecallDeps): Promise<RecallResult>;
+//# sourceMappingURL=recall-tool.d.ts.map

package/dist/mcp/recall-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-tool.d.ts","sourceRoot":"","sources":["../../src/mcp/recall-tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKhE,eAAO,MAAM,gBAAgB,WAAW,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;CAmBhC,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AASD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAoB/F"}

package/dist/mcp/recall-tool.js

@@ -0,0 +1,60 @@
+import { recall as recallEngine } from "../recall/engine.js";
+import { MemorySqliteStore } from "../sqlite/store.js";
+import { MemoryVectorStore } from "../vector/store.js";
+import { SessionChunkStore } from "../vector/session.js";
+export const RECALL_TOOL_NAME = "recall";
+/**
+ * MCP tool descriptor for `recall`, as plain JSON (no MCP SDK types at build
+ * time — the SDK is an optional, runtime-resolved dependency). The low-level
+ * MCP Server validates the request envelope; arguments are read defensively in
+ * {@link runRecall} and the server handler.
+ */
+export const recallToolDefinition = {
+    name: RECALL_TOOL_NAME,
+    description: "Semantic search over the user's VortEX memory (markdown frontmatter memories + session archive). " +
+        "Returns structured hits: score, name, description, type, tags, and a short excerpt. " +
+        "Use it to recall prior context, decisions, preferences, or facts the user has stored.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: { type: "string", description: "Natural-language search query." },
+            k: { type: "number", description: "Maximum number of hits to return (default 5)." },
+            source: {
+                type: "string",
+                enum: ["memory", "session-archive"],
+                description: "Restrict the search to one corpus. Omit to search all.",
+            },
+        },
+        required: ["query"],
+    },
+};
+const EMPTY_RESULT = {
+    query: "",
+    intent: { filters: {}, semanticText: "", notes: ["empty query"] },
+    stage: { appliedFilters: {}, hardFilterCandidates: 0, hardFilterDropped: false, corpusSize: 0 },
+    hits: [],
+};
+/**
+ * Open the recall stores, run a hybrid recall query, and always close the stores
+ * (releasing the SQLite file lock — critical on Windows). The embedder is injected,
+ * not opened here, so its one-time model load is amortised across the server's life.
+ */
+export async function runRecall(args, deps) {
+    const query = (args.query ?? "").trim();
+    if (query.length === 0) {
+        return EMPTY_RESULT;
+    }
+    const k = args.k && args.k > 0 ? args.k : deps.defaultK ?? 5;
+    const sqlStore = new MemorySqliteStore(deps.dbPath);
+    const vecStore = new MemoryVectorStore({ db: deps.dbPath });
+    const chunkStore = new SessionChunkStore(deps.dbPath);
+    try {
+        return await recallEngine({ query, k, source: args.source, noHardFilter: args.noHardFilter }, { sqlite: sqlStore, vector: vecStore, embed: deps.embed, sessionChunks: chunkStore });
+    }
+    finally {
+        chunkStore.close();
+        vecStore.close();
+        sqlStore.close();
+    }
+}
+//# sourceMappingURL=recall-tool.js.map

package/dist/mcp/recall-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-tool.js","sourceRoot":"","sources":["../../src/mcp/recall-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAG7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,gBAAgB;IACtB,WAAW,EACT,mGAAmG;QACnG,sFAAsF;QACtF,uFAAuF;IACzF,WAAW,EAAE;QACX,IAAI,EAAE,QAAiB;QACvB,UAAU,EAAE;YACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gCAAgC,EAAE;YACxE,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,+CAA+C,EAAE;YACnF,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,QAAQ,EAAE,iBAAiB,CAAC;gBACnC,WAAW,EAAE,wDAAwD;aACtE;SACF;QACD,QAAQ,EAAE,CAAC,OAAO,CAAC;KACpB;CACF,CAAC;AAiBF,MAAM,YAAY,GAAiB;IACjC,KAAK,EAAE,EAAE;IACT,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,aAAa,CAAC,EAAE;IACjE,KAAK,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,oBAAoB,EAAE,CAAC,EAAE,iBAAiB,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE;IAC/F,IAAI,EAAE,EAAE;CACT,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAmB,EAAE,IAAmB;IACtE,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;IAE7D,MAAM,QAAQ,GAAG,IAAI,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,IAAI,iBAAiB,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5D,MAAM,UAAU,GAAG,IAAI,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,OAAO,MAAM,YAAY,CACvB,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,EAClE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,CACrF,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,UAAU,CAAC,KAAK,EAAE,CAAC;QACnB,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjB,QAAQ,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/mcp/server.d.ts

@@ -0,0 +1,32 @@
+import type { EmbedFn } from "../vector/types.js";
+export interface RecallServerOptions {
+    /** Warm embedder, created once by the host (see bin.ts / createLocalEmbedder). */
+    readonly embed: EmbedFn;
+    /** Absolute path to <dataDir>/_indexes/memory.sqlite. */
+    readonly dbPath: string;
+    /**
+     * Absolute path to the instance data dir (parent of data/<topic>/). Required
+     * for the document tools (suggest/write/decline). If omitted, those tools
+     * return an error rather than guessing a path.
+     */
+    readonly dataDir?: string;
+    readonly defaultK?: number;
+    readonly name?: string;
+    readonly version?: string;
+}
+/**
+ * The MCP SDK (`@modelcontextprotocol/sdk`) is an OPTIONAL dependency of
+ * memory-extended — only consumers who run the MCP server need it, exactly as
+ * `@huggingface/transformers` is optional for those who run the local embedder.
+ * So the SDK is loaded at runtime via dynamic import (a runtime-resolved
+ * specifier keeps tsc from requiring its types at build time), and the server
+ * is returned typed loosely. Hosts that never call this never pay for the SDK.
+ *
+ * Returns the connected-but-not-transported `Server` instance; the caller
+ * attaches a transport (stdio for slice 1) with `await server.connect(t)`.
+ */
+export declare function createRecallServer(options: RecallServerOptions): Promise<{
+    connect: (transport: unknown) => Promise<void>;
+    close: () => Promise<void>;
+}>;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAsBlD,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC;IAC9E,OAAO,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC,CA6FD"}