@stigmer/mcp-server 3.12.6 → 3.12.8

package/src/domains/memory/memory.integration.test.ts

@@ -0,0 +1,248 @@
+// In-process integration test for the memory roster (the
+// channels.integration.test.ts pattern: real Connect backend with a
+// stubbed memory service, real MCP client over an in-memory transport).
+//
+// Verifies the DD-005 D1/D2 contract surface:
+//   - the memory-only roster is exactly remember with ONLY a fact
+//     argument (agent audience; org, subject, and provenance are never
+//     the model's to supply);
+//   - argument + capture-context → request mapping: fact → spec.content,
+//     context org → metadata.org, context triple → spec.provenance,
+//     subject never travels, tool_call_id stays empty (v1);
+//   - the answer is the chip contract: { outcome, memory } with the
+//     created record as verbatim proto JSON and the honest
+//     proposed-not-remembered outcome line;
+//   - the memory-own error mapper passes domain messages verbatim as
+//     {error, code, reason} JSON; transport errors delegate to the
+//     shared classifier.
+
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError, type ConnectRouter } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import {
+  createServer as createHttp2Server,
+  type Http2Server,
+  type ServerHttp2Session,
+} from "node:http2";
+import type { AddressInfo } from "node:net";
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { MemorySchema, type Memory } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/api_pb";
+import { MemoryCommandController } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/command_pb";
+import { MemoryLifecycleState } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/enum_pb";
+import { MemorySpecSchema } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/spec_pb";
+import { MemoryStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/status_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { configureLogger } from "../../logger";
+import { MEMORY_ROUTE, createMemoryServer } from "../../server";
+import { PROPOSED_OUTCOME } from "./calls";
+import {
+  MEMORY_AGENT_ID_ENV,
+  MEMORY_AGENT_ID_HEADER,
+  MEMORY_EXECUTION_ID_ENV,
+  MEMORY_EXECUTION_ID_HEADER,
+  MEMORY_ORG_ENV,
+  MEMORY_ORG_HEADER,
+  MEMORY_SESSION_ID_ENV,
+  MEMORY_SESSION_ID_HEADER,
+} from "./context";
+
+configureLogger({ level: "error", format: "text" });
+
+let backend: Http2Server;
+let client: Client;
+const openSessions = new Set<ServerHttp2Session>();
+
+/** The next stubbed created record; tests set this. */
+let createResponse: () => Memory;
+
+/** Requests the stub captured (object property for closure narrowing). */
+const captured: { create?: Memory } = {};
+
+interface ToolResult {
+  content: Array<{ type: string; text?: string }>;
+  isError?: boolean;
+}
+
+async function remember(args: Record<string, unknown>): Promise<ToolResult> {
+  return (await client.callTool({ name: "remember", arguments: args })) as ToolResult;
+}
+
+/** A plausible created record echoing the request's content. */
+function proposedRecord(content: string): Memory {
+  return create(MemorySchema, {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "Memory",
+    metadata: create(ApiResourceMetadataSchema, { id: "mem_01test", org: "acme" }),
+    spec: create(MemorySpecSchema, {
+      content,
+      subjectIdentityAccountId: "ida_subject",
+    }),
+    status: create(MemoryStatusSchema, {
+      lifecycleState: MemoryLifecycleState.lifecycle_state_proposed,
+    }),
+  });
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(MemoryCommandController, {
+      create: (req) => {
+        captured.create = req;
+        return createResponse();
+      },
+    });
+  };
+  backend = createHttp2Server(connectNodeAdapter({ routes }));
+  backend.on("session", (session) => {
+    openSessions.add(session);
+    session.on("close", () => openSessions.delete(session));
+  });
+  await new Promise<void>((resolve) => backend.listen(0, "127.0.0.1", resolve));
+  const port = (backend.address() as AddressInfo).port;
+
+  // The stdio shape: the startup capture context stands in for the
+  // runner-set STIGMER_MEMORY_* environment.
+  const mcp = createMemoryServer(
+    { serverAddress: `127.0.0.1:${port}`, apiKey: "" },
+    { org: "acme", agentId: "agt_1", sessionId: "ses_1", agentExecutionId: "aex_1" },
+  );
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  client = new Client({ name: "memory-integration", version: "test" });
+  await Promise.all([mcp.connect(serverTransport), client.connect(clientTransport)]);
+});
+
+afterAll(async () => {
+  await client?.close();
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("memory roster (DD-005 D1)", () => {
+  it("exposes exactly remember with only a fact argument", async () => {
+    const { tools } = await client.listTools();
+    expect(tools.map((t) => t.name)).toEqual(["remember"]);
+
+    // The agent audience supplies the fact and NOTHING else — org,
+    // subject, and provenance derive from the credential and the
+    // runner-threaded capture context, so no argument exists to forge
+    // them (the channels no-org rule, applied to attribution).
+    const properties = (tools[0].inputSchema as { properties?: Record<string, unknown> })
+      .properties;
+    expect(Object.keys(properties ?? {})).toEqual(["fact"]);
+  });
+
+  it("pins the cross-repo attachment strings (the TOOL_CALL_LIMIT precedent)", () => {
+    // The runner's memory-attachment.ts builds these independently; a
+    // drift strands every synthesized attachment on a 404 (route) or an
+    // attribution-less record (context keys).
+    expect(MEMORY_ROUTE).toBe("/memory");
+    expect(MEMORY_ORG_ENV).toBe("STIGMER_MEMORY_ORG");
+    expect(MEMORY_AGENT_ID_ENV).toBe("STIGMER_MEMORY_AGENT_ID");
+    expect(MEMORY_SESSION_ID_ENV).toBe("STIGMER_MEMORY_SESSION_ID");
+    expect(MEMORY_EXECUTION_ID_ENV).toBe("STIGMER_MEMORY_EXECUTION_ID");
+    expect(MEMORY_ORG_HEADER).toBe("x-stigmer-memory-org");
+    expect(MEMORY_AGENT_ID_HEADER).toBe("x-stigmer-memory-agent-id");
+    expect(MEMORY_SESSION_ID_HEADER).toBe("x-stigmer-memory-session-id");
+    expect(MEMORY_EXECUTION_ID_HEADER).toBe("x-stigmer-memory-execution-id");
+  });
+});
+
+describe("argument + capture context → request mapping (DD-005 D2)", () => {
+  it("maps the fact and the startup context; subject never travels", async () => {
+    createResponse = () => proposedRecord("Prefers concise answers.");
+    captured.create = undefined;
+
+    const result = await remember({ fact: "Prefers concise answers." });
+
+    expect(result.isError).toBeFalsy();
+    const req = captured.create;
+    expect(req?.metadata?.org).toBe("acme");
+    expect(req?.metadata?.name).toBe(""); // id-addressed; the server defaults the name
+    expect(req?.spec?.content).toBe("Prefers concise answers.");
+    // Subject is the server's to derive from the credential — the tool
+    // never supplies one, so forgery is structurally impossible.
+    expect(req?.spec?.subjectIdentityAccountId).toBe("");
+    expect(req?.spec?.provenance?.agentId).toBe("agt_1");
+    expect(req?.spec?.provenance?.sessionId).toBe("ses_1");
+    expect(req?.spec?.provenance?.agentExecutionId).toBe("aex_1");
+    // v1: MCP does not carry the harness's tool-call identity.
+    expect(req?.spec?.provenance?.toolCallId).toBe("");
+  });
+
+  it("answers with the chip contract: outcome line + created record as proto JSON", async () => {
+    createResponse = () => proposedRecord("Works primarily in Go.");
+
+    const result = await remember({ fact: "Works primarily in Go." });
+
+    expect(result.isError).toBeFalsy();
+    const body = JSON.parse(result.content[0]?.text ?? "{}") as {
+      outcome?: string;
+      memory?: Record<string, unknown>;
+    };
+    // The honest relay (DD-005 D2): proposed, the user decides.
+    expect(body.outcome).toBe(PROPOSED_OUTCOME);
+    // The record rides verbatim with proto (snake_case) field names —
+    // what the SDK's normalizeToolResult parses to render the chip.
+    const memory = body.memory as {
+      metadata?: { id?: string };
+      spec?: { content?: string };
+      status?: { lifecycle_state?: string };
+    };
+    expect(memory?.metadata?.id).toBe("mem_01test");
+    expect(memory?.spec?.content).toBe("Works primarily in Go.");
+    expect(memory?.status?.lifecycle_state).toBe("lifecycle_state_proposed");
+  });
+});
+
+describe("memory error mapper", () => {
+  it("passes the visible-full refusal through verbatim — never the shared rewrite", async () => {
+    createResponse = () => {
+      throw new ConnectError(
+        "memory is full — review and delete existing memories",
+        Code.FailedPrecondition,
+      );
+    };
+
+    const result = await remember({ fact: "One fact too many." });
+
+    expect(result.isError).toBe(true);
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual({
+      error: "memory is full — review and delete existing memories",
+      code: "FAILED_PRECONDITION",
+    });
+  });
+
+  it("passes the caller-gate refusal through verbatim", async () => {
+    createResponse = () => {
+      throw new ConnectError(
+        "memory capture is limited to first-party sessions",
+        Code.PermissionDenied,
+      );
+    };
+
+    const result = await remember({ fact: "A fact from the wrong caller." });
+
+    expect(result.isError).toBe(true);
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual({
+      error: "memory capture is limited to first-party sessions",
+      code: "PERMISSION_DENIED",
+    });
+  });
+
+  it("delegates transport codes to the shared classifier", async () => {
+    createResponse = () => {
+      throw new ConnectError("upstream down", Code.Unavailable);
+    };
+
+    const result = await remember({ fact: "Any fact." });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toBe(
+      "Stigmer server is unavailable. Ensure it is running and reachable.",
+    );
+  });
+});

package/src/domains/memory/tools.ts

@@ -0,0 +1,75 @@
+// The remember tool — the ONE tool of the memory roster (DD-005 D1: the
+// first-party capture verb both harnesses receive through the
+// runner-synthesized memory attachment).
+//
+// Agent audience only, by construction: this roster is what the memory
+// attachment connects to, and the record's org, subject, and provenance
+// all derive from the credential and the runner-threaded capture context
+// (context.ts) — no org argument exists to invite rejected calls, and no
+// argument can aim the record at another person. The tool is deliberately
+// NOT on the full roster: a human operator manages memories through the
+// console and SDK, which carry the addressing this path derives.
+//
+// The tool creates a PROPOSAL and nothing more (DD-005 D2/D3): the record
+// lands lifecycle_state=proposed, and only the user's confirm — a
+// control-plane command the model cannot reach — makes it recallable. The
+// answer's `outcome` line states this so the model relays honestly.
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { resolveToken, type BackendTarget } from "../client.js";
+import { proposeMemory } from "./calls.js";
+import {
+  resolveCaptureContext,
+  type CaptureContext,
+  type RequestHeaders,
+} from "./context.js";
+import { memoryResult } from "./errors.js";
+
+/**
+ * Register the memory capture tool; returns the tool names.
+ *
+ * `startupContext` is the stdio-shape capture context (env-loaded at
+ * server construction); over HTTP each request's headers supersede it —
+ * the resolveToken fallback shape, applied to attribution.
+ */
+export function registerMemoryTools(
+  server: McpServer,
+  target: BackendTarget,
+  startupContext: CaptureContext,
+): string[] {
+  server.registerTool(
+    "remember",
+    {
+      description:
+        "Propose one durable fact about the person you are assisting, to be recalled in " +
+        "their future sessions — a stable preference, situation, or way of working " +
+        "(e.g. \"Prefers concise answers with code examples\"). Not task state, not " +
+        "secrets or credentials, not one-off details. The fact is only PROPOSED: the " +
+        "user reviews the exact text and decides — tell them you have suggested it, " +
+        "never that you have remembered it. Keep each fact self-contained and under " +
+        "500 characters; call once per fact.",
+      inputSchema: {
+        fact: z
+          .string()
+          .describe(
+            "The fact to remember, stated in the third person and self-contained " +
+              '(e.g. "Works primarily in Go and prefers table-driven tests"). ' +
+              "1–500 characters; stored and shown to the user verbatim.",
+          ),
+      },
+    },
+    (args, extra) =>
+      memoryResult("memory proposal", () =>
+        proposeMemory(
+          target.serverAddress,
+          resolveToken(extra, target.apiKey),
+          args.fact,
+          resolveCaptureContext(extra as RequestHeaders, startupContext),
+        ),
+      ),
+  );
+
+  return ["remember"];
+}

package/src/http.integration.test.ts

@@ -212,6 +212,7 @@ describe("HTTP route dispatch (the closed route table)", () => {
     ["/", "mcp-server-stigmer"],
     ["/channels", "mcp-server-stigmer-channels"],
     ["/conversation", "mcp-server-stigmer-conversation"],
+    ["/memory", "mcp-server-stigmer-memory"],
   ])("serves the %s roster as %s", async (path, serverName) => {
     const res = await initialize(path);
     expect(res.status).toBe(200);

package/src/index.ts

@@ -23,8 +23,10 @@ export {
   CONVERSATION_ROUTE,
   createChannelsServer,
   createConversationServer,
+  createMemoryServer,
   createServer,
   FULL_ROUTE,
+  MEMORY_ROUTE,
   SERVER_VERSION,
 } from "./server.js";
 

package/src/server.ts

@@ -31,6 +31,11 @@ import { registerEnvironmentTools } from "./domains/environments/tools.js";
 import { registerExecutionControlTools } from "./domains/executions/tools.js";
 import { registerMcpServerResources } from "./domains/mcpservers/resources.js";
 import { registerMcpServerTools } from "./domains/mcpservers/tools.js";
+import {
+  loadCaptureContextFromEnv,
+  type CaptureContext,
+} from "./domains/memory/context.js";
+import { registerMemoryTools } from "./domains/memory/tools.js";
 import { registerSearchTools } from "./domains/search/tools.js";
 import { registerSkillResources } from "./domains/skills/resources.js";
 import { registerSkillTools } from "./domains/skills/tools.js";
@@ -107,6 +112,29 @@ export function createConversationServer(target: BackendTarget): McpServer {
   return server;
 }
 
+/**
+ * Build a memory-only MCP server: remember with the agent-facing argument
+ * surface, and nothing else (DD-005 D1 — the channels-roster pattern).
+ * This is the roster the runner-synthesized memory attachment connects
+ * to; the structural guarantee mirrors the channels roster's. Served on
+ * the /memory HTTP route and as the stdio roster when
+ * STIGMER_MCP_ROSTER=memory.
+ *
+ * `startupContext` is the stdio-shape capture context, read from the
+ * runner-set STIGMER_MEMORY_* environment at construction (the startup
+ * API key pattern). Over HTTP each request's provenance headers
+ * supersede it, so the http factory's env read is a harmless no-op.
+ */
+export function createMemoryServer(
+  target: BackendTarget,
+  startupContext: CaptureContext = loadCaptureContextFromEnv(),
+): McpServer {
+  const server = new McpServer({ name: "mcp-server-stigmer-memory", version: SERVER_VERSION });
+  const tools = registerMemoryTools(server, target, startupContext);
+  log.info("tools registered (memory roster)", { count: tools.length, tools });
+  return server;
+}
+
 /**
  * Wire up every domain's tools. Each domain returns the names it registered so
  * the startup log's count and roster cannot drift from what is actually wired,
@@ -193,10 +221,14 @@ export const CHANNELS_ROUTE = "/channels";
 /** HTTP route serving the conversation-only roster (channel-conversations A14). */
 export const CONVERSATION_ROUTE = "/conversation";
 
+/** HTTP route serving the memory-only roster (memory capture, DD-005 D1). */
+export const MEMORY_ROUTE = "/memory";
+
 /**
  * The standard HTTP route dispatch: the full roster on {@link FULL_ROUTE},
  * the channels-only roster on {@link CHANNELS_ROUTE}, the
- * conversation-only roster on {@link CONVERSATION_ROUTE} — and NOTHING
+ * conversation-only roster on {@link CONVERSATION_ROUTE}, the
+ * memory-only roster on {@link MEMORY_ROUTE} — and NOTHING
  * anywhere else.
  *
  * The closed route table is load-bearing, not tidiness. This dispatch
@@ -214,6 +246,7 @@ export function routedServerFactory(target: BackendTarget): RouteServerFactory {
     if (path === FULL_ROUTE) return createServer(target);
     if (path === CHANNELS_ROUTE) return createChannelsServer(target);
     if (path === CONVERSATION_ROUTE) return createConversationServer(target);
+    if (path === MEMORY_ROUTE) return createMemoryServer(target);
     return undefined;
   };
 }
@@ -425,12 +458,13 @@ async function routeRequest(
 }
 
 /**
- * The stdio server for the configured roster: the channels-only roster
- * when STIGMER_MCP_ROSTER names it (what the OSS runner-synthesized
- * attachment spawns), the full roster otherwise.
+ * The stdio server for the configured roster: the channels-only or
+ * memory-only roster when STIGMER_MCP_ROSTER names one (what the OSS
+ * runner-synthesized attachments spawn), the full roster otherwise.
  */
 export function stdioServer(target: BackendTarget, cfg: Config): McpServer {
   if (cfg.roster === "channels") return createChannelsServer(target);
+  if (cfg.roster === "memory") return createMemoryServer(target);
   return createServer(target);
 }