@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 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-05.v8
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
- Also pass `workspace` — the absolute path of the project directory you
23
- are working in. The server's own working directory is often `/` or your
24
- home directory when a desktop app launched it; those count as "unknown
25
- project" and turn project scoping off. If the response shows
26
- `workspace: null` with a `workspace_warning`, pass `workspace` on this
27
- and later calls (`reasoning_start_session`, `memory_save`).
28
- 2. Read what the server hands back — this is free recall, act on it:
29
- - `related_memories`: saved knowledge matched to your title, ranked by
30
- a blend of term coverage, text relevance, workspace and recency.
31
- Memories from other projects appear only when they match nearly your
32
- whole title (user `preference` memories are the exception). Weak matches
33
- are filtered out, so an empty list is normal — do not pad the title just
34
- to get results. Review
35
- the snippets before working; fetch full content
36
- with `memory_get` if needed. Entries persisted from a past reasoning
37
- session carry a `source` field (`{session_id, session_title, created_at}`)
38
- — when you need to verify how a conclusion was reached, replay its origin
39
- with `reasoning_get_trace(source.session_id)`. Remember which ones
40
- actually help — you will report them at completion.
41
- If `related_memories` has 2 or more entries, do not act on the first one
42
- blindly: skim all the snippets for contradictions before proceeding.
43
- - Agree or don't overlap → use the most relevant one(s) directly.
44
- - Conflict, or you're unsure → call
45
- `reasoning_get_trace(source.session_id)` on the newer, same-workspace
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`; `reasoning_mark_step`
62
- instead takes the `step_id` returned by `reasoning_add_step`.
63
-
64
- - Log decisions, hypotheses, rejected options, conflicts, and meaningful
65
- observations with `reasoning_add_step`. Routine mechanical actions do not
66
- need steps. Within a step: `thought` = your reasoning, `action` = what you
67
- did, `observation` = what resulted — fill whichever apply (at least one).
68
- - Prefer batch mode when it lowers friction: `reasoning_add_step` with
69
- `steps: [{thought/action/observation}, ...]` logs up to 20 steps in one
70
- call — ideal for recording a stretch of work you just finished instead of
71
- pausing after every step. A post-hoc trace is far better than an empty one.
72
- - Mark pivotal steps with `reasoning_mark_step` in the same turn you log
73
- them with `reasoning_add_step` — don't defer it, deferred marks get
74
- forgotten. Call it whenever the step you just logged was any of: a choice
75
- between alternatives (`decision`), an option you rejected (`decision`),
76
- a genuine contradiction you found (`conflict`), an unverified guess you're
77
- about to test (`hypothesis`), or a result that changed the direction of the
78
- task (`milestone`). If none of these apply, skip it — not every step needs
79
- 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.
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 actual answer/decision, written to be reusable. Required
86
- even when abandoning — one line stating why the task was dropped is enough.
87
- - `used_memory_ids`: ids of memories (e.g. from `related_memories`) that
88
- genuinely helped. Report honestly, including reporting none. This is the
89
- "used" feedback path when you have a session; call
90
- `memory_record_usage_feedback` directly instead when there is no session to
91
- close, or the moment you discover a recalled memory is stale or wrong. A
92
- failed report (e.g. an unknown memory id) returns a warning and is not
93
- recorded.
94
- - Saving the conclusion as durable memory is opt-in: pass
95
- `save_as_memory=true` or `memory_mode='always'`. The default (`auto`) does
96
- NOT save on its own. Save when the conclusion would help a future task;
97
- skip with `memory_mode='never'` (requires `not_saved_reason`) when it is
98
- one-off noise.
99
- - When persisting, pick a `memory_type` (`fact`, `preference`, `episodic`,
100
- `decision`, `reasoning_summary`) and a `memory_importance` (1–5 scale;
101
- anchors: 5 = convention or decision affecting every task in the workspace,
102
- 3 = reusable pattern within one area, 1 = minor context note).
103
- - If the task was dropped without a real conclusion, complete with
104
- `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'`.
105
101
 
106
102
  ## Tool Reference
107
103
 
108
- - `get_usage_guide`: returns this guide (with its version) at runtime
109
-
110
- Durable memory:
111
-
112
- - `memory_save`: store durable facts, decisions, preferences, or summaries.
113
- Tags describe topics ('sqlite', 'auth', 'perf'), not locations — do not put
114
- workspace or project names in tags. Pass `workspace` (your project
115
- directory); if omitted the server records its own working directory (never
116
- `/` or the home directory) and prefers same-workspace memories at recall time
117
- - `memory_search`: targeted recall by keyword, topic, or hypothesis
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
- This list applies to durable memory — `memory_save` and conclusions persisted
149
- via `save_as_memory`. Reasoning steps may summarize tool output briefly, but
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 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
 
@@ -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
- and can mark pivotal steps for later audit.
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` / `memory_save`; that overrides this |
147
- | `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 |
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`, you can replay its
204
- origin with `reasoning_get_trace`.
205
- - Log meaningful steps with `reasoning_add_step` (batch mode `steps: [...]`
206
- 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.
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
- | `reasoning_get_trace` | Return the full ordered trace |
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
- `reasoning_step_marks`, `tool_usage_events`, `schema_migrations` — plus FTS5
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 and audit tool handlers
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.3.3";
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
@@ -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(`