@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 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-07-18.v7
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 first:
13
- - Trivial one-step lookup: do NOT open a reasoning session and do NOT call
14
- memory tools unless prior recall is genuinely needed. Stop here.
15
- (Examples: read one config value, answer a question from context you
16
- already have.)
17
- - Anything multi-step, uncertain, or involving debugging, planning, review,
18
- or trade-offs: call `reasoning_start_session` with a specific title.
19
- (Examples: any bug hunt, any change touching more than one file.)
20
- The title doubles as the recall query — favor concrete keywords
21
- (component, module, error names) over generic phrasing.
22
- 2. Read what the server hands back — this is free recall, act on it:
23
- - `related_memories`: saved knowledge matched to your title, ranked by
24
- text relevance and biased toward your current workspace. Weak one-word
25
- matches are filtered out, so an empty or short list is normal. Review
26
- the snippets before working; fetch full content
27
- with `memory_get` if needed. Entries persisted from a past reasoning
28
- session carry a `source` field (`{session_id, session_title, created_at}`)
29
- — when you need to verify how a conclusion was reached, replay its origin
30
- with `reasoning_get_trace(source.session_id)`. Remember which ones
31
- actually help — you will report them at completion.
32
- If `related_memories` has 2 or more entries, do not act on the first one
33
- blindly: skim all the snippets for contradictions before proceeding.
34
- - Agree or don't overlap → use the most relevant one(s) directly.
35
- - Conflict, or you're unsure → call
36
- `reasoning_get_trace(source.session_id)` on the newer, same-workspace
37
- one *before* deciding, not after. Once resolved, clean up the losing
38
- memory with `memory_update` or `memory_delete`.
39
- - `open_sessions_warning` / `open_sessions`: sessions left in_progress.
40
- Close the ones YOU opened and finished with
41
- `reasoning_complete_session`. Leave sessions you don't recognize alone —
42
- they may belong to another agent or a parallel run; stale ones are
43
- auto-abandoned by the server. A completed or abandoned session cannot be
44
- reopened: to resume interrupted work, start a new session and reference
45
- the old one in the title or an early step.
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`; `reasoning_mark_step`
53
- instead takes the `step_id` returned by `reasoning_add_step`.
54
-
55
- - Log decisions, hypotheses, rejected options, conflicts, and meaningful
56
- observations with `reasoning_add_step`. Routine mechanical actions do not
57
- need steps. Within a step: `thought` = your reasoning, `action` = what you
58
- did, `observation` = what resulted — fill whichever apply (at least one).
59
- - Prefer batch mode when it lowers friction: `reasoning_add_step` with
60
- `steps: [{thought/action/observation}, ...]` logs up to 20 steps in one
61
- call — ideal for recording a stretch of work you just finished instead of
62
- pausing after every step. A post-hoc trace is far better than an empty one.
63
- - Mark pivotal steps with `reasoning_mark_step` in the same turn you log
64
- them with `reasoning_add_step` — don't defer it, deferred marks get
65
- forgotten. Call it whenever the step you just logged was any of: a choice
66
- between alternatives (`decision`), an option you rejected (`decision`),
67
- a genuine contradiction you found (`conflict`), an unverified guess you're
68
- about to test (`hypothesis`), or a result that changed the direction of the
69
- task (`milestone`). If none of these apply, skip it — not every step needs
70
- a mark.
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 actual answer/decision, written to be reusable. Required
77
- even when abandoning — one line stating why the task was dropped is enough.
78
- - `used_memory_ids`: ids of memories (e.g. from `related_memories`) that
79
- genuinely helped. Report honestly, including reporting none. This is the
80
- "used" feedback path when you have a session; call
81
- `memory_record_usage_feedback` directly instead when there is no session to
82
- close, or the moment you discover a recalled memory is stale or wrong. A
83
- failed report (e.g. an unknown memory id) returns a warning and is not
84
- recorded.
85
- - Saving the conclusion as durable memory is opt-in: pass
86
- `save_as_memory=true` or `memory_mode='always'`. The default (`auto`) does
87
- NOT save on its own. Save when the conclusion would help a future task;
88
- skip with `memory_mode='never'` (requires `not_saved_reason`) when it is
89
- one-off noise.
90
- - When persisting, pick a `memory_type` (`fact`, `preference`, `episodic`,
91
- `decision`, `reasoning_summary`) and a `memory_importance` (1–5 scale;
92
- anchors: 5 = convention or decision affecting every task in the workspace,
93
- 3 = reusable pattern within one area, 1 = minor context note).
94
- - If the task was dropped without a real conclusion, complete with
95
- `status='abandoned'` instead of leaving the session open.
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`: returns this guide (with its version) at runtime
100
-
101
- Durable memory:
102
-
103
- - `memory_save`: store durable facts, decisions, preferences, or summaries.
104
- Tags describe topics ('sqlite', 'auth', 'perf'), not locations — do not put
105
- workspace or project names in tags; the server records the workspace
106
- automatically and prefers same-workspace memories at recall time
107
- - `memory_search`: targeted recall by keyword, topic, or hypothesis
108
- - `memory_list`: recent or filtered browsing (when browsing beats searching)
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
- This list applies to durable memory — `memory_save` and conclusions persisted
139
- via `save_as_memory`. Reasoning steps may summarize tool output briefly, but
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 and audit
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 `reasoning_get_trace(source.session_id)` replays exactly
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, marks, outlines |
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 teams running **multiple agent personas**, there is also an opt-in telemetry
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 `memory_list`.
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 — best text match first, current
119
- workspace preferred, weak one-word matches filtered out — warns about
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
- and can mark pivotal steps for later audit.
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 | Workspace identity stamped on saved memories and used to prefer same-workspace results at recall time. The default works out of the box for clients that launch the server inside the project (Claude Code, Codex); set explicitly if yours doesn't |
146
- | `MEMORY_TELEMETRY` | `off` | Set `on` to record diagnostics events locally (searches, saves, recalls, latency) — required for full data in the report tools (`memory_usage_report`, `memory_adoption_report`, `memory_agent_scorecard`). 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 |
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`, you can replay its
200
- origin with `reasoning_get_trace`.
201
- - Log meaningful steps with `reasoning_add_step` (batch mode `steps: [...]`
202
- is fine for recording finished work).
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
- | `reasoning_get_trace` | Return the full ordered trace |
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
- `reasoning_step_marks`, `tool_usage_events`, `schema_migrations` — plus FTS5
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 and audit tool handlers
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.3.2";
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. Claude Code/Codex launch the MCP
35
- * server inside the project directory, so cwd identifies the project;
36
- * MEMORY_WORKSPACE pins it explicitly when a client launches elsewhere.
37
- * Read at call time (same pattern as isTelemetryEnabled) for testability.
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 ?? process.cwd();
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