@zythum02/fello-server 0.1.42 → 0.1.46

package/out/scripts/mcp-memo/server.mjs

@@ -3,42 +3,68 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import * as http from "http";
 const memoryEntrySchema = z.object({
-  weight: z.number().int().min(1).max(3).describe("Priority weight: 3=critical, 2=important, 1=general"),
-  text: z.string().max(200).describe("The memory fact, concise and self-contained"),
-  date: z.string().describe("Date when this fact was recorded or last updated (YYYY-MM-DD)"),
-  tags: z.array(z.string()).describe("Category tags: preferences, architecture, commands, corrections, context")
+  weight: z.number().int().min(1).max(3).describe(
+    "Future-work impact: 3=explicit must-follow constraint, 2=stable work-shaping knowledge, 1=background context"
+  ),
+  text: z.string().max(512).describe("The memory fact, concise and self-contained"),
+  date: z.string().describe("Date when this fact was recorded, updated, or last marked as used (YYYY-MM-DD)"),
+  tags: z.array(z.string()).describe("Open-ended semantic keywords used for retrieval; concise and reusable")
 });
 z.object({
   version: z.number().int().describe("Schema version for future migration"),
-  entries: z.array(memoryEntrySchema).describe("Memory entries sorted by weight descending")
+  entries: z.array(memoryEntrySchema).describe("Persistent project memory entries")
 });
+const memoryEntryIdSchema = z.string().length(16).regex(/^[0-9a-f]{16}$/).describe("Read-only ID derived by the backend from the entry text");
+const mutableWeightSchema = z.number().int().min(1).max(3).describe(
+  "New weight. Use 3 only for an explicit durable instruction or prohibition governing how the agent must act."
+);
 const memoGetCurrentRequestSchema = z.object({});
 const memoGetCurrentRespondSchema = z.object({
-  content: z.string().describe("The current memory.json content as a JSON string.")
+  content: z.string().describe("JSON text containing the current entries and their read-only IDs.")
+});
+const memoAddRequestSchema = z.object({
+  text: z.string().min(1).max(512).describe("New immutable memory fact"),
+  weight: mutableWeightSchema,
+  tags: z.array(z.string().min(1)).min(1).max(3).describe("Immutable open-ended semantic keywords derived from the text")
+});
+const memoAddRespondSchema = z.object({
+  ok: z.boolean(),
+  id: memoryEntryIdSchema,
+  error: z.literal("content_exists").optional()
+});
+const memoDeleteRequestSchema = z.object({
+  id: memoryEntryIdSchema
+});
+const memoDeleteRespondSchema = z.object({
+  ok: z.boolean(),
+  id: memoryEntryIdSchema,
+  error: z.literal("entry_not_found").optional()
 });
-const memoSaveRequestSchema = z.object({
-  content: z.string().max(16e3).describe(
-    "The complete memory content as a JSON string. Must conform to the memory file schema: { version, entries: [...] }"
-  )
+const memoSetWeightRequestSchema = z.object({
+  id: memoryEntryIdSchema,
+  weight: mutableWeightSchema
 });
-const memoSaveRespondSchema = z.object({
+const memoSetWeightRespondSchema = z.object({
   ok: z.boolean(),
-  entries: z.number().describe("Number of entries saved.")
+  id: memoryEntryIdSchema,
+  error: z.literal("entry_not_found").optional()
 });
 const memoTouchRequestSchema = z.object({
-  indices: z.array(z.number().int().min(0)).min(1).describe(
-    "Indices of entries in the entries array that were relevant/used. Updates their date to today."
-  )
+  ids: z.array(memoryEntryIdSchema).min(1).describe("IDs of entries represented in the final response; updates their date to today")
 });
 const memoTouchRespondSchema = z.object({
   ok: z.boolean(),
-  touched: z.number().describe("Number of entries touched.")
+  touched: z.number().describe("Number of entries touched")
 });
 function getArg(name) {
   const idx = process.argv.indexOf(`--${name}`);
   return idx !== -1 ? process.argv[idx + 1] : void 0;
 }
+function getErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 const socketPath = getArg("socket-path");
+const writable = process.argv.includes("--writable");
 if (!socketPath) {
   console.error("[mcp-memo] Missing required argument: --socket-path");
   process.exit(1);
@@ -46,12 +72,12 @@ if (!socketPath) {
 const server = new McpServer({
   name: "Memo",
   version: "1.0.0",
-  description: "Provides memo_get_current and memo_save tools for the memory organizer agent."
+  description: writable ? "Provides transactional tools for organizing project memory entries." : "Provides tools to retrieve and mark project memory entries as used."
 });
 server.registerTool(
   "memo_get_current",
   {
-    description: `Read the current project memory file. Call this first to see what's already stored before making changes.`,
+    description: "Read the current project memory entries and their backend-generated, read-only IDs. Call this exactly once before any other memo tool.",
     inputSchema: memoGetCurrentRequestSchema
   },
   async () => {
@@ -61,75 +87,143 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: result.content || "(empty - no memories stored yet)"
+            text: result.content || '{"entries":[]}'
           }
         ]
       };
-    } catch (err) {
-      return {
-        content: [{ type: "text", text: `Error reading memory: ${err.message}` }],
-        isError: true
-      };
-    }
-  }
-);
-server.registerTool(
-  "memo_save",
-  {
-    description: `Save the complete organized memory content as a JSON string. This replaces the entire memory file.
-The JSON must be an object with: { "version": 1, "entries": [...] }
-Each entry has fields: weight (number), text (string), date (string), tags (string[]).
-Entries must be sorted by weight descending. You MUST include all entries you want to keep.`,
-    inputSchema: memoSaveRequestSchema
-  },
-  async (input) => {
-    try {
-      const result = memoSaveRespondSchema.parse(
-        await postToSocket("/memo/save", { content: input.content })
-      );
+    } catch (error) {
       return {
         content: [
-          {
-            type: "text",
-            text: `Memory saved (${result.entries} entries).`
-          }
-        ]
-      };
-    } catch (err) {
-      return {
-        content: [{ type: "text", text: `Error saving memory: ${err.message}` }],
+          { type: "text", text: `Error reading memory: ${getErrorMessage(error)}` }
+        ],
         isError: true
       };
     }
   }
 );
-server.registerTool(
-  "memo_touch",
-  {
-    description: `Mark memory entries as "used" by updating their date to today. Call this after retrieving memories to indicate which entries were relevant to the query. This prevents active entries from being evicted by age-based cleanup.`,
-    inputSchema: memoTouchRequestSchema
-  },
-  async (input) => {
-    try {
-      const result = memoTouchRespondSchema.parse(
-        await postToSocket("/memo/touch", { indices: input.indices })
-      );
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Touched ${result.touched} entries.`
-          }
-        ]
-      };
-    } catch (err) {
-      return {
-        content: [{ type: "text", text: `Error touching entries: ${err.message}` }],
-        isError: true
-      };
+if (writable) {
+  server.registerTool(
+    "memo_add",
+    {
+      description: `Add one new immutable memory entry to the current transaction draft. The backend generates its ID and date.
+Use weight 3 only for an explicit durable instruction or prohibition governing how the agent must act. If the same text already exists, the tool reports content_exists and leaves the draft unchanged.`,
+      inputSchema: memoAddRequestSchema
+    },
+    async (input) => {
+      try {
+        const result = memoAddRespondSchema.parse(await postToSocket("/memo/add", input));
+        return {
+          content: [
+            {
+              type: "text",
+              text: result.ok ? `Added memory entry ${result.id}.` : `Content already exists as memory entry ${result.id}. Decide whether no further action is needed or whether the existing entry must first be deleted and replaced.`
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [
+            { type: "text", text: `Error adding memory: ${getErrorMessage(error)}` }
+          ],
+          isError: true
+        };
+      }
     }
-  }
-);
+  );
+  server.registerTool(
+    "memo_delete",
+    {
+      description: "Delete one entry from the current transaction draft by its read-only ID. Use delete plus add when immutable text or tags must be replaced.",
+      inputSchema: memoDeleteRequestSchema
+    },
+    async (input) => {
+      try {
+        const result = memoDeleteRespondSchema.parse(await postToSocket("/memo/delete", input));
+        return {
+          content: [
+            {
+              type: "text",
+              text: result.ok ? `Deleted memory entry ${result.id}.` : `Memory entry ${result.id} was not found; the draft was unchanged.`
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [
+            { type: "text", text: `Error deleting memory: ${getErrorMessage(error)}` }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.registerTool(
+    "memo_set_weight",
+    {
+      description: `Set one entry's weight in the current transaction draft. This always refreshes its date.
+Use weight 3 only for an explicit durable instruction or prohibition governing how the agent must act; repetition, correction, urgency, or technical necessity alone never justify weight 3.`,
+      inputSchema: memoSetWeightRequestSchema
+    },
+    async (input) => {
+      try {
+        const result = memoSetWeightRespondSchema.parse(
+          await postToSocket("/memo/set-weight", input)
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: result.ok ? `Updated memory entry ${result.id} weight.` : `Memory entry ${result.id} was not found; the draft was unchanged.`
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error setting memory weight: ${getErrorMessage(error)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+} else {
+  server.registerTool(
+    "memo_touch",
+    {
+      description: "Mark only the entries represented in the final retrieval response as used by refreshing their date. Pass their read-only IDs, not array indices.",
+      inputSchema: memoTouchRequestSchema
+    },
+    async (input) => {
+      try {
+        const result = memoTouchRespondSchema.parse(
+          await postToSocket("/memo/touch", { ids: input.ids })
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Touched ${result.touched} entries.`
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error touching entries: ${getErrorMessage(error)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
 function postToSocket(path, body) {
   return new Promise((resolve, reject) => {
     const data = JSON.stringify(body);
@@ -152,15 +246,16 @@ function postToSocket(path, body) {
           if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
             resolve(parsed);
           } else {
-            reject(new Error(parsed.error || `HTTP ${res.statusCode}: ${raw}`));
+            const message = typeof parsed === "object" && parsed && "error" in parsed ? String(parsed.error) : `HTTP ${res.statusCode}: ${raw}`;
+            reject(new Error(message));
           }
         } catch {
           reject(new Error(`Invalid response (${res.statusCode}): ${raw}`));
         }
       });
     });
-    req.on("error", (err) => {
-      reject(new Error(`Socket request failed: ${err.message}`));
+    req.on("error", (error) => {
+      reject(new Error(`Socket request failed: ${error.message}`));
     });
     req.write(data);
     req.end();

package/out/scripts/mcp-memory/server.mjs

@@ -4,19 +4,19 @@ import { z } from "zod";
 import * as fs from "fs";
 import * as http from "http";
 const memoryQueryRequestSchema = z.object({
-  query: z.string().min(1).describe(
-    "What to search for in memory. Describe what you need to recall (e.g. 'tech stack', 'user preferences', 'build commands')."
+  query: z.string().min(1).optional().describe(
+    "Focused topic to retrieve. Required for every specific task, question, recommendation, or domain discussion; never omit it merely to discover whether relevant memories exist. Omit only when a broad project-memory briefing is genuinely needed."
   )
 });
 const memoryQueryRespondSchema = z.object({
-  content: z.string().describe("The memory content (full or filtered).")
+  content: z.string().describe("The generated project briefing or relevant memory details.")
 });
 const memoryStoreRequestSchema = z.object({
   facts: z.array(
     z.object({
-      text: z.string().max(200).describe("The fact to remember, concise and self-contained."),
+      text: z.string().max(512).describe("The fact to remember, concise and self-contained."),
       reason: z.string().max(300).optional().describe(
-        "Why this should be remembered — context that helps determine weight and tags (e.g. 'user explicitly corrected me', 'user emphasized with 一定/never')."
+        "Why this should be remembered — context that helps determine weight and tags (e.g. if the user strongly emphasized it or corrected the agent)."
       )
     })
   ).min(1).max(10).describe(
@@ -24,35 +24,40 @@ const memoryStoreRequestSchema = z.object({
   )
 });
 const memoryStoreRespondSchema = z.object({
-  stored: z.number().describe("Number of facts successfully integrated."),
-  summary: z.string().optional().describe("Brief confirmation of what was stored.")
+  stored: z.number().describe("Number of facts submitted for integration."),
+  message: z.string().optional().describe("Brief confirmation of the memory operation.")
 });
 function getArg(name) {
   const idx = process.argv.indexOf(`--${name}`);
   return idx !== -1 ? process.argv[idx + 1] : void 0;
 }
-const socketPath = getArg("socket-path");
-const projectDir = getArg("project-dir");
-const memorySummaryFile = getArg("memory-summary");
-if (!socketPath) {
-  console.error("[mcp-memory] Missing required argument: --socket-path");
-  process.exit(1);
-}
-if (!projectDir) {
-  console.error("[mcp-memory] Missing required argument: --project-dir");
-  process.exit(1);
+function getErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
 }
-let initialMemorySummary = "";
-if (memorySummaryFile) {
+function loadCriticalMemories(filePath) {
+  if (!filePath) return [];
   try {
-    initialMemorySummary = fs.readFileSync(memorySummaryFile, "utf8").trim();
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    return Array.isArray(parsed) ? parsed.filter((entry) => typeof entry === "string") : [];
+  } catch (error) {
+    console.error(`[mcp-memory] Failed to load critical memories: ${getErrorMessage(error)}`);
+    return [];
   } finally {
-    try {
-      fs.unlinkSync(memorySummaryFile);
-    } catch {
-    }
+    fs.rmSync(filePath, { force: true });
   }
 }
+const socketPath = getArg("socket-path");
+const criticalMemories = loadCriticalMemories(getArg("critical-memory"));
+if (!socketPath) {
+  console.error("[mcp-memory] Missing required argument: --socket-path");
+  process.exit(1);
+}
+const criticalMemoryDescription = criticalMemories.length === 0 ? "" : `
+
+Automatically loaded critical project memories — always follow these:
+${criticalMemories.map((memory) => `- ${memory.replaceAll("\n", "\n  ")}`).join("\n")}
+
+These are only the highest-priority project constraints, not the complete project memory. Do not treat the absence of a detail here as evidence that no relevant memory exists. This list does not replace task-specific retrieval.`;
 const server = new McpServer({
   name: "Memory",
   version: "1.0.0",
@@ -61,16 +66,13 @@ const server = new McpServer({
 server.registerTool(
   "memory_query",
   {
-    description: `Query the project's persistent memory. Performs semantic retrieval to find memories relevant to your question.
+    description: `Query the project's persistent memory.${criticalMemoryDescription}
 
-Use this to recall project conventions, user preferences, past decisions, or corrections.
-Provide a descriptive query about what you need (e.g. "tech stack and build tools", "user's coding style preferences", "things to avoid").` + (() => {
-      if (!initialMemorySummary) return "";
-      return `
+For every specific task, question, recommendation, or domain discussion that may depend on memory, provide a focused query. Include all relevant dimensions in that query, such as applicable conventions, preferences, decisions, corrections, architecture, or commands.
 
-Key memories (high priority — always consider these):
-${initialMemorySummary}`;
-    })(),
+Never omit query merely to discover whether relevant memories exist. Omit it only when a broad project-memory briefing is genuinely needed, such as when the user asks what is remembered.
+
+A focused query returns relevant details. An omitted query generates a current summary from the stored entries. In either mode, memories included in the response are marked as used.`,
     inputSchema: memoryQueryRequestSchema
   },
   async (input) => {
@@ -84,9 +86,11 @@ ${initialMemorySummary}`;
           }
         ]
       };
-    } catch (err) {
+    } catch (error) {
       return {
-        content: [{ type: "text", text: `Error querying memory: ${err.message}` }],
+        content: [
+          { type: "text", text: `Error querying memory: ${getErrorMessage(error)}` }
+        ],
         isError: true
       };
     }
@@ -97,12 +101,21 @@ server.registerTool(
   {
     description: `Store facts into persistent project memory for future sessions.
 
-Use this when:
-- The user states a preference or corrects your behavior
-- You discover a project convention or architectural decision
-- The user explicitly asks you to remember something
+Proactively store facts worth remembering for future sessions. Common triggers:
+- User states a preference, makes a choice, or corrects your behavior (even subtly)
+- You discover a project convention, tech stack detail, or architectural decision
+- User emphasizes something with "always", "never", "remember", "一定", "不要"
+- User explicitly asks you to remember something
+
+Also store when:
+- User explains why they do something a certain way
+- User mentions a tool, framework, or library choice
+- You make a decision during the conversation that affects future work
+- User tells you to skip or avoid something
 
-Each fact should be a concise, self-contained statement. Include a reason when the context helps determine importance (e.g. if the user strongly emphasized something, or corrected you).`,
+When in doubt about whether to store — store it. Forgetting costs more than duplicating.
+
+Each fact should be a concise, self-contained statement. Include a reason when the context helps determine importance (e.g. if the user strongly emphasized it or corrected the agent).`,
     inputSchema: memoryStoreRequestSchema
   },
   async (input) => {
@@ -112,13 +125,15 @@ Each fact should be a concise, self-contained statement. Include a reason when t
         content: [
           {
             type: "text",
-            text: result.summary || `Stored ${result.stored} fact(s) to project memory.`
+            text: result.message || `Stored ${result.stored} fact(s) to project memory.`
           }
         ]
       };
-    } catch (err) {
+    } catch (error) {
       return {
-        content: [{ type: "text", text: `Error storing memory: ${err.message}` }],
+        content: [
+          { type: "text", text: `Error storing memory: ${getErrorMessage(error)}` }
+        ],
         isError: true
       };
     }
@@ -146,15 +161,16 @@ function postToSocket(path, body) {
           if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
             resolve(parsed);
           } else {
-            reject(new Error(parsed.error || `HTTP ${res.statusCode}: ${raw}`));
+            const message = typeof parsed === "object" && parsed && "error" in parsed ? String(parsed.error) : `HTTP ${res.statusCode}: ${raw}`;
+            reject(new Error(message));
           }
         } catch {
           reject(new Error(`Invalid response (${res.statusCode}): ${raw}`));
         }
       });
     });
-    req.on("error", (err) => {
-      reject(new Error(`Socket request failed: ${err.message}`));
+    req.on("error", (error) => {
+      reject(new Error(`Socket request failed: ${error.message}`));
     });
     req.write(data);
     req.end();