@nhatnguyen9317/memory-mcp-server 1.2.0 → 1.3.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,44 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.3.0 (2026-07-11)
4
+
5
+ Theme: recall that stays right as the store grows — relevance ranking, provenance, and an always-on learning signal.
6
+
7
+ ### Added
8
+
9
+ - **Workspace-aware recall**: memories are stamped with the workspace they were saved from (`MEMORY_WORKSPACE`, defaulting to the server's working directory — which is the project folder under Claude Code/Codex), and auto-recall softly prefers the current workspace: same workspace > unknown/legacy > other workspaces, applied *after* text relevance so strong cross-project matches still win. Migration `0005_memory_workspace` adds the column non-destructively; existing rows rank as neutral. No configuration required.
10
+ - **Recall quality floor**: for titles with 3+ significant words, auto-recall now requires candidates to match at least 2 of them — one-common-word junk ("fix", "service") no longer fills the slots. When nothing clears the floor, recall returns at most one best-effort match instead of three, cutting input-token noise where it hurt most. Short 1–2 word titles behave as before; `memory_search` is unchanged.
11
+ - **Provenance on auto-recall**: memories that were persisted from a reasoning session now carry a `source` field (`{session_id, session_title, created_at}`) in `related_memories`, turning a recalled sentence into a conclusion with an origin — pass `source.session_id` to `reasoning_get_trace` to replay how it was reached. Manually saved memories are unchanged (no `source` field).
12
+ - **Cold-start nudge**: while the memory store is completely empty, `reasoning_start_session` adds one sentence to its text response suggesting `save_as_memory=true` at completion. It disappears forever after the first memory is saved — zero noise for existing stores.
13
+ - README "What it feels like": a two-scene text walkthrough of save-then-auto-recall with provenance. (An animated GIF/asciinema recording of the same scenario is planned but deferred — it needs a human-recorded terminal session.)
14
+
15
+ ### Changed
16
+
17
+ - **Recall and search are now relevance-ranked** (BM25): both auto-recall (`related_memories` on `reasoning_start_session`) and `memory_search` order results by FTS5 text-match quality first, with `importance` and `updated_at` as tie-breaks — previously ordering was importance-first, which let a high-importance but off-topic memory outrank the best match as the store grows. No response shape change, no new configuration; all existing filters (`type`, `agent_id`, `tags`) behave the same.
18
+ - **Usage feedback is now always recorded** (learning signal ≠ diagnostics): `used_memory_ids` on `reasoning_complete_session` and `memory_record_usage_feedback` persist locally regardless of `MEMORY_TELEMETRY`. Feedback is the first-party signal that measures whether recall is actually helping, so it no longer shares a gate with opt-in diagnostics. Only *successful* feedback is exempt — failed feedback attempts (error codes, latency) are diagnostics and stay gated. Everything else (searches, saves, recalls, reports data) stays opt-in via `MEMORY_TELEMETRY=on`. `memory_record_usage_feedback` no longer returns `recorded: false` when telemetry is off. Nothing leaves your machine in either mode.
19
+ - **Report outputs are self-describing about telemetry**: when `MEMORY_TELEMETRY` is off, `memory_usage_report`, `memory_adoption_report`, and `memory_agent_scorecard` include a `telemetry_note` field in their JSON output so empty funnels cannot be mistaken for real zeros.
20
+ - `GUIDELINES.md` bumped to `2026-07-12.v5`: feedback reporting described as always-on for successful feedback; report tools clarified to need `MEMORY_TELEMETRY=on` for full funnels; task-start guidance now teaches the relevance-ranked, workspace-aware recall and the `source` provenance field (replay origins with `reasoning_get_trace`); **tag hygiene** — tags describe topics, not locations: do not put workspace/project names in tags, the server records workspace automatically (also stated in the `memory_save` tool description). The README AGENTS snippet gained the provenance hint.
21
+
22
+ ### Fixed
23
+
24
+ - `memory_adoption_report` and `memory_agent_scorecard` crashed with "ambiguous column name: created_at" when called with `date_from`/`date_to` while session data existed — the session-table filter is now column-qualified in the queries that join `reasoning_steps`. (Pre-existing since 1.2.0, surfaced by the new coverage suite.)
25
+
26
+ ## 1.2.5 (2026-07-11)
27
+
28
+ Theme: cut logging friction and make the docs tell the new story.
29
+
30
+ ### Added
31
+
32
+ - **Batch steps**: `reasoning_add_step` accepts `steps: [{thought?, action?, observation?}, ...]` (max 20) to log several steps in one call — ideal for recording a stretch of finished work instead of pausing after every step. Insertion is atomic (all steps or none) and numbering stays sequential. Single-step calls and their response shape are unchanged.
33
+ - `keywords` in package.json and a registry submission playbook under `docs/growth/registry-submissions.md`.
34
+
35
+ ### Changed
36
+
37
+ - **Telemetry is now opt-in**: `MEMORY_TELEMETRY` defaults to **off**; set `MEMORY_TELEMETRY=on` to record usage events locally. The report tools (`memory_usage_report`, `memory_adoption_report`, `memory_agent_scorecard`) only have data when it is on, and usage feedback is only persisted when it is on. Core features — auto-recall, stale-session cleanup, batch steps, memory CRUD — work fully without it. Rationale: telemetry serves operators who run multiple agent personas and study their behavior; for single-agent users it was overhead with no benefit. If you were relying on the previous default, add `MEMORY_TELEMETRY=on` to your MCP config env.
38
+ - **`memory_record_usage_feedback` degrades softly when telemetry is off**: instead of a hard error, it validates inputs normally and returns `{recorded: false, ...}` with a warning explaining how to enable telemetry. Validation failures (unknown memory id, unverifiable event) still return real errors. The telemetry check now runs after input validation.
39
+ - **GUIDELINES.md rewritten around the task lifecycle** (`2026-07-11.v1`): task start (act on `related_memories`, close forgotten sessions), during (log decisions, batch mode, mark pivotal steps), task end (`used_memory_ids`, opt-in memory save). All 20 tools are now documented in the guide, including the audit and report layers.
40
+ - **README rewritten as a user-facing landing page**: npx quick-install for Claude Code / Claude Desktop / Codex / Cursor / Antigravity, a "why this one" comparison, configuration table, and an updated AGENTS.md snippet matching the v1.2.x lifecycle. Telemetry is presented as an optional operator feature rather than a headline.
41
+
3
42
  ## 1.2.0 (2026-07-10)
4
43
 
5
44
  Theme: close the memory value loop — recall becomes automatic, cleanup becomes automatic, and usefulness becomes measurable.
package/GUIDELINES.md CHANGED
@@ -1,34 +1,98 @@
1
1
  # Memory MCP Guidelines
2
2
 
3
- Version: 2026-07-10.v1
3
+ Version: 2026-07-12.v5
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.
6
7
 
7
- ## Fast Rule
8
+ ## Moment 1 — Task Start
8
9
 
9
- 1. Trivial one-step lookup:
10
- - do not open a reasoning session
11
- - do not use memory tools unless prior recall is actually needed
12
- 2. Single-step factual task where prior context may change the answer:
13
- - use `memory_search` when you have a real keyword or topic
14
- - use `memory_list` only when browsing is better than searching
15
- 3. Non-trivial task with multiple steps, uncertainty, debugging, planning, review, or trade-offs:
16
- - start with `reasoning_start_session` before the main investigation
17
- - add only meaningful steps with `reasoning_add_step`
18
- - finish with `reasoning_complete_session`
19
- - save only durable conclusions
10
+ 1. Decide the task size first:
11
+ - Trivial one-step lookup: do NOT open a reasoning session and do NOT call
12
+ memory tools unless prior recall is genuinely needed. Stop here.
13
+ - Anything multi-step, uncertain, or involving debugging, planning, review,
14
+ or trade-offs: call `reasoning_start_session` with a specific title.
15
+ 2. Read what the server hands back — this is free recall, act on it:
16
+ - `related_memories`: saved knowledge matched to your title, ranked by
17
+ text relevance and biased toward your current workspace. Weak one-word
18
+ matches are filtered out, so an empty or short list is normal. Review
19
+ the snippets before working; fetch full content
20
+ with `memory_get` if needed. Entries persisted from a past reasoning
21
+ session carry a `source` field (`{session_id, session_title, created_at}`)
22
+ — when you need to verify how a conclusion was reached, replay its origin
23
+ with `reasoning_get_trace(source.session_id)`. Remember which ones
24
+ actually help — you will report them at completion.
25
+ - `open_sessions_warning` / `open_sessions`: sessions you (or a previous
26
+ run) forgot to close. Close finished ones with
27
+ `reasoning_complete_session`; stale ones are auto-abandoned by the server.
28
+ 3. Only call `memory_search` yourself when you need recall on a topic that is
29
+ NOT the session title (the server already searched the title for you).
20
30
 
21
- ## Tool Choice
31
+ ## Moment 2 — During The Task
22
32
 
33
+ - Log decisions, hypotheses, rejected options, conflicts, and meaningful
34
+ observations with `reasoning_add_step`. Routine mechanical actions do not
35
+ need steps.
36
+ - Prefer batch mode when it lowers friction: `reasoning_add_step` with
37
+ `steps: [{thought/action/observation}, ...]` logs up to 20 steps in one
38
+ call — ideal for recording a stretch of work you just finished instead of
39
+ pausing after every step. A post-hoc trace is far better than an empty one.
40
+ - Mark pivotal steps with `reasoning_mark_step` (`decision`, `conflict`,
41
+ `hypothesis`, `milestone`, `important`) when a future reviewer would want to
42
+ jump straight to them.
43
+
44
+ ## Moment 3 — Task End
45
+
46
+ Always close the session with `reasoning_complete_session`:
47
+
48
+ - `conclusion`: the actual answer/decision, written to be reusable.
49
+ - `used_memory_ids`: ids of memories (e.g. from `related_memories`) that
50
+ genuinely helped. Report honestly, including reporting none. Successful
51
+ usage feedback is a learning signal for recall quality and is always
52
+ recorded locally, regardless of the `MEMORY_TELEMETRY` setting (failed
53
+ attempts, e.g. an unknown memory id, return a warning and are not recorded).
54
+ - Saving the conclusion as durable memory is opt-in: pass
55
+ `save_as_memory=true` or `memory_mode='always'`. The default (`auto`) does
56
+ NOT save on its own. Save when the conclusion would help a future task;
57
+ skip (optionally with `memory_mode='never'` + `not_saved_reason`) when it is
58
+ one-off noise.
59
+ - If the task was dropped without a real conclusion, complete with
60
+ `status='abandoned'` instead of leaving the session open.
61
+
62
+ ## Tool Reference
63
+
64
+ Durable memory:
65
+
66
+ - `memory_save`: store durable facts, decisions, preferences, or summaries.
67
+ Tags describe topics ('sqlite', 'auth', 'perf'), not locations — do not put
68
+ workspace or project names in tags; the server records the workspace
69
+ automatically and prefers same-workspace memories at recall time
23
70
  - `memory_search`: targeted recall by keyword, topic, or hypothesis
24
- - `memory_list`: recent or filtered browsing
25
- - `memory_get`: fetch one memory when you already know the exact id
26
- - `memory_save`: store durable facts, decisions, preferences, or reasoning summaries
71
+ - `memory_list`: recent or filtered browsing (when browsing beats searching)
72
+ - `memory_get`: fetch one memory by exact id
27
73
  - `memory_update`: correct an existing memory in place
28
74
  - `memory_delete`: remove unsafe, duplicated, or wrong memory
29
- - `reasoning_start_session`: open live trace capture for a non-trivial task
30
- - `reasoning_add_step`: log a decision, hypothesis, rejected option, or meaningful observation
31
- - `reasoning_complete_session`: close the session and optionally persist only the conclusion; the conclusion is saved as a memory only when you pass `save_as_memory=true` or `memory_mode='always'` — the default (`auto`) does not save on its own
75
+ - `memory_record_usage_feedback`: record whether a recalled memory was
76
+ used/ignored/stale — prefer `used_memory_ids` at completion for the common
77
+ case; successful feedback is always persisted locally regardless of
78
+ `MEMORY_TELEMETRY`
79
+
80
+ Reasoning traces:
81
+
82
+ - `reasoning_start_session` / `reasoning_add_step` / `reasoning_complete_session`:
83
+ the core loop described above
84
+ - `reasoning_get_trace`: replay a session's full ordered trace
85
+ - `reasoning_list_sessions`: find past sessions before retrieving a trace
86
+
87
+ Audit & reports (mostly for reviewers and operators, not everyday tasks):
88
+
89
+ - `reasoning_mark_step`, `reasoning_list_milestones`,
90
+ `reasoning_get_session_outline`, `reasoning_search_steps`: navigate traces
91
+ by their pivotal moments
92
+ - `memory_usage_report`, `memory_adoption_report`, `memory_agent_scorecard`:
93
+ telemetry-backed views of how memory/reasoning is actually being used — with
94
+ `MEMORY_TELEMETRY` off (the default) only usage-feedback events and session
95
+ tables have data; full funnels and ratios need `MEMORY_TELEMETRY=on`
32
96
 
33
97
  ## Do Not Store
34
98
 
@@ -41,4 +105,5 @@ This file is the single source of truth for how an agent should use this MCP.
41
105
 
42
106
  - durable reusable knowledge -> `memory_*`
43
107
  - live multi-step task trace -> `reasoning_*`
44
- - when in doubt, skip storage unless the information will help a future agent or future run
108
+ - when in doubt, skip storage unless the information will help a future agent
109
+ or future run
package/README.md CHANGED
@@ -1,185 +1,186 @@
1
1
  # memory-mcp-server
2
2
 
3
- MCP server for agents that need:
3
+ [![npm version](https://img.shields.io/npm/v/%40nhatnguyen9317%2Fmemory-mcp-server)](https://www.npmjs.com/package/@nhatnguyen9317/memory-mcp-server)
4
+ [![CI](https://github.com/ngquocnhat9317/memory-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/ngquocnhat9317/memory-mcp-server/actions/workflows/ci.yml)
5
+ [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
6
+ [![node >= 22.5](https://img.shields.io/badge/node-%3E%3D22.5-brightgreen)](#requirements)
4
7
 
5
- - durable memory across tasks
6
- - per-task reasoning traces
7
- - lightweight audit/review tools over those traces
8
+ **Memory that runs itself** — your agent remembers past work without being
9
+ told, and you maintain nothing.
8
10
 
9
- This server runs over stdio, stores data in SQLite, and is meant to be installed into an MCP client such as Claude Code, Codex, or another MCP-compatible agent.
11
+ Long-term memory and reasoning traces for AI agents.
10
12
 
11
- ## What This MCP Is For
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
15
+ - **Auto-recall**: starting a session automatically surfaces related memories
16
+ - **Self-cleaning**: stale sessions are auto-abandoned instead of piling up
12
17
 
13
- Use this MCP when you want an agent to:
18
+ Runs over stdio. Local only, no network service, no native addon build.
14
19
 
15
- - save stable facts, decisions, and preferences for later reuse
16
- - keep a reasoning session for one concrete task
17
- - search or review prior reasoning traces
18
- - measure memory/reasoning usage through telemetry reports
20
+ ## What it feels like
19
21
 
20
- High-level split:
22
+ **Session 1 — Tuesday.** Your agent debugs a flaky checkout test and closes its
23
+ reasoning session:
21
24
 
22
- - `memory_*` tools: durable recall
23
- - `reasoning_*` tools: live task trace and audit retrieval
24
- - `get_usage_guide`: runtime usage guide an agent can call after connection
25
-
26
- ## Requirements
27
-
28
- - Node.js `>= 22.5.0`
29
- - support for Node's built-in `node:sqlite`
30
-
31
- No native addon build is required.
32
-
33
- > Note: `node:sqlite` is still an experimental Node.js API on Node 22. The server
34
- > works reliably, but Node prints an `ExperimentalWarning` to stderr on startup,
35
- > and the API surface may change between Node releases.
36
-
37
- ## Install
38
-
39
- ```bash
40
- npm install
41
- npm run build
42
25
  ```
43
-
44
- Built entrypoint:
45
-
46
- - `dist/index.js`
47
-
48
- ## Run
49
-
50
- ```bash
51
- npm start
26
+ reasoning_complete_session
27
+ conclusion: "checkout retry logic must reopen the connection before retrying"
28
+ save_as_memory: true
29
+ → memory mem_a1b2… saved
52
30
  ```
53
31
 
54
- or:
32
+ **Session 2 — Friday, fresh context, nobody mentions Tuesday.** The agent starts
33
+ a related task:
55
34
 
56
- ```bash
57
- node dist/index.js
58
35
  ```
59
-
60
- The server runs over stdio and logs the active DB path to stderr on startup.
61
-
62
- ## Practical Setup
63
-
64
- If you are a real user wiring this into Claude Code, Codex, Antigravity, or another MCP client, the normal setup is:
65
-
66
- 1. Build this repo:
67
-
68
- ```bash
69
- npm install
70
- npm run build
36
+ reasoning_start_session title: "checkout intermittently times out under load"
37
+ → related_memories: [
38
+ {
39
+ snippet: "checkout retry logic must reopen the connection before retrying",
40
+ source: { session_title: "diagnose flaky checkout retry logic",
41
+ session_id: "sess_9f3c…", created_at: "…Tue…" }
42
+ }
43
+ ]
71
44
  ```
72
45
 
73
- 2. Register it in your MCP client as a stdio server:
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.
74
49
 
75
- - command: `node`
76
- - args: `["/absolute/path/to/memory-mcp-server/dist/index.js"]`
50
+ ## Why this one?
77
51
 
78
- 3. Optionally set `MEMORY_DB_PATH` if you do not want the default database location.
52
+ Most memory servers store what you save and hope the agent remembers to search.
53
+ In practice agents don't: they write memories nobody ever reads. This server
54
+ makes the right behavior the default behavior:
79
55
 
80
- Default DB path:
56
+ | | typical memory MCP | this server |
57
+ | --- | --- | --- |
58
+ | Recall | agent must remember to search | server auto-recalls related memories at session start |
59
+ | Reasoning traces | — | first-class sessions with steps, marks, outlines |
60
+ | Stale state | grows forever | stale sessions auto-abandoned (configurable TTL) |
81
61
 
82
- - `~/.memory-mcp-server/memory.db`
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.
83
67
 
84
- 4. Restart the MCP client.
68
+ ## Quick Install
85
69
 
86
- 5. Verify the connection with a cheap read-only tool such as:
70
+ ### Claude Code
87
71
 
88
- - `get_usage_guide`
89
- - `memory_list`
72
+ ```bash
73
+ claude mcp add memory -- npx -y @nhatnguyen9317/memory-mcp-server
74
+ ```
90
75
 
91
- ### Example MCP Config
76
+ ### Claude Desktop / Cursor / Antigravity (JSON config)
92
77
 
93
78
  ```json
94
79
  {
95
80
  "mcpServers": {
96
81
  "memory": {
97
- "command": "node",
98
- "args": ["/absolute/path/to/memory-mcp-server/dist/index.js"],
99
- "env": {
100
- "MEMORY_DB_PATH": "/absolute/path/to/memory.db"
101
- }
82
+ "command": "npx",
83
+ "args": ["-y", "@nhatnguyen9317/memory-mcp-server"]
102
84
  }
103
85
  }
104
86
  }
105
87
  ```
106
88
 
107
- ### Shared vs Project-Scoped Memory
89
+ Optionally pin the database location with `"env": {"MEMORY_DB_PATH": "/path/to/memory.db"}`
90
+ (default: `~/.memory-mcp-server/memory.db`).
108
91
 
109
- Shared memory across many repos:
110
-
111
- ```json
112
- {
113
- "env": {
114
- "MEMORY_DB_PATH": "/Users/you/.memory-mcp-server/shared-memory.db"
115
- }
116
- }
117
- ```
92
+ ### Codex CLI (TOML config)
118
93
 
119
- Project-scoped memory:
94
+ Add to `~/.codex/config.toml`:
120
95
 
121
- ```json
122
- {
123
- "env": {
124
- "MEMORY_DB_PATH": "/absolute/path/to/your-project/.memory/project-memory.db"
125
- }
126
- }
96
+ ```toml
97
+ [mcp_servers.memory]
98
+ enabled = true
99
+ command = "npx"
100
+ args = ["-y", "@nhatnguyen9317/memory-mcp-server"]
127
101
  ```
128
102
 
129
- Practical recommendation:
130
-
131
- - use shared memory if you want one agent persona to accumulate knowledge across projects
132
- - use project-scoped memory if you want isolation per repository or customer
133
-
134
- ### How An Agent Learns To Use This MCP
135
-
136
- The human installer reads this `README`.
137
-
138
- The runtime agent usually does not.
139
-
140
- That means:
103
+ Verify the connection by calling a cheap read-only tool such as `get_usage_guide`
104
+ or `memory_list`.
141
105
 
142
- - `README.md` is for the person installing the MCP
143
- - `AGENTS.md` in this repo is for agents working inside this repo
144
- - an agent working in some other repo will usually only see:
145
- - tool names
146
- - tool descriptions
147
- - schemas
148
- - any runtime tool it can call, especially `get_usage_guide`
149
-
150
- If you want a newly connected agent to use this MCP correctly, the most reliable pattern is:
106
+ ## Requirements
151
107
 
152
- 1. install the MCP
153
- 2. add a short instruction snippet to your own repo's `AGENTS.md` or client prompt
154
- 3. tell the agent to call `get_usage_guide` before using memory/reasoning tools the first time
108
+ - Node.js `>= 22.5.0` (for the built-in `node:sqlite` — no native addon build)
155
109
 
156
- ## Suggested AGENTS.md Snippet
110
+ > Note: `node:sqlite` is still an experimental Node.js API on Node 22. The server
111
+ > works reliably, but Node prints an `ExperimentalWarning` to stderr on startup,
112
+ > and the API surface may change between Node releases.
157
113
 
158
- If you want your agent to use this MCP well, you can paste something like this into your own repo's `AGENTS.md`:
114
+ ## How it works
115
+
116
+ 1. **Task start** — the agent calls `reasoning_start_session`. The server
117
+ 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
120
+ still-open sessions, and auto-abandons stale ones
121
+ (`MEMORY_SESSION_TTL_HOURS`, default 24).
122
+ 2. **During the task** — the agent logs decisions and observations with
123
+ `reasoning_add_step` (single, or up to 20 steps per call in batch mode),
124
+ and can mark pivotal steps for later audit.
125
+ 3. **Task end** — `reasoning_complete_session` records the conclusion,
126
+ optionally saves it as durable memory, and accepts `used_memory_ids` so the
127
+ server learns which recalled memories actually helped. This usage feedback
128
+ is a local learning signal and is always recorded, regardless of the
129
+ 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
+
135
+ Agents learn the rules at runtime by calling `get_usage_guide`, which returns
136
+ the versioned [GUIDELINES.md](./GUIDELINES.md).
137
+
138
+ ## Configuration
139
+
140
+ | Env var | Default | Purpose |
141
+ | --- | --- | --- |
142
+ | `MEMORY_DB_PATH` | `~/.memory-mcp-server/memory.db` | SQLite database location |
143
+ | `MEMORY_SESSION_TTL_HOURS` | `24` | Auto-abandon in_progress sessions older than this (`0` disables) |
144
+ | `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 |
147
+
148
+ ### Shared vs project-scoped memory
149
+
150
+ - **Shared** (default path): one agent persona accumulates knowledge across all
151
+ projects. Since v1.3.0 the shared store is workspace-aware by default:
152
+ memories are stamped with the workspace they were saved from, and recall
153
+ softly prefers the current workspace — cross-project memories still surface
154
+ when they match strongly (that's the point of a shared store), but they no
155
+ longer crowd out local ones.
156
+ - **Project-scoped**: point `MEMORY_DB_PATH` at a file inside the project
157
+ (e.g. `.memory/project-memory.db`) for hard isolation per repository or
158
+ customer.
159
+
160
+ ## Teaching your agent to use it
161
+
162
+ The runtime agent never reads this README — it only sees tool names, schemas,
163
+ and whatever it can call. The reliable pattern:
164
+
165
+ 1. Install the MCP (above).
166
+ 2. Paste a short snippet into your own repo's `AGENTS.md` / client prompt:
159
167
 
160
168
  ```md
161
169
  ## Memory MCP
162
170
 
163
171
  When the `memory` MCP server is available:
164
172
 
165
- - On first use, call `get_usage_guide` to load the current usage rules.
166
- - Use `memory_*` tools for durable facts, decisions, and reusable context.
167
- - Use `reasoning_*` tools for multi-step task traces, debugging, or planning.
168
- - Do not store secrets, tokens, or raw sensitive data in memory.
169
- - Prefer `memory_search` for targeted recall and `memory_list` only for browsing.
170
- - Start a `reasoning_start_session` before substantial multi-step investigation, then close it with `reasoning_complete_session`.
173
+ - On first use, call `get_usage_guide` and follow it.
174
+ - Non-trivial task? `reasoning_start_session` first — review the
175
+ `related_memories` it returns before working; if one carries a `source`,
176
+ you can replay its origin with `reasoning_get_trace`.
177
+ - Log meaningful steps with `reasoning_add_step` (batch mode `steps: [...]`
178
+ is fine for recording finished work).
179
+ - Always close with `reasoning_complete_session`; report helpful memories via
180
+ `used_memory_ids`; pass `save_as_memory=true` for durable conclusions.
181
+ - Never store secrets, tokens, or raw sensitive data.
171
182
  ```
172
183
 
173
- Keep that snippet in the repo where the agent actually works. Do not rely on the agent reading this MCP repo.
174
-
175
- ## Do I Need `AGENTS.md` or `CLAUDE.md` In This Repo?
176
-
177
- Usually no.
178
-
179
- - You do not need to edit this repo's `AGENTS.md` just to install the MCP into your own agent.
180
- - You do not need a `CLAUDE.md` here unless you want Claude-specific rules for contributors working inside this MCP repo.
181
- - The useful place for runtime instructions is the user's own repo or client prompt, not this MCP repo.
182
-
183
184
  ## Tool Surface
184
185
 
185
186
  ### Memory tools
@@ -193,77 +194,52 @@ Usually no.
193
194
  | `memory_update` | Update an existing memory |
194
195
  | `memory_delete` | Delete a memory |
195
196
  | `memory_usage_report` | Aggregate tool usage telemetry |
196
- | `memory_adoption_report` | Summarize adoption behavior across memory and reasoning |
197
+ | `memory_adoption_report` | Adoption funnel + risk flags |
197
198
  | `memory_agent_scorecard` | Compare agent usage patterns |
198
199
  | `memory_record_usage_feedback` | Record whether recalled memory was useful |
199
- | `get_usage_guide` | Return the runtime usage guide for this MCP |
200
+ | `get_usage_guide` | Return the runtime usage guide |
200
201
 
201
202
  ### Reasoning tools
202
203
 
203
204
  | Tool | Purpose |
204
205
  | --- | --- |
205
- | `reasoning_start_session` | Open a reasoning session |
206
- | `reasoning_add_step` | Append a thought, action, or observation |
206
+ | `reasoning_start_session` | Open a session (auto-recall + stale cleanup) |
207
+ | `reasoning_add_step` | Append one step or a batch of steps |
207
208
  | `reasoning_get_trace` | Return the full ordered trace |
208
- | `reasoning_list_sessions` | List sessions with grouped step counts |
209
- | `reasoning_mark_step` | Add or update an audit mark on a step |
209
+ | `reasoning_list_sessions` | List sessions with step counts |
210
+ | `reasoning_mark_step` | Add/update an audit mark on a step |
210
211
  | `reasoning_search_steps` | Search reasoning steps |
211
- | `reasoning_list_milestones` | List marked steps without loading a full trace |
212
- | `reasoning_get_session_outline` | Return marked steps or deterministic fallback outline |
213
- | `reasoning_complete_session` | Close a session and optionally save its conclusion as memory |
212
+ | `reasoning_list_milestones` | List marked steps across sessions |
213
+ | `reasoning_get_session_outline` | Marked steps or deterministic outline |
214
+ | `reasoning_complete_session` | Close a session; optional memory save + usage feedback |
214
215
 
215
216
  ## Storage Model
216
217
 
217
- Main tables:
218
-
219
- - `memories`
220
- - `reasoning_sessions`
221
- - `reasoning_steps`
222
- - `reasoning_step_marks`
223
- - `tool_usage_events`
224
- - `schema_migrations`
225
-
226
- FTS tables:
227
-
228
- - `memories_fts`
229
- - `reasoning_steps_fts`
230
-
231
- ## Migrations
218
+ Tables: `memories`, `reasoning_sessions`, `reasoning_steps`,
219
+ `reasoning_step_marks`, `tool_usage_events`, `schema_migrations` — plus FTS5
220
+ indexes `memories_fts` and `reasoning_steps_fts`.
232
221
 
233
- Schema is managed in `src/migrations/`.
234
-
235
- Migrations run automatically at server startup. There is currently no separate manual migration CLI command in this repo.
236
-
237
- If you need migrations applied, start the server normally:
238
-
239
- ```bash
240
- npm start
241
- ```
242
-
243
- or:
244
-
245
- ```bash
246
- node dist/index.js
247
- ```
222
+ Migrations run automatically at server startup; upgrading the package never
223
+ requires manual schema work.
248
224
 
249
225
  ## Development
250
226
 
251
227
  ```bash
252
- npm run dev
253
- npm run build
254
- npm run test
255
- npm run clean
228
+ npm install
229
+ npm run build # tsc -> dist/
230
+ npm test # build + node --test
231
+ npm run dev # tsx watch src/index.ts
256
232
  ```
257
233
 
258
- ## Implementation Notes
259
-
260
234
  - `src/db.ts` owns DB open and migration bootstrap
261
235
  - `src/tools/memory.ts` owns memory tool handlers
262
236
  - `src/tools/reasoning.ts` owns reasoning and audit tool handlers
263
237
  - `src/tools/usage-guide.ts` owns `get_usage_guide`
264
238
 
239
+ See [CHANGELOG.md](./CHANGELOG.md) for release history.
240
+
265
241
  ## Notes
266
242
 
267
- - `node:sqlite` is still experimental in Node and may print an `ExperimentalWarning`
268
- - this is a local stdio MCP server, not a network service
243
+ - Local stdio MCP server, not a network service
269
244
  - `agent_id` is a filtering aid, not a security boundary
245
+ - License: MIT
package/dist/constants.js CHANGED
@@ -2,8 +2,16 @@ 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.2.0";
6
- export const TELEMETRY_ENABLED = process.env.MEMORY_TELEMETRY !== "off";
5
+ export const MCP_VERSION = "1.3.0";
6
+ /**
7
+ * Diagnostics-event recording is opt-in: set MEMORY_TELEMETRY=on to enable.
8
+ * Read at call time so tests and long-lived processes can toggle it.
9
+ * Usage-feedback events are a first-party learning signal and are always
10
+ * recorded regardless of this flag (see recordToolUsageEvent).
11
+ */
12
+ export function isTelemetryEnabled() {
13
+ return process.env.MEMORY_TELEMETRY === "on";
14
+ }
7
15
  /**
8
16
  * Hours after which an untouched in_progress reasoning session is
9
17
  * auto-abandoned on the next reasoning_start_session call.
@@ -22,6 +30,15 @@ export const AUTO_RECALL_LIMIT = Number(process.env.MEMORY_AUTO_RECALL_LIMIT ??
22
30
  */
23
31
  export const DB_PATH = process.env.MEMORY_DB_PATH ??
24
32
  path.join(os.homedir(), ".memory-mcp-server", "memory.db");
33
+ /**
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.
38
+ */
39
+ export function getWorkspace() {
40
+ return process.env.MEMORY_WORKSPACE ?? process.cwd();
41
+ }
25
42
  export const DEFAULT_LIST_LIMIT = 20;
26
43
  export const MAX_LIST_LIMIT = 200;
27
44
  //# sourceMappingURL=constants.js.map
@@ -0,0 +1,10 @@
1
+ export const migration0005MemoryWorkspace = {
2
+ version: "0005_memory_workspace",
3
+ apply(db) {
4
+ db.exec(`
5
+ ALTER TABLE memories ADD COLUMN workspace TEXT;
6
+ CREATE INDEX IF NOT EXISTS idx_memories_workspace ON memories(workspace);
7
+ `);
8
+ },
9
+ };
10
+ //# sourceMappingURL=0005_memory_workspace.js.map