@synth-coder/memhub 0.1.5 → 0.2.0
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.
- package/AGENTS.md +1 -0
- package/README.md +2 -2
- package/README.zh-CN.md +1 -1
- package/dist/src/contracts/mcp.d.ts +2 -5
- package/dist/src/contracts/mcp.d.ts.map +1 -1
- package/dist/src/contracts/mcp.js +77 -23
- package/dist/src/contracts/mcp.js.map +1 -1
- package/dist/src/contracts/schemas.d.ts +67 -76
- package/dist/src/contracts/schemas.d.ts.map +1 -1
- package/dist/src/contracts/schemas.js +4 -8
- package/dist/src/contracts/schemas.js.map +1 -1
- package/dist/src/contracts/types.d.ts +1 -4
- package/dist/src/contracts/types.d.ts.map +1 -1
- package/dist/src/contracts/types.js.map +1 -1
- package/dist/src/server/mcp-server.d.ts.map +1 -1
- package/dist/src/server/mcp-server.js +21 -4
- package/dist/src/server/mcp-server.js.map +1 -1
- package/dist/src/services/embedding-service.d.ts +43 -0
- package/dist/src/services/embedding-service.d.ts.map +1 -0
- package/dist/src/services/embedding-service.js +80 -0
- package/dist/src/services/embedding-service.js.map +1 -0
- package/dist/src/services/memory-service.d.ts +30 -44
- package/dist/src/services/memory-service.d.ts.map +1 -1
- package/dist/src/services/memory-service.js +212 -161
- package/dist/src/services/memory-service.js.map +1 -1
- package/dist/src/storage/vector-index.d.ts +62 -0
- package/dist/src/storage/vector-index.d.ts.map +1 -0
- package/dist/src/storage/vector-index.js +123 -0
- package/dist/src/storage/vector-index.js.map +1 -0
- package/package.json +16 -13
- package/src/contracts/mcp.ts +84 -29
- package/src/contracts/schemas.ts +4 -8
- package/src/contracts/types.ts +4 -8
- package/src/server/mcp-server.ts +23 -7
- package/src/services/embedding-service.ts +114 -0
- package/src/services/memory-service.ts +252 -179
- package/src/storage/vector-index.ts +160 -0
- package/test/server/mcp-server.test.ts +11 -9
- package/test/services/memory-service-edge.test.ts +1 -1
- package/test/services/memory-service.test.ts +1 -1
- package/test/storage/vector-index.test.ts +153 -0
- package/vitest.config.ts +3 -1
- /package/docs/{proposal-close-gates.md → proposals/proposal-close-gates.md} +0 -0
package/AGENTS.md
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
你是Alex, “你若盛开,蝴蝶自来”——把自己打磨成一个能创造价值的人。有需要的时候你可以停下来让老曹协助你。
|
package/README.md
CHANGED
|
@@ -72,7 +72,7 @@ Example MCP client config:
|
|
|
72
72
|
"command": "npx",
|
|
73
73
|
"args": ["-y", "@synth-coder/memhub"],
|
|
74
74
|
"env": {
|
|
75
|
-
"MEMHUB_STORAGE_PATH": "/absolute/path/to
|
|
75
|
+
"MEMHUB_STORAGE_PATH": "/absolute/path/to/memories",
|
|
76
76
|
"MEMHUB_LOG_LEVEL": "info"
|
|
77
77
|
}
|
|
78
78
|
}
|
|
@@ -97,7 +97,7 @@ Example MCP client config:
|
|
|
97
97
|
|
|
98
98
|
## Environment Variables
|
|
99
99
|
|
|
100
|
-
- `MEMHUB_STORAGE_PATH` (default:
|
|
100
|
+
- `MEMHUB_STORAGE_PATH` (default: `./memories`)
|
|
101
101
|
- `MEMHUB_LOG_LEVEL` (default: `info`, options: `debug|info|warn|error`)
|
|
102
102
|
|
|
103
103
|
---
|
package/README.zh-CN.md
CHANGED
|
@@ -8,7 +8,7 @@ export declare const MCP_PROTOCOL_VERSION = "2024-11-05";
|
|
|
8
8
|
/** Server information */
|
|
9
9
|
export declare const SERVER_INFO: {
|
|
10
10
|
readonly name: "memhub";
|
|
11
|
-
readonly version: "0.
|
|
11
|
+
readonly version: "0.2.0";
|
|
12
12
|
};
|
|
13
13
|
/** Tool definition for tool/list */
|
|
14
14
|
export interface Tool {
|
|
@@ -63,18 +63,15 @@ export type ToolResult<T extends ToolName> = T extends 'memory_load' ? {
|
|
|
63
63
|
/** Helper type to extract input type from a tool name */
|
|
64
64
|
export type ToolInput<T extends ToolName> = T extends 'memory_load' ? {
|
|
65
65
|
id?: string;
|
|
66
|
-
sessionId?: string;
|
|
67
|
-
date?: string;
|
|
68
66
|
query?: string;
|
|
69
67
|
category?: string;
|
|
70
68
|
tags?: string[];
|
|
71
69
|
limit?: number;
|
|
72
|
-
scope?: 'stm' | 'all';
|
|
73
70
|
} : T extends 'memory_update' ? {
|
|
74
71
|
id?: string;
|
|
75
72
|
sessionId?: string;
|
|
76
73
|
mode?: 'append' | 'upsert';
|
|
77
|
-
entryType?: '
|
|
74
|
+
entryType?: 'preference' | 'decision' | 'context' | 'fact';
|
|
78
75
|
title?: string;
|
|
79
76
|
content: string;
|
|
80
77
|
tags?: string[];
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/contracts/mcp.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAMzC,mCAAmC;AACnC,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD,yBAAyB;AACzB,eAAO,MAAM,WAAW;;;CAGd,CAAC;AAMX,oCAAoC;AACpC,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,eAAe,CAAC;CAC9B;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAMD,+BAA+B;AAC/B,eAAO,MAAM,UAAU,2CAA4C,CAAC;AAEpE,qBAAqB;AACrB,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,sCAAsC;AACtC,eAAO,MAAM,gBAAgB,EAAE,SAAS,IAAI,
|
|
1
|
+
{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/contracts/mcp.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAMzC,mCAAmC;AACnC,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD,yBAAyB;AACzB,eAAO,MAAM,WAAW;;;CAGd,CAAC;AAMX,oCAAoC;AACpC,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,eAAe,CAAC;CAC9B;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAMD,+BAA+B;AAC/B,eAAO,MAAM,UAAU,2CAA4C,CAAC;AAEpE,qBAAqB;AACrB,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,sCAAsC;AACtC,eAAO,MAAM,gBAAgB,EAAE,SAAS,IAAI,EA6GlC,CAAC;AAMX,gCAAgC;AAChC,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AAEX,8DAA8D;AAC9D,eAAO,MAAM,WAAW;;;;;;;;;;CAOd,CAAC;AAMX,0DAA0D;AAC1D,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,QAAQ,IAAI,CAAC,SAAS,aAAa,GAChE;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClC,CAAC,SAAS,eAAe,GACvB;IACE,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,GACD,KAAK,CAAC;AAEZ,yDAAyD;AACzD,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,QAAQ,IAAI,CAAC,SAAS,aAAa,GAC/D;IACE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACD,CAAC,SAAS,eAAe,GACvB;IACE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC3B,SAAS,CAAC,EAAE,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACD,KAAK,CAAC"}
|
|
@@ -10,7 +10,7 @@ export const MCP_PROTOCOL_VERSION = '2024-11-05';
|
|
|
10
10
|
/** Server information */
|
|
11
11
|
export const SERVER_INFO = {
|
|
12
12
|
name: 'memhub',
|
|
13
|
-
version: '0.
|
|
13
|
+
version: '0.2.0',
|
|
14
14
|
};
|
|
15
15
|
// ============================================================================
|
|
16
16
|
// MCP Tool List
|
|
@@ -21,24 +21,45 @@ export const TOOL_NAMES = ['memory_load', 'memory_update'];
|
|
|
21
21
|
export const TOOL_DEFINITIONS = [
|
|
22
22
|
{
|
|
23
23
|
name: 'memory_load',
|
|
24
|
-
description:
|
|
24
|
+
description: `Retrieve stored memories to recall user preferences, past decisions, project context, and learned knowledge.
|
|
25
|
+
|
|
26
|
+
WHEN TO USE (call proactively):
|
|
27
|
+
• Starting a new conversation or task
|
|
28
|
+
• User references past discussions ("remember when...", "as I mentioned before")
|
|
29
|
+
• Need context about user's coding style, preferences, or project decisions
|
|
30
|
+
• Uncertain about user's existing preferences or constraints
|
|
31
|
+
• Before making assumptions about user requirements
|
|
32
|
+
|
|
33
|
+
WHAT IT PROVIDES:
|
|
34
|
+
• User preferences (coding style, frameworks, naming conventions)
|
|
35
|
+
• Past decisions and their rationale
|
|
36
|
+
• Project-specific context and constraints
|
|
37
|
+
• Previously learned knowledge about the user
|
|
38
|
+
|
|
39
|
+
Call this early to provide personalized, context-aware responses.`,
|
|
25
40
|
inputSchema: {
|
|
26
41
|
type: 'object',
|
|
27
42
|
properties: {
|
|
28
|
-
|
|
29
|
-
sessionId: {
|
|
43
|
+
query: {
|
|
30
44
|
type: 'string',
|
|
31
|
-
description: '
|
|
45
|
+
description: 'Search query to find relevant memories. Examples: "react preferences", "error handling approach", "database choice"',
|
|
32
46
|
},
|
|
33
|
-
|
|
34
|
-
query: { type: 'string', description: 'Optional text query for relevant context' },
|
|
35
|
-
category: { type: 'string' },
|
|
36
|
-
tags: { type: 'array', items: { type: 'string' } },
|
|
37
|
-
limit: { type: 'number', description: 'Max results, default 20' },
|
|
38
|
-
scope: {
|
|
47
|
+
id: {
|
|
39
48
|
type: 'string',
|
|
40
|
-
|
|
41
|
-
|
|
49
|
+
description: 'Direct lookup by memory ID (if known)',
|
|
50
|
+
},
|
|
51
|
+
category: {
|
|
52
|
+
type: 'string',
|
|
53
|
+
description: 'Filter by category: "general" (default), "preference", "decision", "knowledge", "project"',
|
|
54
|
+
},
|
|
55
|
+
tags: {
|
|
56
|
+
type: 'array',
|
|
57
|
+
items: { type: 'string' },
|
|
58
|
+
description: 'Filter by tags. Example: ["typescript", "backend"]',
|
|
59
|
+
},
|
|
60
|
+
limit: {
|
|
61
|
+
type: 'number',
|
|
62
|
+
description: 'Max results (default: 20, max: 100)',
|
|
42
63
|
},
|
|
43
64
|
},
|
|
44
65
|
additionalProperties: false,
|
|
@@ -46,22 +67,55 @@ export const TOOL_DEFINITIONS = [
|
|
|
46
67
|
},
|
|
47
68
|
{
|
|
48
69
|
name: 'memory_update',
|
|
49
|
-
description:
|
|
70
|
+
description: `Store important information to remember for future conversations.
|
|
71
|
+
|
|
72
|
+
WHEN TO USE (call when learning something worth remembering):
|
|
73
|
+
• User explicitly states a preference ("I prefer functional components")
|
|
74
|
+
• User makes a decision with rationale ("We'll use PostgreSQL because...")
|
|
75
|
+
• You discover important project context (tech stack, constraints, patterns)
|
|
76
|
+
• User corrects your assumption ("Actually, I don't use Redux")
|
|
77
|
+
• Task state changes that should persist
|
|
78
|
+
|
|
79
|
+
WHAT TO STORE:
|
|
80
|
+
• Preferences: coding style, frameworks, naming conventions
|
|
81
|
+
• Decisions: architecture choices, library selections, with reasoning
|
|
82
|
+
• Knowledge: project-specific patterns, gotchas, conventions
|
|
83
|
+
• Context: team structure, deployment process, testing approach
|
|
84
|
+
|
|
85
|
+
TIPS:
|
|
86
|
+
• content is required and most important
|
|
87
|
+
• title helps with search (auto-generated if omitted)
|
|
88
|
+
• Use entryType to categorize: "preference", "decision", "context", "fact"
|
|
89
|
+
• importance: 1-5 (default: 3), higher = more critical to remember`,
|
|
50
90
|
inputSchema: {
|
|
51
91
|
type: 'object',
|
|
52
92
|
properties: {
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
93
|
+
content: {
|
|
94
|
+
type: 'string',
|
|
95
|
+
description: 'The information to remember. Be specific and include context. Example: "User prefers TypeScript with strict mode. Uses functional React components with hooks. Avoids class components."',
|
|
96
|
+
},
|
|
97
|
+
title: {
|
|
98
|
+
type: 'string',
|
|
99
|
+
description: 'Brief title for the memory (auto-generated from content if omitted). Example: "TypeScript and React preferences"',
|
|
100
|
+
},
|
|
56
101
|
entryType: {
|
|
57
102
|
type: 'string',
|
|
58
|
-
enum: ['
|
|
103
|
+
enum: ['preference', 'decision', 'context', 'fact'],
|
|
104
|
+
description: 'Type of memory. "preference" for user likes/dislikes, "decision" for choices made, "context" for project info, "fact" for learned facts',
|
|
105
|
+
},
|
|
106
|
+
category: {
|
|
107
|
+
type: 'string',
|
|
108
|
+
description: 'Category for grouping. Default: "general". Example: "frontend", "backend", "project-alpha"',
|
|
109
|
+
},
|
|
110
|
+
tags: {
|
|
111
|
+
type: 'array',
|
|
112
|
+
items: { type: 'string' },
|
|
113
|
+
description: 'Tags for filtering. Example: ["typescript", "react", "coding-style"]',
|
|
114
|
+
},
|
|
115
|
+
importance: {
|
|
116
|
+
type: 'number',
|
|
117
|
+
description: 'Importance level 1-5. 5 = critical, always recall. Default: 3',
|
|
59
118
|
},
|
|
60
|
-
title: { type: 'string', description: 'Optional title' },
|
|
61
|
-
content: { type: 'string', description: 'Required memory body' },
|
|
62
|
-
tags: { type: 'array', items: { type: 'string' } },
|
|
63
|
-
category: { type: 'string' },
|
|
64
|
-
importance: { type: 'number' },
|
|
65
119
|
},
|
|
66
120
|
required: ['content'],
|
|
67
121
|
additionalProperties: false,
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../../src/contracts/mcp.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E,mCAAmC;AACnC,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC;AAEjD,yBAAyB;AACzB,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,OAAO;CACR,CAAC;AAqBX,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E,+BAA+B;AAC/B,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,aAAa,EAAE,eAAe,CAAU,CAAC;AAKpE,sCAAsC;AACtC,MAAM,CAAC,MAAM,gBAAgB,GAAoB;IAC/C;QACE,IAAI,EAAE,aAAa;QACnB,WAAW,
|
|
1
|
+
{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../../src/contracts/mcp.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E,mCAAmC;AACnC,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC;AAEjD,yBAAyB;AACzB,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,OAAO;CACR,CAAC;AAqBX,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E,+BAA+B;AAC/B,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,aAAa,EAAE,eAAe,CAAU,CAAC;AAKpE,sCAAsC;AACtC,MAAM,CAAC,MAAM,gBAAgB,GAAoB;IAC/C;QACE,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE;;;;;;;;;;;;;;;kEAeiD;QAC9D,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,qHAAqH;iBACxH;gBACD,EAAE,EAAE;oBACF,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,uCAAuC;iBACrD;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,2FAA2F;iBAC9F;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACzB,WAAW,EAAE,oDAAoD;iBAClE;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,qCAAqC;iBACnD;aACF;YACD,oBAAoB,EAAE,KAAK;SAC5B;KACF;IACD;QACE,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE;;;;;;;;;;;;;;;;;;;mEAmBkD;QAC/D,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,0LAA0L;iBAC7L;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,kHAAkH;iBACrH;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC;oBACnD,WAAW,EACT,yIAAyI;iBAC5I;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,4FAA4F;iBAC/F;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACzB,WAAW,EAAE,sEAAsE;iBACpF;gBACD,UAAU,EAAE;oBACV,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,+DAA+D;iBAC7E;aACF;YACD,QAAQ,EAAE,CAAC,SAAS,CAAC;YACrB,oBAAoB,EAAE,KAAK;SAC5B;KACF;CACO,CAAC;AAEX,+EAA+E;AAC/E,8BAA8B;AAC9B,+EAA+E;AAE/E,gCAAgC;AAChC,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,SAAS,EAAE,CAAC,KAAK;IACjB,aAAa,EAAE,CAAC,KAAK;IACrB,gBAAgB,EAAE,CAAC,KAAK;IACxB,eAAe,EAAE,CAAC,KAAK;CACf,CAAC;AAEX,8DAA8D;AAC9D,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,WAAW,EAAE,CAAC,KAAK;IACnB,eAAe,EAAE,CAAC,KAAK;IACvB,gBAAgB,EAAE,CAAC,KAAK;IACxB,cAAc,EAAE,CAAC,KAAK;IACtB,cAAc,EAAE,CAAC,KAAK;IACtB,GAAG,kBAAkB;CACb,CAAC"}
|