@bli-cockpit/memory-mcp 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# @bli-cockpit/memory-mcp — BLI Memory
+
+An MCP server for **BLI Memory**, the memory layer BLI owns: one table in our
+own Postgres, four operations, no vendor in the path.
+
+Four tools:
+
+| Tool | What it does | Annotations |
+|---|---|---|
+| `search_memory` | Search one space by meaning, by keyword, and by recency at once. | read-only, idempotent |
+| `save_memory` | Remember something durable. `customId` upserts. `extract: true` distils atomic facts first. | additive |
+| `update_memory` | Replace what a memory says, keeping the old version as history. | additive |
+| `forget_memory` | Tombstone a memory by id, by exact text, or by the closest match ≥ 0.85. | **destructive** |
+
+`search_memory` and `save_memory` keep the names and argument names the hosted
+Supermemory MCP used, so an agent, a skill or a habit pointed at those words
+keeps working. `update_memory` is new — the vendor had no update tool at all,
+and correction there meant forget-then-save, which loses the link between the
+two.
+
+## Install
+
+```bash
+npm i -g @bli-cockpit/memory-mcp
+```
+
+Then register it. The server prints the exact block each host wants, so nothing
+has to be retyped:
+
+```bash
+bli-memory-mcp --print-config           # both
+bli-memory-mcp --print-config=claude    # ~/.claude.json  (or a plugin's .mcp.json)
+bli-memory-mcp --print-config=codex     # ~/.codex/config.toml
+```
+
+`cockpit memory install` (a later slice of BLI-3580) consumes those two blocks
+verbatim rather than keeping its own copy of them.
+
+## Auth
+
+None to set up. The server reads the collector's existing paired session at
+`~/.config/bli-cockpit/session.json` — the one `cockpit login` wrote — and
+sends that device token to Tower's memory doors. If the machine is not paired
+it says so, in one sentence, on **stderr**, and exits 1.
+
+Optional environment overrides:
+
+| Variable | Effect |
+|---|---|
+| `BLI_MEMORY_DEVICE_TOKEN` | Use this token instead of the session file (CI, containers). |
+| `BLI_MEMORY_DASHBOARD_URL` | Point at another Tower deployment. |
+| `BLI_MEMORY_CONTAINER_TAG` | Force the memory space, instead of deriving it. |
+| `BLI_MEMORY_ISOLATE_WORKTREES=1` | Give each worktree its own space rather than sharing the repo's. |
+
+## The space a memory lands in
+
+The container tag is computed exactly the way the old vendor plugin computed
+it — `repo_<name>__<sha256(normalised git remote)[0:16]>` — because that is
+what makes the switch invisible: the memories a repo had yesterday are the
+memories it has today. The **remote** is the identity, so every worktree of one
+repo shares a space. A folder that is not a git repository still gets its own
+space (`dir_<name>__<sha16>`), because a folder is a legitimate workspace.
+
+## The stdio contract
+
+**stdout carries the JSON-RPC stream and nothing else.** Every operational
+line — the startup banner, an auth failure, a warning — goes to stderr. The one
+exception is `--print-config`, which prints a config block to stdout and exits
+without opening a transport.
+
+## Two things worth knowing
+
+**Zero matches is data; a transport failure is not.** A search that found
+nothing returns text saying the record is silent. A search that could not run
+returns `isError` and names why. An agent that cannot tell those apart will
+confidently report the first when the second happened.
+
+**The old plugin's auto-approve regex does not match this server.** The vendor's
+Claude Code plugin ships a `PreToolUse` hook matching
+`^mcp__(?:plugin_supermemory_|claude_ai_)?supermemory__(.+)$` and auto-allowing
+its read-only tools. Our server is named `bli-memory`, so tool ids read
+`mcp__bli-memory__search_memory` and that hook does not fire — reads will
+prompt for permission until BLI ships its own plugin (with its own approve
+hook) through `bli-agents-marketplace`. Renaming this server to contain
+"supermemory" to inherit somebody else's auto-approve would be a worse trade
+than one extra prompt.
+
+## Development
+
+```bash
+npm run build --workspace=@bli-cockpit/memory-mcp
+npm test  --workspace=@bli-cockpit/memory-mcp
+```
+
+Publish: `npm publish --workspace=@bli-cockpit/memory-mcp --access public --tag latest`.
+
+Architecture, the trap list and the trial plan: `docs/architecture/agent-memory.md`.

package/dist/container-tag.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Scheme modified from supermemoryai/supermemory's Claude Code plugin
+ * `hooks/lib/container-tag.js:106-121` (plugin 0.1.5; repo commit
+ * 4d8a4ebfddadc3430f7f59a752cd374670833f50), MIT — see
+ * THIRD_PARTY_NOTICES.md. Rewritten in TypeScript with an argument-array
+ * spawn; the tag format is theirs and is kept byte for byte on purpose.
+ *
+ * Which space does this repository's memory live in? (BLI-3580)
+ *
+ * The scheme is the vendor plugin's, deliberately and exactly:
+ *
+ *     repo_<sanitised repo name, ≤72>__<sha256(normalised git remote)[0:16]>
+ *
+ * Matching it byte for byte is what makes the cutover invisible: an exported
+ * Supermemory container lands under the same tag the plugin was already
+ * writing, so the memories a repo had yesterday are the memories it has today.
+ * Inventing a nicer scheme would strand 5.7k memories in a space nothing asks
+ * about.
+ *
+ * The REMOTE is the identity, not the path, which is why every worktree of a
+ * repo shares one container — the property that made
+ * `repo_bli_cockpit__c69eb0d08c…` the biggest space on the shelf. With no
+ * remote (or with `BLI_MEMORY_ISOLATE_WORKTREES=1`) the fallback is the real
+ * path of the git root, hashed.
+ *
+ * No shell string is ever built here: `git` is spawned with an argument array
+ * and `shell: false`, the same rule `commands/editor.ts` follows in the
+ * collector.
+ */
+export declare const CONTAINER_TAG_MAX_NAME = 72;
+export interface ContainerTagOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Injected in tests. Returns stdout, or null when git said no. */
+    git?: (args: string[], cwd: string) => string | null;
+    realpath?: (value: string) => string;
+}
+export interface ContainerTagResult {
+    containerTag: string;
+    /** How it was derived, for the startup line. */
+    basis: "override" | "remote" | "path" | "cwd";
+}
+export declare function resolveContainerTag(options?: ContainerTagOptions): ContainerTagResult;
+/**
+ * The plugin's normalisation, restated: scheme and credentials dropped, `.git`
+ * suffix dropped, lowercased. `git@github.com:org/repo.git` and
+ * `https://github.com/org/repo` are one identity, which is the point.
+ */
+export declare function normalizeRemote(remote: string): string;

package/dist/container-tag.js

@@ -0,0 +1,108 @@
+/**
+ * Scheme modified from supermemoryai/supermemory's Claude Code plugin
+ * `hooks/lib/container-tag.js:106-121` (plugin 0.1.5; repo commit
+ * 4d8a4ebfddadc3430f7f59a752cd374670833f50), MIT — see
+ * THIRD_PARTY_NOTICES.md. Rewritten in TypeScript with an argument-array
+ * spawn; the tag format is theirs and is kept byte for byte on purpose.
+ *
+ * Which space does this repository's memory live in? (BLI-3580)
+ *
+ * The scheme is the vendor plugin's, deliberately and exactly:
+ *
+ *     repo_<sanitised repo name, ≤72>__<sha256(normalised git remote)[0:16]>
+ *
+ * Matching it byte for byte is what makes the cutover invisible: an exported
+ * Supermemory container lands under the same tag the plugin was already
+ * writing, so the memories a repo had yesterday are the memories it has today.
+ * Inventing a nicer scheme would strand 5.7k memories in a space nothing asks
+ * about.
+ *
+ * The REMOTE is the identity, not the path, which is why every worktree of a
+ * repo shares one container — the property that made
+ * `repo_bli_cockpit__c69eb0d08c…` the biggest space on the shelf. With no
+ * remote (or with `BLI_MEMORY_ISOLATE_WORKTREES=1`) the fallback is the real
+ * path of the git root, hashed.
+ *
+ * No shell string is ever built here: `git` is spawned with an argument array
+ * and `shell: false`, the same rule `commands/editor.ts` follows in the
+ * collector.
+ */
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+export const CONTAINER_TAG_MAX_NAME = 72;
+export function resolveContainerTag(options = {}) {
+    const env = options.env ?? process.env;
+    const cwd = options.cwd ?? process.cwd();
+    const git = options.git ?? runGit;
+    const realpath = options.realpath ?? ((value) => fs.realpathSync(value));
+    const override = (env.BLI_MEMORY_CONTAINER_TAG ?? env.SUPERMEMORY_REPO_TAG ?? "").trim();
+    if (override.length > 0)
+        return { containerTag: override, basis: "override" };
+    const root = git(["rev-parse", "--show-toplevel"], cwd);
+    if (!root) {
+        // Not a repository. A folder is still a legitimate workspace — the
+        // session-first commandment says so about collection and it holds here —
+        // so it gets its own space rather than being refused.
+        return {
+            containerTag: `dir_${sanitize(path.basename(cwd))}__${hash16(`path:${safeRealpath(cwd, realpath)}`)}`,
+            basis: "cwd",
+        };
+    }
+    const isolate = (env.BLI_MEMORY_ISOLATE_WORKTREES ?? "").trim() === "1";
+    const remote = isolate ? null : git(["config", "--get", "remote.origin.url"], cwd);
+    const name = sanitize(path.basename(root));
+    if (remote && remote.length > 0) {
+        return { containerTag: `repo_${name}__${hash16(normalizeRemote(remote))}`, basis: "remote" };
+    }
+    return {
+        containerTag: `repo_${name}__${hash16(`path:${safeRealpath(root, realpath)}`)}`,
+        basis: "path",
+    };
+}
+/**
+ * The plugin's normalisation, restated: scheme and credentials dropped, `.git`
+ * suffix dropped, lowercased. `git@github.com:org/repo.git` and
+ * `https://github.com/org/repo` are one identity, which is the point.
+ */
+export function normalizeRemote(remote) {
+    let value = remote.trim().toLowerCase();
+    value = value.replace(/^ssh:\/\//, "").replace(/^https?:\/\//, "").replace(/^git:\/\//, "");
+    value = value.replace(/^[^@/]+@/, "");
+    value = value.replace(/:/g, "/");
+    value = value.replace(/\.git$/, "");
+    return value.replace(/\/+$/, "");
+}
+function sanitize(name) {
+    const cleaned = name.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
+    const safe = cleaned.length > 0 ? cleaned : "workspace";
+    return safe.slice(0, CONTAINER_TAG_MAX_NAME);
+}
+function hash16(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex").slice(0, 16);
+}
+function safeRealpath(value, realpath) {
+    try {
+        return realpath(value);
+    }
+    catch {
+        // A path that will not resolve still identifies a workspace well enough to
+        // hash. Silence here is deliberate and bounded: the fallback is the same
+        // string the caller passed, so nothing is invented.
+        return value;
+    }
+}
+function runGit(args, cwd) {
+    const result = spawnSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        shell: false,
+        windowsHide: true,
+        timeout: 5_000,
+    });
+    if (result.status !== 0 || typeof result.stdout !== "string")
+        return null;
+    const value = result.stdout.trim();
+    return value.length > 0 ? value : null;
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * BLI Memory MCP server — entry point (BLI-3580).
+ *
+ * stdio only. **stdout is the JSON-RPC channel and carries nothing else**;
+ * every operational line goes to stderr. The one exception is
+ * `--print-config`, which prints a config block and exits without ever opening
+ * a transport.
+ *
+ * Usage:
+ *   bli-memory-mcp                          run the server over stdio
+ *   bli-memory-mcp --print-config           both host blocks
+ *   bli-memory-mcp --print-config --claude  the Claude Code JSON block
+ *   bli-memory-mcp --print-config --codex   the Codex TOML block
+ *   bli-memory-mcp --print-config=claude    the same, as one token
+ *
+ * Both spellings are accepted deliberately. `cockpit memory install`
+ * (BLI-3580's installer slice) spawns this with separate flags; a person
+ * typing it by hand tends to write the `=` form. A config printer that only
+ * understands one of them is a config printer somebody works around by
+ * hand-copying the block, which is how the two hosts drift apart.
+ *
+ * Auth is the collector's own device token (`cockpit login`). Environment
+ * overrides, all optional: `BLI_MEMORY_DEVICE_TOKEN`,
+ * `BLI_MEMORY_DASHBOARD_URL`, `BLI_MEMORY_CONTAINER_TAG`,
+ * `BLI_MEMORY_ISOLATE_WORKTREES=1`.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * BLI Memory MCP server — entry point (BLI-3580).
+ *
+ * stdio only. **stdout is the JSON-RPC channel and carries nothing else**;
+ * every operational line goes to stderr. The one exception is
+ * `--print-config`, which prints a config block and exits without ever opening
+ * a transport.
+ *
+ * Usage:
+ *   bli-memory-mcp                          run the server over stdio
+ *   bli-memory-mcp --print-config           both host blocks
+ *   bli-memory-mcp --print-config --claude  the Claude Code JSON block
+ *   bli-memory-mcp --print-config --codex   the Codex TOML block
+ *   bli-memory-mcp --print-config=claude    the same, as one token
+ *
+ * Both spellings are accepted deliberately. `cockpit memory install`
+ * (BLI-3580's installer slice) spawns this with separate flags; a person
+ * typing it by hand tends to write the `=` form. A config printer that only
+ * understands one of them is a config printer somebody works around by
+ * hand-copying the block, which is how the two hosts drift apart.
+ *
+ * Auth is the collector's own device token (`cockpit login`). Environment
+ * overrides, all optional: `BLI_MEMORY_DEVICE_TOKEN`,
+ * `BLI_MEMORY_DASHBOARD_URL`, `BLI_MEMORY_CONTAINER_TAG`,
+ * `BLI_MEMORY_ISOLATE_WORKTREES=1`.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { resolveContainerTag } from "./container-tag.js";
+import { parseFormat, printConfig } from "./print-config.js";
+import { createServer, SERVER_NAME } from "./server.js";
+import { loadMemorySession } from "./session.js";
+const TAG = "[bli-memory-mcp]";
+async function main() {
+    const argv = process.argv.slice(2);
+    const format = parseFormat(argv);
+    if (format === "invalid") {
+        process.stderr.write(`${TAG} unknown --print-config value — use claude, codex, or omit it for both\n`);
+        process.exit(2);
+    }
+    if (format) {
+        // The one thing that goes to stdout besides the protocol: an installer
+        // pipes this straight into a config file.
+        process.stdout.write(`${printConfig(format, {
+            command: "npx",
+            args: ["-y", "@bli-cockpit/memory-mcp"],
+            serverName: SERVER_NAME,
+        })}\n`);
+        return;
+    }
+    const session = loadMemorySession({ env: process.env });
+    if (!session.ok) {
+        process.stderr.write(`${TAG} ${session.reason}: ${session.message}\n`);
+        process.exit(1);
+    }
+    const container = resolveContainerTag({ cwd: process.cwd(), env: process.env });
+    // The startup line. Metadata only: which space, how it was derived, which
+    // host, where the credential came from. Never the token, never a path.
+    process.stderr.write(`${TAG} ready — container ${container.containerTag} (${container.basis}), ` +
+        `dashboard ${session.session.dashboardUrl}, auth ${session.session.source}\n`);
+    const server = createServer({
+        session: session.session,
+        fetchImpl: globalThis.fetch,
+        defaultContainerTag: container.containerTag,
+    });
+    await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+    process.stderr.write(`${TAG} fatal: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/print-config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `bli-memory-mcp --print-config` — the exact block each host wants
+ * (BLI-3580).
+ *
+ * A third slice of this ticket builds `cockpit memory install`, which registers
+ * this server on every machine, for Claude Code and for Codex. That installer
+ * must not hand-assemble JSON or TOML from a template it maintains separately —
+ * that is how the two drift and how a fleet ends up half-registered. It reads
+ * THESE strings verbatim, and so does a person doing it by hand.
+ *
+ * Two hosts, two formats, one server:
+ *
+ *   claude → the `mcpServers` entry for `~/.claude.json` (project or global) or
+ *            a plugin's `.mcp.json`. Claude Code speaks stdio here.
+ *   codex  → the `[mcp_servers.bli-memory]` block for `~/.codex/config.toml`.
+ *
+ * The stdio contract, stated once because both installers depend on it:
+ * **stdout is the MCP protocol channel and carries nothing else.** Every
+ * operational line — the startup banner, an auth failure, a warning — goes to
+ * stderr. A single stray `console.log` here corrupts the JSON-RPC stream and
+ * the host reports a server that "does not work" with no reason attached.
+ */
+export interface PrintConfigOptions {
+    /** How the host should launch this server. */
+    command: string;
+    args: string[];
+    serverName: string;
+    /** Env the block should carry, e.g. a dashboard override. Usually empty. */
+    env?: Record<string, string>;
+}
+export type ConfigFormat = "claude" | "codex" | "both";
+export declare function claudeConfigBlock(options: PrintConfigOptions): string;
+export declare function codexConfigBlock(options: PrintConfigOptions): string;
+export declare function printConfig(format: ConfigFormat, options: PrintConfigOptions): string;
+/**
+ * Which block was asked for, if any.
+ *
+ * Both spellings are accepted deliberately: `cockpit memory install` spawns
+ * separate flags (`--print-config --codex`) and a person typing it by hand
+ * writes `--print-config=codex`. A printer that understands only one of them
+ * is a printer somebody works around by hand-copying the block, which is how
+ * two hosts' configs drift apart.
+ *
+ * `null` means nobody asked and the server should start; `"invalid"` means a
+ * host was named that does not exist, which is a refusal rather than a
+ * silently-defaulted "both".
+ */
+export declare function parseFormat(argv: readonly string[]): ConfigFormat | "invalid" | null;

package/dist/print-config.js

@@ -0,0 +1,106 @@
+/**
+ * `bli-memory-mcp --print-config` — the exact block each host wants
+ * (BLI-3580).
+ *
+ * A third slice of this ticket builds `cockpit memory install`, which registers
+ * this server on every machine, for Claude Code and for Codex. That installer
+ * must not hand-assemble JSON or TOML from a template it maintains separately —
+ * that is how the two drift and how a fleet ends up half-registered. It reads
+ * THESE strings verbatim, and so does a person doing it by hand.
+ *
+ * Two hosts, two formats, one server:
+ *
+ *   claude → the `mcpServers` entry for `~/.claude.json` (project or global) or
+ *            a plugin's `.mcp.json`. Claude Code speaks stdio here.
+ *   codex  → the `[mcp_servers.bli-memory]` block for `~/.codex/config.toml`.
+ *
+ * The stdio contract, stated once because both installers depend on it:
+ * **stdout is the MCP protocol channel and carries nothing else.** Every
+ * operational line — the startup banner, an auth failure, a warning — goes to
+ * stderr. A single stray `console.log` here corrupts the JSON-RPC stream and
+ * the host reports a server that "does not work" with no reason attached.
+ */
+export function claudeConfigBlock(options) {
+    const entry = {
+        command: options.command,
+        args: options.args,
+    };
+    if (options.env && Object.keys(options.env).length > 0)
+        entry.env = options.env;
+    return JSON.stringify({ mcpServers: { [options.serverName]: entry } }, null, 2);
+}
+export function codexConfigBlock(options) {
+    const lines = [
+        `[mcp_servers.${options.serverName}]`,
+        `command = ${tomlString(options.command)}`,
+        `args = [${options.args.map(tomlString).join(", ")}]`,
+    ];
+    if (options.env && Object.keys(options.env).length > 0) {
+        lines.push(`[mcp_servers.${options.serverName}.env]`);
+        for (const [key, value] of Object.entries(options.env)) {
+            lines.push(`${key} = ${tomlString(value)}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function printConfig(format, options) {
+    if (format === "claude")
+        return claudeConfigBlock(options);
+    if (format === "codex")
+        return codexConfigBlock(options);
+    return [
+        "# Claude Code — merge into ~/.claude.json (or a plugin's .mcp.json)",
+        claudeConfigBlock(options),
+        "",
+        "# Codex — append to ~/.codex/config.toml",
+        codexConfigBlock(options),
+    ].join("\n");
+}
+/**
+ * A TOML basic string. Escaping is explicit rather than `JSON.stringify` by
+ * luck: the two formats agree on `\"` and `\\` and disagree elsewhere, and a
+ * path with a backslash in it is the normal case on Windows.
+ */
+function tomlString(value) {
+    const escaped = value
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\t/g, "\\t");
+    return `"${escaped}"`;
+}
+/**
+ * Which block was asked for, if any.
+ *
+ * Both spellings are accepted deliberately: `cockpit memory install` spawns
+ * separate flags (`--print-config --codex`) and a person typing it by hand
+ * writes `--print-config=codex`. A printer that understands only one of them
+ * is a printer somebody works around by hand-copying the block, which is how
+ * two hosts' configs drift apart.
+ *
+ * `null` means nobody asked and the server should start; `"invalid"` means a
+ * host was named that does not exist, which is a refusal rather than a
+ * silently-defaulted "both".
+ */
+export function parseFormat(argv) {
+    let asked = false;
+    let format = "both";
+    for (const arg of argv) {
+        if (arg === "--print-config") {
+            asked = true;
+            continue;
+        }
+        if (arg.startsWith("--print-config=")) {
+            asked = true;
+            const value = arg.slice("--print-config=".length).trim();
+            if (value !== "claude" && value !== "codex" && value !== "both")
+                return "invalid";
+            format = value;
+            continue;
+        }
+        if (asked && (arg === "--claude" || arg === "--codex" || arg === "--both")) {
+            format = arg.slice(2);
+        }
+    }
+    return asked ? format : null;
+}

package/dist/server.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Tool shapes modified from supermemoryai/supermemory
+ * `apps/mcp/src/server/tools/*.ts` + `container-tag.ts` at commit
+ * 4d8a4ebfddadc3430f7f59a752cd374670833f50, MIT — see THIRD_PARTY_NOTICES.md.
+ *
+ * BLI Memory — the MCP server (BLI-3580).
+ *
+ * Four tools, forwarding to the dashboard's four doors with this machine's
+ * collector device token. Tool NAMES and argument names match what the vendor
+ * MCP exposed (`search_memory`, `save_memory`), because every agent config,
+ * skill and habit already points at those words — the swap should be invisible
+ * from the outside. What a PERSON reads says BLI Memory.
+ *
+ * Shapes lifted from supermemoryai/supermemory `apps/mcp/src/server/tools/*`
+ * and `container-tag.ts` at commit 4d8a4ebfddadc3430f7f59a752cd374670833f50
+ * (MIT — see THIRD_PARTY_NOTICES.md): the argument names, the bounds
+ * (query ≤ 1000, content ≤ 200000, containerTag 1..128), the text-block +
+ * `structuredContent` twin (a model reads the prose, a program reads the rows),
+ * and the annotation sets. Reimplemented against our doors; the transport,
+ * the auth and every message are ours.
+ *
+ * Three wire contracts, each from somewhere that learned it the hard way:
+ *
+ *  - **Zero matches is data; a transport failure is not.** An empty search
+ *    returns text and NOT `isError`; a search that could not run returns
+ *    `isError` and names why. Collapsing them lets the calling agent
+ *    synthesise around an outage — ByteRover states it exactly this way and it
+ *    is this repo's own never-fail-silently rule as a wire contract.
+ *  - **Annotations on every tool.** `readOnlyHint` / `destructiveHint` /
+ *    `idempotentHint`, so a client knows not to retry a forget.
+ *  - **Tell the model when NOT to call it.** Each description carries USE WHEN
+ *    and DO NOT USE lines.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { MemorySession } from "./session.js";
+export declare const PACKAGE_NAME = "@bli-cockpit/memory-mcp";
+export declare const PACKAGE_VERSION = "0.1.0";
+/** The server id an MCP client registers. Named in every install block. */
+export declare const SERVER_NAME = "bli-memory";
+export type FetchImpl = typeof fetch;
+export interface ServerDeps {
+    session: MemorySession;
+    fetchImpl: FetchImpl;
+    /** The container tag when the caller did not name one. */
+    defaultContainerTag: string;
+    /** Injected in tests. */
+    now?: () => number;
+}
+export declare const searchMemoryInput: {
+    query: z.ZodString;
+    containerTag: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    includeProfile: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const saveMemoryInput: {
+    content: z.ZodString;
+    containerTag: z.ZodOptional<z.ZodString>;
+    customId: z.ZodOptional<z.ZodString>;
+    extract: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const updateMemoryInput: {
+    id: z.ZodString;
+    content: z.ZodString;
+};
+export declare const forgetMemoryInput: {
+    id: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodString>;
+    containerTag: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+};
+export declare function createServer(deps: ServerDeps): McpServer;
+/** The container tag this process will use when a tool names none. */
+export declare function defaultContainerTagFor(cwd: string, env: NodeJS.ProcessEnv): string;

package/dist/server.js

@@ -0,0 +1,297 @@
+/**
+ * Tool shapes modified from supermemoryai/supermemory
+ * `apps/mcp/src/server/tools/*.ts` + `container-tag.ts` at commit
+ * 4d8a4ebfddadc3430f7f59a752cd374670833f50, MIT — see THIRD_PARTY_NOTICES.md.
+ *
+ * BLI Memory — the MCP server (BLI-3580).
+ *
+ * Four tools, forwarding to the dashboard's four doors with this machine's
+ * collector device token. Tool NAMES and argument names match what the vendor
+ * MCP exposed (`search_memory`, `save_memory`), because every agent config,
+ * skill and habit already points at those words — the swap should be invisible
+ * from the outside. What a PERSON reads says BLI Memory.
+ *
+ * Shapes lifted from supermemoryai/supermemory `apps/mcp/src/server/tools/*`
+ * and `container-tag.ts` at commit 4d8a4ebfddadc3430f7f59a752cd374670833f50
+ * (MIT — see THIRD_PARTY_NOTICES.md): the argument names, the bounds
+ * (query ≤ 1000, content ≤ 200000, containerTag 1..128), the text-block +
+ * `structuredContent` twin (a model reads the prose, a program reads the rows),
+ * and the annotation sets. Reimplemented against our doors; the transport,
+ * the auth and every message are ours.
+ *
+ * Three wire contracts, each from somewhere that learned it the hard way:
+ *
+ *  - **Zero matches is data; a transport failure is not.** An empty search
+ *    returns text and NOT `isError`; a search that could not run returns
+ *    `isError` and names why. Collapsing them lets the calling agent
+ *    synthesise around an outage — ByteRover states it exactly this way and it
+ *    is this repo's own never-fail-silently rule as a wire contract.
+ *  - **Annotations on every tool.** `readOnlyHint` / `destructiveHint` /
+ *    `idempotentHint`, so a client knows not to retry a forget.
+ *  - **Tell the model when NOT to call it.** Each description carries USE WHEN
+ *    and DO NOT USE lines.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { resolveContainerTag } from "./container-tag.js";
+export const PACKAGE_NAME = "@bli-cockpit/memory-mcp";
+export const PACKAGE_VERSION = "0.1.0";
+/** The server id an MCP client registers. Named in every install block. */
+export const SERVER_NAME = "bli-memory";
+const READ_ONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+const ADDITIVE_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+};
+const DESTRUCTIVE_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false,
+};
+const containerTagSchema = z
+    .string()
+    .min(1)
+    .max(128)
+    .describe("The memory space. Omit it and this machine's own repository space is used, which is almost always what you want.");
+export const searchMemoryInput = {
+    query: z.string().min(1).max(1000).describe("What to look for, in plain language."),
+    containerTag: containerTagSchema.optional(),
+    limit: z.number().int().min(1).max(20).optional().describe("How many memories. Default 5."),
+    includeProfile: z
+        .boolean()
+        .optional()
+        .describe("Also return the newest memories in this space as recent context. Default true."),
+};
+export const saveMemoryInput = {
+    content: z.string().min(1).max(200_000).describe("The memory to store."),
+    containerTag: containerTagSchema.optional(),
+    customId: z
+        .string()
+        .min(1)
+        .max(255)
+        .optional()
+        .describe("A stable id for this memory's source, e.g. the session id. Saving twice with the same one updates rather than duplicates."),
+    extract: z
+        .boolean()
+        .optional()
+        .describe("Distil the content into atomic facts first (costs one model call). Default false: store it as given."),
+};
+export const updateMemoryInput = {
+    id: z.string().min(1).describe("The memory id, as returned by search_memory."),
+    content: z.string().min(1).max(200_000).describe("What it should say now."),
+};
+export const forgetMemoryInput = {
+    id: z.string().min(1).optional().describe("The memory id to forget."),
+    content: z
+        .string()
+        .min(1)
+        .max(10_000)
+        .optional()
+        .describe("The exact text to forget, when you do not have an id. Needs a containerTag."),
+    containerTag: containerTagSchema.optional(),
+    reason: z
+        .string()
+        .max(120)
+        .optional()
+        .describe("A short label for why, e.g. asked_by_person. Never prose."),
+};
+async function callDoor(deps, path, body) {
+    const url = `${deps.session.dashboardUrl}${path}`;
+    let response;
+    try {
+        response = await deps.fetchImpl(url, {
+            method: "POST",
+            headers: {
+                // The device token. Never logged, never echoed into a message.
+                authorization: `Bearer ${deps.session.deviceToken}`,
+                "content-type": "application/json",
+                accept: "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            status: 0,
+            body: {},
+            transportError: error instanceof Error ? error.message.split("\n")[0] : String(error),
+        };
+    }
+    let parsed = {};
+    try {
+        const text = await response.text();
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        return {
+            ok: false,
+            status: response.status,
+            body: {},
+            transportError: `Tower answered ${response.status} with a body this server could not read as JSON.`,
+        };
+    }
+    return { ok: response.ok, status: response.status, body: parsed, transportError: null };
+}
+function textResult(text, structured) {
+    return {
+        content: [{ type: "text", text }],
+        ...(structured ? { structuredContent: structured } : {}),
+    };
+}
+/**
+ * A failure, said out loud. `isError` is the difference between "the shelf is
+ * empty" and "nobody could reach the shelf", and an agent that cannot tell
+ * them apart will confidently report the first when the second happened.
+ */
+function errorResult(what, detail) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: `${what} ${detail}` }],
+    };
+}
+function doorFailure(door, response) {
+    if (response.transportError) {
+        return errorResult(`BLI Memory could not be reached (${door}).`, `${response.transportError} Nothing was read or written. This is an outage, not an empty memory store.`);
+    }
+    const message = typeof response.body.message === "string"
+        ? response.body.message
+        : `Tower answered ${response.status}.`;
+    const label = typeof response.body.error === "string" ? response.body.error : "unknown_error";
+    return errorResult(`BLI Memory refused the ${door} (${label}).`, message);
+}
+export function createServer(deps) {
+    const server = new McpServer({ name: SERVER_NAME, version: PACKAGE_VERSION });
+    const tagFor = (given) => given?.trim() || deps.defaultContainerTag;
+    server.registerTool("search_memory", {
+        title: "Search BLI Memory",
+        description: "Search what this project and this team have deliberately remembered — decisions, preferences, " +
+            "stable facts about people and systems. USE WHEN a question turns on something decided or " +
+            "learned earlier that the files in front of you do not answer. DO NOT USE to search code, " +
+            "recent commits, or the contents of the current repository — read those directly. " +
+            "Zero matches means the record is silent, not that the memory store is down; a store that " +
+            "could not answer says so explicitly.",
+        inputSchema: searchMemoryInput,
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (args) => {
+        const containerTag = tagFor(args.containerTag);
+        const response = await callDoor(deps, "/api/memory/search", {
+            query: args.query,
+            containerTag,
+            limit: args.limit,
+            includeProfile: args.includeProfile,
+        });
+        if (!response.ok)
+            return doorFailure("search", response);
+        const results = Array.isArray(response.body.results)
+            ? response.body.results
+            : [];
+        const recent = Array.isArray(response.body.recent)
+            ? response.body.recent
+            : [];
+        const lines = [];
+        if (results.length > 0) {
+            lines.push("## Matching memories");
+            for (const row of results) {
+                const similarity = Math.round(Number(row.similarity ?? 0) * 100);
+                lines.push(`- [${similarity}%] ${String(row.memory ?? "")} (id: ${String(row.id ?? "")})`);
+            }
+        }
+        else {
+            lines.push("No memories matched. The record is silent on this — it does not mean the store is empty.");
+        }
+        if (recent.length > 0) {
+            lines.push("", "## Recent context");
+            for (const row of recent)
+                lines.push(`- ${String(row.preview ?? row.memory ?? "")}`);
+        }
+        if (typeof response.body.degraded === "string" && response.body.degraded) {
+            lines.push("", `Note: this answer is thinner than usual (${response.body.degraded}) — one search channel did not run.`);
+        }
+        return textResult(lines.join("\n"), {
+            query: args.query,
+            containerTag,
+            results,
+            recent,
+            degraded: response.body.degraded ?? null,
+        });
+    });
+    server.registerTool("save_memory", {
+        title: "Save to BLI Memory",
+        description: "Remember something durable about this project or team. USE WHEN a decision is made, a " +
+            "preference is stated, a system's shape is established, or somebody commits to something — " +
+            "anything a teammate would need to know next month. DO NOT USE for transient state, code, " +
+            "tool output, or anything already in a file. Pass customId (e.g. the session id) when you " +
+            "may save the same thing again: it updates instead of duplicating.",
+        inputSchema: saveMemoryInput,
+        annotations: ADDITIVE_ANNOTATIONS,
+    }, async (args) => {
+        const containerTag = tagFor(args.containerTag);
+        const response = await callDoor(deps, "/api/memory/save", {
+            content: args.content,
+            containerTag,
+            customId: args.customId,
+            mode: args.extract ? "extract" : "verbatim",
+            sourceRef: { kind: "mcp", device_id: deps.session.deviceId },
+        });
+        if (!response.ok)
+            return doorFailure("save", response);
+        const outcome = String(response.body.outcome ?? "created");
+        const id = response.body.id === null ? "—" : String(response.body.id ?? "—");
+        const embedNote = response.body.embedded === false && response.body.embedSkippedReason
+            ? ` It was stored without a search vector (${String(response.body.embedSkippedReason)}), so it is findable by keyword and not yet by meaning.`
+            : "";
+        return textResult(`Memory ${outcome} in ${containerTag} (id: ${id}).${embedNote}`, response.body);
+    });
+    server.registerTool("update_memory", {
+        title: "Correct a memory",
+        description: "Replace what a memory says, keeping the old version as history. USE WHEN a remembered fact " +
+            "has CHANGED — a decision reversed, a preference moved, a name corrected. DO NOT USE to add a " +
+            "related fact (save it instead) and DO NOT USE to remove one (forget it instead). Search " +
+            "first: this needs the memory's id.",
+        inputSchema: updateMemoryInput,
+        annotations: ADDITIVE_ANNOTATIONS,
+    }, async (args) => {
+        const response = await callDoor(deps, "/api/memory/update", {
+            id: args.id,
+            content: args.content,
+        });
+        if (!response.ok)
+            return doorFailure("update", response);
+        return textResult(`Updated. The new memory is ${String(response.body.id ?? "")}, and ${String(response.body.supersededId ?? args.id)} is kept as its previous version.`, response.body);
+    });
+    server.registerTool("forget_memory", {
+        title: "Forget a memory",
+        description: "Remove a memory so it never comes back — including through later extraction, which is the " +
+            "part most memory tools get wrong. USE WHEN a person asks you to forget something, or a " +
+            "remembered fact turns out to be false. DO NOT USE for a fact that merely became outdated: " +
+            "update it, so the history survives. Give an id, or the exact text plus its containerTag.",
+        inputSchema: forgetMemoryInput,
+        annotations: DESTRUCTIVE_ANNOTATIONS,
+    }, async (args) => {
+        const response = await callDoor(deps, "/api/memory/forget", {
+            id: args.id,
+            content: args.content,
+            // Only defaulted for a content match, which is the case that would
+            // otherwise sweep the whole shelf. An id needs no space.
+            containerTag: args.content ? tagFor(args.containerTag) : args.containerTag,
+            reason: args.reason,
+        });
+        if (!response.ok)
+            return doorFailure("forget", response);
+        return textResult(String(response.body.message ?? "Forgotten."), response.body);
+    });
+    return server;
+}
+/** The container tag this process will use when a tool names none. */
+export function defaultContainerTagFor(cwd, env) {
+    return resolveContainerTag({ cwd, env }).containerTag;
+}

package/dist/session.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Who is this machine, and where does it send a memory? (BLI-3580)
+ *
+ * The collector already paired this laptop: `cockpit login` wrote
+ * `~/.config/bli-cockpit/session.json` holding the dashboard URL, the device id
+ * and a `bli_dev_*` device token, and `resolveCaller` in the dashboard already
+ * accepts that token on the memory doors. So this server invents NO fourth
+ * credential — it reads the one the fleet already has.
+ *
+ * The file is read directly rather than through `@bli-cockpit/local-collector`,
+ * deliberately: this package is published on its own and installed by an MCP
+ * config on machines that may not have the collector's node_modules on hand.
+ * The path and the three field names are the contract, and they are pinned by
+ * a test.
+ *
+ * The token is never logged, never printed, never returned in an error. What
+ * travels is the reason a session could not be loaded, which is what an
+ * operator can act on.
+ */
+export declare const SESSION_RELATIVE_PATH: string[];
+export type SessionFailure = "session_file_missing" | "session_file_unreadable" | "session_file_invalid" | "session_missing_token";
+export interface MemorySession {
+    dashboardUrl: string;
+    deviceToken: string;
+    deviceId: string;
+    /** Where it came from, for the startup line. Never the token itself. */
+    source: "env" | "session_file";
+}
+export type LoadSessionResult = {
+    ok: true;
+    session: MemorySession;
+} | {
+    ok: false;
+    reason: SessionFailure;
+    message: string;
+};
+export interface LoadSessionOptions {
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    readFile?: (file: string) => string;
+}
+export declare function sessionFilePath(homeDir?: string): string;
+/**
+ * Environment first (CI, a container, a machine that pairs some other way),
+ * then the paired session file. Both paths produce the same shape.
+ */
+export declare function loadMemorySession(options?: LoadSessionOptions): LoadSessionResult;
+/** The collector's own default (`local-state.ts:51`), restated for a package
+ * that must install without it. If that one moves, this moves. */
+export declare const DEFAULT_DASHBOARD_URL = "https://bli-cockpit-dashboard.vercel.app";

package/dist/session.js

@@ -0,0 +1,101 @@
+/**
+ * Who is this machine, and where does it send a memory? (BLI-3580)
+ *
+ * The collector already paired this laptop: `cockpit login` wrote
+ * `~/.config/bli-cockpit/session.json` holding the dashboard URL, the device id
+ * and a `bli_dev_*` device token, and `resolveCaller` in the dashboard already
+ * accepts that token on the memory doors. So this server invents NO fourth
+ * credential — it reads the one the fleet already has.
+ *
+ * The file is read directly rather than through `@bli-cockpit/local-collector`,
+ * deliberately: this package is published on its own and installed by an MCP
+ * config on machines that may not have the collector's node_modules on hand.
+ * The path and the three field names are the contract, and they are pinned by
+ * a test.
+ *
+ * The token is never logged, never printed, never returned in an error. What
+ * travels is the reason a session could not be loaded, which is what an
+ * operator can act on.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const SESSION_RELATIVE_PATH = [".config", "bli-cockpit", "session.json"];
+export function sessionFilePath(homeDir = os.homedir()) {
+    return path.join(homeDir, ...SESSION_RELATIVE_PATH);
+}
+/**
+ * Environment first (CI, a container, a machine that pairs some other way),
+ * then the paired session file. Both paths produce the same shape.
+ */
+export function loadMemorySession(options = {}) {
+    const env = options.env ?? process.env;
+    const readFile = options.readFile ?? ((file) => fs.readFileSync(file, "utf8"));
+    const envToken = (env.BLI_MEMORY_DEVICE_TOKEN ?? "").trim();
+    if (envToken.length > 0) {
+        return {
+            ok: true,
+            session: {
+                deviceToken: envToken,
+                deviceId: (env.BLI_MEMORY_DEVICE_ID ?? "env").trim() || "env",
+                dashboardUrl: normalizeUrl(env.BLI_MEMORY_DASHBOARD_URL ?? env.COCKPIT_DASHBOARD_URL ?? ""),
+                source: "env",
+            },
+        };
+    }
+    const file = sessionFilePath(options.homeDir ?? env.HOME ?? os.homedir());
+    let raw;
+    try {
+        raw = readFile(file);
+    }
+    catch (error) {
+        const missing = error?.code === "ENOENT";
+        return {
+            ok: false,
+            reason: missing ? "session_file_missing" : "session_file_unreadable",
+            message: missing
+                ? "This machine is not paired with Tower. Run `cockpit login` once, then restart your agent."
+                : "The Tower session file exists but could not be read. Run `cockpit login` again.",
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            ok: false,
+            reason: "session_file_invalid",
+            message: "The Tower session file is not valid JSON. Run `cockpit login` again.",
+        };
+    }
+    const record = parsed && typeof parsed === "object" ? parsed : {};
+    const deviceToken = typeof record.device_token === "string" ? record.device_token.trim() : "";
+    if (deviceToken.length === 0) {
+        return {
+            ok: false,
+            reason: "session_missing_token",
+            message: "The Tower session file carries no device token. Run `cockpit login` again.",
+        };
+    }
+    const envUrl = env.BLI_MEMORY_DASHBOARD_URL ?? env.COCKPIT_DASHBOARD_URL ?? "";
+    const fileUrl = typeof record.dashboard_url === "string" ? record.dashboard_url : "";
+    return {
+        ok: true,
+        session: {
+            deviceToken,
+            deviceId: typeof record.device_id === "string" ? record.device_id : "unknown",
+            // The env override wins so a developer can point one agent at a preview
+            // deployment without re-pairing the machine.
+            dashboardUrl: normalizeUrl(envUrl || fileUrl),
+            source: "session_file",
+        },
+    };
+}
+/** The collector's own default (`local-state.ts:51`), restated for a package
+ * that must install without it. If that one moves, this moves. */
+export const DEFAULT_DASHBOARD_URL = "https://bli-cockpit-dashboard.vercel.app";
+function normalizeUrl(value) {
+    const trimmed = value.trim().replace(/\/+$/, "");
+    return trimmed.length > 0 ? trimmed : DEFAULT_DASHBOARD_URL;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@bli-cockpit/memory-mcp",
+  "version": "0.1.0",
+  "private": false,
+  "description": "BLI Memory — an MCP server for the memory layer BLI owns (save, search, update, forget).",
+  "type": "module",
+  "bin": {
+    "bli-memory-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepack": "rm -rf dist && tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5",
+    "vitest": "^3.2.4"
+  }
+}