@synth-coder/memhub 0.1.4 → 0.1.6

package/README.md

@@ -72,7 +72,7 @@ Example MCP client config:
       "command": "npx",
       "args": ["-y", "@synth-coder/memhub"],
       "env": {
-        "MEMHUB_STORAGE_PATH": "/absolute/path/to/memories",
+        "MEMHUB_STORAGE_PATH": "/absolute/path/to/.memhub",
         "MEMHUB_LOG_LEVEL": "info"
       }
     }
@@ -97,7 +97,7 @@ Example MCP client config:
 
 ## Environment Variables
 
-- `MEMHUB_STORAGE_PATH` (default: `./memories`)
+- `MEMHUB_STORAGE_PATH` (default: `~/.memhub`)
 - `MEMHUB_LOG_LEVEL` (default: `info`, options: `debug|info|warn|error`)
 
 ---

package/README.zh-CN.md

@@ -97,7 +97,7 @@ npx -y @synth-coder/memhub
 
 ## 环境变量
 
-- `MEMHUB_STORAGE_PATH`：记忆存储目录（默认：`./memories`）
+- `MEMHUB_STORAGE_PATH`：记忆存储目录（默认：`~/.memhub`）
 - `MEMHUB_LOG_LEVEL`：日志级别（默认：`info`，可选：`debug|info|warn|error`）
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synth-coder/memhub",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "A Git-friendly memory hub using Markdown-based storage with YAML Front Matter",
   "type": "module",
   "main": "dist/src/index.js",

package/src/contracts/mcp.ts

@@ -52,14 +52,14 @@ export const TOOL_DEFINITIONS: readonly Tool[] = [
   {
     name: 'memory_load',
     description:
-      'STM first step. Call at the first turn after receiving user prompt to load short-term memory context for this session/task.',
+      'MANDATORY STM step #1 (stability-first). Call memory_load as the FIRST tool call after each new user prompt, before analysis or planning. Goal: recover short-term memory for the current task so the next 1-3 turns stay coherent and do not repeat user input. Prefer { sessionId, scope:"stm", limit:20 }; add { date } for date-scoped tasks and { query } for keyword-driven tasks. If unavailable, continue the task and still provide a final answer.',
     inputSchema: {
       type: 'object',
       properties: {
         id: { type: 'string', description: 'Optional memory id for direct fetch' },
         sessionId: {
           type: 'string',
-          description: 'Optional session UUID to load current CLI/task context',
+          description: 'Recommended. Stable session UUID for this task/thread. Reuse same value across memory_load/memory_update.',
         },
         date: { type: 'string', description: 'Optional date filter (YYYY-MM-DD)' },
         query: { type: 'string', description: 'Optional text query for relevant context' },
@@ -69,7 +69,7 @@ export const TOOL_DEFINITIONS: readonly Tool[] = [
         scope: {
           type: 'string',
           enum: ['stm', 'all'],
-          description: 'stm for short-term context window; all for broader retrieval',
+          description: 'Use "stm" by default for current-task context expected to be reused in ~3 turns. Use "all" only when broad historical recall is required.',
         },
       },
       additionalProperties: false,
@@ -78,22 +78,23 @@ export const TOOL_DEFINITIONS: readonly Tool[] = [
   {
     name: 'memory_update',
     description:
-      'STM write-back step. Call at the final turn to append/upsert new decisions, preferences, task-state changes, and key outputs.',
+      'MANDATORY STM step #2 (closed loop). Call memory_update as the FINAL tool call before your final user answer. Write only high-value short-term updates likely reused in the next 1-3 turns: decisions made, preference/constraint changes, task state transitions, and reusable conclusions. Keep content concise, factual, and task-bound. Never store secrets or credentials. If unavailable, still return the final user answer.',
     inputSchema: {
       type: 'object',
       properties: {
         id: { type: 'string', description: 'Optional id. Present = update existing record' },
-        sessionId: { type: 'string', description: 'Session UUID. Auto-created if omitted' },
-        mode: { type: 'string', enum: ['append', 'upsert'], description: 'Default append' },
+        sessionId: { type: 'string', description: 'Recommended. Same session UUID used in memory_load. Auto-created if omitted.' },
+        mode: { type: 'string', enum: ['append', 'upsert'], description: 'append = add new STM item (default). upsert = update existing item, usually with id.' },
         entryType: {
           type: 'string',
           enum: ['decision', 'preference', 'knowledge', 'todo', 'state_change'],
+          description: 'Use the most specific type to improve next-turn retrieval quality: decision/preference/knowledge/todo/state_change.',
         },
         title: { type: 'string', description: 'Optional title' },
-        content: { type: 'string', description: 'Required memory body' },
+        content: { type: 'string', description: 'Required. Concise reusable summary (for next ~3 turns), not full transcript.' },
         tags: { type: 'array', items: { type: 'string' } },
         category: { type: 'string' },
-        importance: { type: 'number' },
+        importance: { type: 'number', description: 'Optional priority score (1-5). Use higher values for likely near-term reuse.' },
       },
       required: ['content'],
       additionalProperties: false,

package/src/server/mcp-server.ts

@@ -7,6 +7,7 @@
 import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { homedir } from 'os';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import {
@@ -37,7 +38,8 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as Packag
  * Create McpServer instance using SDK
  */
 export function createMcpServer(): Server {
-  const storagePath = process.env.MEMHUB_STORAGE_PATH || './memories';
+  const defaultStoragePath = join(homedir(), '.memhub');
+  const storagePath = process.env.MEMHUB_STORAGE_PATH || defaultStoragePath;
   const memoryService = new MemoryService({ storagePath });
 
   // Create server using SDK