@minns/openclaw-minns 0.2.0

package/README.md

@@ -0,0 +1,109 @@
+# @minns/openclaw-minns
+
+MCP stdio server that connects [OpenClaw](https://github.com/anthropics/openclaw) to [Minns EventGraphDB](https://github.com/minns/minns-sdk) for persistent agent memory, strategy recall, and claim search.
+
+## Install
+
+```bash
+npm i @minns/openclaw-minns
+```
+
+Or clone and build locally:
+
+```bash
+cd openclaw-minns
+npm install
+npm run build
+```
+
+## Configure OpenClaw
+
+Add the MCP server entry to your OpenClaw config (typically `~/.config/openclaw/config.json` or the `mcpServers` section of your project settings):
+
+```json
+{
+  "mcpServers": {
+    "minns": {
+      "command": "openclaw-minns-mcp",
+      "env": {
+        "MINNS_BASE_URL": "http://127.0.0.1:3000",
+        "MINNS_DEBUG": "false"
+      }
+    }
+  }
+}
+```
+
+If your EventGraphDB instance requires authentication:
+
+```json
+{
+  "mcpServers": {
+    "minns": {
+      "command": "openclaw-minns-mcp",
+      "env": {
+        "MINNS_BASE_URL": "https://your-server.example.com",
+        "MINNS_API_KEY": "your-secret-key",
+        "MINNS_DEBUG": "false"
+      }
+    }
+  }
+}
+```
+
+## Environment variables
+
+| Variable         | Default                   | Description                                    |
+| ---------------- | ------------------------- | ---------------------------------------------- |
+| `MINNS_BASE_URL` | `http://127.0.0.1:3000`  | EventGraphDB HTTP endpoint                     |
+| `MINNS_API_KEY`  | *(none)*                  | Optional Bearer token for authenticated access |
+| `MINNS_DEBUG`    | `false`                   | Set to `true` for verbose stderr logging       |
+
+## Available tools
+
+| Tool                           | Description                                          |
+| ------------------------------ | ---------------------------------------------------- |
+| `memory.search`                | Semantic search over memories                        |
+| `memory.capture`               | Store a new memory (context event with embeddings)   |
+| `memory.memories`              | List agent memories by strength                      |
+| `memory.strategies`            | List agent strategies by quality                     |
+| `strategy.similar`             | Find strategies matching a signature                 |
+| `strategy.suggest_next_action` | Get next-action suggestions for a context            |
+| `claims.search`                | Search extracted claims semantically                 |
+| `stats.get`                    | System-wide EventGraphDB statistics                  |
+| `health.check`                 | Verify EventGraphDB is reachable                     |
+
+## Test locally
+
+Start EventGraphDB, then run the binary directly. It speaks JSON-RPC 2.0 over stdio:
+
+```bash
+# Start the MCP server
+MINNS_BASE_URL=http://127.0.0.1:3000 npx openclaw-minns-mcp
+```
+
+In another terminal, pipe a JSON-RPC request to test:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx openclaw-minns-mcp
+```
+
+To call a tool:
+
+```bash
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"health.check","arguments":{}}}' | npx openclaw-minns-mcp
+```
+
+Memory search example:
+
+```bash
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"memory.search","arguments":{"query":"user preferences","limit":5}}}' | npx openclaw-minns-mcp
+```
+
+## Fallback skill
+
+If your agent runtime does not support MCP natively, copy `skills/minns-memory/SKILL.md` into your agent's skill/policy directory. It instructs the agent to call `memory.search` before answering and `memory.capture` after answering, with safety rules to avoid storing secrets.
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+export interface MinnsConfig {
+    baseUrl: string;
+    debug: boolean;
+    apiKey?: string;
+}
+export declare function loadConfig(): MinnsConfig;
+export declare function buildClient(cfg: MinnsConfig): import("minns-sdk").EventGraphDBClient;

package/dist/config.js

@@ -0,0 +1,22 @@
+import { createClient } from "minns-sdk";
+export function loadConfig() {
+    return {
+        baseUrl: process.env.MINNS_BASE_URL ?? "http://127.0.0.1:3000",
+        debug: process.env.MINNS_DEBUG === "true",
+        apiKey: process.env.MINNS_API_KEY || undefined,
+    };
+}
+export function buildClient(cfg) {
+    const opts = {
+        baseUrl: cfg.baseUrl,
+        debug: cfg.debug,
+    };
+    if (cfg.apiKey) {
+        opts.headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${cfg.apiKey}`,
+        };
+    }
+    return createClient(opts);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAiC,MAAM,WAAW,CAAC;AAQxE,MAAM,UAAU,UAAU;IACxB,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,uBAAuB;QAC9D,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,KAAK,MAAM;QACzC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,SAAS;KAC/C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAgB;IAC1C,MAAM,IAAI,GAA6B;QACrC,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,KAAK,EAAE,GAAG,CAAC,KAAK;KACjB,CAAC;IAEF,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QACf,IAAI,CAAC,OAAO,GAAG;YACb,cAAc,EAAE,kBAAkB;YAClC,aAAa,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE;SACtC,CAAC;IACJ,CAAC;IAED,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC"}

package/dist/mcp.d.ts

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

package/dist/mcp.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { ZodError } from "zod";
+import { loadConfig, buildClient } from "./config.js";
+import { TOOL_DEFS, dispatch } from "./tools.js";
+const cfg = loadConfig();
+const client = buildClient(cfg);
+const server = new Server({ name: "openclaw-minns", version: "0.1.0" }, { capabilities: { tools: {} } });
+// ---- tools/list -----------------------------------------------------------
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOL_DEFS.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+    })),
+}));
+// ---- tools/call -----------------------------------------------------------
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        const result = await dispatch(client, name, args ?? {});
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        if (err instanceof ZodError) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "validation_error",
+                            issues: err.issues.map((i) => ({
+                                path: i.path.join("."),
+                                message: i.message,
+                            })),
+                        }),
+                    },
+                ],
+            };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: message }),
+                },
+            ],
+        };
+    }
+});
+// ---- start ----------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    if (cfg.debug) {
+        process.stderr.write(`[openclaw-minns] MCP server running -- base=${cfg.baseUrl}\n`);
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`[openclaw-minns] Fatal: ${err}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -0,0 +1,196 @@
+import { z } from "zod";
+import type { EventGraphDBClient } from "minns-sdk";
+import { IntentSpecRegistry, type IntentSpec } from "minns-sdk";
+declare const registry: IntentSpecRegistry;
+declare const DEFAULT_MEMORY_SPEC: IntentSpec;
+export declare const MemorySearchSchema: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    min_similarity: z.ZodOptional<z.ZodNumber>;
+    agent_id: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    session_id: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    limit: number;
+    min_similarity?: number | undefined;
+    agent_id?: string | number | undefined;
+    session_id?: string | number | undefined;
+}, {
+    query: string;
+    limit?: number | undefined;
+    min_similarity?: number | undefined;
+    agent_id?: string | number | undefined;
+    session_id?: string | number | undefined;
+}>;
+export declare const MemoryCaptureSchema: z.ZodObject<{
+    agent_type: z.ZodString;
+    agent_id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+    session_id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+    text: z.ZodString;
+    context_type: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    user_id: z.ZodOptional<z.ZodString>;
+    goals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        priority: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>]>>>;
+        progress: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        text: string;
+        priority: 1 | 5 | 2 | 3 | 4;
+        progress: number;
+    }, {
+        text: string;
+        priority?: 1 | 5 | 2 | 3 | 4 | undefined;
+        progress?: number | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    context_type: string;
+    agent_id: string | number;
+    session_id: string | number;
+    agent_type: string;
+    user_id?: string | undefined;
+    goals?: {
+        text: string;
+        priority: 1 | 5 | 2 | 3 | 4;
+        progress: number;
+    }[] | undefined;
+}, {
+    text: string;
+    agent_id: string | number;
+    session_id: string | number;
+    agent_type: string;
+    context_type?: string | undefined;
+    user_id?: string | undefined;
+    goals?: {
+        text: string;
+        priority?: 1 | 5 | 2 | 3 | 4 | undefined;
+        progress?: number | undefined;
+    }[] | undefined;
+}>;
+export declare const MemoryMemoriesSchema: z.ZodObject<{
+    agent_id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    agent_id: string | number;
+}, {
+    agent_id: string | number;
+    limit?: number | undefined;
+}>;
+export declare const MemoryStrategiesSchema: z.ZodObject<{
+    agent_id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    agent_id: string | number;
+}, {
+    agent_id: string | number;
+    limit?: number | undefined;
+}>;
+export declare const StrategySimilarSchema: z.ZodObject<{
+    agent_id: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    goal_ids: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodNumber, z.ZodString]>, "many">>;
+    tool_names: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    result_types: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    context_hash: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    min_score: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    agent_id?: string | number | undefined;
+    goal_ids?: (string | number)[] | undefined;
+    tool_names?: string[] | undefined;
+    result_types?: string[] | undefined;
+    context_hash?: string | number | undefined;
+    min_score?: number | undefined;
+}, {
+    limit?: number | undefined;
+    agent_id?: string | number | undefined;
+    goal_ids?: (string | number)[] | undefined;
+    tool_names?: string[] | undefined;
+    result_types?: string[] | undefined;
+    context_hash?: string | number | undefined;
+    min_score?: number | undefined;
+}>;
+export declare const StrategySuggestSchema: z.ZodObject<{
+    context_hash: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+    last_action_node: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    context_hash: string | number;
+    last_action_node?: number | undefined;
+}, {
+    context_hash: string | number;
+    limit?: number | undefined;
+    last_action_node?: number | undefined;
+}>;
+export declare const ClaimsSearchSchema: z.ZodObject<{
+    query_text: z.ZodString;
+    top_k: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    min_similarity: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query_text: string;
+    top_k: number;
+    min_similarity?: number | undefined;
+}, {
+    query_text: string;
+    min_similarity?: number | undefined;
+    top_k?: number | undefined;
+}>;
+export declare const StatsGetSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const HealthCheckSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const IntentInstructionSchema: z.ZodObject<{
+    agent_type: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    goals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        description?: string | undefined;
+    }, {
+        description?: string | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    agent_type: string;
+    goals?: {
+        description?: string | undefined;
+    }[] | undefined;
+}, {
+    agent_type?: string | undefined;
+    goals?: {
+        description?: string | undefined;
+    }[] | undefined;
+}>;
+export declare const IntentParseSchema: z.ZodObject<{
+    model_text: z.ZodString;
+    user_message: z.ZodString;
+    agent_type: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    goals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        description?: string | undefined;
+    }, {
+        description?: string | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    agent_type: string;
+    model_text: string;
+    user_message: string;
+    goals?: {
+        description?: string | undefined;
+    }[] | undefined;
+}, {
+    model_text: string;
+    user_message: string;
+    agent_type?: string | undefined;
+    goals?: {
+        description?: string | undefined;
+    }[] | undefined;
+}>;
+export interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export declare const TOOL_DEFS: ToolDef[];
+export declare function dispatch(client: EventGraphDBClient, toolName: string, rawArgs: unknown): Promise<unknown>;
+export { registry, DEFAULT_MEMORY_SPEC };

package/dist/tools.js

@@ -0,0 +1,318 @@
+import { z } from "zod";
+import { IntentSpecRegistry, buildSidecarInstruction, extractIntentAndResponse, } from "minns-sdk";
+// ---------------------------------------------------------------------------
+// Shared intent registry -- agents register specs, MCP resolves them
+// ---------------------------------------------------------------------------
+const registry = new IntentSpecRegistry();
+const DEFAULT_MEMORY_SPEC = {
+    domain: "memory",
+    fallback_intent: "query",
+    intents: [
+        { name: "recall", slots: { query: { freeText: true } } },
+        {
+            name: "capture",
+            slots: {
+                text: { freeText: true },
+                context_type: { optional: true, enum: ["preference", "fact", "decision", "constraint", "general"] },
+            },
+        },
+        { name: "query", slots: { query: { freeText: true } } },
+    ],
+    extensions: {
+        allow_claims_hint: true,
+        allowed_claim_types: ["preference", "fact", "decision", "constraint"],
+        max_claims_hint: 5,
+    },
+    enableSemantic: (intent) => intent.intent === "capture" ||
+        (intent.claims_hint !== undefined && intent.claims_hint.length > 0),
+};
+registry.registerAgentFallback("memory", DEFAULT_MEMORY_SPEC);
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+const IdField = z.union([z.number(), z.string()]);
+export const MemorySearchSchema = z.object({
+    query: z.string().min(1, "query is required"),
+    limit: z.number().int().positive().optional().default(10),
+    min_similarity: z.number().min(0).max(1).optional(),
+    agent_id: IdField.optional(),
+    session_id: IdField.optional(),
+});
+export const MemoryCaptureSchema = z.object({
+    agent_type: z.string().min(1, "agent_type is required"),
+    agent_id: IdField,
+    session_id: IdField,
+    text: z.string().min(1, "text is required"),
+    context_type: z.string().optional().default("general"),
+    user_id: z.string().optional(),
+    goals: z.array(z.object({
+        text: z.string(),
+        priority: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4), z.literal(5)]).optional().default(3),
+        progress: z.number().min(0).max(1).optional().default(0),
+    })).optional(),
+});
+export const MemoryMemoriesSchema = z.object({
+    agent_id: IdField,
+    limit: z.number().int().positive().optional().default(10),
+});
+export const MemoryStrategiesSchema = z.object({
+    agent_id: IdField,
+    limit: z.number().int().positive().optional().default(10),
+});
+export const StrategySimilarSchema = z.object({
+    agent_id: IdField.optional(),
+    goal_ids: z.array(IdField).optional(),
+    tool_names: z.array(z.string()).optional(),
+    result_types: z.array(z.string()).optional(),
+    context_hash: IdField.optional(),
+    min_score: z.number().min(0).max(1).optional(),
+    limit: z.number().int().positive().optional().default(10),
+});
+export const StrategySuggestSchema = z.object({
+    context_hash: IdField,
+    last_action_node: z.number().int().optional(),
+    limit: z.number().int().positive().optional().default(5),
+});
+export const ClaimsSearchSchema = z.object({
+    query_text: z.string().min(1, "query_text is required"),
+    top_k: z.number().int().positive().optional().default(5),
+    min_similarity: z.number().min(0).max(1).optional(),
+});
+export const StatsGetSchema = z.object({});
+export const HealthCheckSchema = z.object({});
+export const IntentInstructionSchema = z.object({
+    agent_type: z.string().optional().default("memory"),
+    goals: z.array(z.object({ description: z.string().optional() })).optional(),
+});
+export const IntentParseSchema = z.object({
+    model_text: z.string().min(1, "model_text is required"),
+    user_message: z.string().min(1, "user_message is required"),
+    agent_type: z.string().optional().default("memory"),
+    goals: z.array(z.object({ description: z.string().optional() })).optional(),
+});
+function zodToJsonSchema(schema) {
+    const shape = schema.shape;
+    const properties = {};
+    const required = [];
+    for (const [key, value] of Object.entries(shape)) {
+        const field = value;
+        properties[key] = zodFieldToJson(field);
+        if (!field.isOptional()) {
+            required.push(key);
+        }
+    }
+    return {
+        type: "object",
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+    };
+}
+function zodFieldToJson(field) {
+    if (field instanceof z.ZodOptional) {
+        return zodFieldToJson(field._def.innerType);
+    }
+    if (field instanceof z.ZodDefault) {
+        const inner = zodFieldToJson(field._def.innerType);
+        return { ...inner, default: field._def.defaultValue() };
+    }
+    if (field instanceof z.ZodString) {
+        return { type: "string" };
+    }
+    if (field instanceof z.ZodNumber) {
+        return { type: "number" };
+    }
+    if (field instanceof z.ZodLiteral) {
+        return { const: field._def.value };
+    }
+    if (field instanceof z.ZodUnion) {
+        return { oneOf: field._def.options.map((o) => zodFieldToJson(o)) };
+    }
+    if (field instanceof z.ZodArray) {
+        return { type: "array", items: zodFieldToJson(field._def.type) };
+    }
+    if (field instanceof z.ZodObject) {
+        return zodToJsonSchema(field);
+    }
+    return {};
+}
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+export const TOOL_DEFS = [
+    {
+        name: "memory.search",
+        description: "Search memories by semantic similarity to a query string. Returns the most relevant memories.",
+        inputSchema: zodToJsonSchema(MemorySearchSchema),
+    },
+    {
+        name: "memory.capture",
+        description: "Capture a new memory via the fluent event builder. Sends a Context event with semantic indexing enabled. Optionally attach goals.",
+        inputSchema: zodToJsonSchema(MemoryCaptureSchema),
+    },
+    {
+        name: "memory.memories",
+        description: "List memories for a specific agent, sorted by strength.",
+        inputSchema: zodToJsonSchema(MemoryMemoriesSchema),
+    },
+    {
+        name: "memory.strategies",
+        description: "List strategies learned by a specific agent, sorted by quality score.",
+        inputSchema: zodToJsonSchema(MemoryStrategiesSchema),
+    },
+    {
+        name: "strategy.similar",
+        description: "Find strategies similar to a given signature (goals, tools, results, context).",
+        inputSchema: zodToJsonSchema(StrategySimilarSchema),
+    },
+    {
+        name: "strategy.suggest_next_action",
+        description: "Get action suggestions for a context hash based on learned strategies.",
+        inputSchema: zodToJsonSchema(StrategySuggestSchema),
+    },
+    {
+        name: "claims.search",
+        description: "Search claims extracted from events via semantic similarity.",
+        inputSchema: zodToJsonSchema(ClaimsSearchSchema),
+    },
+    {
+        name: "stats.get",
+        description: "Get system-wide statistics about EventGraphDB.",
+        inputSchema: zodToJsonSchema(StatsGetSchema),
+    },
+    {
+        name: "health.check",
+        description: "Health check -- verify that EventGraphDB is running.",
+        inputSchema: zodToJsonSchema(HealthCheckSchema),
+    },
+    {
+        name: "intent.instruction",
+        description: "Get the sidecar instruction prompt for a given agent type. Inject this into your system prompt so the LLM outputs structured intent JSON alongside its response.",
+        inputSchema: zodToJsonSchema(IntentInstructionSchema),
+    },
+    {
+        name: "intent.parse",
+        description: "Parse raw LLM output into a structured intent + assistant response using the sidecar extractor. Returns the parsed intent (with slots, goal_updates, claims_hint) and the clean assistant text.",
+        inputSchema: zodToJsonSchema(IntentParseSchema),
+    },
+];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolveSpec(agentType, goals) {
+    return registry.resolve(agentType, goals) ?? DEFAULT_MEMORY_SPEC;
+}
+// ---------------------------------------------------------------------------
+// Tool dispatch
+// ---------------------------------------------------------------------------
+export async function dispatch(client, toolName, rawArgs) {
+    switch (toolName) {
+        // ---- Memory tools ---------------------------------------------------
+        case "memory.search": {
+            const args = MemorySearchSchema.parse(rawArgs);
+            // Use the fluent builder to construct a minimal search context,
+            // then extract the built EventContext for the query API.
+            const builder = client
+                .event("memory", {
+                agentId: args.agent_id ?? 0,
+                sessionId: args.session_id ?? 0,
+            })
+                .context(args.query, "search")
+                .state({ query: args.query });
+            const searchContext = builder.build().context;
+            return client.getContextMemories(searchContext, {
+                limit: args.limit,
+                min_similarity: args.min_similarity,
+                agent_id: args.agent_id,
+                session_id: args.session_id,
+            });
+        }
+        case "memory.capture": {
+            const args = MemoryCaptureSchema.parse(rawArgs);
+            const builder = client
+                .event(args.agent_type, {
+                agentId: args.agent_id,
+                sessionId: args.session_id,
+                enableSemantic: true,
+            })
+                .context(args.text, args.context_type);
+            if (args.user_id) {
+                builder.state({ user_id: args.user_id });
+            }
+            if (args.goals) {
+                for (const g of args.goals) {
+                    builder.goal(g.text, g.priority, g.progress);
+                }
+            }
+            return builder.send();
+        }
+        case "memory.memories": {
+            const args = MemoryMemoriesSchema.parse(rawArgs);
+            return client.getAgentMemories(args.agent_id, args.limit);
+        }
+        case "memory.strategies": {
+            const args = MemoryStrategiesSchema.parse(rawArgs);
+            return client.getAgentStrategies(args.agent_id, args.limit);
+        }
+        // ---- Strategy tools -------------------------------------------------
+        case "strategy.similar": {
+            const args = StrategySimilarSchema.parse(rawArgs);
+            return client.getSimilarStrategies({
+                agent_id: args.agent_id,
+                goal_ids: args.goal_ids,
+                tool_names: args.tool_names,
+                result_types: args.result_types,
+                context_hash: args.context_hash,
+                min_score: args.min_score,
+                limit: args.limit,
+            });
+        }
+        case "strategy.suggest_next_action": {
+            const args = StrategySuggestSchema.parse(rawArgs);
+            return client.getActionSuggestions(args.context_hash, args.last_action_node, args.limit);
+        }
+        // ---- Claims ---------------------------------------------------------
+        case "claims.search": {
+            const args = ClaimsSearchSchema.parse(rawArgs);
+            return client.searchClaims({
+                query_text: args.query_text,
+                top_k: args.top_k,
+                min_similarity: args.min_similarity,
+            });
+        }
+        // ---- System ---------------------------------------------------------
+        case "stats.get": {
+            StatsGetSchema.parse(rawArgs);
+            return client.getStats();
+        }
+        case "health.check": {
+            HealthCheckSchema.parse(rawArgs);
+            return client.healthCheck();
+        }
+        // ---- Intent sidecar tools -------------------------------------------
+        case "intent.instruction": {
+            const args = IntentInstructionSchema.parse(rawArgs);
+            const spec = resolveSpec(args.agent_type, args.goals);
+            return {
+                instruction: buildSidecarInstruction(spec),
+                domain: spec.domain,
+                intents: spec.intents.map((i) => i.name),
+            };
+        }
+        case "intent.parse": {
+            const args = IntentParseSchema.parse(rawArgs);
+            const spec = resolveSpec(args.agent_type, args.goals);
+            const { intent, assistantResponse } = extractIntentAndResponse(args.model_text, args.user_message, spec);
+            return {
+                intent,
+                assistant_response: assistantResponse,
+            };
+        }
+        default:
+            throw new Error(`Unknown tool: ${toolName}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Public: allow external code to register custom intent specs
+// ---------------------------------------------------------------------------
+export { registry, DEFAULT_MEMORY_SPEC };
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@minns/openclaw-minns",
+  "version": "0.2.0",
+  "description": "MCP stdio server integrating Minns EventGraphDB into OpenClaw",
+  "type": "module",
+  "main": "./dist/mcp.js",
+  "types": "./dist/mcp.d.ts",
+  "bin": {
+    "openclaw-minns-mcp": "./dist/mcp.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "minns-sdk": "^0.4.2",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/skills/minns-memory/SKILL.md

@@ -0,0 +1,37 @@
+# Minns Memory Skill
+
+Fallback policy skill for agents that do not yet have native MCP tool support.
+When active, the agent should follow these rules automatically.
+
+## Before answering
+
+1. Call `memory.search` with a short query derived from the user's message.
+2. If relevant memories are returned, incorporate them into your response.
+3. If no memories match, proceed without referencing memory.
+
+## After answering
+
+1. Decide whether the interaction produced a **durable fact or preference** worth keeping.
+   - Examples: user timezone, preferred language, project conventions, confirmed decisions.
+2. If yes, call `memory.capture` with a concise summary of the fact.
+3. If the interaction was ephemeral (greetings, small talk, transient debug output), do **not** capture it.
+
+## Safety rules
+
+- **Never** store secrets, passwords, API keys, tokens, or credentials.
+- **Never** store personally identifiable information (PII) unless the user explicitly asks you to remember it.
+- Only store facts that are likely to remain true across sessions.
+- Prefer short, precise text over long paragraphs when capturing memories.
+
+## Tool reference
+
+| Tool                         | When to use                                      |
+| ---------------------------- | ------------------------------------------------ |
+| `memory.search`              | Before answering -- recall relevant context       |
+| `memory.capture`             | After answering -- persist durable facts          |
+| `memory.memories`            | When the user asks "what do you know about me?"   |
+| `memory.strategies`          | When reviewing learned strategies for an agent    |
+| `strategy.similar`           | When looking for reusable approaches              |
+| `strategy.suggest_next_action` | When deciding what to do next in a workflow     |
+| `claims.search`              | When verifying factual claims from past events    |
+| `health.check`               | When diagnosing connectivity to EventGraphDB      |