@nhatnguyen9317/memory-mcp-server 1.1.5 → 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 +74 -0
- package/GUIDELINES.md +86 -21
- package/README.md +156 -176
- package/dist/constants.js +30 -2
- package/dist/migrations/0005_memory_workspace.js +10 -0
- package/dist/migrations/index.js +2 -0
- package/dist/schemas/reasoning.js +33 -3
- package/dist/tools/memory.js +78 -50
- package/dist/tools/reasoning.js +259 -31
- package/dist/tools/telemetry.js +9 -2
- package/dist/utils.js +29 -3
- package/package.json +16 -3
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Changelog
|
|
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
|
+
|
|
42
|
+
## 1.2.0 (2026-07-10)
|
|
43
|
+
|
|
44
|
+
Theme: close the memory value loop — recall becomes automatic, cleanup becomes automatic, and usefulness becomes measurable.
|
|
45
|
+
|
|
46
|
+
### Added
|
|
47
|
+
|
|
48
|
+
- **Auto-recall in `reasoning_start_session`**: the response now includes `related_memories` — up to 3 saved memories relevant to the session title (id, type, importance, tags, snippet), matched via full-text search. Configure the limit with `MEMORY_AUTO_RECALL_LIMIT` (default 3, `0` disables). Recall is best-effort: a failed lookup never blocks session creation.
|
|
49
|
+
- **Stale-session cleanup**: `in_progress` sessions untouched for longer than `MEMORY_SESSION_TTL_HOURS` (default 24, `0` disables) are automatically marked `abandoned` (conclusion `auto-abandoned: stale session`) the next time `reasoning_start_session` is called. The response reports `auto_abandoned_sessions` when cleanup happened, and lists up to 5 other still-open sessions under `open_sessions` with an `open_sessions_warning`.
|
|
50
|
+
- **Usage feedback at completion**: `reasoning_complete_session` accepts `used_memory_ids` (string[], max 50) — ids of memories that actually helped during the session. The server records a `used` usage-feedback telemetry event per id; unknown ids produce warnings instead of errors. The response includes `used_memory_feedback_recorded`.
|
|
51
|
+
- **Recall telemetry**: `memory_search` and `memory_list` events now record the returned memory ids (bounded to 20) in `output_shape.memory_ids`, so recalled-but-unused memories become measurable.
|
|
52
|
+
- `CHANGELOG.md`, GitHub Actions CI (`npm test` on Node 22), and direct unit tests for the memory CRUD tools.
|
|
53
|
+
|
|
54
|
+
### Changed
|
|
55
|
+
|
|
56
|
+
- **`memory_record_usage_feedback` verification widened**: `event_id` may now reference any event that recalled the memory — `memory_get`, `memory_search`, or `memory_list` (previously only `memory_get`, which made verified feedback impossible in practice). Feedback without `event_id` is unchanged.
|
|
57
|
+
- **Adoption/scorecard reports** count feedback events regardless of `related_event_id`, so feedback recorded via `reasoning_complete_session` is included.
|
|
58
|
+
- **`memory_record_usage_feedback` output**: returns `{recorded: true, memory_id, usefulness}` instead of an `event_id` field that was always `null`.
|
|
59
|
+
- Documentation now matches actual behavior of `memory_mode='auto'`: it does **not** save a memory on its own; a memory is only created with `save_as_memory=true` or `memory_mode='always'`. (Behavior unchanged — the docs were wrong.) GUIDELINES version bumped to `2026-07-10.v1`.
|
|
60
|
+
- Tag filters (`tags` on search/list) treat `%`, `_`, and `\` literally instead of as SQL LIKE wildcards.
|
|
61
|
+
|
|
62
|
+
### Fixed
|
|
63
|
+
|
|
64
|
+
- Telemetry `not_saved_reason_category` now correctly records `zero_step` for zero-step completions (substring mismatch made it unreachable).
|
|
65
|
+
- Stale internal references to better-sqlite3; two accidentally tracked temp `.db` files removed from git.
|
|
66
|
+
|
|
67
|
+
### Upgrade notes
|
|
68
|
+
|
|
69
|
+
- Existing dangling `in_progress` sessions will be auto-abandoned on your first `reasoning_start_session` after upgrading. This is intended cleanup; set `MEMORY_SESSION_TTL_HOURS=0` before starting the server if you want to keep them open.
|
|
70
|
+
- No schema migration required; the SQLite database is fully compatible.
|
|
71
|
+
|
|
72
|
+
## 1.1.5 and earlier
|
|
73
|
+
|
|
74
|
+
See git history.
|
package/GUIDELINES.md
CHANGED
|
@@ -1,34 +1,98 @@
|
|
|
1
1
|
# Memory MCP Guidelines
|
|
2
2
|
|
|
3
|
-
Version: 2026-07-
|
|
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
|
-
##
|
|
8
|
+
## Moment 1 — Task Start
|
|
8
9
|
|
|
9
|
-
1.
|
|
10
|
-
- do
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
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
|
-
##
|
|
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
|
|
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
|
-
- `
|
|
30
|
-
|
|
31
|
-
|
|
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
|
|
108
|
+
- when in doubt, skip storage unless the information will help a future agent
|
|
109
|
+
or future run
|
package/README.md
CHANGED
|
@@ -1,181 +1,186 @@
|
|
|
1
1
|
# memory-mcp-server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@nhatnguyen9317/memory-mcp-server)
|
|
4
|
+
[](https://github.com/ngquocnhat9317/memory-mcp-server/actions/workflows/ci.yml)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
[](#requirements)
|
|
4
7
|
|
|
5
|
-
|
|
6
|
-
|
|
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
|
-
|
|
11
|
+
Long-term memory and reasoning traces for AI agents.
|
|
10
12
|
|
|
11
|
-
|
|
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
|
-
|
|
18
|
+
Runs over stdio. Local only, no network service, no native addon build.
|
|
14
19
|
|
|
15
|
-
|
|
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
|
-
|
|
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
|
-
## Install
|
|
34
|
-
|
|
35
|
-
```bash
|
|
36
|
-
npm install
|
|
37
|
-
npm run build
|
|
38
25
|
```
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
## Run
|
|
45
|
-
|
|
46
|
-
```bash
|
|
47
|
-
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
|
|
48
30
|
```
|
|
49
31
|
|
|
50
|
-
|
|
32
|
+
**Session 2 — Friday, fresh context, nobody mentions Tuesday.** The agent starts
|
|
33
|
+
a related task:
|
|
51
34
|
|
|
52
|
-
```bash
|
|
53
|
-
node dist/index.js
|
|
54
35
|
```
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
```bash
|
|
65
|
-
npm install
|
|
66
|
-
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
|
+
]
|
|
67
44
|
```
|
|
68
45
|
|
|
69
|
-
|
|
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.
|
|
70
49
|
|
|
71
|
-
|
|
72
|
-
- args: `["/absolute/path/to/memory-mcp-server/dist/index.js"]`
|
|
50
|
+
## Why this one?
|
|
73
51
|
|
|
74
|
-
|
|
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:
|
|
75
55
|
|
|
76
|
-
|
|
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) |
|
|
77
61
|
|
|
78
|
-
-
|
|
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.
|
|
79
67
|
|
|
80
|
-
|
|
68
|
+
## Quick Install
|
|
81
69
|
|
|
82
|
-
|
|
70
|
+
### Claude Code
|
|
83
71
|
|
|
84
|
-
|
|
85
|
-
-
|
|
72
|
+
```bash
|
|
73
|
+
claude mcp add memory -- npx -y @nhatnguyen9317/memory-mcp-server
|
|
74
|
+
```
|
|
86
75
|
|
|
87
|
-
###
|
|
76
|
+
### Claude Desktop / Cursor / Antigravity (JSON config)
|
|
88
77
|
|
|
89
78
|
```json
|
|
90
79
|
{
|
|
91
80
|
"mcpServers": {
|
|
92
81
|
"memory": {
|
|
93
|
-
"command": "
|
|
94
|
-
"args": ["/
|
|
95
|
-
"env": {
|
|
96
|
-
"MEMORY_DB_PATH": "/absolute/path/to/memory.db"
|
|
97
|
-
}
|
|
82
|
+
"command": "npx",
|
|
83
|
+
"args": ["-y", "@nhatnguyen9317/memory-mcp-server"]
|
|
98
84
|
}
|
|
99
85
|
}
|
|
100
86
|
}
|
|
101
87
|
```
|
|
102
88
|
|
|
103
|
-
|
|
89
|
+
Optionally pin the database location with `"env": {"MEMORY_DB_PATH": "/path/to/memory.db"}`
|
|
90
|
+
(default: `~/.memory-mcp-server/memory.db`).
|
|
104
91
|
|
|
105
|
-
|
|
92
|
+
### Codex CLI (TOML config)
|
|
106
93
|
|
|
107
|
-
|
|
108
|
-
{
|
|
109
|
-
"env": {
|
|
110
|
-
"MEMORY_DB_PATH": "/Users/you/.memory-mcp-server/shared-memory.db"
|
|
111
|
-
}
|
|
112
|
-
}
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
Project-scoped memory:
|
|
94
|
+
Add to `~/.codex/config.toml`:
|
|
116
95
|
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
}
|
|
96
|
+
```toml
|
|
97
|
+
[mcp_servers.memory]
|
|
98
|
+
enabled = true
|
|
99
|
+
command = "npx"
|
|
100
|
+
args = ["-y", "@nhatnguyen9317/memory-mcp-server"]
|
|
123
101
|
```
|
|
124
102
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
- use shared memory if you want one agent persona to accumulate knowledge across projects
|
|
128
|
-
- use project-scoped memory if you want isolation per repository or customer
|
|
129
|
-
|
|
130
|
-
### How An Agent Learns To Use This MCP
|
|
131
|
-
|
|
132
|
-
The human installer reads this `README`.
|
|
133
|
-
|
|
134
|
-
The runtime agent usually does not.
|
|
135
|
-
|
|
136
|
-
That means:
|
|
137
|
-
|
|
138
|
-
- `README.md` is for the person installing the MCP
|
|
139
|
-
- `AGENTS.md` in this repo is for agents working inside this repo
|
|
140
|
-
- an agent working in some other repo will usually only see:
|
|
141
|
-
- tool names
|
|
142
|
-
- tool descriptions
|
|
143
|
-
- schemas
|
|
144
|
-
- any runtime tool it can call, especially `get_usage_guide`
|
|
103
|
+
Verify the connection by calling a cheap read-only tool such as `get_usage_guide`
|
|
104
|
+
or `memory_list`.
|
|
145
105
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
1. install the MCP
|
|
149
|
-
2. add a short instruction snippet to your own repo's `AGENTS.md` or client prompt
|
|
150
|
-
3. tell the agent to call `get_usage_guide` before using memory/reasoning tools the first time
|
|
151
|
-
|
|
152
|
-
## Suggested AGENTS.md Snippet
|
|
106
|
+
## Requirements
|
|
153
107
|
|
|
154
|
-
|
|
108
|
+
- Node.js `>= 22.5.0` (for the built-in `node:sqlite` — no native addon build)
|
|
109
|
+
|
|
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.
|
|
113
|
+
|
|
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:
|
|
155
167
|
|
|
156
168
|
```md
|
|
157
169
|
## Memory MCP
|
|
158
170
|
|
|
159
171
|
When the `memory` MCP server is available:
|
|
160
172
|
|
|
161
|
-
- On first use, call `get_usage_guide`
|
|
162
|
-
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
-
|
|
166
|
-
|
|
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.
|
|
167
182
|
```
|
|
168
183
|
|
|
169
|
-
Keep that snippet in the repo where the agent actually works. Do not rely on the agent reading this MCP repo.
|
|
170
|
-
|
|
171
|
-
## Do I Need `AGENTS.md` or `CLAUDE.md` In This Repo?
|
|
172
|
-
|
|
173
|
-
Usually no.
|
|
174
|
-
|
|
175
|
-
- You do not need to edit this repo's `AGENTS.md` just to install the MCP into your own agent.
|
|
176
|
-
- You do not need a `CLAUDE.md` here unless you want Claude-specific rules for contributors working inside this MCP repo.
|
|
177
|
-
- The useful place for runtime instructions is the user's own repo or client prompt, not this MCP repo.
|
|
178
|
-
|
|
179
184
|
## Tool Surface
|
|
180
185
|
|
|
181
186
|
### Memory tools
|
|
@@ -189,77 +194,52 @@ Usually no.
|
|
|
189
194
|
| `memory_update` | Update an existing memory |
|
|
190
195
|
| `memory_delete` | Delete a memory |
|
|
191
196
|
| `memory_usage_report` | Aggregate tool usage telemetry |
|
|
192
|
-
| `memory_adoption_report` |
|
|
197
|
+
| `memory_adoption_report` | Adoption funnel + risk flags |
|
|
193
198
|
| `memory_agent_scorecard` | Compare agent usage patterns |
|
|
194
199
|
| `memory_record_usage_feedback` | Record whether recalled memory was useful |
|
|
195
|
-
| `get_usage_guide` | Return the runtime usage guide
|
|
200
|
+
| `get_usage_guide` | Return the runtime usage guide |
|
|
196
201
|
|
|
197
202
|
### Reasoning tools
|
|
198
203
|
|
|
199
204
|
| Tool | Purpose |
|
|
200
205
|
| --- | --- |
|
|
201
|
-
| `reasoning_start_session` | Open a
|
|
202
|
-
| `reasoning_add_step` | Append a
|
|
206
|
+
| `reasoning_start_session` | Open a session (auto-recall + stale cleanup) |
|
|
207
|
+
| `reasoning_add_step` | Append one step or a batch of steps |
|
|
203
208
|
| `reasoning_get_trace` | Return the full ordered trace |
|
|
204
|
-
| `reasoning_list_sessions` | List sessions with
|
|
205
|
-
| `reasoning_mark_step` | Add
|
|
209
|
+
| `reasoning_list_sessions` | List sessions with step counts |
|
|
210
|
+
| `reasoning_mark_step` | Add/update an audit mark on a step |
|
|
206
211
|
| `reasoning_search_steps` | Search reasoning steps |
|
|
207
|
-
| `reasoning_list_milestones` | List marked steps
|
|
208
|
-
| `reasoning_get_session_outline` |
|
|
209
|
-
| `reasoning_complete_session` | Close a session
|
|
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 |
|
|
210
215
|
|
|
211
216
|
## Storage Model
|
|
212
217
|
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
- `reasoning_sessions`
|
|
217
|
-
- `reasoning_steps`
|
|
218
|
-
- `reasoning_step_marks`
|
|
219
|
-
- `tool_usage_events`
|
|
220
|
-
- `schema_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`.
|
|
221
221
|
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
- `memories_fts`
|
|
225
|
-
- `reasoning_steps_fts`
|
|
226
|
-
|
|
227
|
-
## Migrations
|
|
228
|
-
|
|
229
|
-
Schema is managed in `src/migrations/`.
|
|
230
|
-
|
|
231
|
-
Migrations run automatically at server startup. There is currently no separate manual migration CLI command in this repo.
|
|
232
|
-
|
|
233
|
-
If you need migrations applied, start the server normally:
|
|
234
|
-
|
|
235
|
-
```bash
|
|
236
|
-
npm start
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
or:
|
|
240
|
-
|
|
241
|
-
```bash
|
|
242
|
-
node dist/index.js
|
|
243
|
-
```
|
|
222
|
+
Migrations run automatically at server startup; upgrading the package never
|
|
223
|
+
requires manual schema work.
|
|
244
224
|
|
|
245
225
|
## Development
|
|
246
226
|
|
|
247
227
|
```bash
|
|
248
|
-
npm
|
|
249
|
-
npm run build
|
|
250
|
-
npm
|
|
251
|
-
npm run
|
|
228
|
+
npm install
|
|
229
|
+
npm run build # tsc -> dist/
|
|
230
|
+
npm test # build + node --test
|
|
231
|
+
npm run dev # tsx watch src/index.ts
|
|
252
232
|
```
|
|
253
233
|
|
|
254
|
-
## Implementation Notes
|
|
255
|
-
|
|
256
234
|
- `src/db.ts` owns DB open and migration bootstrap
|
|
257
235
|
- `src/tools/memory.ts` owns memory tool handlers
|
|
258
236
|
- `src/tools/reasoning.ts` owns reasoning and audit tool handlers
|
|
259
237
|
- `src/tools/usage-guide.ts` owns `get_usage_guide`
|
|
260
238
|
|
|
239
|
+
See [CHANGELOG.md](./CHANGELOG.md) for release history.
|
|
240
|
+
|
|
261
241
|
## Notes
|
|
262
242
|
|
|
263
|
-
-
|
|
264
|
-
- this is a local stdio MCP server, not a network service
|
|
243
|
+
- Local stdio MCP server, not a network service
|
|
265
244
|
- `agent_id` is a filtering aid, not a security boundary
|
|
245
|
+
- License: MIT
|