@topodb/pi 0.0.1

package/README.md

@@ -0,0 +1,14 @@
+# @topodb/pi
+
+One-command [TopoDB](https://github.com/TopoDB/TopoDB) memory for the
+[Pi](https://pi.dev) coding agent.
+
+    pi install npm:@topodb/pi
+
+Registers a single `topodb` tool that lazily spawns the `topodb-mcp` server and
+proxies its 16 memory tools. Call `{action:"list"}` to discover them, then
+`{tool, args}` to use one. Config via env: `TOPODB_DB` (default
+`.topodb/memory.redb`), `TOPODB_SCOPE` (default `shared`).
+
+No Rust toolchain and no separate MCP adapter required — the prebuilt
+`topodb-mcp` binary is pulled in automatically for your platform.

package/dist/extension.js

@@ -0,0 +1,52 @@
+import { Type } from "typebox";
+import { TopodbServer } from "./server-handle.js";
+export default function (pi) {
+    const server = new TopodbServer();
+    pi.registerTool({
+        name: "topodb",
+        label: "topodb memory",
+        description: "Persistent agent memory (temporal property graph). Call with " +
+            '{action:"list"} to see the available sub-tools and their schemas, then ' +
+            '{tool:"<name>", args:{...}} to invoke one.',
+        promptSnippet: "topodb: persistent memory. {action:\"list\"} to discover, then {tool,args}.",
+        promptGuidelines: [
+            "Before answering from prior context, recall with topodb search_memories/traverse.",
+            "Store durable facts (decisions, entities, relationships) with create_memory/create_entity/link.",
+        ],
+        parameters: Type.Object({
+            action: Type.Optional(Type.Literal("list")),
+            tool: Type.Optional(Type.String()),
+            args: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            try {
+                if (params.action === "list" && params.tool) {
+                    return {
+                        content: [
+                            { type: "text", text: 'error: provide exactly one of {action:"list"} or {tool, args}' },
+                        ],
+                        details: { error: "bad-params" },
+                    };
+                }
+                if (params.action === "list") {
+                    const tools = await server.list();
+                    return { content: [{ type: "text", text: JSON.stringify(tools) }], details: { action: "list" } };
+                }
+                if (!params.tool) {
+                    return {
+                        content: [{ type: "text", text: 'error: provide {action:"list"} or {tool, args}' }],
+                        details: { error: "bad-params" },
+                    };
+                }
+                const result = await server.call(params.tool, params.args ?? {});
+                return { content: [{ type: "text", text: JSON.stringify(result) }], details: { tool: params.tool } };
+            }
+            catch (e) {
+                return { content: [{ type: "text", text: `topodb error: ${e.message}` }], details: { error: true } };
+            }
+        },
+    });
+    pi.on("session_shutdown", async () => {
+        server.shutdown();
+    });
+}

package/dist/mcp-client.js

@@ -0,0 +1,110 @@
+// src/mcp-client.ts
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+export class McpStdioClient {
+    nodeArgs;
+    child;
+    rl;
+    nextId = 1;
+    pending = new Map();
+    requestTimeoutMs;
+    command;
+    constructor(nodeArgs, opts = {}) {
+        this.nodeArgs = nodeArgs;
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.command = opts.command ?? process.execPath;
+    }
+    get running() {
+        return !!this.child && this.child.exitCode === null && !this.child.killed;
+    }
+    async start() {
+        const child = spawn(this.command, this.nodeArgs, {
+            stdio: ["pipe", "pipe", "ignore"],
+        });
+        this.child = child;
+        // A spawn failure (bad executable, EMFILE/EAGAIN, ...) emits 'error' instead of
+        // (or in addition to) 'exit'. Without a handler this is an uncaught exception
+        // that crashes the host process. Route it through the same failAll() path.
+        child.on("error", (e) => this.failAll(e));
+        // Writing to stdin after the child has died surfaces as EPIPE here. failAll()
+        // (via the 'exit'/'error' handlers above) already rejects pending requests, so
+        // this handler exists purely to prevent an unhandled 'error' event from
+        // throwing and crashing the host process.
+        child.stdin.on("error", () => { });
+        this.rl = createInterface({ input: child.stdout });
+        this.rl.on("line", (line) => this.onLine(line));
+        child.on("exit", () => this.failAll(new Error("topodb-mcp exited")));
+        await this.request("initialize", {
+            protocolVersion: "2025-11-25",
+            capabilities: {},
+            clientInfo: { name: "topodb-pi", version: "0.0.1" },
+        });
+        this.notify("notifications/initialized");
+    }
+    async listTools() {
+        const r = (await this.request("tools/list"));
+        return r.tools ?? [];
+    }
+    async callTool(name, args) {
+        const r = (await this.request("tools/call", { name, arguments: args }));
+        // NOTE: tool-level MCP `isError:true` results are currently surfaced as a
+        // success (the content is returned as-is). Treating that as a rejection is
+        // deferred — accepted v0 limitation, tracked as finding 5.
+        return r.structuredContent ?? r.content ?? r;
+    }
+    stop() {
+        this.rl?.close();
+        this.child?.kill();
+        this.failAll(new Error("client stopped"));
+    }
+    onLine(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (typeof msg?.id !== "number")
+            return; // notifications/logs
+        const p = this.pending.get(msg.id);
+        if (!p)
+            return;
+        this.pending.delete(msg.id);
+        if (msg.error)
+            p.reject(new Error(msg.error.message ?? "MCP error"));
+        else
+            p.resolve(msg.result);
+    }
+    request(method, params) {
+        const id = this.nextId++;
+        const line = JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n";
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`topodb-mcp request timed out after ${this.requestTimeoutMs}ms: ${method}`));
+            }, this.requestTimeoutMs);
+            timer.unref?.();
+            this.pending.set(id, {
+                resolve: (v) => {
+                    clearTimeout(timer);
+                    resolve(v);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+            this.child.stdin.write(line);
+        });
+    }
+    notify(method, params) {
+        this.child.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n");
+    }
+    failAll(err) {
+        for (const p of this.pending.values())
+            p.reject(err);
+        this.pending.clear();
+    }
+}

package/dist/server-handle.js

@@ -0,0 +1,41 @@
+// src/server-handle.ts
+import { createRequire } from "node:module";
+import { McpStdioClient } from "./mcp-client.js";
+const require = createRequire(import.meta.url);
+export class TopodbServer {
+    env;
+    client;
+    toolCache;
+    constructor(env = process.env) {
+        this.env = env;
+    }
+    static resolveLauncher() {
+        return require.resolve("@topodb/topodb-mcp/bin/topodb-mcp.js");
+    }
+    args() {
+        const db = this.env.TOPODB_DB || ".topodb/memory.redb";
+        const scope = this.env.TOPODB_SCOPE || "shared";
+        return [TopodbServer.resolveLauncher(), "--db", db, "--scope", scope];
+    }
+    async ensure() {
+        if (this.client?.running)
+            return this.client;
+        this.client = new McpStdioClient(this.args());
+        await this.client.start();
+        return this.client;
+    }
+    async list() {
+        const c = await this.ensure();
+        if (!this.toolCache)
+            this.toolCache = await c.listTools();
+        return this.toolCache;
+    }
+    async call(tool, args) {
+        const c = await this.ensure();
+        return c.callTool(tool, args);
+    }
+    shutdown() {
+        this.client?.stop();
+        this.client = undefined;
+    }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@topodb/pi",
+  "version": "0.0.1",
+  "description": "Pi (pi.dev) extension: topodb agent memory via one install.",
+  "type": "module",
+  "license": "MIT OR Apache-2.0",
+  "repository": { "type": "git", "url": "https://github.com/TopoDB/TopoDB" },
+  "keywords": ["pi-package", "pi", "topodb", "memory", "mcp"],
+  "pi": { "extensions": ["./dist/extension.js"] },
+  "files": ["dist/", "README.md"],
+  "engines": { "node": ">=22.19.0" },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --import tsx --test \"test/*.test.ts\"",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@topodb/topodb-mcp": "0.0.3",
+    "typebox": "1.1.38"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "tsx": "^4.19.0",
+    "@earendil-works/pi-coding-agent": "0.80.6"
+  }
+}