@kalera/munin-runtime 1.2.9 → 1.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,4 @@
1
1
 
2
- > @kalera/munin-runtime@1.2.9 build /home/runner/work/munin-for-agents/munin-for-agents/packages/runtime
2
+ > @kalera/munin-runtime@1.4.1 build /home/runner/work/munin-for-agents/munin-for-agents/packages/runtime
3
3
  > tsc -p tsconfig.json
4
4
 
package/dist/index.d.ts CHANGED
@@ -10,6 +10,11 @@ export interface CliEnv {
10
10
  backoffMs: number;
11
11
  }
12
12
  export declare function parseCliArgs(argv: string[], usage: string): ParsedCliArgs;
13
+ /**
14
+ * Resolve MUNIN_API_KEY — reads from process.env first, then walks up from CWD
15
+ * for .env.local / .env files. This mirrors the MUNIN_PROJECT resolution pattern.
16
+ */
17
+ export declare function resolveApiKey(): string | undefined;
13
18
  export declare function loadCliEnv(): CliEnv;
14
19
  /**
15
20
  * Resolve MUNIN_PROJECT from multiple sources, in priority order:
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import fs from "node:fs";
2
- import path from "node:path";
1
+ import * as fs from "fs";
2
+ import * as path from "path";
3
3
  const REDACT_KEYS = ["apiKey", "authorization", "token", "secret", "password"];
4
4
  export function parseCliArgs(argv, usage) {
5
5
  const [action, payloadRaw] = argv;
@@ -19,10 +19,27 @@ export function parseCliArgs(argv, usage) {
19
19
  throw new Error("Payload must be valid JSON");
20
20
  }
21
21
  }
22
+ /**
23
+ * Resolve MUNIN_API_KEY — reads from process.env first, then walks up from CWD
24
+ * for .env.local / .env files. This mirrors the MUNIN_PROJECT resolution pattern.
25
+ */
26
+ export function resolveApiKey() {
27
+ if (process.env.MUNIN_API_KEY) {
28
+ return process.env.MUNIN_API_KEY;
29
+ }
30
+ // Walk upward from CWD — find .env.local first, then .env
31
+ const fromLocal = resolveEnvFileUpward(".env.local", "MUNIN_API_KEY");
32
+ if (fromLocal)
33
+ return fromLocal;
34
+ const fromEnv = resolveEnvFileUpward(".env", "MUNIN_API_KEY");
35
+ if (fromEnv)
36
+ return fromEnv;
37
+ return undefined;
38
+ }
22
39
  export function loadCliEnv() {
23
40
  return {
24
41
  baseUrl: process.env.MUNIN_BASE_URL || "https://munin.kalera.dev",
25
- apiKey: process.env.MUNIN_API_KEY,
42
+ apiKey: resolveApiKey(),
26
43
  timeoutMs: safeParseInt(process.env.MUNIN_TIMEOUT_MS, 15_000),
27
44
  retries: safeParseInt(process.env.MUNIN_RETRIES, 3),
28
45
  backoffMs: safeParseInt(process.env.MUNIN_BACKOFF_MS, 300),
@@ -36,10 +53,11 @@ function safeParseInt(envVal, defaultVal) {
36
53
  }
37
54
  /**
38
55
  * Walk up the directory tree from `startDir` (default CWD) toward root,
39
- * searching each ancestor for `filename`. Returns the value of the first match.
40
- * Stops at filesystem root or when a `.git` dir is found (project boundary).
56
+ * searching each ancestor for a .env file containing `key=`. Returns the value
57
+ * of the first match. Stops at filesystem root or when a `.git` dir is found
58
+ * (project boundary).
41
59
  */
42
- function resolveEnvFileUpward(filename, startDir) {
60
+ function resolveEnvFileUpward(filename, key, startDir) {
43
61
  let current = startDir ?? process.cwd();
44
62
  let last = "";
45
63
  while (current !== last) {
@@ -48,11 +66,12 @@ function resolveEnvFileUpward(filename, startDir) {
48
66
  try {
49
67
  if (fs.existsSync(filePath)) {
50
68
  const content = fs.readFileSync(filePath, "utf8");
69
+ const prefix = `${key}=`;
51
70
  for (const line of content.split("\n")) {
52
71
  const trimmed = line.trim();
53
- if (!trimmed.startsWith("MUNIN_PROJECT="))
72
+ if (!trimmed.startsWith(prefix))
54
73
  continue;
55
- return trimmed.slice("MUNIN_PROJECT=".length).trim();
74
+ return trimmed.slice(prefix.length).trim();
56
75
  }
57
76
  }
58
77
  }
@@ -80,11 +99,11 @@ export function resolveProjectId() {
80
99
  return process.env.MUNIN_PROJECT;
81
100
  }
82
101
  // 2. Walk upward from CWD — find .env.local in any ancestor dir
83
- const fromLocal = resolveEnvFileUpward(".env.local");
102
+ const fromLocal = resolveEnvFileUpward(".env.local", "MUNIN_PROJECT");
84
103
  if (fromLocal)
85
104
  return fromLocal;
86
105
  // 3. Walk upward from CWD — find .env in any ancestor dir
87
- const fromEnv = resolveEnvFileUpward(".env");
106
+ const fromEnv = resolveEnvFileUpward(".env", "MUNIN_PROJECT");
88
107
  if (fromEnv)
89
108
  return fromEnv;
90
109
  return undefined;
@@ -5,7 +5,7 @@ import { MuninClient } from "@kalera/munin-sdk";
5
5
  import { loadCliEnv, resolveProjectId, resolveEncryptionKey, safeError } from "./index.js";
6
6
  export function createMcpServerInstance(env, opts) {
7
7
  if (!env.apiKey && !opts?.allowMissingApiKey) {
8
- throw new Error("MUNIN_API_KEY is required. Set it in your environment or .env file.");
8
+ throw new Error("MUNIN_API_KEY is required. Set it in your environment, or in a .env.local / .env file in your project directory (walked up automatically).");
9
9
  }
10
10
  const client = new MuninClient({
11
11
  baseUrl: env.baseUrl,
@@ -14,7 +14,7 @@ export function createMcpServerInstance(env, opts) {
14
14
  });
15
15
  const server = new Server({
16
16
  name: "munin-mcp-server",
17
- version: "1.2.9",
17
+ version: "1.4.1",
18
18
  }, {
19
19
  capabilities: {
20
20
  tools: {},
@@ -25,21 +25,51 @@ export function createMcpServerInstance(env, opts) {
25
25
  tools: [
26
26
  {
27
27
  name: "munin_store_memory",
28
- description: "Store or update a memory in Munin Context Core. It will automatically use the active project from environment if projectId is omitted. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
28
+ description: "Store or update one or more memories in Munin Context Core. Auto-uses active project if projectId omitted. BATCH MODE: pass `memories: [...]` (up to 50 items per call) to save many memories in a single call — drastically reduces API quota usage at session end / /compact. When `memories` is provided, single-memory params (key/content/...) are ignored. TIPS for better recall later: (1) Set `validFrom`/`validTo` for time-bound facts so search auto-filters stale memories; (2) Pin durable identity facts via `isPinned: true`. IMPORTANT: Call as MCP tool, not shell command.",
29
29
  inputSchema: {
30
30
  type: "object",
31
31
  properties: {
32
32
  projectId: { type: "string", description: "Optional. Only use if cross-saving to a different Context Core ID." },
33
- key: { type: "string", description: "Unique identifier for this memory" },
34
- content: { type: "string", description: "The content to remember" },
33
+ key: { type: "string", description: "Unique identifier for this memory (single-memory mode)" },
34
+ content: { type: "string", description: "The content to remember (single-memory mode)" },
35
35
  title: { type: "string", description: "Optional title" },
36
36
  tags: {
37
37
  type: "array",
38
38
  items: { type: "string" },
39
39
  description: "List of tags, e.g. ['planning', 'frontend']"
40
+ },
41
+ validFrom: {
42
+ type: "string",
43
+ description: "Optional ISO-8601 date — memory is hidden from search before this date. Use for facts that take effect later (e.g., new policy). Omit for always-valid memories."
44
+ },
45
+ validTo: {
46
+ type: "string",
47
+ description: "Optional ISO-8601 date — memory expires from search after this date. Use for time-bound facts (deadlines, sprint goals, expiring promotions). Omit for never-expiring."
48
+ },
49
+ isPinned: {
50
+ type: "boolean",
51
+ description: "Mark as pinned to boost in search ranking. Reserve for high-importance identity/anchor facts (project name, user role, key constraints)."
52
+ },
53
+ memories: {
54
+ type: "array",
55
+ description: "OPTIONAL. For batch storing up to 50 memories in one call (saves API quota at /compact / session end). Each item has same shape as single-memory params (key, content, tags, title, validFrom, validTo, isPinned). When provided, single-memory params (key/content/...) are ignored. Returns per-item success/error in `data.results`.",
56
+ maxItems: 50,
57
+ items: {
58
+ type: "object",
59
+ properties: {
60
+ key: { type: "string" },
61
+ content: { type: "string" },
62
+ title: { type: "string" },
63
+ tags: { type: "array", items: { type: "string" } },
64
+ validFrom: { type: "string" },
65
+ validTo: { type: "string" },
66
+ isPinned: { type: "boolean" }
67
+ },
68
+ required: ["key", "content"]
69
+ }
40
70
  }
41
71
  },
42
- required: ["key", "content"],
72
+ required: [],
43
73
  },
44
74
  },
45
75
  {
@@ -56,13 +86,22 @@ export function createMcpServerInstance(env, opts) {
56
86
  },
57
87
  {
58
88
  name: "munin_search_memories",
59
- description: "Search for memories using semantic search or keywords. Returns formatted, token-efficient GraphRAG context. Supports pagination with topK/offset and optional total count. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
89
+ description: "Hybrid 6-signal search (keyword + semantic + named-entity + quoted-phrase + recency + pinned). QUERY TIPS to lift recall: (1) Wrap exact strings in double quotes — e.g., `\"Project Munin v1.3\"` — to trigger quoted-phrase boost (+0.25); (2) Include capitalized names (people, products, places) for name-entity boost (+0.15); (3) Use `filters.since`/`before` for temporal scoping (relative strings supported: 'yesterday', 'last week', '7 days ago'). Returns token-efficient GraphRAG context with mermaid graph. IMPORTANT: Call as MCP tool.",
60
90
  inputSchema: {
61
91
  type: "object",
62
92
  properties: {
63
93
  projectId: { type: "string", description: "Optional. The Munin Context Core ID." },
64
- query: { type: "string", description: "Search query" },
65
- tags: { type: "array", items: { type: "string" } },
94
+ query: { type: "string", description: "Search query. Tip: wrap exact phrases in quotes for boost; capitalize entity names." },
95
+ tags: { type: "array", items: { type: "string" }, description: "Filter results to memories containing these tags" },
96
+ tagMode: { type: "string", enum: ["or", "and"], description: "Tag combination: 'or' (any match) or 'and' (all match). Default: 'or'." },
97
+ filters: {
98
+ type: "object",
99
+ description: "Temporal filter on memory createdAt. Supports ISO-8601 dates AND relative strings: 'yesterday', 'last week', 'last month', 'last year', '7 days ago', '3 weeks ago', etc.",
100
+ properties: {
101
+ since: { type: "string", description: "Memories created on/after this date (e.g., 'last week', '2026-04-01')" },
102
+ before: { type: "string", description: "Memories created on/before this date" }
103
+ }
104
+ },
66
105
  topK: { type: "number", description: "Max results to return (default: 10, max: 50)" },
67
106
  offset: { type: "number", description: "Pagination offset for fetching more results (default: 0)" },
68
107
  includeTotal: { type: "boolean", description: "If true, includes total count in response (default: false)" },
@@ -97,7 +136,7 @@ export function createMcpServerInstance(env, opts) {
97
136
  },
98
137
  {
99
138
  name: "munin_share_memory",
100
- description: "Share one or more memories to other projects owned by the same user. The target project must share the same Hash Key to read encrypted content. Requires Pro or Elite tier. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
139
+ description: "Share one or more memories to other projects owned by the same user. The target project must share the same Hash Key to read encrypted content. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
101
140
  inputSchema: {
102
141
  type: "object",
103
142
  properties: {
@@ -127,6 +166,82 @@ export function createMcpServerInstance(env, opts) {
127
166
  required: [],
128
167
  },
129
168
  },
169
+ {
170
+ name: "munin_versions",
171
+ description: "List all versions of a memory (version history). Use this to review past changes before rolling back. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
172
+ inputSchema: {
173
+ type: "object",
174
+ properties: {
175
+ projectId: { type: "string", description: "Optional. Defaults to active project." },
176
+ key: { type: "string", description: "Memory key (provide this OR id, not both)" },
177
+ id: { type: "string", description: "Memory ID (provide this OR key, not both)" },
178
+ },
179
+ oneOf: [
180
+ { required: ["key"] },
181
+ { required: ["id"] },
182
+ ],
183
+ },
184
+ },
185
+ {
186
+ name: "munin_rollback",
187
+ description: "Rollback a memory to a previous version. Run munin_versions first to find the version number. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
188
+ inputSchema: {
189
+ type: "object",
190
+ properties: {
191
+ projectId: { type: "string", description: "Optional. Defaults to active project." },
192
+ key: { type: "string", description: "Memory key (provide this OR id, not both)" },
193
+ id: { type: "string", description: "Memory ID (provide this OR key, not both)" },
194
+ version: { type: "number", description: "The version number to rollback to (required)" },
195
+ },
196
+ required: ["version"],
197
+ oneOf: [
198
+ { required: ["key"] },
199
+ { required: ["id"] },
200
+ ],
201
+ },
202
+ },
203
+ {
204
+ name: "munin_diff_memory",
205
+ description: "Compare two specific versions of the same memory. Returns a diff showing what changed between v1 and v2. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
206
+ inputSchema: {
207
+ type: "object",
208
+ properties: {
209
+ projectId: { type: "string", description: "Optional. Defaults to active project." },
210
+ key: { type: "string", description: "Memory key" },
211
+ v1: { type: "number", description: "First version number" },
212
+ v2: { type: "number", description: "Second version number" },
213
+ },
214
+ required: ["key", "v1", "v2"],
215
+ },
216
+ },
217
+ {
218
+ name: "munin_delete_memory",
219
+ description: "Permanently delete a memory by key or id from the current Munin Context Core. This action is destructive and cannot be undone — the memory and all its version history are removed. Use with caution. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
220
+ inputSchema: {
221
+ type: "object",
222
+ properties: {
223
+ projectId: { type: "string", description: "Optional. Defaults to active project." },
224
+ key: { type: "string", description: "Memory key (provide this OR id, not both)" },
225
+ id: { type: "string", description: "Memory ID (provide this OR key, not both)" }
226
+ },
227
+ oneOf: [
228
+ { required: ["key"] },
229
+ { required: ["id"] }
230
+ ]
231
+ }
232
+ },
233
+ {
234
+ name: "munin_acknowledge_setup",
235
+ description: "Acknowledge that you have read the latest Munin setup guide. Call this AFTER reading the setup guide URL provided in any ERR_STALE_PROTOCOL response. Subsequent write actions (store, share) will then proceed without setup-version errors. Pass the version exactly as shown in the remediation hint.",
236
+ inputSchema: {
237
+ type: "object",
238
+ properties: {
239
+ projectId: { type: "string", description: "Optional. Defaults to active project." },
240
+ version: { type: "string", description: "Setup version in ISO date format (YYYY-MM-DD), exactly as shown in the ERR_STALE_PROTOCOL remediation hint." }
241
+ },
242
+ required: ["version"]
243
+ }
244
+ },
130
245
  ],
131
246
  };
132
247
  });
@@ -163,6 +278,9 @@ export function createMcpServerInstance(env, opts) {
163
278
  case "munin_share_memory":
164
279
  result = await client.invoke(projectId, "share", enrichedPayload);
165
280
  break;
281
+ case "munin_diff_memory":
282
+ result = await client.invoke(projectId, "diff", enrichedPayload);
283
+ break;
166
284
  case "munin_get_project_info": {
167
285
  const caps = await client.capabilities();
168
286
  result = {
@@ -172,6 +290,30 @@ export function createMcpServerInstance(env, opts) {
172
290
  };
173
291
  break;
174
292
  }
293
+ case "munin_versions":
294
+ if (!args.key && !args.id) {
295
+ throw new Error("munin_versions requires either 'key' or 'id' to identify the target memory.");
296
+ }
297
+ result = await client.invoke(projectId, "versions", { key: args.key, id: args.id });
298
+ break;
299
+ case "munin_rollback":
300
+ if (!args.key && !args.id) {
301
+ throw new Error("munin_rollback requires either 'key' or 'id' to identify the target memory.");
302
+ }
303
+ if (typeof args.version !== "number") {
304
+ throw new Error("munin_rollback requires a numeric 'version' to roll back to.");
305
+ }
306
+ result = await client.invoke(projectId, "rollback", { key: args.key, id: args.id, version: args.version });
307
+ break;
308
+ case "munin_delete_memory":
309
+ if (!args.key && !args.id) {
310
+ throw new Error("munin_delete_memory requires either 'key' or 'id' to identify the target memory.");
311
+ }
312
+ result = await client.invoke(projectId, "delete", { key: args.key, id: args.id });
313
+ break;
314
+ case "munin_acknowledge_setup":
315
+ result = await client.invoke(projectId, "acknowledge_setup", { version: args.version });
316
+ break;
175
317
  default:
176
318
  throw new Error(`Unknown tool: ${request.params.name}`);
177
319
  }
package/package.json CHANGED
@@ -1,6 +1,5 @@
1
1
  {
2
2
  "name": "@kalera/munin-runtime",
3
- "version": "1.2.9",
4
3
  "type": "module",
5
4
  "main": "dist/index.js",
6
5
  "types": "dist/index.d.ts",
@@ -8,12 +7,14 @@
8
7
  ".": "./dist/index.js"
9
8
  },
10
9
  "devDependencies": {
10
+ "@types/node": "^24.3.0",
11
11
  "typescript": "^5.9.2"
12
12
  },
13
13
  "dependencies": {
14
14
  "@modelcontextprotocol/sdk": "^1.27.1",
15
- "@kalera/munin-sdk": "1.2.9"
15
+ "@kalera/munin-sdk": "1.4.1"
16
16
  },
17
+ "version": "1.4.1",
17
18
  "scripts": {
18
19
  "build": "tsc -p tsconfig.json",
19
20
  "lint": "tsc -p tsconfig.json --noEmit",
package/src/index.ts CHANGED
@@ -1,5 +1,5 @@
1
- import fs from "node:fs";
2
- import path from "node:path";
1
+ import * as fs from "fs";
2
+ import * as path from "path";
3
3
 
4
4
  export interface ParsedCliArgs {
5
5
  action: string;
@@ -36,10 +36,26 @@ export function parseCliArgs(argv: string[], usage: string): ParsedCliArgs {
36
36
  }
37
37
  }
38
38
 
39
+ /**
40
+ * Resolve MUNIN_API_KEY — reads from process.env first, then walks up from CWD
41
+ * for .env.local / .env files. This mirrors the MUNIN_PROJECT resolution pattern.
42
+ */
43
+ export function resolveApiKey(): string | undefined {
44
+ if (process.env.MUNIN_API_KEY) {
45
+ return process.env.MUNIN_API_KEY;
46
+ }
47
+ // Walk upward from CWD — find .env.local first, then .env
48
+ const fromLocal = resolveEnvFileUpward(".env.local", "MUNIN_API_KEY");
49
+ if (fromLocal) return fromLocal;
50
+ const fromEnv = resolveEnvFileUpward(".env", "MUNIN_API_KEY");
51
+ if (fromEnv) return fromEnv;
52
+ return undefined;
53
+ }
54
+
39
55
  export function loadCliEnv(): CliEnv {
40
56
  return {
41
57
  baseUrl: process.env.MUNIN_BASE_URL || "https://munin.kalera.dev",
42
- apiKey: process.env.MUNIN_API_KEY,
58
+ apiKey: resolveApiKey(),
43
59
  timeoutMs: safeParseInt(process.env.MUNIN_TIMEOUT_MS, 15_000),
44
60
  retries: safeParseInt(process.env.MUNIN_RETRIES, 3),
45
61
  backoffMs: safeParseInt(process.env.MUNIN_BACKOFF_MS, 300),
@@ -54,10 +70,15 @@ function safeParseInt(envVal: string | undefined, defaultVal: number): number {
54
70
 
55
71
  /**
56
72
  * Walk up the directory tree from `startDir` (default CWD) toward root,
57
- * searching each ancestor for `filename`. Returns the value of the first match.
58
- * Stops at filesystem root or when a `.git` dir is found (project boundary).
73
+ * searching each ancestor for a .env file containing `key=`. Returns the value
74
+ * of the first match. Stops at filesystem root or when a `.git` dir is found
75
+ * (project boundary).
59
76
  */
60
- function resolveEnvFileUpward(filename: string, startDir?: string): string | undefined {
77
+ function resolveEnvFileUpward(
78
+ filename: string,
79
+ key: string,
80
+ startDir?: string,
81
+ ): string | undefined {
61
82
  let current = startDir ?? process.cwd();
62
83
  let last = "";
63
84
 
@@ -67,10 +88,11 @@ function resolveEnvFileUpward(filename: string, startDir?: string): string | und
67
88
  try {
68
89
  if (fs.existsSync(filePath)) {
69
90
  const content = fs.readFileSync(filePath, "utf8");
91
+ const prefix = `${key}=`;
70
92
  for (const line of content.split("\n")) {
71
93
  const trimmed = line.trim();
72
- if (!trimmed.startsWith("MUNIN_PROJECT=")) continue;
73
- return trimmed.slice("MUNIN_PROJECT=".length).trim();
94
+ if (!trimmed.startsWith(prefix)) continue;
95
+ return trimmed.slice(prefix.length).trim();
74
96
  }
75
97
  }
76
98
  } catch (error) {
@@ -100,11 +122,11 @@ export function resolveProjectId(): string | undefined {
100
122
  }
101
123
 
102
124
  // 2. Walk upward from CWD — find .env.local in any ancestor dir
103
- const fromLocal = resolveEnvFileUpward(".env.local");
125
+ const fromLocal = resolveEnvFileUpward(".env.local", "MUNIN_PROJECT");
104
126
  if (fromLocal) return fromLocal;
105
127
 
106
128
  // 3. Walk upward from CWD — find .env in any ancestor dir
107
- const fromEnv = resolveEnvFileUpward(".env");
129
+ const fromEnv = resolveEnvFileUpward(".env", "MUNIN_PROJECT");
108
130
  if (fromEnv) return fromEnv;
109
131
 
110
132
  return undefined;
package/src/mcp-server.ts CHANGED
@@ -13,7 +13,7 @@ export function createMcpServerInstance(
13
13
  ) {
14
14
  if (!env.apiKey && !opts?.allowMissingApiKey) {
15
15
  throw new Error(
16
- "MUNIN_API_KEY is required. Set it in your environment or .env file.",
16
+ "MUNIN_API_KEY is required. Set it in your environment, or in a .env.local / .env file in your project directory (walked up automatically).",
17
17
  );
18
18
  }
19
19
 
@@ -26,7 +26,7 @@ export function createMcpServerInstance(
26
26
  const server = new Server(
27
27
  {
28
28
  name: "munin-mcp-server",
29
- version: "1.2.9",
29
+ version: "1.4.1",
30
30
  },
31
31
  {
32
32
  capabilities: {
@@ -40,21 +40,51 @@ export function createMcpServerInstance(
40
40
  tools: [
41
41
  {
42
42
  name: "munin_store_memory",
43
- description: "Store or update a memory in Munin Context Core. It will automatically use the active project from environment if projectId is omitted. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
43
+ description: "Store or update one or more memories in Munin Context Core. Auto-uses active project if projectId omitted. BATCH MODE: pass `memories: [...]` (up to 50 items per call) to save many memories in a single call — drastically reduces API quota usage at session end / /compact. When `memories` is provided, single-memory params (key/content/...) are ignored. TIPS for better recall later: (1) Set `validFrom`/`validTo` for time-bound facts so search auto-filters stale memories; (2) Pin durable identity facts via `isPinned: true`. IMPORTANT: Call as MCP tool, not shell command.",
44
44
  inputSchema: {
45
45
  type: "object",
46
46
  properties: {
47
47
  projectId: { type: "string", description: "Optional. Only use if cross-saving to a different Context Core ID." },
48
- key: { type: "string", description: "Unique identifier for this memory" },
49
- content: { type: "string", description: "The content to remember" },
48
+ key: { type: "string", description: "Unique identifier for this memory (single-memory mode)" },
49
+ content: { type: "string", description: "The content to remember (single-memory mode)" },
50
50
  title: { type: "string", description: "Optional title" },
51
- tags: {
52
- type: "array",
53
- items: { type: "string" },
51
+ tags: {
52
+ type: "array",
53
+ items: { type: "string" },
54
54
  description: "List of tags, e.g. ['planning', 'frontend']"
55
+ },
56
+ validFrom: {
57
+ type: "string",
58
+ description: "Optional ISO-8601 date — memory is hidden from search before this date. Use for facts that take effect later (e.g., new policy). Omit for always-valid memories."
59
+ },
60
+ validTo: {
61
+ type: "string",
62
+ description: "Optional ISO-8601 date — memory expires from search after this date. Use for time-bound facts (deadlines, sprint goals, expiring promotions). Omit for never-expiring."
63
+ },
64
+ isPinned: {
65
+ type: "boolean",
66
+ description: "Mark as pinned to boost in search ranking. Reserve for high-importance identity/anchor facts (project name, user role, key constraints)."
67
+ },
68
+ memories: {
69
+ type: "array",
70
+ description: "OPTIONAL. For batch storing up to 50 memories in one call (saves API quota at /compact / session end). Each item has same shape as single-memory params (key, content, tags, title, validFrom, validTo, isPinned). When provided, single-memory params (key/content/...) are ignored. Returns per-item success/error in `data.results`.",
71
+ maxItems: 50,
72
+ items: {
73
+ type: "object",
74
+ properties: {
75
+ key: { type: "string" },
76
+ content: { type: "string" },
77
+ title: { type: "string" },
78
+ tags: { type: "array", items: { type: "string" } },
79
+ validFrom: { type: "string" },
80
+ validTo: { type: "string" },
81
+ isPinned: { type: "boolean" }
82
+ },
83
+ required: ["key", "content"]
84
+ }
55
85
  }
56
86
  },
57
- required: ["key", "content"],
87
+ required: [],
58
88
  },
59
89
  },
60
90
  {
@@ -71,13 +101,22 @@ export function createMcpServerInstance(
71
101
  },
72
102
  {
73
103
  name: "munin_search_memories",
74
- description: "Search for memories using semantic search or keywords. Returns formatted, token-efficient GraphRAG context. Supports pagination with topK/offset and optional total count. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
104
+ description: "Hybrid 6-signal search (keyword + semantic + named-entity + quoted-phrase + recency + pinned). QUERY TIPS to lift recall: (1) Wrap exact strings in double quotes — e.g., `\"Project Munin v1.3\"` — to trigger quoted-phrase boost (+0.25); (2) Include capitalized names (people, products, places) for name-entity boost (+0.15); (3) Use `filters.since`/`before` for temporal scoping (relative strings supported: 'yesterday', 'last week', '7 days ago'). Returns token-efficient GraphRAG context with mermaid graph. IMPORTANT: Call as MCP tool.",
75
105
  inputSchema: {
76
106
  type: "object",
77
107
  properties: {
78
108
  projectId: { type: "string", description: "Optional. The Munin Context Core ID." },
79
- query: { type: "string", description: "Search query" },
80
- tags: { type: "array", items: { type: "string" } },
109
+ query: { type: "string", description: "Search query. Tip: wrap exact phrases in quotes for boost; capitalize entity names." },
110
+ tags: { type: "array", items: { type: "string" }, description: "Filter results to memories containing these tags" },
111
+ tagMode: { type: "string", enum: ["or", "and"], description: "Tag combination: 'or' (any match) or 'and' (all match). Default: 'or'." },
112
+ filters: {
113
+ type: "object",
114
+ description: "Temporal filter on memory createdAt. Supports ISO-8601 dates AND relative strings: 'yesterday', 'last week', 'last month', 'last year', '7 days ago', '3 weeks ago', etc.",
115
+ properties: {
116
+ since: { type: "string", description: "Memories created on/after this date (e.g., 'last week', '2026-04-01')" },
117
+ before: { type: "string", description: "Memories created on/before this date" }
118
+ }
119
+ },
81
120
  topK: { type: "number", description: "Max results to return (default: 10, max: 50)" },
82
121
  offset: { type: "number", description: "Pagination offset for fetching more results (default: 0)" },
83
122
  includeTotal: { type: "boolean", description: "If true, includes total count in response (default: false)" },
@@ -112,7 +151,7 @@ export function createMcpServerInstance(
112
151
  },
113
152
  {
114
153
  name: "munin_share_memory",
115
- description: "Share one or more memories to other projects owned by the same user. The target project must share the same Hash Key to read encrypted content. Requires Pro or Elite tier. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
154
+ description: "Share one or more memories to other projects owned by the same user. The target project must share the same Hash Key to read encrypted content. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
116
155
  inputSchema: {
117
156
  type: "object",
118
157
  properties: {
@@ -142,6 +181,82 @@ export function createMcpServerInstance(
142
181
  required: [],
143
182
  },
144
183
  },
184
+ {
185
+ name: "munin_versions",
186
+ description: "List all versions of a memory (version history). Use this to review past changes before rolling back. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
187
+ inputSchema: {
188
+ type: "object",
189
+ properties: {
190
+ projectId: { type: "string", description: "Optional. Defaults to active project." },
191
+ key: { type: "string", description: "Memory key (provide this OR id, not both)" },
192
+ id: { type: "string", description: "Memory ID (provide this OR key, not both)" },
193
+ },
194
+ oneOf: [
195
+ { required: ["key"] },
196
+ { required: ["id"] },
197
+ ],
198
+ },
199
+ },
200
+ {
201
+ name: "munin_rollback",
202
+ description: "Rollback a memory to a previous version. Run munin_versions first to find the version number. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
203
+ inputSchema: {
204
+ type: "object",
205
+ properties: {
206
+ projectId: { type: "string", description: "Optional. Defaults to active project." },
207
+ key: { type: "string", description: "Memory key (provide this OR id, not both)" },
208
+ id: { type: "string", description: "Memory ID (provide this OR key, not both)" },
209
+ version: { type: "number", description: "The version number to rollback to (required)" },
210
+ },
211
+ required: ["version"],
212
+ oneOf: [
213
+ { required: ["key"] },
214
+ { required: ["id"] },
215
+ ],
216
+ },
217
+ },
218
+ {
219
+ name: "munin_diff_memory",
220
+ description: "Compare two specific versions of the same memory. Returns a diff showing what changed between v1 and v2. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
221
+ inputSchema: {
222
+ type: "object",
223
+ properties: {
224
+ projectId: { type: "string", description: "Optional. Defaults to active project." },
225
+ key: { type: "string", description: "Memory key" },
226
+ v1: { type: "number", description: "First version number" },
227
+ v2: { type: "number", description: "Second version number" },
228
+ },
229
+ required: ["key", "v1", "v2"],
230
+ },
231
+ },
232
+ {
233
+ name: "munin_delete_memory",
234
+ description: "Permanently delete a memory by key or id from the current Munin Context Core. This action is destructive and cannot be undone — the memory and all its version history are removed. Use with caution. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
235
+ inputSchema: {
236
+ type: "object",
237
+ properties: {
238
+ projectId: { type: "string", description: "Optional. Defaults to active project." },
239
+ key: { type: "string", description: "Memory key (provide this OR id, not both)" },
240
+ id: { type: "string", description: "Memory ID (provide this OR key, not both)" }
241
+ },
242
+ oneOf: [
243
+ { required: ["key"] },
244
+ { required: ["id"] }
245
+ ]
246
+ }
247
+ },
248
+ {
249
+ name: "munin_acknowledge_setup",
250
+ description: "Acknowledge that you have read the latest Munin setup guide. Call this AFTER reading the setup guide URL provided in any ERR_STALE_PROTOCOL response. Subsequent write actions (store, share) will then proceed without setup-version errors. Pass the version exactly as shown in the remediation hint.",
251
+ inputSchema: {
252
+ type: "object",
253
+ properties: {
254
+ projectId: { type: "string", description: "Optional. Defaults to active project." },
255
+ version: { type: "string", description: "Setup version in ISO date format (YYYY-MM-DD), exactly as shown in the ERR_STALE_PROTOCOL remediation hint." }
256
+ },
257
+ required: ["version"]
258
+ }
259
+ },
145
260
  ],
146
261
  };
147
262
  });
@@ -186,6 +301,9 @@ export function createMcpServerInstance(
186
301
  case "munin_share_memory":
187
302
  result = await client.invoke(projectId, "share", enrichedPayload);
188
303
  break;
304
+ case "munin_diff_memory":
305
+ result = await client.invoke(projectId, "diff", enrichedPayload);
306
+ break;
189
307
  case "munin_get_project_info": {
190
308
  const caps = await client.capabilities();
191
309
  result = {
@@ -195,6 +313,30 @@ export function createMcpServerInstance(
195
313
  };
196
314
  break;
197
315
  }
316
+ case "munin_versions":
317
+ if (!args.key && !args.id) {
318
+ throw new Error("munin_versions requires either 'key' or 'id' to identify the target memory.");
319
+ }
320
+ result = await client.invoke(projectId, "versions", { key: args.key, id: args.id });
321
+ break;
322
+ case "munin_rollback":
323
+ if (!args.key && !args.id) {
324
+ throw new Error("munin_rollback requires either 'key' or 'id' to identify the target memory.");
325
+ }
326
+ if (typeof args.version !== "number") {
327
+ throw new Error("munin_rollback requires a numeric 'version' to roll back to.");
328
+ }
329
+ result = await client.invoke(projectId, "rollback", { key: args.key, id: args.id, version: args.version });
330
+ break;
331
+ case "munin_delete_memory":
332
+ if (!args.key && !args.id) {
333
+ throw new Error("munin_delete_memory requires either 'key' or 'id' to identify the target memory.");
334
+ }
335
+ result = await client.invoke(projectId, "delete", { key: args.key, id: args.id });
336
+ break;
337
+ case "munin_acknowledge_setup":
338
+ result = await client.invoke(projectId, "acknowledge_setup", { version: args.version });
339
+ break;
198
340
  default:
199
341
  throw new Error(`Unknown tool: ${request.params.name}`);
200
342
  }