@nuzo/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,176 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the
+copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other
+entities that control, are controlled by, or are under common control with
+that entity. For the purposes of this definition, "control" means (i) the
+power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+(50%) or more of the outstanding shares, or (iii) beneficial ownership of
+such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation source,
+and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation
+or translation of a Source form, including but not limited to compiled
+object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form,
+that is based on (or derived from) the Work and for which the editorial
+revisions, annotations, elaborations, or other modifications represent, as a
+whole, an original work of authorship. For the purposes of this License,
+Derivative Works shall not include works that remain separable from, or
+merely link (or bind by name) to the interfaces of, the Work and Derivative
+Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner. For the
+purposes of this definition, "submitted" means any form of electronic,
+verbal, or written communication sent to the Licensor or its representatives,
+including but not limited to communication on electronic mailing lists,
+source code control systems, and issue tracking systems that are managed by,
+or on behalf of, the Licensor for the purpose of discussing and improving the
+Work, but excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on
+behalf of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily infringed
+by their Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You institute
+patent litigation against any entity (including a cross-claim or
+counterclaim in a lawsuit) alleging that the Work or a Contribution
+incorporated within the Work constitutes direct or contributory patent
+infringement, then any patent licenses granted to You under this License for
+that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy
+of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from
+the Source form of the Work, excluding those notices that do not pertain to
+any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution,
+then any Derivative Works that You distribute must include a readable copy of
+the attribution notices contained within such NOTICE file, excluding those
+notices that do not pertain to any part of the Derivative Works, in at least
+one of the following places: within a NOTICE text file distributed as part of
+the Derivative Works; within the Source form or documentation, if provided
+along with the Derivative Works; or, within a display generated by the
+Derivative Works, if and wherever such third-party notices normally appear.
+The contents of the NOTICE file are for informational purposes only and do
+not modify the License. You may add Your own attribution notices within
+Derivative Works that You distribute, alongside or as an addendum to the
+NOTICE text from the Work, provided that such additional attribution notices
+cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may
+provide additional or different license terms and conditions for use,
+reproduction, or distribution of Your modifications, or for any such
+Derivative Works as a whole, provided Your use, reproduction, and
+distribution of the Work otherwise complies with the conditions stated in
+this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein
+shall supersede or modify the terms of any separate license agreement you may
+have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as
+required for reasonable and customary use in describing the origin of the
+Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to
+in writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability
+to use the Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all other
+commercial damages or losses), even if such Contributor has been advised of
+the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work
+or Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree
+to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 fabionfsc
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,23 @@
+# @nuzo/mcp-server
+
+The MCP stdio server for Nuzo, a local-first and auditable memory layer for AI
+agents.
+
+The server exposes Nuzo memory tools and stores memory locally under
+`~/.nuzo/memory/` by default.
+
+Its read-only tools include recall, listing, audit history, export, and doctor
+diagnostics.
+
+Run a published version with:
+
+```bash
+npx --yes @nuzo/mcp-server@<version>
+```
+
+Use a fixed version in host plugins and automated configuration. Do not depend
+on `latest` for reproducible installs.
+
+Documentation: https://nuzo.com.br/
+
+License: Apache-2.0

package/dist/handlers.d.ts

@@ -0,0 +1,178 @@
+import type { MemoryExportDocument, MemoryKind, MemoryScope, MemoryService } from "@nuzo/memory-core";
+export interface RememberToolInput {
+    content: string;
+    kind: MemoryKind;
+    scope: string;
+    tags: string[];
+    source: string;
+    confidence?: number;
+}
+export interface RecallToolInput {
+    query: string;
+    scope: string;
+    limit: number;
+    include_global: boolean;
+}
+export interface RecallHookToolInput {
+    task_context: string;
+    project_scope?: string;
+    limit?: number;
+}
+export interface ListToolInput {
+    scope?: string;
+    tags: string[];
+    include_archived: boolean;
+}
+export interface UpdateToolInput {
+    id: string;
+    content?: string;
+    kind?: MemoryKind;
+    scope?: string;
+    tags?: string[];
+    confidence?: number;
+}
+export interface HistoryToolInput {
+    id: string;
+}
+export interface ForgetToolInput {
+    id: string;
+    mode: "archive" | "delete";
+    confirm: boolean;
+    reason?: string;
+}
+export interface ForgetManyToolInput {
+    scope?: string;
+    tags: string[];
+    all: boolean;
+    mode: "archive" | "delete";
+    confirm: boolean;
+    dry_run: boolean;
+    reason?: string;
+}
+export interface ExportToolInput {
+    scope?: string;
+    tags: string[];
+    include_archived: boolean;
+}
+export interface ImportToolInput {
+    document: MemoryExportDocument;
+    scope?: string;
+    dry_run: boolean;
+}
+export interface MemoryToolHandlerOptions {
+    storePath?: string;
+    doctorDiagnostics?: MemoryDoctorDiagnostics;
+}
+export interface MemoryDoctorDiagnostics {
+    schema?: {
+        currentVersion: number;
+        supportedVersion: number;
+    };
+    writable?: boolean;
+}
+export interface MemoryToolHandlers {
+    remember(input: RememberToolInput): Promise<{
+        id: string;
+        created: true;
+        warnings: string[];
+    }>;
+    recall(input: RecallToolInput): Promise<{
+        results: Array<{
+            id: string;
+            content: string;
+            kind: MemoryKind;
+            scope: MemoryScope;
+            tags: string[];
+            score: number;
+            reason: string;
+        }>;
+    }>;
+    recallHook(input: RecallHookToolInput): Promise<{
+        mode: "read_only";
+        memory_writes: false;
+        capture_suggestions: false;
+        query: string;
+        scope: MemoryScope;
+        include_global: true;
+        limit: number;
+        results: Array<{
+            id: string;
+            content: string;
+            kind: MemoryKind;
+            scope: MemoryScope;
+            tags: string[];
+            score: number;
+            reason: string;
+        }>;
+    }>;
+    list(input: ListToolInput): Promise<{
+        memories: MemoryToolRecord[];
+    }>;
+    update(input: UpdateToolInput): Promise<{
+        memory: MemoryToolRecord;
+    }>;
+    history(input: HistoryToolInput): Promise<{
+        events: MemoryToolEvent[];
+    }>;
+    forget(input: ForgetToolInput): Promise<{
+        id: string;
+        forgotten: true;
+        mode: "archive" | "delete";
+    }>;
+    forgetMany(input: ForgetManyToolInput): Promise<{
+        matched: number;
+        affected: number;
+        mode: "archive" | "delete";
+        dry_run: boolean;
+        ids: string[];
+    }>;
+    exportMemories(input: ExportToolInput): Promise<MemoryExportDocument>;
+    importMemories(input: ImportToolInput): Promise<{
+        imported: number;
+        skipped: number;
+        dry_run: boolean;
+    }>;
+    doctor(): Promise<{
+        ok: boolean;
+        network: "disabled";
+        store: {
+            path: string | null;
+            readable: boolean;
+            writable_check: "writable" | "not_writable" | "not_performed";
+        };
+        schema: {
+            current_version: number | null;
+            supported_version: number | null;
+            status: "current" | "outdated" | "newer" | "not_performed";
+        };
+        counts: {
+            active_memories: number | null;
+            archived_memories: number | null;
+            total_memories: number | null;
+        };
+        tools: string[];
+        warnings: string[];
+    }>;
+}
+export type MemoryToolRecord = {
+    id: string;
+    content: string;
+    kind: MemoryKind;
+    scope: MemoryScope;
+    tags: string[];
+    source: string;
+    confidence: number;
+    created_at: string;
+    updated_at: string;
+    last_used_at: string | null;
+    archived_at: string | null;
+};
+export type MemoryToolEvent = {
+    id: string;
+    memory_id: string | null;
+    event_type: string;
+    actor: string;
+    payload: Record<string, unknown>;
+    created_at: string;
+};
+export declare function createMemoryToolHandlers(service: MemoryService, options?: MemoryToolHandlerOptions): MemoryToolHandlers;

package/dist/handlers.js

@@ -0,0 +1,301 @@
+export function createMemoryToolHandlers(service, options = {}) {
+    return {
+        async remember(input) {
+            const rememberInput = {
+                content: input.content,
+                kind: input.kind,
+                scope: input.scope,
+                tags: input.tags,
+                source: input.source,
+            };
+            if (input.confidence !== undefined) {
+                rememberInput.confidence = input.confidence;
+            }
+            const memory = await service.remember(rememberInput);
+            return {
+                id: memory.id,
+                created: true,
+                warnings: [],
+            };
+        },
+        async recall(input) {
+            const results = await service.recall({
+                query: input.query,
+                scope: input.scope,
+                limit: input.limit,
+                includeGlobal: input.include_global,
+            });
+            return {
+                results: results.map(toRecallOutput),
+            };
+        },
+        async recallHook(input) {
+            const query = buildRecallHookQuery(input.task_context);
+            const limit = clampRecallHookLimit(input.limit);
+            const scope = (input.project_scope ?? "project:auto");
+            const results = await service.recall({
+                query,
+                scope,
+                limit,
+                includeGlobal: true,
+                recordUsage: false,
+            });
+            return {
+                mode: "read_only",
+                memory_writes: false,
+                capture_suggestions: false,
+                query,
+                scope,
+                include_global: true,
+                limit,
+                results: results.map(toRecallOutput),
+            };
+        },
+        async list(input) {
+            const listInput = {
+                includeArchived: input.include_archived,
+            };
+            if (input.scope !== undefined) {
+                listInput.scope = input.scope;
+            }
+            if (input.tags.length > 0) {
+                listInput.tags = input.tags;
+            }
+            const memories = await service.list(listInput);
+            return {
+                memories: memories.map(toToolRecord),
+            };
+        },
+        async update(input) {
+            const updateInput = {
+                id: input.id,
+                actor: "nuzo:mcp",
+            };
+            if (input.content !== undefined) {
+                updateInput.content = input.content;
+            }
+            if (input.kind !== undefined) {
+                updateInput.kind = input.kind;
+            }
+            if (input.scope !== undefined) {
+                updateInput.scope = input.scope;
+            }
+            if (input.tags !== undefined) {
+                updateInput.tags = input.tags;
+            }
+            if (input.confidence !== undefined) {
+                updateInput.confidence = input.confidence;
+            }
+            const memory = await service.update(updateInput);
+            return {
+                memory: toToolRecord(memory),
+            };
+        },
+        async history(input) {
+            const events = await service.history(input.id);
+            return {
+                events: events.map((event) => ({
+                    id: event.id,
+                    memory_id: event.memoryId,
+                    event_type: event.eventType,
+                    actor: event.actor,
+                    payload: event.payload,
+                    created_at: event.createdAt.toISOString(),
+                })),
+            };
+        },
+        async forget(input) {
+            const forgetInput = {
+                id: input.id,
+                mode: input.mode,
+                confirm: input.confirm,
+                actor: "nuzo:mcp",
+            };
+            if (input.reason !== undefined) {
+                forgetInput.reason = input.reason;
+            }
+            await service.forget(forgetInput);
+            return {
+                id: input.id,
+                forgotten: true,
+                mode: input.mode,
+            };
+        },
+        async forgetMany(input) {
+            const forgetInput = {
+                tags: input.tags,
+                all: input.all,
+                mode: input.mode,
+                confirm: input.confirm,
+                dryRun: input.dry_run,
+                actor: "nuzo:mcp",
+            };
+            if (input.scope !== undefined) {
+                forgetInput.scope = input.scope;
+            }
+            if (input.reason !== undefined) {
+                forgetInput.reason = input.reason;
+            }
+            const result = await service.forgetMany(forgetInput);
+            return {
+                matched: result.matched,
+                affected: result.affected,
+                mode: result.mode,
+                dry_run: result.dryRun,
+                ids: result.ids,
+            };
+        },
+        async exportMemories(input) {
+            const exportInput = {
+                actor: "nuzo:mcp",
+                includeArchived: input.include_archived,
+            };
+            if (input.scope !== undefined) {
+                exportInput.scope = input.scope;
+            }
+            if (input.tags.length > 0) {
+                exportInput.tags = input.tags;
+            }
+            return service.exportMemories(exportInput);
+        },
+        async importMemories(input) {
+            const importInput = {
+                document: input.document,
+                actor: "nuzo:mcp",
+                dryRun: input.dry_run,
+            };
+            if (input.scope !== undefined) {
+                importInput.scope = input.scope;
+            }
+            const result = await service.importMemories(importInput);
+            return {
+                imported: result.imported,
+                skipped: result.skipped,
+                dry_run: result.dryRun,
+            };
+        },
+        async doctor() {
+            const warnings = [];
+            let activeMemories = null;
+            let archivedMemories = null;
+            let totalMemories = null;
+            let readable = false;
+            try {
+                const [active, all] = await Promise.all([
+                    service.list({ includeArchived: false }),
+                    service.list({ includeArchived: true }),
+                ]);
+                activeMemories = active.length;
+                totalMemories = all.length;
+                archivedMemories = Math.max(totalMemories - activeMemories, 0);
+                readable = true;
+            }
+            catch (error) {
+                warnings.push(`memory store read check failed: ${formatDoctorError(error)}`);
+            }
+            const writableCheck = options.doctorDiagnostics?.writable === undefined
+                ? "not_performed"
+                : options.doctorDiagnostics.writable
+                    ? "writable"
+                    : "not_writable";
+            if (writableCheck === "not_writable") {
+                warnings.push("memory store writability check failed");
+            }
+            const schema = formatSchemaDiagnostics(options.doctorDiagnostics?.schema);
+            if (schema.status === "outdated") {
+                warnings.push("memory store schema is older than the supported version");
+            }
+            if (schema.status === "newer") {
+                warnings.push("memory store schema is newer than the supported version");
+            }
+            return {
+                ok: warnings.length === 0,
+                network: "disabled",
+                store: {
+                    path: options.storePath ?? null,
+                    readable,
+                    writable_check: writableCheck,
+                },
+                schema,
+                counts: {
+                    active_memories: activeMemories,
+                    archived_memories: archivedMemories,
+                    total_memories: totalMemories,
+                },
+                tools: [
+                    "memory.remember",
+                    "memory.recall",
+                    "memory.recall_hook",
+                    "memory.list",
+                    "memory.update",
+                    "memory.history",
+                    "memory.forget",
+                    "memory.forget_many",
+                    "memory.export",
+                    "memory.import",
+                    "memory.doctor",
+                ],
+                warnings,
+            };
+        },
+    };
+}
+function formatSchemaDiagnostics(schema) {
+    if (schema === undefined) {
+        return {
+            current_version: null,
+            supported_version: null,
+            status: "not_performed",
+        };
+    }
+    return {
+        current_version: schema.currentVersion,
+        supported_version: schema.supportedVersion,
+        status: schema.currentVersion === schema.supportedVersion
+            ? "current"
+            : schema.currentVersion < schema.supportedVersion
+                ? "outdated"
+                : "newer",
+    };
+}
+function formatDoctorError(error) {
+    if (error instanceof Error && error.message.length > 0) {
+        return error.message;
+    }
+    return "unknown error";
+}
+function buildRecallHookQuery(taskContext) {
+    return taskContext.trim().replace(/\s+/g, " ").slice(0, 500);
+}
+function clampRecallHookLimit(limit) {
+    if (limit === undefined) {
+        return 5;
+    }
+    return Math.min(Math.max(Math.trunc(limit), 1), 8);
+}
+function toRecallOutput(result) {
+    return {
+        id: result.memory.id,
+        content: result.memory.content,
+        kind: result.memory.kind,
+        scope: result.memory.scope,
+        tags: result.memory.tags,
+        score: result.score,
+        reason: result.reason,
+    };
+}
+function toToolRecord(memory) {
+    return {
+        id: memory.id,
+        content: memory.content,
+        kind: memory.kind,
+        scope: memory.scope,
+        tags: memory.tags,
+        source: memory.source,
+        confidence: memory.confidence,
+        created_at: memory.createdAt.toISOString(),
+        updated_at: memory.updatedAt.toISOString(),
+        last_used_at: memory.lastUsedAt?.toISOString() ?? null,
+        archived_at: memory.archivedAt?.toISOString() ?? null,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type MemoryService } from "@nuzo/memory-core";
+import type { MemoryDoctorDiagnostics } from "./handlers.js";
+export interface NuzoMcpServerOptions {
+    storePath?: string;
+    doctorDiagnostics?: MemoryDoctorDiagnostics;
+}
+export interface NuzoMcpServerRuntime {
+    server: McpServer;
+    close(): void;
+}
+export declare function createNuzoMcpServer(options?: NuzoMcpServerOptions): McpServer;
+export declare function createNuzoMcpServerRuntime(options?: NuzoMcpServerOptions): NuzoMcpServerRuntime;
+export declare function registerMemoryTools(server: McpServer, service: MemoryService, options?: NuzoMcpServerOptions): void;

package/dist/index.js

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+import { accessSync, constants, mkdirSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createMemoryService, DefaultPolicyEngine, RandomIdGenerator, RegexSecretScanner, SQLiteMemoryDatabase, SystemClock, memoryScopePattern, memoryTagPattern, schemaVersion, } from "@nuzo/memory-core";
+import { createMemoryToolHandlers } from "./handlers.js";
+const defaultStorePath = resolve(homedir(), ".nuzo", "memory", "memories.sqlite");
+const scopeSchema = z.string().regex(memoryScopePattern);
+const tagSchema = z.string().regex(memoryTagPattern);
+export function createNuzoMcpServer(options = {}) {
+    return createNuzoMcpServerRuntime(options).server;
+}
+export function createNuzoMcpServerRuntime(options = {}) {
+    const storePath = options.storePath ?? defaultStorePath;
+    const database = openDatabase(storePath);
+    const service = createService(database);
+    let closed = false;
+    const server = new McpServer({
+        name: "nuzo",
+        version: "0.1.0",
+    });
+    registerMemoryTools(server, service, {
+        storePath,
+        doctorDiagnostics: options.doctorDiagnostics ?? {
+            schema: {
+                currentVersion: database.getSchemaVersion(),
+                supportedVersion: schemaVersion,
+            },
+            writable: isStoreWritable(storePath),
+        },
+    });
+    return {
+        server,
+        close: () => {
+            if (!closed) {
+                database.close();
+                closed = true;
+            }
+        },
+    };
+}
+export function registerMemoryTools(server, service, options = {}) {
+    const handlerOptions = {
+        ...(options.storePath === undefined ? {} : { storePath: options.storePath }),
+        ...(options.doctorDiagnostics === undefined
+            ? {}
+            : { doctorDiagnostics: options.doctorDiagnostics }),
+    };
+    const handlers = createMemoryToolHandlers(service, handlerOptions);
+    server.registerTool("memory.remember", {
+        description: "Store a local Nuzo memory.",
+        inputSchema: {
+            content: z.string().min(1),
+            kind: z.enum(["preference", "project_decision", "fact", "instruction", "note"]),
+            scope: scopeSchema.default("user:default"),
+            tags: z.array(tagSchema).default([]),
+            source: z.string().min(1).default("nuzo:mcp"),
+            confidence: z.number().min(0).max(1).optional(),
+        },
+    }, async (input) => {
+        const rememberInput = {
+            content: input.content,
+            kind: input.kind,
+            scope: input.scope,
+            tags: input.tags,
+            source: input.source,
+        };
+        if (input.confidence !== undefined) {
+            rememberInput.confidence = input.confidence;
+        }
+        return jsonToolResult(await handlers.remember(rememberInput));
+    });
+    server.registerTool("memory.recall", {
+        description: "Recall relevant local Nuzo memories.",
+        inputSchema: {
+            query: z.string().min(1),
+            scope: scopeSchema.default("user:default"),
+            limit: z.number().int().min(1).max(50).default(8),
+            include_global: z.boolean().default(false),
+        },
+    }, async (input) => {
+        return jsonToolResult(await handlers.recall(input));
+    });
+    server.registerTool("memory.recall_hook", {
+        description: "Prototype read-only recall entrypoint for host lifecycle hooks. It never captures or creates memories.",
+        inputSchema: {
+            task_context: z.string().min(1),
+            project_scope: scopeSchema.optional(),
+            limit: z.number().int().min(1).max(8).default(5),
+        },
+    }, async (input) => {
+        const recallHookInput = {
+            task_context: input.task_context,
+            limit: input.limit,
+        };
+        if (input.project_scope !== undefined) {
+            recallHookInput.project_scope = input.project_scope;
+        }
+        return jsonToolResult(await handlers.recallHook(recallHookInput));
+    });
+    server.registerTool("memory.list", {
+        description: "List local Nuzo memories.",
+        inputSchema: {
+            scope: scopeSchema.optional(),
+            tags: z.array(tagSchema).default([]),
+            include_archived: z.boolean().default(false),
+        },
+    }, async (input) => {
+        const listInput = {
+            tags: input.tags,
+            include_archived: input.include_archived,
+        };
+        if (input.scope !== undefined) {
+            listInput.scope = input.scope;
+        }
+        return jsonToolResult(await handlers.list(listInput));
+    });
+    server.registerTool("memory.update", {
+        description: "Update a local Nuzo memory.",
+        inputSchema: {
+            id: z.string().min(1),
+            content: z.string().optional(),
+            kind: z.enum(["preference", "project_decision", "fact", "instruction", "note"]).optional(),
+            scope: scopeSchema.optional(),
+            tags: z.array(tagSchema).optional(),
+            confidence: z.number().min(0).max(1).optional(),
+        },
+    }, async (input) => {
+        const updateInput = {
+            id: input.id,
+        };
+        if (input.content !== undefined) {
+            updateInput.content = input.content;
+        }
+        if (input.kind !== undefined) {
+            updateInput.kind = input.kind;
+        }
+        if (input.scope !== undefined) {
+            updateInput.scope = input.scope;
+        }
+        if (input.tags !== undefined) {
+            updateInput.tags = input.tags;
+        }
+        if (input.confidence !== undefined) {
+            updateInput.confidence = input.confidence;
+        }
+        return jsonToolResult(await handlers.update(updateInput));
+    });
+    server.registerTool("memory.history", {
+        description: "List audit events for one Nuzo memory ID.",
+        inputSchema: {
+            id: z.string().min(1),
+        },
+    }, async (input) => {
+        const historyInput = {
+            id: input.id,
+        };
+        return jsonToolResult(await handlers.history(historyInput));
+    });
+    server.registerTool("memory.forget", {
+        description: "Archive or delete a local Nuzo memory.",
+        inputSchema: {
+            id: z.string().min(1),
+            mode: z.enum(["archive", "delete"]).default("archive"),
+            confirm: z.boolean().default(false),
+            reason: z.string().optional(),
+        },
+    }, async (input) => {
+        const forgetInput = {
+            id: input.id,
+            mode: input.mode,
+            confirm: input.confirm,
+        };
+        if (input.reason !== undefined) {
+            forgetInput.reason = input.reason;
+        }
+        return jsonToolResult(await handlers.forget(forgetInput));
+    });
+    server.registerTool("memory.forget_many", {
+        description: "Preview or apply a filtered bulk archive/delete operation.",
+        inputSchema: {
+            scope: scopeSchema.optional(),
+            tags: z.array(tagSchema).default([]),
+            all: z.boolean().default(false),
+            mode: z.enum(["archive", "delete"]).default("archive"),
+            confirm: z.boolean().default(false),
+            dry_run: z.boolean().default(true),
+            reason: z.string().optional(),
+        },
+    }, async (input) => {
+        const forgetInput = {
+            tags: input.tags,
+            all: input.all,
+            mode: input.mode,
+            confirm: input.confirm,
+            dry_run: input.dry_run,
+        };
+        if (input.scope !== undefined) {
+            forgetInput.scope = input.scope;
+        }
+        if (input.reason !== undefined) {
+            forgetInput.reason = input.reason;
+        }
+        return jsonToolResult(await handlers.forgetMany(forgetInput));
+    });
+    server.registerTool("memory.export", {
+        description: "Export local Nuzo memories as a versioned JSON document.",
+        inputSchema: {
+            scope: scopeSchema.optional(),
+            tags: z.array(tagSchema).default([]),
+            include_archived: z.boolean().default(false),
+        },
+    }, async (input) => {
+        const exportInput = {
+            tags: input.tags,
+            include_archived: input.include_archived,
+        };
+        if (input.scope !== undefined) {
+            exportInput.scope = input.scope;
+        }
+        return jsonToolResult(await handlers.exportMemories(exportInput));
+    });
+    server.registerTool("memory.import", {
+        description: "Import local Nuzo memories from a versioned JSON document.",
+        inputSchema: {
+            document: z.object({
+                format: z.literal("nuzo-memory-export"),
+                version: z.literal(1),
+                exported_at: z.string(),
+                memories: z.array(z.object({
+                    scope: scopeSchema,
+                    kind: z.enum(["preference", "project_decision", "fact", "instruction", "note"]),
+                    content: z.string(),
+                    tags: z.array(tagSchema),
+                    source: z.string().min(1),
+                    confidence: z.number().min(0).max(1),
+                    created_at: z.string(),
+                    updated_at: z.string(),
+                    last_used_at: z.string().nullable(),
+                    archived_at: z.string().nullable(),
+                })),
+            }),
+            scope: scopeSchema.optional(),
+            dry_run: z.boolean().default(false),
+        },
+    }, async (input) => {
+        const importInput = {
+            document: input.document,
+            dry_run: input.dry_run,
+        };
+        if (input.scope !== undefined) {
+            importInput.scope = input.scope;
+        }
+        return jsonToolResult(await handlers.importMemories(importInput));
+    });
+    server.registerTool("memory.doctor", {
+        description: "Report the local Nuzo MCP memory environment.",
+        inputSchema: {},
+    }, async () => {
+        return jsonToolResult(await handlers.doctor());
+    });
+}
+if (isMainModule()) {
+    const options = {};
+    if (process.env.NUZO_MEMORY_STORE !== undefined) {
+        options.storePath = process.env.NUZO_MEMORY_STORE;
+    }
+    const runtime = createNuzoMcpServerRuntime(options);
+    const closeRuntime = () => {
+        runtime.close();
+    };
+    process.once("SIGINT", () => {
+        closeRuntime();
+        process.exit(130);
+    });
+    process.once("SIGTERM", () => {
+        closeRuntime();
+        process.exit(143);
+    });
+    process.once("beforeExit", closeRuntime);
+    await runtime.server.connect(new StdioServerTransport());
+}
+function isMainModule() {
+    const entrypoint = process.argv[1];
+    if (entrypoint === undefined) {
+        return false;
+    }
+    try {
+        return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(entrypoint);
+    }
+    catch {
+        return false;
+    }
+}
+function openDatabase(storePath) {
+    mkdirSync(dirname(storePath), { recursive: true });
+    return new SQLiteMemoryDatabase({ path: storePath });
+}
+function isStoreWritable(storePath) {
+    try {
+        accessSync(dirname(storePath), constants.W_OK);
+        accessSync(storePath, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function createService(database) {
+    return createMemoryService({
+        store: database,
+        searchIndex: database,
+        auditLog: database,
+        clock: new SystemClock(),
+        ids: new RandomIdGenerator(),
+        policy: new DefaultPolicyEngine(new RegexSecretScanner()),
+        transactions: database,
+    });
+}
+function jsonToolResult(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@nuzo/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for Nuzo.",
+  "keywords": [
+    "ai-agents",
+    "mcp",
+    "memory",
+    "codex",
+    "claude-code",
+    "local-first"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22",
+    "npm": ">=10"
+  },
+  "bin": {
+    "nuzo-mcp-server": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@nuzo/memory-core": "0.1.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.1.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fabionfsc/nuzo-memory.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://nuzo.com.br/",
+  "bugs": {
+    "url": "https://github.com/fabionfsc/nuzo-memory/issues"
+  }
+}