@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/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,77 @@
|
|
|
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
|
+
|
|
57
|
+
## 1.3.3 (2026-10-05)
|
|
58
|
+
|
|
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′.
|
|
60
|
+
|
|
61
|
+
### Added
|
|
62
|
+
|
|
63
|
+
- Optional `workspace` input on `reasoning_start_session` and `memory_save`; `reasoning_start_session` returns the resolved `workspace` and a `workspace_warning` when it is unknown.
|
|
64
|
+
- Migration `0006_workspace_identity`: `reasoning_sessions.workspace`; legacy `memories.workspace` values of `/` and the home directory are set to NULL (unknown).
|
|
65
|
+
- Recall eval base (WI-11): a labelled fixture (`src/__tests__/fixtures/recall-eval-cases.ts`) and suite (`src/__tests__/recall-eval.test.ts`) that drive the real `reasoning_start_session` and `memory_search` tools to lock auto-recall and search ranking behavior.
|
|
66
|
+
|
|
67
|
+
### Changed
|
|
68
|
+
|
|
69
|
+
- `getWorkspace` treats `/`, the home directory and empty as unknown instead of as a project.
|
|
70
|
+
- Auto-recall: other projects' non-preference memories need a near-complete title match; `preference` memories bypass that gate; one blended score (coverage 0.45, BM25 0.20, workspace 0.30, recency 0.05) replaces the lexicographic comparator; memories reported `stale`/`unsafe_to_use` are excluded; generic title words (fix, bug, update, …) no longer count as matches.
|
|
71
|
+
- **Behavior change:** `memory_search` matches with OR instead of implicit AND, with the same coverage floor as auto-recall (3+ distinct terms need at least 2 matches; fewer need 1; punctuation-only tokens such as `-` are ignored). Results are ranked by the blended score shared with auto-recall (coverage 0.45, BM25 0.20, recency 0.05, no workspace term), computed in SQL so `limit`/`offset` pagination is stable (ties break on importance, `updated_at`, then id). `RECALL_WEIGHTS` and `RECALL_RECENCY_DAYS` moved to `src/constants.ts`. Compatibility: multi-term queries that previously returned nothing because one term was absent now return partial matches, ranked below full matches.
|
|
72
|
+
- **Behavior change:** the "serendipity lifeline" is removed — when nothing is relevant, `related_memories` is `[]`.
|
|
73
|
+
- `GUIDELINES.md` `2026-07-18.v7` → `2026-10-05.v8`: agents are told to pass `workspace`, and an empty `related_memories` is described as normal.
|
|
74
|
+
|
|
3
75
|
## 1.3.2 (2026-07-18)
|
|
4
76
|
|
|
5
77
|
Theme: guide-contract alignment — `GUIDELINES.md`, tool descriptions, and server instructions now match what the code actually does, locked in by a new docs-consistency test; conflict-check and step-marking guidance tightened from soft suggestions into concrete triggers after live-store telemetry showed near-zero adoption.
|
|
@@ -17,7 +89,7 @@ Theme: guide-contract alignment — `GUIDELINES.md`, tool descriptions, and serv
|
|
|
17
89
|
|
|
18
90
|
### Notes
|
|
19
91
|
|
|
20
|
-
- 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.
|
|
21
93
|
|
|
22
94
|
## 1.3.1 (2026-07-14)
|
|
23
95
|
|
package/GUIDELINES.md
CHANGED
|
@@ -1,152 +1,123 @@
|
|
|
1
1
|
# Memory MCP Guidelines
|
|
2
2
|
|
|
3
|
-
Version: 2026-
|
|
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
|
-
the
|
|
27
|
-
with `memory_get`
|
|
28
|
-
session
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
If
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
the
|
|
46
|
-
3. Only call `memory_search` yourself when you need recall on a topic that is
|
|
47
|
-
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)`.
|
|
48
47
|
|
|
49
48
|
## Moment 2 — During The Task
|
|
50
49
|
|
|
51
50
|
Every `reasoning_add_step` and `reasoning_complete_session` call requires the
|
|
52
|
-
`session_id` returned by `reasoning_start_session
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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.
|
|
71
72
|
|
|
72
73
|
## Moment 3 — Task End
|
|
73
74
|
|
|
74
75
|
Always close the session with `reasoning_complete_session`:
|
|
75
76
|
|
|
76
|
-
- `conclusion`: the
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
`
|
|
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'`.
|
|
96
101
|
|
|
97
102
|
## Tool Reference
|
|
98
103
|
|
|
99
|
-
- `get_usage_guide`:
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
- `
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
- `
|
|
108
|
-
|
|
109
|
-
- `memory_get`: fetch one memory by exact id
|
|
110
|
-
- `memory_update`: correct an existing memory in place
|
|
111
|
-
- `memory_delete`: remove unsafe, duplicated, or wrong memory
|
|
112
|
-
- `memory_record_usage_feedback`: record how a recalled memory turned out
|
|
113
|
-
(`used`, `ignored`, `irrelevant`, `stale`, `unsafe_to_use`) — prefer
|
|
114
|
-
`used_memory_ids` at completion for the common case; use this tool directly
|
|
115
|
-
for no-session tasks and for non-`used` reports
|
|
116
|
-
|
|
117
|
-
Reasoning traces:
|
|
118
|
-
|
|
119
|
-
- `reasoning_start_session` / `reasoning_add_step` / `reasoning_complete_session`:
|
|
120
|
-
the core loop described above
|
|
121
|
-
- `reasoning_get_trace`: replay a session's full ordered trace
|
|
122
|
-
- `reasoning_list_sessions`: find past sessions before retrieving a trace
|
|
123
|
-
|
|
124
|
-
Audit & reports (mostly for reviewers and operators, not everyday tasks):
|
|
125
|
-
|
|
126
|
-
- `reasoning_mark_step`, `reasoning_list_milestones`,
|
|
127
|
-
`reasoning_get_session_outline`, `reasoning_search_steps`: navigate traces
|
|
128
|
-
by their pivotal moments
|
|
129
|
-
- `memory_usage_report`, `memory_adoption_report`, `memory_agent_scorecard`:
|
|
130
|
-
telemetry-backed views of how memory/reasoning is actually being used
|
|
131
|
-
- Telemetry note: `MEMORY_TELEMETRY` is a server-side env var (`on`/`off`,
|
|
132
|
-
default `off`); agents cannot change it. Successful usage feedback and
|
|
133
|
-
session data are always recorded locally regardless of the setting — only
|
|
134
|
-
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.
|
|
135
114
|
|
|
136
115
|
## Do Not Store
|
|
137
116
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
secrets are banned everywhere.
|
|
117
|
+
Applies to conclusions saved as memory. Steps may summarize tool output
|
|
118
|
+
briefly, but secrets are banned everywhere.
|
|
141
119
|
|
|
142
120
|
- secrets, tokens, or credentials
|
|
143
121
|
- full hidden chain-of-thought
|
|
144
122
|
- transient debugging noise
|
|
145
123
|
- raw tool dumps with no durable value
|
|
146
|
-
|
|
147
|
-
## Rule Of Thumb
|
|
148
|
-
|
|
149
|
-
- durable reusable knowledge -> `memory_*`
|
|
150
|
-
- live multi-step task trace -> `reasoning_*`
|
|
151
|
-
- when in doubt, skip storage unless the information will help a future agent
|
|
152
|
-
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
|
|
|
@@ -115,22 +110,19 @@ or `memory_list`.
|
|
|
115
110
|
|
|
116
111
|
1. **Task start** — the agent calls `reasoning_start_session`. The server
|
|
117
112
|
full-text-searches the title against saved memories and returns
|
|
118
|
-
`related_memories` in the response —
|
|
119
|
-
|
|
113
|
+
`related_memories` in the response — ranked by relevance, workspace and
|
|
114
|
+
recency; other projects' memories only when they match nearly the whole
|
|
115
|
+
title; nothing returned when nothing is relevant — warns about
|
|
120
116
|
still-open sessions, and auto-abandons stale ones
|
|
121
117
|
(`MEMORY_SESSION_TTL_HOURS`, default 24).
|
|
122
118
|
2. **During the task** — the agent logs decisions and observations with
|
|
123
119
|
`reasoning_add_step` (single, or up to 20 steps per call in batch mode),
|
|
124
|
-
|
|
120
|
+
so later sessions can recover the work with `reasoning_find`.
|
|
125
121
|
3. **Task end** — `reasoning_complete_session` records the conclusion,
|
|
126
122
|
optionally saves it as durable memory, and accepts `used_memory_ids` so the
|
|
127
123
|
server learns which recalled memories actually helped. This usage feedback
|
|
128
124
|
is a local learning signal and is always recorded, regardless of the
|
|
129
125
|
telemetry setting.
|
|
130
|
-
4. **Optional, for multi-agent operators** — with `MEMORY_TELEMETRY=on`,
|
|
131
|
-
`memory_adoption_report` shows the funnel (sessions → completions → saves →
|
|
132
|
-
recalls → reuse) with risk flags, and `memory_agent_scorecard` compares
|
|
133
|
-
agent personas' habits and suggests corrections.
|
|
134
126
|
|
|
135
127
|
Agents learn the rules at runtime by calling `get_usage_guide`, which returns
|
|
136
128
|
the versioned [GUIDELINES.md](./GUIDELINES.md).
|
|
@@ -142,8 +134,8 @@ the versioned [GUIDELINES.md](./GUIDELINES.md).
|
|
|
142
134
|
| `MEMORY_DB_PATH` | `~/.memory-mcp-server/memory.db` | SQLite database location |
|
|
143
135
|
| `MEMORY_SESSION_TTL_HOURS` | `24` | Auto-abandon in_progress sessions older than this (`0` disables) |
|
|
144
136
|
| `MEMORY_AUTO_RECALL_LIMIT` | `3` | Max related memories returned at session start (`0` disables) |
|
|
145
|
-
| `MEMORY_WORKSPACE` | current working directory |
|
|
146
|
-
| `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 |
|
|
147
139
|
|
|
148
140
|
### Shared vs project-scoped memory
|
|
149
141
|
|
|
@@ -152,7 +144,10 @@ the versioned [GUIDELINES.md](./GUIDELINES.md).
|
|
|
152
144
|
memories are stamped with the workspace they were saved from, and recall
|
|
153
145
|
softly prefers the current workspace — cross-project memories still surface
|
|
154
146
|
when they match strongly (that's the point of a shared store), but they no
|
|
155
|
-
longer crowd out local ones.
|
|
147
|
+
longer crowd out local ones. Since v1.3.3 an explicit `workspace` argument
|
|
148
|
+
is honored, `/` and the home directory are treated as unknown, and
|
|
149
|
+
memories from other projects are recalled only on a near-complete title
|
|
150
|
+
match (user preferences excepted).
|
|
156
151
|
- **Project-scoped**: point `MEMORY_DB_PATH` at a file inside the project
|
|
157
152
|
(e.g. `.memory/project-memory.db`) for hard isolation per repository or
|
|
158
153
|
customer.
|
|
@@ -196,10 +191,11 @@ whether the task looks like it needs memory.
|
|
|
196
191
|
|
|
197
192
|
- Non-trivial task (multi-step, debugging, planning, trade-offs)?
|
|
198
193
|
`reasoning_start_session` first — review the `related_memories` it
|
|
199
|
-
returns before working; if one carries a `source`,
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
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.
|
|
203
199
|
- Always close with `reasoning_complete_session`; report helpful memories via
|
|
204
200
|
`used_memory_ids`; pass `save_as_memory=true` for durable conclusions.
|
|
205
201
|
- Never store secrets, tokens, or raw sensitive data.
|
|
@@ -212,15 +208,9 @@ whether the task looks like it needs memory.
|
|
|
212
208
|
|
|
213
209
|
| Tool | Purpose |
|
|
214
210
|
| --- | --- |
|
|
215
|
-
| `memory_save` | Save a durable memory |
|
|
216
211
|
| `memory_search` | Search memory content and tags |
|
|
217
|
-
| `memory_list` | Browse memories with filters |
|
|
218
212
|
| `memory_get` | Fetch one memory by id |
|
|
219
213
|
| `memory_update` | Update an existing memory |
|
|
220
|
-
| `memory_delete` | Delete a memory |
|
|
221
|
-
| `memory_usage_report` | Aggregate tool usage telemetry |
|
|
222
|
-
| `memory_adoption_report` | Adoption funnel + risk flags |
|
|
223
|
-
| `memory_agent_scorecard` | Compare agent usage patterns |
|
|
224
214
|
| `memory_record_usage_feedback` | Record whether recalled memory was useful |
|
|
225
215
|
| `get_usage_guide` | Return the runtime usage guide |
|
|
226
216
|
|
|
@@ -230,18 +220,21 @@ whether the task looks like it needs memory.
|
|
|
230
220
|
| --- | --- |
|
|
231
221
|
| `reasoning_start_session` | Open a session (auto-recall + stale cleanup) |
|
|
232
222
|
| `reasoning_add_step` | Append one step or a batch of steps |
|
|
233
|
-
| `
|
|
234
|
-
| `reasoning_list_sessions` | List sessions with step counts |
|
|
235
|
-
| `reasoning_mark_step` | Add/update an audit mark on a step |
|
|
236
|
-
| `reasoning_search_steps` | Search reasoning steps |
|
|
237
|
-
| `reasoning_list_milestones` | List marked steps across sessions |
|
|
238
|
-
| `reasoning_get_session_outline` | Marked steps or deterministic outline |
|
|
223
|
+
| `reasoning_find` | Find past sessions by query, or read one session's full trace |
|
|
239
224
|
| `reasoning_complete_session` | Close a session; optional memory save + usage feedback |
|
|
240
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
|
+
|
|
241
234
|
## Storage Model
|
|
242
235
|
|
|
243
236
|
Tables: `memories`, `reasoning_sessions`, `reasoning_steps`,
|
|
244
|
-
`
|
|
237
|
+
`tool_usage_events`, `schema_migrations` — plus FTS5
|
|
245
238
|
indexes `memories_fts` and `reasoning_steps_fts`.
|
|
246
239
|
|
|
247
240
|
Migrations run automatically at server startup; upgrading the package never
|
|
@@ -258,7 +251,7 @@ npm run dev # tsx watch src/index.ts
|
|
|
258
251
|
|
|
259
252
|
- `src/db.ts` owns DB open and migration bootstrap
|
|
260
253
|
- `src/tools/memory.ts` owns memory tool handlers
|
|
261
|
-
- `src/tools/reasoning.ts` owns reasoning
|
|
254
|
+
- `src/tools/reasoning.ts` owns reasoning tool handlers
|
|
262
255
|
- `src/tools/usage-guide.ts` owns `get_usage_guide`
|
|
263
256
|
|
|
264
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.
|
|
@@ -30,15 +30,53 @@ export const AUTO_RECALL_LIMIT = Number(process.env.MEMORY_AUTO_RECALL_LIMIT ??
|
|
|
30
30
|
*/
|
|
31
31
|
export const DB_PATH = process.env.MEMORY_DB_PATH ??
|
|
32
32
|
path.join(os.homedir(), ".memory-mcp-server", "memory.db");
|
|
33
|
+
function stripTrailingSeparators(value) {
|
|
34
|
+
let result = value.trim();
|
|
35
|
+
while (result.length > 1 && /[\\/]$/.test(result)) {
|
|
36
|
+
result = result.slice(0, -1);
|
|
37
|
+
}
|
|
38
|
+
return result;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Normalizes a workspace path: trims it and strips trailing separators.
|
|
42
|
+
* Returns null ("unknown") for values that cannot identify a project —
|
|
43
|
+
* empty, "/", and the home directory. Desktop clients launch the server
|
|
44
|
+
* from those, and treating them as a project merges unrelated projects.
|
|
45
|
+
*/
|
|
46
|
+
export function normalizeWorkspace(raw) {
|
|
47
|
+
if (!raw)
|
|
48
|
+
return null;
|
|
49
|
+
const value = stripTrailingSeparators(raw);
|
|
50
|
+
if (value === "" || value === "/")
|
|
51
|
+
return null;
|
|
52
|
+
if (value === stripTrailingSeparators(os.homedir()))
|
|
53
|
+
return null;
|
|
54
|
+
return value;
|
|
55
|
+
}
|
|
33
56
|
/**
|
|
34
|
-
* Workspace identity for memory scoping
|
|
35
|
-
*
|
|
36
|
-
* MEMORY_WORKSPACE
|
|
37
|
-
*
|
|
57
|
+
* Workspace identity for memory scoping, or null when unknown. Precedence:
|
|
58
|
+
* an explicit value passed by the agent (it always knows its project),
|
|
59
|
+
* then MEMORY_WORKSPACE, then process.cwd() — Claude Code/Codex launch the
|
|
60
|
+
* server inside the project, desktop apps often do not. Read at call time
|
|
61
|
+
* (same pattern as isTelemetryEnabled) for testability.
|
|
38
62
|
*/
|
|
39
|
-
export function getWorkspace() {
|
|
40
|
-
return process.env.MEMORY_WORKSPACE
|
|
63
|
+
export function getWorkspace(explicit) {
|
|
64
|
+
return normalizeWorkspace(explicit?.trim() || process.env.MEMORY_WORKSPACE || process.cwd());
|
|
41
65
|
}
|
|
42
66
|
export const DEFAULT_LIST_LIMIT = 20;
|
|
43
67
|
export const MAX_LIST_LIMIT = 200;
|
|
68
|
+
/**
|
|
69
|
+
* Blended auto-recall score weights — see
|
|
70
|
+
* docs/design/2026-10-05-spec-recall-workspace-identity.md §3.4.
|
|
71
|
+
* Relevance (coverage + bm25) is the largest block; workspace only orders
|
|
72
|
+
* candidates that already passed the cross-project gate.
|
|
73
|
+
*/
|
|
74
|
+
export const RECALL_WEIGHTS = {
|
|
75
|
+
coverage: 0.45,
|
|
76
|
+
bm25: 0.2,
|
|
77
|
+
workspace: 0.3,
|
|
78
|
+
recency: 0.05,
|
|
79
|
+
};
|
|
80
|
+
/** recency = 1 / (1 + age_days / RECALL_RECENCY_DAYS). */
|
|
81
|
+
export const RECALL_RECENCY_DAYS = 60;
|
|
44
82
|
//# sourceMappingURL=constants.js.map
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import os from "node:os";
|
|
2
|
+
export const migration0006WorkspaceIdentity = {
|
|
3
|
+
version: "0006_workspace_identity",
|
|
4
|
+
apply(db) {
|
|
5
|
+
db.exec(`ALTER TABLE reasoning_sessions ADD COLUMN workspace TEXT;`);
|
|
6
|
+
// '/' and the home directory never identified a project; they were the
|
|
7
|
+
// server's cwd when a desktop app launched it. NULL = unknown origin.
|
|
8
|
+
db.prepare(`UPDATE memories SET workspace = NULL WHERE workspace = '/' OR workspace = ?`).run(os.homedir());
|
|
9
|
+
},
|
|
10
|
+
};
|
|
11
|
+
//# sourceMappingURL=0006_workspace_identity.js.map
|
|
@@ -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
|