@nhatnguyen9317/memory-mcp-server 1.1.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.
- package/GUIDELINES.md +44 -0
- package/README.md +265 -0
- package/dist/constants.js +16 -0
- package/dist/db.js +17 -0
- package/dist/index.js +32 -0
- package/dist/migrations/0001_initial.js +74 -0
- package/dist/migrations/0002_reasoning_step_marks.js +22 -0
- package/dist/migrations/0003_reasoning_steps_fts.js +34 -0
- package/dist/migrations/0004_tool_usage_events.js +48 -0
- package/dist/migrations/index.js +40 -0
- package/dist/schemas/memory.js +213 -0
- package/dist/schemas/reasoning.js +159 -0
- package/dist/tools/memory.js +998 -0
- package/dist/tools/reasoning.js +1001 -0
- package/dist/tools/telemetry.js +103 -0
- package/dist/tools/usage-guide.js +83 -0
- package/dist/types.js +2 -0
- package/dist/utils.js +67 -0
- package/package.json +41 -0
|
@@ -0,0 +1,213 @@
|
|
|
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
|
+
export const MemoryTypeEnum = z.enum([
|
|
15
|
+
"fact",
|
|
16
|
+
"preference",
|
|
17
|
+
"episodic",
|
|
18
|
+
"decision",
|
|
19
|
+
"reasoning_summary",
|
|
20
|
+
]);
|
|
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 labels for filtering/search, e.g. ['project-x','backend']."),
|
|
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
|
+
export const MemorySearchInputSchema = z
|
|
53
|
+
.object({
|
|
54
|
+
query: z
|
|
55
|
+
.string()
|
|
56
|
+
.min(1, "query must be at least 1 character")
|
|
57
|
+
.max(300)
|
|
58
|
+
.describe("Free-text search query, matched against content and tags."),
|
|
59
|
+
type: MemoryTypeEnum.optional().describe("Restrict results to a single memory type."),
|
|
60
|
+
agent_id: z.string().max(100).optional().describe("Filter by agent_id."),
|
|
61
|
+
tags: z
|
|
62
|
+
.array(z.string())
|
|
63
|
+
.max(20)
|
|
64
|
+
.optional()
|
|
65
|
+
.describe("Only return memories that contain ALL of these tags."),
|
|
66
|
+
limit: z
|
|
67
|
+
.number()
|
|
68
|
+
.int()
|
|
69
|
+
.min(1)
|
|
70
|
+
.max(200)
|
|
71
|
+
.default(20)
|
|
72
|
+
.describe("Maximum results to return (default 20, max 200)."),
|
|
73
|
+
offset: z
|
|
74
|
+
.number()
|
|
75
|
+
.int()
|
|
76
|
+
.min(0)
|
|
77
|
+
.default(0)
|
|
78
|
+
.describe("Number of results to skip, for pagination."),
|
|
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),
|
|
103
|
+
})
|
|
104
|
+
.strict();
|
|
105
|
+
export const MemoryGetInputSchema = z
|
|
106
|
+
.object({
|
|
107
|
+
id: z.string().min(1).describe("The memory id, e.g. 'mem_...'."),
|
|
108
|
+
})
|
|
109
|
+
.strict();
|
|
110
|
+
// NOTE: kept as a plain ZodObject (no .refine()) so `.shape` stays available
|
|
111
|
+
// for registerTool's inputSchema. The "at least one field" rule is enforced
|
|
112
|
+
// in the tool handler instead.
|
|
113
|
+
export const MemoryUpdateInputSchema = z
|
|
114
|
+
.object({
|
|
115
|
+
id: z.string().min(1).describe("The memory id to update."),
|
|
116
|
+
content: z
|
|
117
|
+
.string()
|
|
118
|
+
.min(1)
|
|
119
|
+
.max(8000)
|
|
120
|
+
.optional()
|
|
121
|
+
.describe("New content text, if changing it."),
|
|
122
|
+
type: MemoryTypeEnum.optional().describe("New memory type, if changing it."),
|
|
123
|
+
tags: z
|
|
124
|
+
.array(z.string().min(1).max(50))
|
|
125
|
+
.max(20)
|
|
126
|
+
.optional()
|
|
127
|
+
.describe("Replaces the full tag list (not merged), if provided."),
|
|
128
|
+
tags_append: z
|
|
129
|
+
.array(z.string().min(1).max(50))
|
|
130
|
+
.max(20)
|
|
131
|
+
.optional()
|
|
132
|
+
.describe("Tags to append when not replacing the full tag list."),
|
|
133
|
+
tags_remove: z
|
|
134
|
+
.array(z.string().min(1).max(50))
|
|
135
|
+
.max(20)
|
|
136
|
+
.optional()
|
|
137
|
+
.describe("Tags to remove when not replacing the full tag list."),
|
|
138
|
+
importance: z.number().int().min(1).max(5).optional().describe("New importance, if changing it."),
|
|
139
|
+
metadata: z
|
|
140
|
+
.record(z.unknown())
|
|
141
|
+
.optional()
|
|
142
|
+
.describe("Replaces the full metadata object (not merged), if provided."),
|
|
143
|
+
metadata_patch: z
|
|
144
|
+
.record(z.unknown())
|
|
145
|
+
.optional()
|
|
146
|
+
.describe("Shallow metadata patch to merge when not replacing the full metadata object."),
|
|
147
|
+
})
|
|
148
|
+
.strict();
|
|
149
|
+
export const MemoryDeleteInputSchema = z
|
|
150
|
+
.object({
|
|
151
|
+
id: z.string().min(1).describe("The memory id to delete."),
|
|
152
|
+
})
|
|
153
|
+
.strict();
|
|
154
|
+
export const MemoryGetUsageGuideInputSchema = z
|
|
155
|
+
.object({
|
|
156
|
+
agent_id: z.string().max(100).optional(),
|
|
157
|
+
client_name: z.string().max(100).optional(),
|
|
158
|
+
client_version: z.string().max(100).optional(),
|
|
159
|
+
})
|
|
160
|
+
.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
|
+
export const MemoryFeedbackUsefulnessEnum = z.enum([
|
|
198
|
+
"used",
|
|
199
|
+
"ignored",
|
|
200
|
+
"irrelevant",
|
|
201
|
+
"stale",
|
|
202
|
+
"unsafe_to_use",
|
|
203
|
+
]);
|
|
204
|
+
export const MemoryRecordUsageFeedbackInputSchema = z
|
|
205
|
+
.object({
|
|
206
|
+
memory_id: z.string().min(1),
|
|
207
|
+
event_id: z.string().min(1).optional(),
|
|
208
|
+
agent_id: z.string().max(100).optional(),
|
|
209
|
+
usefulness: MemoryFeedbackUsefulnessEnum,
|
|
210
|
+
reason: z.string().min(1).max(500).optional(),
|
|
211
|
+
})
|
|
212
|
+
.strict();
|
|
213
|
+
//# sourceMappingURL=memory.js.map
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
export const ReasoningStartSessionInputSchema = z
|
|
3
|
+
.object({
|
|
4
|
+
title: z
|
|
5
|
+
.string()
|
|
6
|
+
.min(1)
|
|
7
|
+
.max(300)
|
|
8
|
+
.describe("Short description of the task/question this reasoning session is about, e.g. 'Diagnose flaky checkout test'."),
|
|
9
|
+
agent_id: z
|
|
10
|
+
.string()
|
|
11
|
+
.max(100)
|
|
12
|
+
.optional()
|
|
13
|
+
.describe("Optional identifier for the agent/persona running this session."),
|
|
14
|
+
})
|
|
15
|
+
.strict();
|
|
16
|
+
// NOTE: kept as a plain ZodObject (no .refine()) so `.shape` stays available
|
|
17
|
+
// for registerTool's inputSchema. The "at least one field" rule is enforced
|
|
18
|
+
// in the tool handler instead.
|
|
19
|
+
export const ReasoningAddStepInputSchema = z
|
|
20
|
+
.object({
|
|
21
|
+
session_id: z
|
|
22
|
+
.string()
|
|
23
|
+
.min(1)
|
|
24
|
+
.describe("The session id returned by reasoning_start_session."),
|
|
25
|
+
thought: z
|
|
26
|
+
.string()
|
|
27
|
+
.max(4000)
|
|
28
|
+
.optional()
|
|
29
|
+
.describe("The agent's reasoning/thinking at this step."),
|
|
30
|
+
action: z
|
|
31
|
+
.string()
|
|
32
|
+
.max(2000)
|
|
33
|
+
.optional()
|
|
34
|
+
.describe("The action taken at this step, if any (e.g. a tool call description)."),
|
|
35
|
+
observation: z
|
|
36
|
+
.string()
|
|
37
|
+
.max(4000)
|
|
38
|
+
.optional()
|
|
39
|
+
.describe("The result/observation from the action, if any."),
|
|
40
|
+
})
|
|
41
|
+
.strict();
|
|
42
|
+
export const ReasoningGetTraceInputSchema = z
|
|
43
|
+
.object({
|
|
44
|
+
session_id: z.string().min(1).describe("The session id to retrieve the full trace for."),
|
|
45
|
+
})
|
|
46
|
+
.strict();
|
|
47
|
+
export const ReasoningListSessionsInputSchema = z
|
|
48
|
+
.object({
|
|
49
|
+
agent_id: z.string().max(100).optional().describe("Filter by agent_id."),
|
|
50
|
+
status: z
|
|
51
|
+
.enum(["in_progress", "completed", "abandoned"])
|
|
52
|
+
.optional()
|
|
53
|
+
.describe("Filter by session status."),
|
|
54
|
+
limit: z.number().int().min(1).max(200).default(20),
|
|
55
|
+
offset: z.number().int().min(0).default(0),
|
|
56
|
+
})
|
|
57
|
+
.strict();
|
|
58
|
+
export const ReasoningMarkTypeEnum = z.enum([
|
|
59
|
+
"milestone",
|
|
60
|
+
"decision",
|
|
61
|
+
"conflict",
|
|
62
|
+
"important",
|
|
63
|
+
"hypothesis",
|
|
64
|
+
]);
|
|
65
|
+
export const ReasoningMarkStepInputSchema = z
|
|
66
|
+
.object({
|
|
67
|
+
step_id: z.string().min(1).describe("The reasoning step id to mark."),
|
|
68
|
+
mark_type: ReasoningMarkTypeEnum.describe("Audit marker type for the step."),
|
|
69
|
+
note: z
|
|
70
|
+
.string()
|
|
71
|
+
.max(1000)
|
|
72
|
+
.optional()
|
|
73
|
+
.describe("Optional note attached to the mark."),
|
|
74
|
+
})
|
|
75
|
+
.strict();
|
|
76
|
+
export const ReasoningSearchStepsInputSchema = z
|
|
77
|
+
.object({
|
|
78
|
+
query: z
|
|
79
|
+
.string()
|
|
80
|
+
.min(1)
|
|
81
|
+
.max(200)
|
|
82
|
+
.describe("Full-text query across thought, action, and observation."),
|
|
83
|
+
session_id: z
|
|
84
|
+
.string()
|
|
85
|
+
.min(1)
|
|
86
|
+
.optional()
|
|
87
|
+
.describe("Optional session id filter."),
|
|
88
|
+
agent_id: z.string().max(100).optional().describe("Optional agent_id filter."),
|
|
89
|
+
mark_type: ReasoningMarkTypeEnum.optional().describe("Optional mark filter."),
|
|
90
|
+
limit: z.number().int().min(1).max(200).default(20),
|
|
91
|
+
offset: z.number().int().min(0).default(0),
|
|
92
|
+
})
|
|
93
|
+
.strict();
|
|
94
|
+
export const ReasoningListMilestonesInputSchema = z
|
|
95
|
+
.object({
|
|
96
|
+
session_id: z
|
|
97
|
+
.string()
|
|
98
|
+
.min(1)
|
|
99
|
+
.optional()
|
|
100
|
+
.describe("Optional session id filter."),
|
|
101
|
+
agent_id: z.string().max(100).optional().describe("Optional agent_id filter."),
|
|
102
|
+
mark_type: ReasoningMarkTypeEnum.optional().describe("Optional mark filter."),
|
|
103
|
+
limit: z.number().int().min(1).max(200).default(20),
|
|
104
|
+
offset: z.number().int().min(0).default(0),
|
|
105
|
+
})
|
|
106
|
+
.strict();
|
|
107
|
+
export const ReasoningGetSessionOutlineInputSchema = z
|
|
108
|
+
.object({
|
|
109
|
+
session_id: z
|
|
110
|
+
.string()
|
|
111
|
+
.min(1)
|
|
112
|
+
.describe("The session id to summarize into an audit outline."),
|
|
113
|
+
})
|
|
114
|
+
.strict();
|
|
115
|
+
export const ReasoningCompleteSessionInputSchema = z
|
|
116
|
+
.object({
|
|
117
|
+
session_id: z.string().min(1).describe("The session id to complete."),
|
|
118
|
+
conclusion: z
|
|
119
|
+
.string()
|
|
120
|
+
.min(1)
|
|
121
|
+
.max(4000)
|
|
122
|
+
.describe("The final conclusion/decision reached by this reasoning session."),
|
|
123
|
+
status: z
|
|
124
|
+
.enum(["completed", "abandoned"])
|
|
125
|
+
.default("completed")
|
|
126
|
+
.describe("Final status: 'completed' if a conclusion was reached, 'abandoned' if the task was dropped."),
|
|
127
|
+
save_as_memory: z
|
|
128
|
+
.boolean()
|
|
129
|
+
.default(false)
|
|
130
|
+
.describe("If true, also create a long-term memory (type='reasoning_summary') containing the conclusion, so it can be recalled later via memory_search."),
|
|
131
|
+
memory_mode: z
|
|
132
|
+
.enum(["auto", "always", "never"])
|
|
133
|
+
.optional()
|
|
134
|
+
.describe("Preferred memory persistence mode. 'auto' saves durable completed conclusions by default, 'always' forces a save, and 'never' skips saving."),
|
|
135
|
+
memory_type: z
|
|
136
|
+
.enum(["fact", "preference", "episodic", "decision", "reasoning_summary"])
|
|
137
|
+
.optional()
|
|
138
|
+
.describe("Memory type to use when a completion is persisted."),
|
|
139
|
+
memory_importance: z
|
|
140
|
+
.number()
|
|
141
|
+
.int()
|
|
142
|
+
.min(1)
|
|
143
|
+
.max(5)
|
|
144
|
+
.optional()
|
|
145
|
+
.describe("Importance to use when a completion is persisted as memory."),
|
|
146
|
+
memory_tags: z
|
|
147
|
+
.array(z.string().min(1).max(50))
|
|
148
|
+
.max(20)
|
|
149
|
+
.default([])
|
|
150
|
+
.describe("Tags to attach to the created memory, only used when save_as_memory is true."),
|
|
151
|
+
not_saved_reason: z
|
|
152
|
+
.string()
|
|
153
|
+
.min(1)
|
|
154
|
+
.max(500)
|
|
155
|
+
.optional()
|
|
156
|
+
.describe("Required when memory_mode='never' to explain why the conclusion should not be kept as durable memory."),
|
|
157
|
+
})
|
|
158
|
+
.strict();
|
|
159
|
+
//# sourceMappingURL=reasoning.js.map
|