memwarden 0.0.1

package/dist/kernel/pubsub.d.ts

@@ -0,0 +1,21 @@
+/** A stream item as emitted by `stream::set` / `stream::send`. */
+export interface StreamItem {
+    stream_name?: string;
+    group_id?: string;
+    item_id?: string;
+    id?: string;
+    type?: string;
+    data?: unknown;
+}
+export declare class PubSub {
+    private emitter;
+    constructor();
+    /** Subscribe to a durable topic (used by `durable:subscriber`). */
+    subscribe(topic: string, handler: (payload: unknown) => void): void;
+    /** Publish to a durable topic. */
+    publish(topic: string, payload: unknown): void;
+    /** Subscribe to the live stream surface (viewer wiring). */
+    onStream(handler: (item: StreamItem) => void): void;
+    /** Emit a stream item. Mirrors `stream::set` / `stream::send`. */
+    emitStream(item: StreamItem): void;
+}

package/dist/kernel/pubsub.js

@@ -0,0 +1,38 @@
+//
+// In-process pub/sub. In a single-process kernel a plain EventEmitter
+// satisfies both the
+// `durable:subscriber` topic triggers (events.ts) and the
+// `stream::set` / `stream::send` surface that observe.ts fires for the
+// live viewer. Durability is effectively unused: the four durable
+// topics duplicate paths already reachable synchronously via trigger.
+import { EventEmitter } from "node:events";
+export class PubSub {
+    emitter = new EventEmitter();
+    constructor() {
+        // The viewer/stream listeners are best-effort; never let an absent
+        // listener or a throwing one crash the process.
+        this.emitter.setMaxListeners(0);
+        this.emitter.on("error", () => {
+            /* swallow: pub/sub is best-effort */
+        });
+    }
+    /** Subscribe to a durable topic (used by `durable:subscriber`). */
+    subscribe(topic, handler) {
+        this.emitter.on(topicKey(topic), handler);
+    }
+    /** Publish to a durable topic. */
+    publish(topic, payload) {
+        this.emitter.emit(topicKey(topic), payload);
+    }
+    /** Subscribe to the live stream surface (viewer wiring). */
+    onStream(handler) {
+        this.emitter.on("stream", handler);
+    }
+    /** Emit a stream item. Mirrors `stream::set` / `stream::send`. */
+    emitStream(item) {
+        this.emitter.emit("stream", item);
+    }
+}
+function topicKey(topic) {
+    return `topic:${topic}`;
+}

package/dist/kernel/types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * HTTP methods the kernel's router understands. Mirrors the
+ * `http_method` values used across the wired route registrations.
+ */
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
+/**
+ * Request object handed to an HTTP-bound function. The body is the
+ * already-JSON-parsed request payload; headers preserve both the
+ * lowercase and original-case spellings the app reads.
+ */
+export interface ApiRequest<T = unknown> {
+    body?: T;
+    headers?: Record<string, string | undefined>;
+    query_params?: Record<string, string>;
+}
+/**
+ * Response shape every HTTP-bound function returns. The kernel sets the
+ * status, merges headers, and JSON-stringifies `body`.
+ */
+export interface ApiResponse {
+    status_code: number;
+    headers?: Record<string, string>;
+    body: unknown;
+}
+/**
+ * Result of an auth/validation middleware function. Either let the
+ * request through, or short-circuit with a canned response.
+ */
+export type MiddlewareResult = {
+    action: "continue";
+} | {
+    action: "respond";
+    response: {
+        status_code: number;
+        body: unknown;
+    };
+};
+/** A registered function: a plain (possibly async) handler. */
+export type FunctionHandler = (payload: any) => Promise<any> | any;
+/**
+ * Fire-and-forget sentinel. `TriggerAction.Void()` marks a trigger call
+ * whose result the caller does not await; a rejected Void trigger must
+ * never crash the process.
+ */
+export interface VoidAction {
+    __void: true;
+}
+/** Options accepted by `trigger`. */
+export interface TriggerOptions<P = any> {
+    function_id: string;
+    payload: P;
+    action?: VoidAction;
+}
+/**
+ * Discriminated trigger registration config. Binds an
+ * already-registered function to an external surface.
+ */
+export type TriggerConfig = {
+    type: "http";
+    function_id: string;
+    config: {
+        api_path: string;
+        http_method: HttpMethod;
+        middleware_function_ids?: string[];
+    };
+} | {
+    type: "durable:subscriber";
+    function_id: string;
+    config: {
+        topic: string;
+    };
+} | {
+    type: "state";
+    function_id: string;
+    config: {
+        scope: string;
+    };
+};
+/** Payload delivered to a `type:"state"` trigger on every KV mutation. */
+export interface StateChangeEvent {
+    key: string;
+    event_type: "set" | "update" | "delete";
+    old_value?: unknown;
+    new_value?: unknown;
+}
+/** Minimal OTel-shaped meter. add/record may be no-ops. */
+export interface Counter {
+    add: (n: number) => void;
+}
+export interface Histogram {
+    record: (v: number) => void;
+}
+export interface Meter {
+    createCounter: (name: string) => Counter;
+    createHistogram: (name: string) => Histogram;
+}
+/** Connection-state callback. Only `"connection_state"` is observed. */
+export type ConnectionStateListener = (state?: unknown) => void;
+/**
+ * Telemetry / otel metadata accepted by `registerWorker`. Ignored by
+ * the in-process kernel beyond being stored for introspection.
+ */
+export interface RegisterWorkerOptions {
+    workerName: string;
+    invocationTimeoutMs?: number;
+    otel?: {
+        serviceName: string;
+        serviceVersion: string;
+        metricsExportIntervalMs: number;
+    };
+    telemetry?: {
+        project_name: string;
+        language: string;
+        framework: string;
+    };
+}
+/**
+ * The single object the rest of the app talks to. Exactly the members
+ * the wired call sites reference. `on` and `getMeter` are optional and
+ * feature-detected by callers.
+ */
+export interface ISdk {
+    registerFunction(id: string, handler: FunctionHandler): void;
+    trigger<P = any, R = any>(opts: TriggerOptions<P>): Promise<R>;
+    registerTrigger(cfg: TriggerConfig): void;
+    on?(event: "connection_state", cb: ConnectionStateListener): void;
+    shutdown(): Promise<void>;
+    getMeter?(name: string): Meter;
+}
+/**
+ * Error carried by a rejected `trigger`. The process-level
+ * unhandledRejection handler in the boot entrypoint reads `code`,
+ * `function_id`, and `message`.
+ */
+export declare class TriggerError extends Error {
+    code: string;
+    function_id: string;
+    constructor(message: string, code: string, functionId: string);
+}

package/dist/kernel/types.js

@@ -0,0 +1,20 @@
+//
+// Type surface for the memwarden kernel. Only the members the app code
+// actually touches are modelled here; the kernel is an in-process,
+// single-instance runtime, so heavier runtime concepts (otel transport,
+// durable streams, worker fleets) collapse to no-ops or in-memory equivalents.
+/**
+ * Error carried by a rejected `trigger`. The process-level
+ * unhandledRejection handler in the boot entrypoint reads `code`,
+ * `function_id`, and `message`.
+ */
+export class TriggerError extends Error {
+    code;
+    function_id;
+    constructor(message, code, functionId) {
+        super(message);
+        this.name = "TriggerError";
+        this.code = code;
+        this.function_id = functionId;
+    }
+}

package/dist/mcp/bin.d.ts

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

package/dist/mcp/bin.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+//
+// memwarden MCP server entrypoint. Speaks JSON-RPC over stdio and proxies
+// to a running memwarden daemon. Point any MCP client at this:
+//
+//   { "command": "npx", "args": ["-y", "@memwarden/mcp"],
+//     "env": { "MEMWARDEN_URL": "http://localhost:3111" } }
+import { createMcpServer, runStdio } from "./server.js";
+import { ensureDaemon } from "../daemon/ensure.js";
+import { getSecret } from "../functions/config.js";
+const baseUrl = process.env.MEMWARDEN_URL ?? "http://localhost:3111";
+// Resolve env first, then the persisted <dataDir>/secret file, so a server
+// launched without the env var still authenticates to a secured daemon.
+const secret = getSecret();
+// Self-heal: revive the daemon on demand if a request finds it down.
+const ensureUp = async () => {
+    await ensureDaemon(baseUrl);
+};
+const server = createMcpServer({
+    baseUrl,
+    ensureUp,
+    ...(secret ? { secret } : {}),
+});
+// Warm the daemon at startup so the first recall is instant, but never block
+// the stdio handshake on it.
+void ensureDaemon(baseUrl).catch(() => undefined);
+runStdio(server);

package/dist/mcp/server.d.ts

@@ -0,0 +1,34 @@
+export interface McpServerOptions {
+    baseUrl: string;
+    secret?: string;
+    fetchFn?: typeof fetch;
+    cwd?: string;
+    ensureUp?: () => Promise<void>;
+}
+interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id?: string | number | null;
+    method: string;
+    params?: unknown;
+}
+interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export declare function createMcpServer(opts: McpServerOptions): {
+    dispatch: (req: JsonRpcRequest) => Promise<JsonRpcResponse | null>;
+    toolNames: () => string[];
+    promptNames: () => string[];
+};
+export type McpServer = ReturnType<typeof createMcpServer>;
+/**
+ * Wire a server to newline-delimited JSON-RPC over stdin/stdout. Kept thin
+ * and separate from dispatch() so the protocol logic stays testable.
+ */
+export declare function runStdio(server: McpServer): void;
+export {};

package/dist/mcp/server.js

@@ -0,0 +1,377 @@
+//
+// Dependency-free MCP server for memwarden. A hand-rolled JSON-RPC 2.0
+// dispatcher over stdio — no @modelcontextprotocol/sdk — so the core stays
+// lean and self-contained, and the dispatcher is unit-testable without a
+// host or a pipe. It proxies to a running memwarden daemon over HTTP, so
+// every MCP client (Claude Code, Cursor, Claude Desktop, Cline, Windsurf)
+// shares the one local brain.
+//
+// Beyond the usual save/search/context tools, it exposes the two memwarden
+// has and others don't: memory_verify (tamper-evident oplog integrity) and
+// memory_stats (live TurboQuant compression ratio).
+//
+// It also exposes an MCP *prompt*, `recall`, which clients surface as a
+// slash command (in Claude Code: `/mcp__memwarden__recall <query>`). The
+// user types it mid-chat, the server searches the project's memory and
+// returns the matching context as a message the client injects into the
+// conversation — on-demand recall from within any MCP-aware tool.
+const PROTOCOL_VERSION = "2024-11-05";
+const SERVER_NAME = "memwarden";
+const SERVER_VERSION = "0.1.0";
+function str(v, fallback = "") {
+    return typeof v === "string" && v.length > 0 ? v : fallback;
+}
+export function createMcpServer(opts) {
+    const base = opts.baseUrl.replace(/\/$/, "");
+    const doFetch = opts.fetchFn ?? fetch;
+    const serverCwd = opts.cwd ?? process.cwd();
+    async function api(method, path, body) {
+        const headers = { "content-type": "application/json" };
+        if (opts.secret)
+            headers["authorization"] = `Bearer ${opts.secret}`;
+        const init = {
+            method,
+            headers,
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        };
+        // One self-heal retry: a network error means the daemon is down; revive
+        // it and try again so the user's request just works.
+        for (let attempt = 0;; attempt++) {
+            try {
+                const res = await doFetch(`${base}${path}`, init);
+                const text = await res.text();
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    return { raw: text, status: res.status };
+                }
+            }
+            catch (err) {
+                if (attempt === 0 && opts.ensureUp) {
+                    await opts.ensureUp();
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+    const tools = [
+        {
+            name: "memory_resume",
+            description: "Recall what was being worked on in THIS project, across every past session and every agent (Claude, Codex, Cursor, …). Call this whenever the user references earlier work — e.g. 'continue what we were doing', 'review the project Claude and I built', 'what was I working on here', 'pick up from the last session'. Returns a narrative digest of the relevant prior context, already scoped to the current working directory, ready to act on.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "What to focus the recall on (e.g. 'the auth refactor', 'review the project'). Optional but improves relevance.",
+                    },
+                    cwd: {
+                        type: "string",
+                        description: "Working directory to scope to. Defaults to where this server was launched (the current project).",
+                    },
+                    token_budget: {
+                        type: "number",
+                        description: "Max tokens of context to return (default 2000).",
+                    },
+                },
+            },
+            call: (a) => api("POST", "/memwarden/search", {
+                query: str(a["query"], "what was I working on"),
+                cwd: str(a["cwd"], serverCwd),
+                format: "narrative",
+                limit: 20,
+                safe_only: true, // Verified Recall: never resume stale memory
+                ...(typeof a["token_budget"] === "number"
+                    ? { token_budget: a["token_budget"] }
+                    : { token_budget: 2000 }),
+            }),
+        },
+        {
+            name: "memory_remember",
+            description: "Save a memory so any agent can recall it later. Persisted to the local memwarden store.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    text: { type: "string", description: "The content to remember" },
+                    sessionId: { type: "string", description: "Optional session id" },
+                    project: { type: "string", description: "Optional project label" },
+                },
+                required: ["text"],
+            },
+            call: (a) => api("POST", "/memwarden/observe", {
+                hookType: "post_tool_use",
+                sessionId: str(a["sessionId"], "mcp"),
+                project: str(a["project"], "mcp"),
+                cwd: str(a["project"], "mcp"),
+                timestamp: new Date().toISOString(),
+                data: {
+                    tool_name: "memory_remember",
+                    tool_input: { text: str(a["text"]) },
+                    tool_output: str(a["text"]),
+                },
+            }),
+        },
+        {
+            name: "memory_search",
+            description: "Search memories by meaning and keywords (TurboQuant vector + BM25 hybrid). Returns ranked matches.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "What to look for" },
+                    limit: { type: "number", description: "Max results (default 10)" },
+                },
+                required: ["query"],
+            },
+            call: (a) => api("POST", "/memwarden/search", {
+                query: str(a["query"]),
+                limit: typeof a["limit"] === "number" ? a["limit"] : 10,
+            }),
+        },
+        {
+            name: "memory_context",
+            description: "Pack the most relevant prior memory for this project into a context block under a token budget.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Optional focus query" },
+                    cwd: { type: "string", description: "Working directory to scope to (defaults to this project)" },
+                    token_budget: { type: "number", description: "Optional token budget" },
+                },
+            },
+            // Routes through the project-scoped narrative search rather than
+            // /context (which needs a sessionId+project the MCP layer doesn't
+            // have). Returns a packed, budgeted context block.
+            call: (a) => api("POST", "/memwarden/search", {
+                query: str(a["query"], "relevant context for this project"),
+                cwd: str(a["cwd"], serverCwd),
+                format: "narrative",
+                limit: 20,
+                safe_only: true, // Verified Recall: never inject stale memory
+                ...(typeof a["token_budget"] === "number"
+                    ? { token_budget: a["token_budget"] }
+                    : { token_budget: 2000 }),
+            }),
+        },
+        {
+            name: "dejafix_lookup",
+            description: "Déjà Fix: before you try to fix an error, check if ANY agent (Claude, Codex, Cursor, …) already solved this exact error in THIS project. Paste the error message, stack trace, or failing-test output. Returns matching fixes that are still valid — each verified against the live repo (a fix whose files changed or vanished is suppressed, never surfaced) and badged 'verified current' or 'sourced, unverified'. Call this whenever you hit an error before debugging from scratch.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    error_text: {
+                        type: "string",
+                        description: "The error message, stack trace, or failing-test output to look up.",
+                    },
+                    cwd: {
+                        type: "string",
+                        description: "Working directory to scope to. Defaults to where this server was launched (the current project).",
+                    },
+                },
+                required: ["error_text"],
+            },
+            call: (a) => api("POST", "/memwarden/dejafix/lookup", {
+                error_text: str(a["error_text"]),
+                cwd: str(a["cwd"], serverCwd),
+            }),
+        },
+        {
+            name: "dejafix_record",
+            description: "Déjà Fix: record how an error was resolved so any agent that hits it again can recall the fix. Provide the original error text and a short fix narrative; optionally a root cause and the files the fix touched (hashed now so stale fixes are auto-suppressed later). Call this right after you resolve a non-trivial error.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    error_text: {
+                        type: "string",
+                        description: "The error message/stack trace that was resolved.",
+                    },
+                    fix: {
+                        type: "string",
+                        description: "Short narrative of the fix that resolved it.",
+                    },
+                    root_cause: {
+                        type: "string",
+                        description: "Optional one-line root cause.",
+                    },
+                    files: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Files the fix touched/relied on (relative to cwd). Hashed for drift detection.",
+                    },
+                    cwd: {
+                        type: "string",
+                        description: "Working directory to scope to. Defaults to where this server was launched.",
+                    },
+                },
+                required: ["error_text", "fix"],
+            },
+            call: (a) => api("POST", "/memwarden/dejafix/record", {
+                error_text: str(a["error_text"]),
+                fix: str(a["fix"]),
+                ...(typeof a["root_cause"] === "string" && a["root_cause"]
+                    ? { root_cause: a["root_cause"] }
+                    : {}),
+                ...(Array.isArray(a["files"])
+                    ? {
+                        files: a["files"].filter((f) => typeof f === "string"),
+                    }
+                    : {}),
+                cwd: str(a["cwd"], serverCwd),
+            }),
+        },
+        {
+            name: "memory_verify",
+            description: "Check the oplog hash chain is intact: tamper-EVIDENT integrity. Detects edits and reorders within the memory log (not tamper-proof: there is no signing yet, and truncating the newest entries is not detectable).",
+            inputSchema: { type: "object", properties: {} },
+            call: () => api("GET", "/memwarden/verify"),
+        },
+        {
+            name: "memory_stats",
+            description: "Report memory counts, the active embedding model, and the live TurboQuant compression ratio.",
+            inputSchema: { type: "object", properties: {} },
+            call: () => api("GET", "/memwarden/stats"),
+        },
+    ];
+    const toolByName = new Map(tools.map((t) => [t.name, t]));
+    // MCP prompts. Clients surface these as slash commands; `recall` is the
+    // on-demand "pull my memory into this chat" command the whole layer is for.
+    const prompts = [
+        {
+            name: "recall",
+            description: "Pull relevant memory from past sessions into THIS chat. Give it what you're working on (e.g. 'the auth refactor'); it searches your memwarden brain — scoped to the current project — and injects the matching context.",
+            arguments: [
+                {
+                    name: "query",
+                    description: "What to recall (e.g. 'auth refactor', 'the proxy work'). Optional — omit to resume the project broadly.",
+                    required: false,
+                },
+            ],
+        },
+    ];
+    async function recallText(query) {
+        try {
+            const result = (await api("POST", "/memwarden/search", {
+                query,
+                cwd: serverCwd,
+                format: "narrative",
+                limit: 20,
+                token_budget: 2000,
+                safe_only: true, // Verified Recall: /recall never injects stale memory
+            }));
+            return typeof result.text === "string" ? result.text : "";
+        }
+        catch {
+            return "";
+        }
+    }
+    function ok(id, result) {
+        return { jsonrpc: "2.0", id, result };
+    }
+    function fail(id, code, message) {
+        return { jsonrpc: "2.0", id, error: { code, message } };
+    }
+    // Returns the response, or null for notifications (no id / initialized).
+    async function dispatch(req) {
+        const id = req.id ?? null;
+        switch (req.method) {
+            case "initialize":
+                return ok(id, {
+                    protocolVersion: PROTOCOL_VERSION,
+                    capabilities: { tools: {}, prompts: {} },
+                    serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+                });
+            case "notifications/initialized":
+            case "initialized":
+                return null;
+            case "ping":
+                return ok(id, {});
+            case "tools/list":
+                return ok(id, {
+                    tools: tools.map((t) => ({
+                        name: t.name,
+                        description: t.description,
+                        inputSchema: t.inputSchema,
+                    })),
+                });
+            case "prompts/list":
+                return ok(id, { prompts });
+            case "prompts/get": {
+                const params = (req.params ?? {});
+                if (params.name !== "recall") {
+                    return fail(id, -32602, `unknown prompt: ${params.name}`);
+                }
+                const query = str(params.arguments?.["query"], "what was I working on in this project");
+                const text = await recallText(query);
+                const body = text
+                    ? `Relevant memory recalled by memwarden (scoped to this project) for "${query}":\n\n${text}`
+                    : `No relevant memory found for "${query}".`;
+                return ok(id, {
+                    description: `memwarden recall: ${query}`,
+                    messages: [{ role: "user", content: { type: "text", text: body } }],
+                });
+            }
+            case "tools/call": {
+                const params = (req.params ?? {});
+                const tool = params.name ? toolByName.get(params.name) : undefined;
+                if (!tool)
+                    return fail(id, -32602, `unknown tool: ${params.name}`);
+                try {
+                    const result = await tool.call(params.arguments ?? {});
+                    return ok(id, {
+                        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                    });
+                }
+                catch (err) {
+                    return ok(id, {
+                        isError: true,
+                        content: [
+                            {
+                                type: "text",
+                                text: `memory tool error: ${err instanceof Error ? err.message : String(err)}`,
+                            },
+                        ],
+                    });
+                }
+            }
+            default:
+                if (id === null)
+                    return null; // unknown notification
+                return fail(id, -32601, `method not found: ${req.method}`);
+        }
+    }
+    return {
+        dispatch,
+        toolNames: () => tools.map((t) => t.name),
+        promptNames: () => prompts.map((p) => p.name),
+    };
+}
+/**
+ * Wire a server to newline-delimited JSON-RPC over stdin/stdout. Kept thin
+ * and separate from dispatch() so the protocol logic stays testable.
+ */
+export function runStdio(server) {
+    let buffer = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+        buffer += chunk;
+        let nl;
+        while ((nl = buffer.indexOf("\n")) >= 0) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (!line)
+                continue;
+            let req;
+            try {
+                req = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            void server.dispatch(req).then((res) => {
+                if (res)
+                    process.stdout.write(JSON.stringify(res) + "\n");
+            });
+        }
+    });
+}