@nhatnguyen9317/memory-mcp-server 1.2.0 → 1.3.1
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 +53 -0
- package/GUIDELINES.md +86 -21
- package/README.md +181 -180
- package/dist/constants.js +19 -2
- package/dist/index.js +19 -18
- package/dist/install-agents.js +74 -0
- package/dist/migrations/0005_memory_workspace.js +10 -0
- package/dist/migrations/index.js +2 -0
- package/dist/schemas/reasoning.js +27 -2
- package/dist/server.js +20 -0
- package/dist/tools/memory.js +49 -35
- package/dist/tools/reasoning.js +162 -39
- package/dist/tools/telemetry.js +9 -2
- package/dist/utils.js +23 -5
- package/package.json +24 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,58 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.3.1 (2026-07-14)
|
|
4
|
+
|
|
5
|
+
Theme: contributor documentation catches up with the code, plus a one-command way to teach an agent to use this MCP.
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- **Contributor architecture docs**: `docs/architecture.md` (layering, module map, data flow, storage model) and `docs/roadmap.md` (shipped/planned release index) — previously only user-facing docs (`README.md`, `GUIDELINES.md`) existed for this repo. `docs/architecture.md`'s `Version:` line is now locked to `package.json`'s version by a new test, `src/__tests__/architecture-doc-version.test.ts`. `AGENTS.md`/`CLAUDE.md` gained Docs Conventions, Release Process, and Version-Sync Conventions sections formalizing where new docs go and what must stay in sync on every release.
|
|
10
|
+
- **`pre-merge-review` skill** (`.claude/skills/pre-merge-review/`): a structured build/test + docs/version-sync check to run before merging a branch.
|
|
11
|
+
- **`install-agents` CLI subcommand**: after installing the package, `npx @nhatnguyen9317/memory-mcp-server install-agents` writes the README's "Memory MCP Server" agent-guidance snippet into a user's global `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`, idempotently (safe to re-run, backs up the existing file to `<path>.bak` first). For users who haven't installed the package yet, `scripts/install-agent-snippet.sh` does the same thing via `curl -fsSL <url> | bash`, no local Node install required first.
|
|
12
|
+
|
|
13
|
+
### Changed
|
|
14
|
+
|
|
15
|
+
- Design specs and implementation plans moved into a single `docs/design/` and `docs/plans/` hierarchy (previously split across `docs/plan-improvement-performance/` and `docs/superpowers/` with inconsistent naming); one previously-untracked spec is now committed. No content changes, links preserved.
|
|
16
|
+
|
|
17
|
+
## 1.3.0 (2026-07-11)
|
|
18
|
+
|
|
19
|
+
Theme: recall that stays right as the store grows — relevance ranking, provenance, and an always-on learning signal.
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
- **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.
|
|
24
|
+
- **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.
|
|
25
|
+
- **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).
|
|
26
|
+
- **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.
|
|
27
|
+
- 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.)
|
|
28
|
+
|
|
29
|
+
### Changed
|
|
30
|
+
|
|
31
|
+
- **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.
|
|
32
|
+
- **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.
|
|
33
|
+
- **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.
|
|
34
|
+
- `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.
|
|
35
|
+
|
|
36
|
+
### Fixed
|
|
37
|
+
|
|
38
|
+
- `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.)
|
|
39
|
+
|
|
40
|
+
## 1.2.5 (2026-07-11)
|
|
41
|
+
|
|
42
|
+
Theme: cut logging friction and make the docs tell the new story.
|
|
43
|
+
|
|
44
|
+
### Added
|
|
45
|
+
|
|
46
|
+
- **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.
|
|
47
|
+
- `keywords` in package.json and a registry submission playbook under `docs/growth/registry-submissions.md`.
|
|
48
|
+
|
|
49
|
+
### Changed
|
|
50
|
+
|
|
51
|
+
- **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.
|
|
52
|
+
- **`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.
|
|
53
|
+
- **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.
|
|
54
|
+
- **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.
|
|
55
|
+
|
|
3
56
|
## 1.2.0 (2026-07-10)
|
|
4
57
|
|
|
5
58
|
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-
|
|
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,185 +1,211 @@
|
|
|
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
|
-
> 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
|
-
|
|
45
|
-
|
|
46
|
-
|
|
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
|
-
|
|
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
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
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
|
-
|
|
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
|
-
|
|
76
|
-
- args: `["/absolute/path/to/memory-mcp-server/dist/index.js"]`
|
|
50
|
+
## Why this one?
|
|
77
51
|
|
|
78
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
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
|
-
|
|
68
|
+
## Quick Install
|
|
85
69
|
|
|
86
|
-
|
|
70
|
+
### Claude Code
|
|
87
71
|
|
|
88
|
-
|
|
89
|
-
-
|
|
72
|
+
```bash
|
|
73
|
+
claude mcp add memory -- npx -y @nhatnguyen9317/memory-mcp-server
|
|
74
|
+
```
|
|
90
75
|
|
|
91
|
-
###
|
|
76
|
+
### Claude Desktop / Cursor / Antigravity (JSON config)
|
|
92
77
|
|
|
93
78
|
```json
|
|
94
79
|
{
|
|
95
80
|
"mcpServers": {
|
|
96
81
|
"memory": {
|
|
97
|
-
"command": "
|
|
98
|
-
"args": ["/
|
|
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
|
-
|
|
108
|
-
|
|
109
|
-
Shared memory across many repos:
|
|
89
|
+
Optionally pin the database location with `"env": {"MEMORY_DB_PATH": "/path/to/memory.db"}`
|
|
90
|
+
(default: `~/.memory-mcp-server/memory.db`).
|
|
110
91
|
|
|
111
|
-
|
|
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
|
-
|
|
94
|
+
Add to `~/.codex/config.toml`:
|
|
120
95
|
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
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
|
-
|
|
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:
|
|
141
|
-
|
|
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`
|
|
103
|
+
Verify the connection by calling a cheap read-only tool such as `get_usage_guide`
|
|
104
|
+
or `memory_list`.
|
|
149
105
|
|
|
150
|
-
|
|
106
|
+
## Requirements
|
|
151
107
|
|
|
152
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 —
|
|
167
|
+
or install it into your **global** Claude Code / Codex CLI config
|
|
168
|
+
automatically:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
# after installing the package (above)
|
|
172
|
+
npx @nhatnguyen9317/memory-mcp-server install-agents
|
|
173
|
+
|
|
174
|
+
# or, without installing anything first
|
|
175
|
+
curl -fsSL https://raw.githubusercontent.com/ngquocnhat9317/memory-mcp-server/master/scripts/install-agent-snippet.sh | bash
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Both are idempotent (safe to re-run) and back up any file they touch to
|
|
179
|
+
`<path>.bak` first.
|
|
159
180
|
|
|
160
181
|
```md
|
|
161
|
-
|
|
182
|
+
<!-- MEMORY_MCP_SERVER_START -->
|
|
183
|
+
## Memory MCP Server
|
|
162
184
|
|
|
163
|
-
|
|
185
|
+
**Hard gate — before anything else, every session, no exceptions:** if
|
|
186
|
+
`memory_*` / `reasoning_*` tools are listed (even deferred/lazy-loaded — load
|
|
187
|
+
them first, don't skip because schemas aren't visible yet), call
|
|
188
|
+
`get_usage_guide` and follow it. Do this unconditionally, before judging
|
|
189
|
+
whether the task looks like it needs memory.
|
|
164
190
|
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
191
|
+
| Thought | Reality |
|
|
192
|
+
| --- | --- |
|
|
193
|
+
| "This task looks simple" | Check first, decide after — the guide says what counts as trivial |
|
|
194
|
+
| "Tools aren't loaded yet" | Load them, don't skip the gate |
|
|
195
|
+
| "I'll search directly instead" | `get_usage_guide` first — it defines when search vs. a reasoning session applies |
|
|
196
|
+
|
|
197
|
+
- Non-trivial task (multi-step, debugging, planning, trade-offs)?
|
|
198
|
+
`reasoning_start_session` first — review the `related_memories` it
|
|
199
|
+
returns before working; if one carries a `source`, you can replay its
|
|
200
|
+
origin with `reasoning_get_trace`.
|
|
201
|
+
- Log meaningful steps with `reasoning_add_step` (batch mode `steps: [...]`
|
|
202
|
+
is fine for recording finished work).
|
|
203
|
+
- Always close with `reasoning_complete_session`; report helpful memories via
|
|
204
|
+
`used_memory_ids`; pass `save_as_memory=true` for durable conclusions.
|
|
205
|
+
- Never store secrets, tokens, or raw sensitive data.
|
|
206
|
+
<!-- MEMORY_MCP_SERVER_END -->
|
|
171
207
|
```
|
|
172
208
|
|
|
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
209
|
## Tool Surface
|
|
184
210
|
|
|
185
211
|
### Memory tools
|
|
@@ -193,77 +219,52 @@ Usually no.
|
|
|
193
219
|
| `memory_update` | Update an existing memory |
|
|
194
220
|
| `memory_delete` | Delete a memory |
|
|
195
221
|
| `memory_usage_report` | Aggregate tool usage telemetry |
|
|
196
|
-
| `memory_adoption_report` |
|
|
222
|
+
| `memory_adoption_report` | Adoption funnel + risk flags |
|
|
197
223
|
| `memory_agent_scorecard` | Compare agent usage patterns |
|
|
198
224
|
| `memory_record_usage_feedback` | Record whether recalled memory was useful |
|
|
199
|
-
| `get_usage_guide` | Return the runtime usage guide
|
|
225
|
+
| `get_usage_guide` | Return the runtime usage guide |
|
|
200
226
|
|
|
201
227
|
### Reasoning tools
|
|
202
228
|
|
|
203
229
|
| Tool | Purpose |
|
|
204
230
|
| --- | --- |
|
|
205
|
-
| `reasoning_start_session` | Open a
|
|
206
|
-
| `reasoning_add_step` | Append a
|
|
231
|
+
| `reasoning_start_session` | Open a session (auto-recall + stale cleanup) |
|
|
232
|
+
| `reasoning_add_step` | Append one step or a batch of steps |
|
|
207
233
|
| `reasoning_get_trace` | Return the full ordered trace |
|
|
208
|
-
| `reasoning_list_sessions` | List sessions with
|
|
209
|
-
| `reasoning_mark_step` | Add
|
|
234
|
+
| `reasoning_list_sessions` | List sessions with step counts |
|
|
235
|
+
| `reasoning_mark_step` | Add/update an audit mark on a step |
|
|
210
236
|
| `reasoning_search_steps` | Search reasoning steps |
|
|
211
|
-
| `reasoning_list_milestones` | List marked steps
|
|
212
|
-
| `reasoning_get_session_outline` |
|
|
213
|
-
| `reasoning_complete_session` | Close a session
|
|
237
|
+
| `reasoning_list_milestones` | List marked steps across sessions |
|
|
238
|
+
| `reasoning_get_session_outline` | Marked steps or deterministic outline |
|
|
239
|
+
| `reasoning_complete_session` | Close a session; optional memory save + usage feedback |
|
|
214
240
|
|
|
215
241
|
## Storage Model
|
|
216
242
|
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
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
|
|
243
|
+
Tables: `memories`, `reasoning_sessions`, `reasoning_steps`,
|
|
244
|
+
`reasoning_step_marks`, `tool_usage_events`, `schema_migrations` — plus FTS5
|
|
245
|
+
indexes `memories_fts` and `reasoning_steps_fts`.
|
|
232
246
|
|
|
233
|
-
|
|
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
|
-
```
|
|
247
|
+
Migrations run automatically at server startup; upgrading the package never
|
|
248
|
+
requires manual schema work.
|
|
248
249
|
|
|
249
250
|
## Development
|
|
250
251
|
|
|
251
252
|
```bash
|
|
252
|
-
npm
|
|
253
|
-
npm run build
|
|
254
|
-
npm
|
|
255
|
-
npm run
|
|
253
|
+
npm install
|
|
254
|
+
npm run build # tsc -> dist/
|
|
255
|
+
npm test # build + node --test
|
|
256
|
+
npm run dev # tsx watch src/index.ts
|
|
256
257
|
```
|
|
257
258
|
|
|
258
|
-
## Implementation Notes
|
|
259
|
-
|
|
260
259
|
- `src/db.ts` owns DB open and migration bootstrap
|
|
261
260
|
- `src/tools/memory.ts` owns memory tool handlers
|
|
262
261
|
- `src/tools/reasoning.ts` owns reasoning and audit tool handlers
|
|
263
262
|
- `src/tools/usage-guide.ts` owns `get_usage_guide`
|
|
264
263
|
|
|
264
|
+
See [CHANGELOG.md](./CHANGELOG.md) for release history.
|
|
265
|
+
|
|
265
266
|
## Notes
|
|
266
267
|
|
|
267
|
-
-
|
|
268
|
-
- this is a local stdio MCP server, not a network service
|
|
268
|
+
- Local stdio MCP server, not a network service
|
|
269
269
|
- `agent_id` is a filtering aid, not a security boundary
|
|
270
|
+
- License: MIT
|