@nhatnguyen9317/memory-mcp-server 1.3.3 → 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 +55 -1
- package/GUIDELINES.md +94 -133
- package/README.md +24 -35
- package/dist/constants.js +1 -1
- 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 +4 -0
- package/dist/schemas/memory.js +14 -127
- package/dist/schemas/reasoning.js +24 -73
- package/dist/server.js +2 -1
- package/dist/tools/memory.js +8 -655
- package/dist/tools/reasoning.js +143 -531
- package/dist/utils.js +100 -7
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,59 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.4.0 (2026-10-06)
|
|
4
|
+
|
|
5
|
+
Theme: a smaller tool surface — 12 tools that were unused or never exploited removed, one retrieval tool added, recalled memories recorded per session. Design: [`docs/design/2026-10-06-spec-v1.4.0-tool-surface-reduction.md`](docs/design/2026-10-06-spec-v1.4.0-tool-surface-reduction.md).
|
|
6
|
+
|
|
7
|
+
### Breaking
|
|
8
|
+
|
|
9
|
+
- Removed 12 tools: `memory_save`, `memory_list`, `memory_delete`,
|
|
10
|
+
`memory_usage_report`, `memory_adoption_report`, `memory_agent_scorecard`,
|
|
11
|
+
`reasoning_get_trace`, `reasoning_list_sessions`, `reasoning_search_steps`,
|
|
12
|
+
`reasoning_list_milestones`, `reasoning_get_session_outline`,
|
|
13
|
+
`reasoning_mark_step`. Eleven had 0 calls over the `GUIDELINES.md` v7 window
|
|
14
|
+
(2026-08-07 → 2026-10-04, 49 sessions); `reasoning_mark_step` was called but
|
|
15
|
+
its data was never read.
|
|
16
|
+
- Breaking change shipped as a minor release: pin
|
|
17
|
+
`@nhatnguyen9317/memory-mcp-server@1.3.3` to stay on the old tool surface.
|
|
18
|
+
A 1.3.x server sharing a database that 1.4.0 has migrated fails on
|
|
19
|
+
`reasoning_mark_step`, `reasoning_list_milestones`,
|
|
20
|
+
`reasoning_get_session_outline`, and on `reasoning_search_steps` with
|
|
21
|
+
`mark_type` (the `reasoning_step_marks` table is gone); the other tools keep
|
|
22
|
+
working.
|
|
23
|
+
- **Data deleted on upgrade:** migration `0007` drops `reasoning_step_marks`.
|
|
24
|
+
Back up `~/.memory-mcp-server/memory.db` first if you want to keep it.
|
|
25
|
+
- Migration notes: create memories with
|
|
26
|
+
`reasoning_complete_session(save_as_memory=true)`; correct them with
|
|
27
|
+
`memory_update`; flag wrong ones with
|
|
28
|
+
`memory_record_usage_feedback(usefulness='stale')`; read telemetry with SQL
|
|
29
|
+
on `tool_usage_events`; find or read past sessions with `reasoning_find`.
|
|
30
|
+
Re-run `npx @nhatnguyen9317/memory-mcp-server install-agents` to refresh the
|
|
31
|
+
installed agent snippet.
|
|
32
|
+
|
|
33
|
+
### Added
|
|
34
|
+
|
|
35
|
+
- `reasoning_find`: find past sessions by query (titles and conclusions by
|
|
36
|
+
word prefix, step text by full-text search) or read one session's full
|
|
37
|
+
trace.
|
|
38
|
+
- Recalled memory ids are recorded per session (migration `0008`); the
|
|
39
|
+
recall used-rate query is in `docs/architecture.md`.
|
|
40
|
+
- Auto-recall snippets show the part of the memory that matched the title
|
|
41
|
+
when it lies beyond the first 160 characters.
|
|
42
|
+
- `reasoning_find` results include each session's `workspace`, and empty
|
|
43
|
+
sessions (no steps, and no conclusion or only the auto-abandoned
|
|
44
|
+
placeholder) rank last; the placeholder conclusion is ignored when matching.
|
|
45
|
+
|
|
46
|
+
### Changed
|
|
47
|
+
|
|
48
|
+
- `GUIDELINES.md` v9 (`2026-10-06.v9`): trace checkpoints and the three trace
|
|
49
|
+
questions, pending-conclusion handling, first-sentence rule, stale triggers,
|
|
50
|
+
defaults for type and importance; shorter (6,525 vs 8,787 characters).
|
|
51
|
+
- Trimmed `memory_update` / `memory_search` descriptions.
|
|
52
|
+
- A memory flagged stale or unsafe returns to auto-recall once it is
|
|
53
|
+
corrected with `memory_update`.
|
|
54
|
+
- `tools/list`: 27,484 → 16,223 characters (9 tools, was 20);
|
|
55
|
+
`memory_update` + `memory_search`: 3,283 → 2,772.
|
|
56
|
+
|
|
3
57
|
## 1.3.3 (2026-10-05)
|
|
4
58
|
|
|
5
59
|
Theme: recall that respects project identity — fixes `reasoning_start_session` recalling other projects' memories, stale memories, and near-zero-relevance memories from the same project — and brings `memory_search` onto the same blended ranking, so multi-term searches stop returning nothing. Design: [`docs/design/2026-10-05-spec-recall-workspace-identity.md`](docs/design/2026-10-05-spec-recall-workspace-identity.md), [`docs/design/2026-08-07-spec-zero-mem-inspired-recall.md`](docs/design/2026-08-07-spec-zero-mem-inspired-recall.md) §2 Option A′.
|
|
@@ -35,7 +89,7 @@ Theme: guide-contract alignment — `GUIDELINES.md`, tool descriptions, and serv
|
|
|
35
89
|
|
|
36
90
|
### Notes
|
|
37
91
|
|
|
38
|
-
- Live-store telemetry (`MEMORY_TELEMETRY=on`) showed the manual memory CRUD surface (`memory_save`/`search`/`list`/`delete`) and the entire reasoning audit tier (`reasoning_get_trace`/`list_sessions`/`search_steps`/`list_milestones`/`get_session_outline`/`mark_step`) at zero real-world calls, while the automatic recall → save → feedback pipeline shows a 63% memory reuse rate. Recorded as an owner monitoring decision in `docs/design/2026-07-12-spec-v1.3.5-recall-refinements.md` §8.1: keep observing with the tightened guide; remove the affected tools in a future release if usage stays near zero.
|
|
92
|
+
- Live-store telemetry (`MEMORY_TELEMETRY=on`) showed the manual memory CRUD surface (`memory_save`/`search`/`list`/`delete`) and the entire reasoning audit tier (`reasoning_get_trace`/`list_sessions`/`search_steps`/`list_milestones`/`get_session_outline`/`mark_step`) at zero real-world calls, while the automatic recall → save → feedback pipeline shows a 63% memory reuse rate. Recorded as an owner monitoring decision in `docs/design/2026-07-12-spec-v1.3.5-recall-refinements.md` §8.1 (removed 2026-10-06; superseded by the 1.4.0 spec): keep observing with the tightened guide; remove the affected tools in a future release if usage stays near zero.
|
|
39
93
|
|
|
40
94
|
## 1.3.1 (2026-07-14)
|
|
41
95
|
|
package/GUIDELINES.md
CHANGED
|
@@ -1,162 +1,123 @@
|
|
|
1
1
|
# Memory MCP Guidelines
|
|
2
2
|
|
|
3
|
-
Version: 2026-10-
|
|
3
|
+
Version: 2026-10-06.v9
|
|
4
4
|
|
|
5
5
|
This file is the single source of truth for how an agent should use this MCP.
|
|
6
|
-
It is organized around the three moments of a task where this MCP matters.
|
|
7
6
|
Tool schemas and descriptions are the source of truth for parameter contracts
|
|
8
7
|
(required fields, types, enums); this guide covers policy — when and why.
|
|
8
|
+
In short: a task's trace goes into a reasoning session; durable knowledge is
|
|
9
|
+
the session's conclusion, saved by `reasoning_complete_session`.
|
|
9
10
|
|
|
10
11
|
## Moment 1 — Task Start
|
|
11
12
|
|
|
12
|
-
1. Decide the task size
|
|
13
|
-
- Trivial one-step lookup
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
one *before* deciding, not after. Once resolved, clean up the losing
|
|
47
|
-
memory with `memory_update` or `memory_delete`.
|
|
48
|
-
- `open_sessions_warning` / `open_sessions`: sessions left in_progress.
|
|
49
|
-
Close the ones YOU opened and finished with
|
|
50
|
-
`reasoning_complete_session`. Leave sessions you don't recognize alone —
|
|
51
|
-
they may belong to another agent or a parallel run; stale ones are
|
|
52
|
-
auto-abandoned by the server. A completed or abandoned session cannot be
|
|
53
|
-
reopened: to resume interrupted work, start a new session and reference
|
|
54
|
-
the old one in the title or an early step.
|
|
55
|
-
3. Only call `memory_search` yourself when you need recall on a topic that is
|
|
56
|
-
NOT the session title (the server already searched the title for you).
|
|
13
|
+
1. Decide the task size:
|
|
14
|
+
- Trivial one-step lookup (read one value, answer from context you
|
|
15
|
+
already have): no session, no memory calls. Stop here.
|
|
16
|
+
- Anything multi-step, uncertain, or involving debugging, planning, review
|
|
17
|
+
or trade-offs: call `reasoning_start_session`. The title is also the
|
|
18
|
+
recall query, so use concrete keywords (module, error, ticket names).
|
|
19
|
+
Pass `workspace` = the absolute path of your project; `/` and the home
|
|
20
|
+
directory count as unknown. If the response has a `workspace_warning`,
|
|
21
|
+
pass `workspace` to every later `reasoning_start_session`.
|
|
22
|
+
- The user's answer to a pending conclusion (a choice, a "go") starts a new
|
|
23
|
+
task. Open a session, short if needed, whose title names the decision.
|
|
24
|
+
2. Read what comes back:
|
|
25
|
+
- `related_memories`: saved conclusions matched to your title. An empty
|
|
26
|
+
list is normal; do not pad the title. Snippets show the start of each
|
|
27
|
+
memory, plus the matching part when it lies further in; read one in full
|
|
28
|
+
with `memory_get`. A `source` says which session produced it; read that
|
|
29
|
+
session with `reasoning_find(session_id)` when the snippet is not enough
|
|
30
|
+
to know why. Note which ones help — you report them at the end.
|
|
31
|
+
- With 2 or more memories, skim them for contradictions first. If two
|
|
32
|
+
conflict: read both with `memory_get` and prefer the newer
|
|
33
|
+
same-workspace one. If the loser can be corrected, fix it with
|
|
34
|
+
`memory_update`; otherwise flag it stale (see Moment 3). A wrong memory
|
|
35
|
+
is corrected or flagged, never deleted. A stale flag removes the memory
|
|
36
|
+
from auto-recall until it is next corrected with `memory_update`; it
|
|
37
|
+
stays reachable through `memory_search`.
|
|
38
|
+
- `open_sessions`: close the ones you opened and finished; leave the others
|
|
39
|
+
alone. A closed session cannot be reopened: start a new one and name the
|
|
40
|
+
old one in the title.
|
|
41
|
+
3. Recall beyond the title:
|
|
42
|
+
- `memory_search`: saved memories on a topic other than your title.
|
|
43
|
+
- `reasoning_find(query)`: when the user refers to earlier work, a past
|
|
44
|
+
decision or a previous conversation that your context does not contain
|
|
45
|
+
("last time…", "continue the unfinished…"). Find first, then read only
|
|
46
|
+
the session that matters with `reasoning_find(session_id)`.
|
|
57
47
|
|
|
58
48
|
## Moment 2 — During The Task
|
|
59
49
|
|
|
60
50
|
Every `reasoning_add_step` and `reasoning_complete_session` call requires the
|
|
61
|
-
`session_id` returned by `reasoning_start_session
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
51
|
+
`session_id` returned by `reasoning_start_session`.
|
|
52
|
+
|
|
53
|
+
Steps are the searchable record of how a task was done. When a later session
|
|
54
|
+
has lost this context, `reasoning_find` searches your steps to recover it. The
|
|
55
|
+
conclusion is a summary; it drops evidence, numbers and the options you
|
|
56
|
+
rejected. A session with only a conclusion can be found, but not
|
|
57
|
+
reconstructed.
|
|
58
|
+
|
|
59
|
+
- A useful trace answers three questions for a future agent: what did you
|
|
60
|
+
check, what did you find, and what did you decide and why — including the
|
|
61
|
+
options you rejected. One to three steps usually cover a normal task. Skip
|
|
62
|
+
routine actions, not the whole trace.
|
|
63
|
+
- Log a step (batch mode `steps: [...]` is fine) at these checkpoints:
|
|
64
|
+
- before you ask the user to choose or confirm something;
|
|
65
|
+
- when you present a plan or result;
|
|
66
|
+
- before `reasoning_complete_session`, if the trace does not yet answer
|
|
67
|
+
the three questions.
|
|
68
|
+
- If you realise mid-task that the work is non-trivial, open the session
|
|
69
|
+
then, and first log what you have done so far as one batch.
|
|
70
|
+
- Within a step: `thought` = your reasoning, `action` = what you did,
|
|
71
|
+
`observation` = what resulted; fill whichever apply.
|
|
80
72
|
|
|
81
73
|
## Moment 3 — Task End
|
|
82
74
|
|
|
83
75
|
Always close the session with `reasoning_complete_session`:
|
|
84
76
|
|
|
85
|
-
- `conclusion`: the
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
`
|
|
77
|
+
- `conclusion`: the answer or decision, written to be reused. Its first
|
|
78
|
+
sentence states the subject and the outcome; dates, sources and caveats come
|
|
79
|
+
after, because a recall snippet always shows the start. State the key
|
|
80
|
+
decisions and the options you rejected, with reasons. Required even when
|
|
81
|
+
abandoning — one line saying why is enough.
|
|
82
|
+
- A conclusion that waits on the user is not final. When the answer comes,
|
|
83
|
+
record it: update the pending memory with `memory_update`, or flag it stale
|
|
84
|
+
and let the new session's conclusion replace it.
|
|
85
|
+
- `used_memory_ids`: ids of recalled memories that genuinely helped. Report
|
|
86
|
+
honestly, including none.
|
|
87
|
+
- Flag a memory with `memory_record_usage_feedback(usefulness='stale')` the
|
|
88
|
+
moment either happens:
|
|
89
|
+
- a recalled memory contradicts what you just verified in code or data and
|
|
90
|
+
you are not correcting it with `memory_update`;
|
|
91
|
+
- a decision you just recorded supersedes an older or pending memory.
|
|
92
|
+
- Saving is opt-in: pass `save_as_memory=true` or `memory_mode='always'`; the
|
|
93
|
+
default (`auto`) does not save. Save when the conclusion would help a future
|
|
94
|
+
task; otherwise skip with `memory_mode='never'` (requires
|
|
95
|
+
`not_saved_reason`). This is the only way to create a memory.
|
|
96
|
+
`memory_tags`: tags describe topics ('sqlite', 'auth'), not projects.
|
|
97
|
+
- Leave `memory_type` and `memory_importance` at their defaults, except
|
|
98
|
+
`memory_type='preference'` for a user preference that applies across
|
|
99
|
+
projects — the only type recall treats differently.
|
|
100
|
+
- Dropped without a real conclusion? Complete with `status='abandoned'`.
|
|
105
101
|
|
|
106
102
|
## Tool Reference
|
|
107
103
|
|
|
108
|
-
- `get_usage_guide`:
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
- `
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
- `memory_list`: recent or filtered browsing (when browsing beats searching)
|
|
119
|
-
- `memory_get`: fetch one memory by exact id
|
|
120
|
-
- `memory_update`: correct an existing memory in place
|
|
121
|
-
- `memory_delete`: remove unsafe, duplicated, or wrong memory
|
|
122
|
-
- `memory_record_usage_feedback`: record how a recalled memory turned out
|
|
123
|
-
(`used`, `ignored`, `irrelevant`, `stale`, `unsafe_to_use`) — prefer
|
|
124
|
-
`used_memory_ids` at completion for the common case; use this tool directly
|
|
125
|
-
for no-session tasks and for non-`used` reports
|
|
126
|
-
|
|
127
|
-
Reasoning traces:
|
|
128
|
-
|
|
129
|
-
- `reasoning_start_session` / `reasoning_add_step` / `reasoning_complete_session`:
|
|
130
|
-
the core loop described above
|
|
131
|
-
- `reasoning_get_trace`: replay a session's full ordered trace
|
|
132
|
-
- `reasoning_list_sessions`: find past sessions before retrieving a trace
|
|
133
|
-
|
|
134
|
-
Audit & reports (mostly for reviewers and operators, not everyday tasks):
|
|
135
|
-
|
|
136
|
-
- `reasoning_mark_step`, `reasoning_list_milestones`,
|
|
137
|
-
`reasoning_get_session_outline`, `reasoning_search_steps`: navigate traces
|
|
138
|
-
by their pivotal moments
|
|
139
|
-
- `memory_usage_report`, `memory_adoption_report`, `memory_agent_scorecard`:
|
|
140
|
-
telemetry-backed views of how memory/reasoning is actually being used
|
|
141
|
-
- Telemetry note: `MEMORY_TELEMETRY` is a server-side env var (`on`/`off`,
|
|
142
|
-
default `off`); agents cannot change it. Successful usage feedback and
|
|
143
|
-
session data are always recorded locally regardless of the setting — only
|
|
144
|
-
the full funnels and ratios in the reports above need `MEMORY_TELEMETRY=on`.
|
|
104
|
+
- `get_usage_guide`: this guide.
|
|
105
|
+
- `reasoning_start_session`, `reasoning_add_step`,
|
|
106
|
+
`reasoning_complete_session`: the core loop above.
|
|
107
|
+
- `reasoning_find`: find past sessions (`query`) or read one (`session_id`).
|
|
108
|
+
- `memory_search`, `memory_get`: recall beyond the title; read one memory.
|
|
109
|
+
- `memory_update`: correct a memory.
|
|
110
|
+
- `memory_record_usage_feedback`: report a stale or unsafe memory, or a use
|
|
111
|
+
outside a session.
|
|
112
|
+
- `MEMORY_TELEMETRY` is a server-side env var (default `off`) that agents
|
|
113
|
+
cannot change. Usage feedback and session data are always recorded locally.
|
|
145
114
|
|
|
146
115
|
## Do Not Store
|
|
147
116
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
secrets are banned everywhere.
|
|
117
|
+
Applies to conclusions saved as memory. Steps may summarize tool output
|
|
118
|
+
briefly, but secrets are banned everywhere.
|
|
151
119
|
|
|
152
120
|
- secrets, tokens, or credentials
|
|
153
121
|
- full hidden chain-of-thought
|
|
154
122
|
- transient debugging noise
|
|
155
123
|
- raw tool dumps with no durable value
|
|
156
|
-
|
|
157
|
-
## Rule Of Thumb
|
|
158
|
-
|
|
159
|
-
- durable reusable knowledge -> `memory_*`
|
|
160
|
-
- live multi-step task trace -> `reasoning_*`
|
|
161
|
-
- when in doubt, skip storage unless the information will help a future agent
|
|
162
|
-
or future run
|
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@ told, and you maintain nothing.
|
|
|
11
11
|
Long-term memory and reasoning traces for AI agents.
|
|
12
12
|
|
|
13
13
|
- **Durable memory** across tasks and sessions (SQLite + full-text search)
|
|
14
|
-
- **Reasoning traces**: per-task step-by-step records you can search
|
|
14
|
+
- **Reasoning traces**: per-task step-by-step records you can search
|
|
15
15
|
- **Auto-recall**: starting a session automatically surfaces related memories
|
|
16
16
|
- **Self-cleaning**: stale sessions are auto-abandoned instead of piling up
|
|
17
17
|
|
|
@@ -44,8 +44,7 @@ reasoning_start_session title: "checkout intermittently times out under load"
|
|
|
44
44
|
```
|
|
45
45
|
|
|
46
46
|
No one asked it to search. The Tuesday conclusion surfaces on its own, with its
|
|
47
|
-
origin attached — and `
|
|
48
|
-
how it was reached.
|
|
47
|
+
origin attached — and `reasoning_find(source.session_id)` replays exactly how it was reached.
|
|
49
48
|
|
|
50
49
|
## Why this one?
|
|
51
50
|
|
|
@@ -56,14 +55,10 @@ makes the right behavior the default behavior:
|
|
|
56
55
|
| | typical memory MCP | this server |
|
|
57
56
|
| --- | --- | --- |
|
|
58
57
|
| Recall | agent must remember to search | server auto-recalls related memories at session start |
|
|
59
|
-
| Reasoning traces | — | first-class sessions with steps,
|
|
58
|
+
| Reasoning traces | — | first-class sessions with steps, searchable later with `reasoning_find` |
|
|
60
59
|
| Stale state | grows forever | stale sessions auto-abandoned (configurable TTL) |
|
|
61
60
|
|
|
62
|
-
For
|
|
63
|
-
layer (`MEMORY_TELEMETRY=on`) with usage reports, an adoption funnel, and
|
|
64
|
-
per-agent scorecards to compare how each persona actually uses memory. If you
|
|
65
|
-
run a single agent for yourself, you can ignore it — everything above works
|
|
66
|
-
without it.
|
|
61
|
+
For operators, an opt-in telemetry layer (`MEMORY_TELEMETRY=on`) records diagnostics events locally in `tool_usage_events` for SQL inspection. If you run a single agent for yourself, you can ignore it — everything above works without it.
|
|
67
62
|
|
|
68
63
|
## Quick Install
|
|
69
64
|
|
|
@@ -101,7 +96,7 @@ args = ["-y", "@nhatnguyen9317/memory-mcp-server"]
|
|
|
101
96
|
```
|
|
102
97
|
|
|
103
98
|
Verify the connection by calling a cheap read-only tool such as `get_usage_guide`
|
|
104
|
-
or `
|
|
99
|
+
or `memory_search`.
|
|
105
100
|
|
|
106
101
|
## Requirements
|
|
107
102
|
|
|
@@ -122,16 +117,12 @@ or `memory_list`.
|
|
|
122
117
|
(`MEMORY_SESSION_TTL_HOURS`, default 24).
|
|
123
118
|
2. **During the task** — the agent logs decisions and observations with
|
|
124
119
|
`reasoning_add_step` (single, or up to 20 steps per call in batch mode),
|
|
125
|
-
|
|
120
|
+
so later sessions can recover the work with `reasoning_find`.
|
|
126
121
|
3. **Task end** — `reasoning_complete_session` records the conclusion,
|
|
127
122
|
optionally saves it as durable memory, and accepts `used_memory_ids` so the
|
|
128
123
|
server learns which recalled memories actually helped. This usage feedback
|
|
129
124
|
is a local learning signal and is always recorded, regardless of the
|
|
130
125
|
telemetry setting.
|
|
131
|
-
4. **Optional, for multi-agent operators** — with `MEMORY_TELEMETRY=on`,
|
|
132
|
-
`memory_adoption_report` shows the funnel (sessions → completions → saves →
|
|
133
|
-
recalls → reuse) with risk flags, and `memory_agent_scorecard` compares
|
|
134
|
-
agent personas' habits and suggests corrections.
|
|
135
126
|
|
|
136
127
|
Agents learn the rules at runtime by calling `get_usage_guide`, which returns
|
|
137
128
|
the versioned [GUIDELINES.md](./GUIDELINES.md).
|
|
@@ -143,8 +134,8 @@ the versioned [GUIDELINES.md](./GUIDELINES.md).
|
|
|
143
134
|
| `MEMORY_DB_PATH` | `~/.memory-mcp-server/memory.db` | SQLite database location |
|
|
144
135
|
| `MEMORY_SESSION_TTL_HOURS` | `24` | Auto-abandon in_progress sessions older than this (`0` disables) |
|
|
145
136
|
| `MEMORY_AUTO_RECALL_LIMIT` | `3` | Max related memories returned at session start (`0` disables) |
|
|
146
|
-
| `MEMORY_WORKSPACE` | current working directory | Pins the workspace identity stamped on saved memories and used at recall time. Default: the server's working directory — but `/` and your home directory count as "unknown project". Agents should pass `workspace` (their project path) to `reasoning_start_session
|
|
147
|
-
| `MEMORY_TELEMETRY` | `off` | Set `on` to record diagnostics events locally (searches, saves, recalls, latency)
|
|
137
|
+
| `MEMORY_WORKSPACE` | current working directory | Pins the workspace identity stamped on saved memories and used at recall time. Default: the server's working directory — but `/` and your home directory count as "unknown project". Agents should pass `workspace` (their project path) to `reasoning_start_session`; that overrides this |
|
|
138
|
+
| `MEMORY_TELEMETRY` | `off` | Set `on` to record diagnostics events locally (searches, saves, recalls, latency) for SQL inspection. Usage feedback (`used_memory_ids`, `memory_record_usage_feedback`) is a learning signal, not diagnostics: it is always recorded locally, with this flag on or off |
|
|
148
139
|
|
|
149
140
|
### Shared vs project-scoped memory
|
|
150
141
|
|
|
@@ -200,10 +191,11 @@ whether the task looks like it needs memory.
|
|
|
200
191
|
|
|
201
192
|
- Non-trivial task (multi-step, debugging, planning, trade-offs)?
|
|
202
193
|
`reasoning_start_session` first — review the `related_memories` it
|
|
203
|
-
returns before working; if one carries a `source`,
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
194
|
+
returns before working; if one carries a `source`, read that session
|
|
195
|
+
with `reasoning_find(session_id)`. When the user refers to earlier work
|
|
196
|
+
you don't have, `reasoning_find(query)` finds it.
|
|
197
|
+
- Log steps with `reasoning_add_step` (batch mode is fine): what you
|
|
198
|
+
checked, what you found, what you decided and why.
|
|
207
199
|
- Always close with `reasoning_complete_session`; report helpful memories via
|
|
208
200
|
`used_memory_ids`; pass `save_as_memory=true` for durable conclusions.
|
|
209
201
|
- Never store secrets, tokens, or raw sensitive data.
|
|
@@ -216,15 +208,9 @@ whether the task looks like it needs memory.
|
|
|
216
208
|
|
|
217
209
|
| Tool | Purpose |
|
|
218
210
|
| --- | --- |
|
|
219
|
-
| `memory_save` | Save a durable memory |
|
|
220
211
|
| `memory_search` | Search memory content and tags |
|
|
221
|
-
| `memory_list` | Browse memories with filters |
|
|
222
212
|
| `memory_get` | Fetch one memory by id |
|
|
223
213
|
| `memory_update` | Update an existing memory |
|
|
224
|
-
| `memory_delete` | Delete a memory |
|
|
225
|
-
| `memory_usage_report` | Aggregate tool usage telemetry |
|
|
226
|
-
| `memory_adoption_report` | Adoption funnel + risk flags |
|
|
227
|
-
| `memory_agent_scorecard` | Compare agent usage patterns |
|
|
228
214
|
| `memory_record_usage_feedback` | Record whether recalled memory was useful |
|
|
229
215
|
| `get_usage_guide` | Return the runtime usage guide |
|
|
230
216
|
|
|
@@ -234,18 +220,21 @@ whether the task looks like it needs memory.
|
|
|
234
220
|
| --- | --- |
|
|
235
221
|
| `reasoning_start_session` | Open a session (auto-recall + stale cleanup) |
|
|
236
222
|
| `reasoning_add_step` | Append one step or a batch of steps |
|
|
237
|
-
| `
|
|
238
|
-
| `reasoning_list_sessions` | List sessions with step counts |
|
|
239
|
-
| `reasoning_mark_step` | Add/update an audit mark on a step |
|
|
240
|
-
| `reasoning_search_steps` | Search reasoning steps |
|
|
241
|
-
| `reasoning_list_milestones` | List marked steps across sessions |
|
|
242
|
-
| `reasoning_get_session_outline` | Marked steps or deterministic outline |
|
|
223
|
+
| `reasoning_find` | Find past sessions by query, or read one session's full trace |
|
|
243
224
|
| `reasoning_complete_session` | Close a session; optional memory save + usage feedback |
|
|
244
225
|
|
|
226
|
+
<!-- REMOVED_1_4_0_START -->
|
|
227
|
+
> Removed in 1.4.0: `memory_save`, `memory_list`, `memory_delete`,
|
|
228
|
+
> `memory_usage_report`, `memory_adoption_report`, `memory_agent_scorecard`,
|
|
229
|
+
> `reasoning_get_trace`, `reasoning_list_sessions`, `reasoning_search_steps`,
|
|
230
|
+
> `reasoning_list_milestones`, `reasoning_get_session_outline`,
|
|
231
|
+
> `reasoning_mark_step`. See `CHANGELOG.md`.
|
|
232
|
+
<!-- REMOVED_1_4_0_END -->
|
|
233
|
+
|
|
245
234
|
## Storage Model
|
|
246
235
|
|
|
247
236
|
Tables: `memories`, `reasoning_sessions`, `reasoning_steps`,
|
|
248
|
-
`
|
|
237
|
+
`tool_usage_events`, `schema_migrations` — plus FTS5
|
|
249
238
|
indexes `memories_fts` and `reasoning_steps_fts`.
|
|
250
239
|
|
|
251
240
|
Migrations run automatically at server startup; upgrading the package never
|
|
@@ -262,7 +251,7 @@ npm run dev # tsx watch src/index.ts
|
|
|
262
251
|
|
|
263
252
|
- `src/db.ts` owns DB open and migration bootstrap
|
|
264
253
|
- `src/tools/memory.ts` owns memory tool handlers
|
|
265
|
-
- `src/tools/reasoning.ts` owns reasoning
|
|
254
|
+
- `src/tools/reasoning.ts` owns reasoning tool handlers
|
|
266
255
|
- `src/tools/usage-guide.ts` owns `get_usage_guide`
|
|
267
256
|
|
|
268
257
|
See [CHANGELOG.md](./CHANGELOG.md) for release history.
|
package/dist/constants.js
CHANGED
|
@@ -2,7 +2,7 @@ import path from "node:path";
|
|
|
2
2
|
import os from "node:os";
|
|
3
3
|
/** Max characters returned in a single tool response before truncation. */
|
|
4
4
|
export const CHARACTER_LIMIT = 25000;
|
|
5
|
-
export const MCP_VERSION = "1.
|
|
5
|
+
export const MCP_VERSION = "1.4.0";
|
|
6
6
|
/**
|
|
7
7
|
* Diagnostics-event recording is opt-in: set MEMORY_TELEMETRY=on to enable.
|
|
8
8
|
* Read at call time so tests and long-lived processes can toggle it.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
// reasoning_mark_step and every reader of marks were removed in 1.4.0;
|
|
2
|
+
// unread data is deleted, not kept (AGENTS.md Tool Surface Policy).
|
|
3
|
+
export const migration0007DropReasoningStepMarks = {
|
|
4
|
+
version: "0007_drop_reasoning_step_marks",
|
|
5
|
+
apply(db) {
|
|
6
|
+
db.exec(`DROP TABLE IF EXISTS reasoning_step_marks;`);
|
|
7
|
+
},
|
|
8
|
+
};
|
|
9
|
+
//# sourceMappingURL=0007_drop_reasoning_step_marks.js.map
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
// Which memories reasoning_start_session recalled, as a JSON array (WI-18).
|
|
2
|
+
// NULL = not recorded (pre-1.4.0) or nothing recalled.
|
|
3
|
+
export const migration0008SessionRecalledMemoryIds = {
|
|
4
|
+
version: "0008_session_recalled_memory_ids",
|
|
5
|
+
apply(db) {
|
|
6
|
+
db.exec(`ALTER TABLE reasoning_sessions ADD COLUMN recalled_memory_ids TEXT;`);
|
|
7
|
+
},
|
|
8
|
+
};
|
|
9
|
+
//# sourceMappingURL=0008_session_recalled_memory_ids.js.map
|
package/dist/migrations/index.js
CHANGED
|
@@ -5,6 +5,8 @@ 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
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";
|
|
8
10
|
const migrations = [
|
|
9
11
|
migration0001Initial,
|
|
10
12
|
migration0002ReasoningStepMarks,
|
|
@@ -12,6 +14,8 @@ const migrations = [
|
|
|
12
14
|
migration0004ToolUsageEvents,
|
|
13
15
|
migration0005MemoryWorkspace,
|
|
14
16
|
migration0006WorkspaceIdentity,
|
|
17
|
+
migration0007DropReasoningStepMarks,
|
|
18
|
+
migration0008SessionRecalledMemoryIds,
|
|
15
19
|
];
|
|
16
20
|
export function runMigrations(db) {
|
|
17
21
|
db.exec(`
|