@nhatnguyen9317/memory-mcp-server 1.3.2 → 1.4.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/CHANGELOG.md +73 -1
- package/GUIDELINES.md +94 -123
- package/README.md +31 -38
- package/dist/constants.js +45 -7
- package/dist/migrations/0006_workspace_identity.js +11 -0
- package/dist/migrations/0007_drop_reasoning_step_marks.js +9 -0
- package/dist/migrations/0008_session_recalled_memory_ids.js +9 -0
- package/dist/migrations/index.js +6 -0
- package/dist/schemas/memory.js +14 -122
- package/dist/schemas/reasoning.js +29 -73
- package/dist/server.js +2 -1
- package/dist/tools/memory.js +56 -668
- package/dist/tools/reasoning.js +209 -552
- package/dist/utils.js +145 -10
- package/package.json +1 -1
package/dist/migrations/index.js
CHANGED
|
@@ -4,12 +4,18 @@ import { migration0002ReasoningStepMarks } from "./0002_reasoning_step_marks.js"
|
|
|
4
4
|
import { migration0003ReasoningStepsFts } from "./0003_reasoning_steps_fts.js";
|
|
5
5
|
import { migration0004ToolUsageEvents } from "./0004_tool_usage_events.js";
|
|
6
6
|
import { migration0005MemoryWorkspace } from "./0005_memory_workspace.js";
|
|
7
|
+
import { migration0006WorkspaceIdentity } from "./0006_workspace_identity.js";
|
|
8
|
+
import { migration0007DropReasoningStepMarks } from "./0007_drop_reasoning_step_marks.js";
|
|
9
|
+
import { migration0008SessionRecalledMemoryIds } from "./0008_session_recalled_memory_ids.js";
|
|
7
10
|
const migrations = [
|
|
8
11
|
migration0001Initial,
|
|
9
12
|
migration0002ReasoningStepMarks,
|
|
10
13
|
migration0003ReasoningStepsFts,
|
|
11
14
|
migration0004ToolUsageEvents,
|
|
12
15
|
migration0005MemoryWorkspace,
|
|
16
|
+
migration0006WorkspaceIdentity,
|
|
17
|
+
migration0007DropReasoningStepMarks,
|
|
18
|
+
migration0008SessionRecalledMemoryIds,
|
|
13
19
|
];
|
|
14
20
|
export function runMigrations(db) {
|
|
15
21
|
db.exec(`
|
package/dist/schemas/memory.js
CHANGED
|
@@ -1,16 +1,4 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
-
const REPORT_DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;
|
|
3
|
-
function isValidReportDate(value) {
|
|
4
|
-
if (REPORT_DATE_ONLY_RE.test(value))
|
|
5
|
-
return true;
|
|
6
|
-
return !Number.isNaN(Date.parse(value));
|
|
7
|
-
}
|
|
8
|
-
const ReportDateInputSchema = z
|
|
9
|
-
.string()
|
|
10
|
-
.max(50)
|
|
11
|
-
.refine(isValidReportDate, {
|
|
12
|
-
message: "Expected YYYY-MM-DD or a valid date-time string.",
|
|
13
|
-
});
|
|
14
2
|
export const MemoryTypeEnum = z.enum([
|
|
15
3
|
"fact",
|
|
16
4
|
"preference",
|
|
@@ -18,88 +6,33 @@ export const MemoryTypeEnum = z.enum([
|
|
|
18
6
|
"decision",
|
|
19
7
|
"reasoning_summary",
|
|
20
8
|
]);
|
|
21
|
-
export const MemorySaveInputSchema = z
|
|
22
|
-
.object({
|
|
23
|
-
content: z
|
|
24
|
-
.string()
|
|
25
|
-
.min(1, "content is required")
|
|
26
|
-
.max(8000, "content must not exceed 8000 characters")
|
|
27
|
-
.describe("The memory text to store, written as a self-contained statement (e.g. 'User prefers TypeScript over Python for new services')."),
|
|
28
|
-
type: MemoryTypeEnum.default("fact").describe("Category of memory: 'fact' (durable info), 'preference' (user/agent preference), 'episodic' (something that happened), 'decision' (a choice that was made and why), 'reasoning_summary' (distilled conclusion from a reasoning session)."),
|
|
29
|
-
tags: z
|
|
30
|
-
.array(z.string().min(1).max(50))
|
|
31
|
-
.max(20)
|
|
32
|
-
.default([])
|
|
33
|
-
.describe("Short lowercase topic labels for filtering/search, e.g. ['sqlite','backend'] — topics, not workspace or project names."),
|
|
34
|
-
importance: z
|
|
35
|
-
.number()
|
|
36
|
-
.int()
|
|
37
|
-
.min(1)
|
|
38
|
-
.max(5)
|
|
39
|
-
.default(3)
|
|
40
|
-
.describe("Priority from 1 (trivial) to 5 (critical). Use to rank recall when many memories match."),
|
|
41
|
-
agent_id: z
|
|
42
|
-
.string()
|
|
43
|
-
.max(100)
|
|
44
|
-
.optional()
|
|
45
|
-
.describe("Optional identifier for the agent/persona this memory belongs to, for multi-agent setups."),
|
|
46
|
-
metadata: z
|
|
47
|
-
.record(z.unknown())
|
|
48
|
-
.optional()
|
|
49
|
-
.describe("Optional free-form JSON object for extra structured context (e.g. {\"source_url\": \"...\"})."),
|
|
50
|
-
})
|
|
51
|
-
.strict();
|
|
52
9
|
export const MemorySearchInputSchema = z
|
|
53
10
|
.object({
|
|
54
11
|
query: z
|
|
55
12
|
.string()
|
|
56
13
|
.min(1, "query must be at least 1 character")
|
|
57
14
|
.max(300)
|
|
58
|
-
.describe("
|
|
59
|
-
type: MemoryTypeEnum.optional().describe("
|
|
15
|
+
.describe("Words to look for in content and tags."),
|
|
16
|
+
type: MemoryTypeEnum.optional().describe("Only this memory type."),
|
|
60
17
|
agent_id: z.string().max(100).optional().describe("Filter by agent_id."),
|
|
61
18
|
tags: z
|
|
62
19
|
.array(z.string())
|
|
63
20
|
.max(20)
|
|
64
21
|
.optional()
|
|
65
|
-
.describe("
|
|
22
|
+
.describe("Must contain all of these tags."),
|
|
66
23
|
limit: z
|
|
67
24
|
.number()
|
|
68
25
|
.int()
|
|
69
26
|
.min(1)
|
|
70
27
|
.max(200)
|
|
71
28
|
.default(20)
|
|
72
|
-
.describe("
|
|
29
|
+
.describe("Max results."),
|
|
73
30
|
offset: z
|
|
74
31
|
.number()
|
|
75
32
|
.int()
|
|
76
33
|
.min(0)
|
|
77
34
|
.default(0)
|
|
78
|
-
.describe("
|
|
79
|
-
})
|
|
80
|
-
.strict();
|
|
81
|
-
export const MemoryListInputSchema = z
|
|
82
|
-
.object({
|
|
83
|
-
type: MemoryTypeEnum.optional().describe("Filter by memory type."),
|
|
84
|
-
agent_id: z.string().max(100).optional().describe("Filter by agent_id."),
|
|
85
|
-
tags: z
|
|
86
|
-
.array(z.string())
|
|
87
|
-
.max(20)
|
|
88
|
-
.optional()
|
|
89
|
-
.describe("Only return memories that contain ALL of these tags."),
|
|
90
|
-
min_importance: z
|
|
91
|
-
.number()
|
|
92
|
-
.int()
|
|
93
|
-
.min(1)
|
|
94
|
-
.max(5)
|
|
95
|
-
.optional()
|
|
96
|
-
.describe("Only return memories with importance >= this value."),
|
|
97
|
-
sort_by: z
|
|
98
|
-
.enum(["created_at", "updated_at", "importance"])
|
|
99
|
-
.default("updated_at")
|
|
100
|
-
.describe("Field to sort by (default: updated_at, newest first)."),
|
|
101
|
-
limit: z.number().int().min(1).max(200).default(20),
|
|
102
|
-
offset: z.number().int().min(0).default(0),
|
|
35
|
+
.describe("Results to skip."),
|
|
103
36
|
})
|
|
104
37
|
.strict();
|
|
105
38
|
export const MemoryGetInputSchema = z
|
|
@@ -112,43 +45,38 @@ export const MemoryGetInputSchema = z
|
|
|
112
45
|
// in the tool handler instead.
|
|
113
46
|
export const MemoryUpdateInputSchema = z
|
|
114
47
|
.object({
|
|
115
|
-
id: z.string().min(1).describe("The memory id
|
|
48
|
+
id: z.string().min(1).describe("The memory id."),
|
|
116
49
|
content: z
|
|
117
50
|
.string()
|
|
118
51
|
.min(1)
|
|
119
52
|
.max(8000)
|
|
120
53
|
.optional()
|
|
121
|
-
.describe("New content
|
|
122
|
-
type: MemoryTypeEnum.optional().describe("New
|
|
54
|
+
.describe("New content."),
|
|
55
|
+
type: MemoryTypeEnum.optional().describe("New type."),
|
|
123
56
|
tags: z
|
|
124
57
|
.array(z.string().min(1).max(50))
|
|
125
58
|
.max(20)
|
|
126
59
|
.optional()
|
|
127
|
-
.describe("Replaces
|
|
60
|
+
.describe("Replaces all tags."),
|
|
128
61
|
tags_append: z
|
|
129
62
|
.array(z.string().min(1).max(50))
|
|
130
63
|
.max(20)
|
|
131
64
|
.optional()
|
|
132
|
-
.describe("Tags to
|
|
65
|
+
.describe("Tags to add."),
|
|
133
66
|
tags_remove: z
|
|
134
67
|
.array(z.string().min(1).max(50))
|
|
135
68
|
.max(20)
|
|
136
69
|
.optional()
|
|
137
|
-
.describe("Tags to remove
|
|
138
|
-
importance: z.number().int().min(1).max(5).optional().describe("New importance
|
|
70
|
+
.describe("Tags to remove."),
|
|
71
|
+
importance: z.number().int().min(1).max(5).optional().describe("New importance."),
|
|
139
72
|
metadata: z
|
|
140
73
|
.record(z.unknown())
|
|
141
74
|
.optional()
|
|
142
|
-
.describe("Replaces the
|
|
75
|
+
.describe("Replaces the whole metadata object."),
|
|
143
76
|
metadata_patch: z
|
|
144
77
|
.record(z.unknown())
|
|
145
78
|
.optional()
|
|
146
|
-
.describe("
|
|
147
|
-
})
|
|
148
|
-
.strict();
|
|
149
|
-
export const MemoryDeleteInputSchema = z
|
|
150
|
-
.object({
|
|
151
|
-
id: z.string().min(1).describe("The memory id to delete."),
|
|
79
|
+
.describe("Keys to merge into metadata (shallow)."),
|
|
152
80
|
})
|
|
153
81
|
.strict();
|
|
154
82
|
export const MemoryGetUsageGuideInputSchema = z
|
|
@@ -158,42 +86,6 @@ export const MemoryGetUsageGuideInputSchema = z
|
|
|
158
86
|
client_version: z.string().max(100).optional(),
|
|
159
87
|
})
|
|
160
88
|
.strict();
|
|
161
|
-
export const MemoryUsageReportGroupByEnum = z.enum([
|
|
162
|
-
"tool_name",
|
|
163
|
-
"agent_id",
|
|
164
|
-
"client_name",
|
|
165
|
-
"mcp_version",
|
|
166
|
-
"operation_type",
|
|
167
|
-
"status",
|
|
168
|
-
"day",
|
|
169
|
-
]);
|
|
170
|
-
export const MemoryUsageReportInputSchema = z
|
|
171
|
-
.object({
|
|
172
|
-
agent_id: z.string().max(100).optional(),
|
|
173
|
-
client_name: z.string().max(100).optional(),
|
|
174
|
-
mcp_version: z.string().max(50).optional(),
|
|
175
|
-
date_from: ReportDateInputSchema.optional(),
|
|
176
|
-
date_to: ReportDateInputSchema.optional(),
|
|
177
|
-
group_by: MemoryUsageReportGroupByEnum.default("tool_name"),
|
|
178
|
-
limit: z.number().int().min(1).max(200).default(50),
|
|
179
|
-
})
|
|
180
|
-
.strict();
|
|
181
|
-
export const MemoryAdoptionReportInputSchema = z
|
|
182
|
-
.object({
|
|
183
|
-
agent_id: z.string().max(100).optional(),
|
|
184
|
-
date_from: ReportDateInputSchema.optional(),
|
|
185
|
-
date_to: ReportDateInputSchema.optional(),
|
|
186
|
-
limit: z.number().int().min(1).max(200).default(50),
|
|
187
|
-
})
|
|
188
|
-
.strict();
|
|
189
|
-
export const MemoryAgentScorecardInputSchema = z
|
|
190
|
-
.object({
|
|
191
|
-
agent_id: z.string().max(100).optional(),
|
|
192
|
-
date_from: ReportDateInputSchema.optional(),
|
|
193
|
-
date_to: ReportDateInputSchema.optional(),
|
|
194
|
-
limit: z.number().int().min(1).max(200).default(20),
|
|
195
|
-
})
|
|
196
|
-
.strict();
|
|
197
89
|
export const MemoryFeedbackUsefulnessEnum = z.enum([
|
|
198
90
|
"used",
|
|
199
91
|
"ignored",
|
|
@@ -11,6 +11,11 @@ export const ReasoningStartSessionInputSchema = z
|
|
|
11
11
|
.max(100)
|
|
12
12
|
.optional()
|
|
13
13
|
.describe("Optional identifier for the agent/persona running this session."),
|
|
14
|
+
workspace: z
|
|
15
|
+
.string()
|
|
16
|
+
.max(500)
|
|
17
|
+
.optional()
|
|
18
|
+
.describe("Absolute path of the project directory you are working in. Pass it so recall prefers this project's memories and your conclusion is saved under it. If omitted the server uses its own working directory; '/' and the home directory count as unknown."),
|
|
14
19
|
})
|
|
15
20
|
.strict();
|
|
16
21
|
export const ReasoningStepEntrySchema = z
|
|
@@ -64,79 +69,6 @@ export const ReasoningAddStepInputSchema = z
|
|
|
64
69
|
.describe("Batch mode: log several steps in one call (each entry needs at least one of thought/action/observation). Use INSTEAD of the top-level thought/action/observation fields, e.g. to record the trace of work you just finished without one call per step."),
|
|
65
70
|
})
|
|
66
71
|
.strict();
|
|
67
|
-
export const ReasoningGetTraceInputSchema = z
|
|
68
|
-
.object({
|
|
69
|
-
session_id: z.string().min(1).describe("The session id to retrieve the full trace for."),
|
|
70
|
-
})
|
|
71
|
-
.strict();
|
|
72
|
-
export const ReasoningListSessionsInputSchema = z
|
|
73
|
-
.object({
|
|
74
|
-
agent_id: z.string().max(100).optional().describe("Filter by agent_id."),
|
|
75
|
-
status: z
|
|
76
|
-
.enum(["in_progress", "completed", "abandoned"])
|
|
77
|
-
.optional()
|
|
78
|
-
.describe("Filter by session status."),
|
|
79
|
-
limit: z.number().int().min(1).max(200).default(20),
|
|
80
|
-
offset: z.number().int().min(0).default(0),
|
|
81
|
-
})
|
|
82
|
-
.strict();
|
|
83
|
-
export const ReasoningMarkTypeEnum = z.enum([
|
|
84
|
-
"milestone",
|
|
85
|
-
"decision",
|
|
86
|
-
"conflict",
|
|
87
|
-
"important",
|
|
88
|
-
"hypothesis",
|
|
89
|
-
]);
|
|
90
|
-
export const ReasoningMarkStepInputSchema = z
|
|
91
|
-
.object({
|
|
92
|
-
step_id: z.string().min(1).describe("The reasoning step id to mark."),
|
|
93
|
-
mark_type: ReasoningMarkTypeEnum.describe("Audit marker type for the step."),
|
|
94
|
-
note: z
|
|
95
|
-
.string()
|
|
96
|
-
.max(1000)
|
|
97
|
-
.optional()
|
|
98
|
-
.describe("Optional note attached to the mark."),
|
|
99
|
-
})
|
|
100
|
-
.strict();
|
|
101
|
-
export const ReasoningSearchStepsInputSchema = z
|
|
102
|
-
.object({
|
|
103
|
-
query: z
|
|
104
|
-
.string()
|
|
105
|
-
.min(1)
|
|
106
|
-
.max(200)
|
|
107
|
-
.describe("Full-text query across thought, action, and observation."),
|
|
108
|
-
session_id: z
|
|
109
|
-
.string()
|
|
110
|
-
.min(1)
|
|
111
|
-
.optional()
|
|
112
|
-
.describe("Optional session id filter."),
|
|
113
|
-
agent_id: z.string().max(100).optional().describe("Optional agent_id filter."),
|
|
114
|
-
mark_type: ReasoningMarkTypeEnum.optional().describe("Optional mark filter."),
|
|
115
|
-
limit: z.number().int().min(1).max(200).default(20),
|
|
116
|
-
offset: z.number().int().min(0).default(0),
|
|
117
|
-
})
|
|
118
|
-
.strict();
|
|
119
|
-
export const ReasoningListMilestonesInputSchema = z
|
|
120
|
-
.object({
|
|
121
|
-
session_id: z
|
|
122
|
-
.string()
|
|
123
|
-
.min(1)
|
|
124
|
-
.optional()
|
|
125
|
-
.describe("Optional session id filter."),
|
|
126
|
-
agent_id: z.string().max(100).optional().describe("Optional agent_id filter."),
|
|
127
|
-
mark_type: ReasoningMarkTypeEnum.optional().describe("Optional mark filter."),
|
|
128
|
-
limit: z.number().int().min(1).max(200).default(20),
|
|
129
|
-
offset: z.number().int().min(0).default(0),
|
|
130
|
-
})
|
|
131
|
-
.strict();
|
|
132
|
-
export const ReasoningGetSessionOutlineInputSchema = z
|
|
133
|
-
.object({
|
|
134
|
-
session_id: z
|
|
135
|
-
.string()
|
|
136
|
-
.min(1)
|
|
137
|
-
.describe("The session id to summarize into an audit outline."),
|
|
138
|
-
})
|
|
139
|
-
.strict();
|
|
140
72
|
export const ReasoningCompleteSessionInputSchema = z
|
|
141
73
|
.object({
|
|
142
74
|
session_id: z.string().min(1).describe("The session id to complete."),
|
|
@@ -186,4 +118,28 @@ export const ReasoningCompleteSessionInputSchema = z
|
|
|
186
118
|
.describe("Ids of memories that were actually used/helpful during this session (e.g. ones returned in related_memories by reasoning_start_session). The server records a 'used' usage-feedback event for each, so recall usefulness can be measured."),
|
|
187
119
|
})
|
|
188
120
|
.strict();
|
|
121
|
+
// Plain ZodObject so `.shape` works for registerTool; "exactly one of
|
|
122
|
+
// query / session_id" is enforced in the handler.
|
|
123
|
+
export const ReasoningFindInputSchema = z
|
|
124
|
+
.object({
|
|
125
|
+
query: z
|
|
126
|
+
.string()
|
|
127
|
+
.min(1)
|
|
128
|
+
.max(300)
|
|
129
|
+
.optional()
|
|
130
|
+
.describe("Find mode: words to look for in past sessions' titles, conclusions and steps."),
|
|
131
|
+
session_id: z
|
|
132
|
+
.string()
|
|
133
|
+
.min(1)
|
|
134
|
+
.optional()
|
|
135
|
+
.describe("Read mode: a session id (from a find result or a memory's source.session_id)."),
|
|
136
|
+
limit: z
|
|
137
|
+
.number()
|
|
138
|
+
.int()
|
|
139
|
+
.min(1)
|
|
140
|
+
.max(10)
|
|
141
|
+
.default(5)
|
|
142
|
+
.describe("Find mode: max sessions returned."),
|
|
143
|
+
})
|
|
144
|
+
.strict();
|
|
189
145
|
//# sourceMappingURL=reasoning.js.map
|
package/dist/server.js
CHANGED
|
@@ -9,7 +9,8 @@ export const SERVER_INSTRUCTIONS = [
|
|
|
9
9
|
"Memory MCP: durable memory (memory_*) plus reasoning traces (reasoning_*).",
|
|
10
10
|
"Call get_usage_guide for the full policy guide before first use.",
|
|
11
11
|
"Core loop: reasoning_start_session at task start (skip for trivial one-step lookups); log pivotal steps with reasoning_add_step; always finish with reasoning_complete_session (conclusion + used_memory_ids).",
|
|
12
|
-
"Every reasoning_add_step/complete_session call requires the session_id returned by reasoning_start_session
|
|
12
|
+
"Every reasoning_add_step/complete_session call requires the session_id returned by reasoning_start_session.",
|
|
13
|
+
"To recover earlier work your context does not contain, use reasoning_find.",
|
|
13
14
|
"Saving a conclusion as memory is opt-in (save_as_memory=true); memory_mode='never' requires not_saved_reason.",
|
|
14
15
|
"Tool schemas are the source of truth for parameter contracts. Never store secrets, tokens, or credentials.",
|
|
15
16
|
].join(" ");
|