Skip to content
Back to search

neuralnexusnote

MarketplaceWorks with Claude CodeGitHub

N3MC-MCPServer Lite

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/NeuralNexusNote/n3mcmcp-lite with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/NeuralNexusNote/n3mcmcp-lite'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/neuralnexusnote--n3mcmcp-lite/badge.svg)](/listings/neuralnexusnote--n3mcmcp-lite)

HTML

<a href="/listings/neuralnexusnote--n3mcmcp-lite"><img src="/api/listings/neuralnexusnote--n3mcmcp-lite/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> The fastest path from "nothing installed" to "Claude Code is using > N3MC memory". Pick the install path that matches you (PyPI / fork / > uvx), then add the server to your client config. Both Claude Code > CLI and Claude Desktop are covered.

Step 1 — Start Redis Stack

docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest
# (Subsequent sessions: `docker start redis-stack`)

Step 2 — Install the package (choose one)

**Quickest path — Claude Code marketplace.** Bundles install + MCP wiring in two commands. Run inside Claude Code:

/plugin marketplace add NeuralNexusNote/n3mcmcp-lite
/plugin install n3mc-workingmemory@neuralnexusnote

Then `/reload-plugins` and skip Step 3 — the plugin manifest handles MCP wiring. The manual options below remain available for forks, custom configs, and Claude Desktop.

---

**(a) From PyPI** — most users:

pip install n3memorycore-mcp-lite

**(b) From a fork (you cloned this repo)** — contributors / customizers:

git clone https://github.com/<YOU>/n3mcmcp-lite
cd n3mcmcp-lite
pip install -e ".[dev]"

**(c) Zero-install via uvx** — no global install, isolated env:

# Just verify it runs; the actual launch is handled by your MCP client config:
uvx --from n3memorycore-mcp-lite n3mc-workingmemory --help

After step 2, the `n3mc-workingmemory` command is on your `PATH`. Run `where n3mc-workingmemory` (Windows) or `which n3mc-workingmemory` (macOS/Linux) to confirm.

Step 3 — Wire it into your MCP client

| Client | What to do | |---|---| | **Claude Code (CLI), this repo's working tree** | `.mcp.json` is already committed — just `cd` into the repo and run `claude`. The CLI auto-connects on next prompt. | | **Claude Code (CLI), a different project directory** | Copy [.mcp.json](./.mcp.json) into that project, or add the same `n3mc-workingmemory` block to its `.mcp.json`. See [Claude Code (standalone CLI)](#claude-code-standalone-cli). | | **Claude Desktop** (incl. its built-in "Code" tab) | Edit `claude_desktop_config.json` (path differs per OS). See [Claude Desktop](#claude-desktop-and-the-code-tab-inside-claude-desktop). | | **Claude Code with auto-tool-approval** | One extra block in `~/.claude/settings.json` so the AI never blocks on "Allow?" prompts. See [Auto-approve tool calls](#auto-approve-tool-calls-claude-code-only). | | **uvx-launched** (no global install needed) | Use the uvx-form `command`/`args` in your client config. See [Claude Code (standalone CLI)](#claude-code-standalone-cli). |

That's it. Once Claude Code is connected, the server's behavioral instructions take over — `search_memory` runs at the start of every turn and `save_memory` runs after each meaningful exchange, all automatically.

> First call may take 30–60 seconds the **first** time only — the > ~400 MB `intfloat/multilingual-e5-base` embedding model downloads to > `~/.cache/huggingface/`. Subsequent starts complete in seconds.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines
  1. {
  2. "name": "neuralnexusnote",
  3. "owner": {
  4. "name": "NeuralNexusNote",
  5. "email": "arnolfjp019@gmail.com"
  6. },
  7. "metadata": {
  8. "description": "Memory-focused MCP servers from NeuralNexusNote",
  9. "version": "1.12.2"
  10. },
  11. "plugins": [
  12. {
  13. "name": "n3mc-workingmemory",
  14. "source": "./plugins/n3mc-workingmemory",
  15. "description": "Ephemeral (7-day TTL) hybrid vector + BM25 memory for Claude Code, backed by Redis Stack. Multilingual (NFKC + bigram for CJK / Hangul / Thai / Lao / Myanmar / Khmer + diacritic fold). Requires a Redis Stack container running on localhost:6379 and uv (for uvx) on PATH.",
  16. "category": "memory",
  17. "tags": ["memory", "rag", "redis", "vector-search", "bm25", "embedding", "ephemeral", "multilingual", "japanese", "cjk"]
  18. }
  19. ]
  20. }
README.md · README · 884 lines
  1. # N3MemoryCore MCP — Lite (Ephemeral)
  2. > **N3MC-MCP-Lite is an "external memory server" used by MCP-compatible
  3. > editors such as Claude Code, Cursor, and Windsurf.**
  4. > It runs as an MCP Server so AI can save and search conversation and
  5. > code context across sessions.
  6. > A NeuralNexusNote™ product — **free Lite** build: ephemeral hybrid
  7. > (vector + BM25) memory exposed as a Model Context Protocol server, backed
  8. > by Redis Stack with a 7-day TTL per entry.
  9. > 💬 **The MCP protocol can only nudge the LLM to call `save_memory`, so
  10. > which conversations actually get saved is ultimately up to the LLM. But
  11. > if you ask Claude Code, it can also wire up hook-based auto-saving of
  12. > every conversation.**
  13. > Just say "after every turn, automatically save the full Claude Code
  14. > transcript to Lite" and Claude Code will drop a script under
  15. > `~/.claude/hooks/` and add a `Stop` hook to `~/.claude/settings.json`.
  16. > The harness runs the hook deterministically — it does not depend on the
  17. > LLM remembering to call `save_memory`, so Claude can never accidentally
  18. > skip a save. See the
  19. > [Hook-based full-transcript saving](#hook-based-full-transcript-saving)
  20. > section below for details.
  21. > 🇯🇵 **[日本語版はこちら](./README_JP.md)**
  22. > 🛡️ **[Development Philosophy](./PHILOSOPHY.md)**
  23. ## Lite or Free? Which one to use
  24. There are two free N3MemoryCore builds. **Lite (this repository) assumes you can start Docker and edit MCP client settings. If you only use Claude Code and this is your first time, [N3MC Free](https://github.com/NeuralNexusNote/n3mc-free) is easier.**
  25. | | **N3MC MCP Lite** (this repository) | **[N3MC Free](https://github.com/NeuralNexusNote/n3mc-free)** |
  26. |---|---|---|
  27. | Works with | MCP clients: Claude Code, Claude Desktop, Cursor, Windsurf, … | Claude Code only |
  28. | What gets saved | What the AI decides to save (`save_memory`) | Every message, automatically (hooks) |
  29. | How long it is kept | 7 days, then deleted automatically | Until you delete it |
  30. | What you need | Python 3.10+, Docker (Redis Stack), and the MCP client settings | Python 3.10+ |
  31. | Setup | Start Redis Stack, install, then register the server in your MCP client | `pip install n3memorycore-free`, then `n3mc --init` |
  32. | Good for | Users who know MCP and Docker; short-lived working memory for a project | Beginners; long-term memory for Claude Code |
  33. - **Choose Lite** if you use an MCP client other than Claude Code, or you want memory that forgets by itself after a short project.
  34. - **Choose Free** if you use Claude Code and want it to remember your conversations without Docker or MCP settings.
  35. ---
  36. ## 🚀 Quickstart — connect to Claude Code in 3 steps
  37. > The fastest path from "nothing installed" to "Claude Code is using
  38. > N3MC memory". Pick the install path that matches you (PyPI / fork /
  39. > uvx), then add the server to your client config. Both Claude Code
  40. > CLI and Claude Desktop are covered.
  41. ### Step 1 — Start Redis Stack
  42. ```bash
  43. docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest
  44. # (Subsequent sessions: `docker start redis-stack`)
  45. ```
  46. ### Step 2 — Install the package (choose one)
  47. **Quickest path — Claude Code marketplace.** Bundles install + MCP wiring in two
  48. commands. Run inside Claude Code:
  49. ```
  50. /plugin marketplace add NeuralNexusNote/n3mcmcp-lite
  51. /plugin install n3mc-workingmemory@neuralnexusnote
  52. ```
  53. Then `/reload-plugins` and skip Step 3 — the plugin manifest handles MCP wiring.
  54. The manual options below remain available for forks, custom configs, and
  55. Claude Desktop.
  56. ---
  57. **(a) From PyPI** — most users:
  58. ```bash
  59. pip install n3memorycore-mcp-lite
  60. ```
  61. **(b) From a fork (you cloned this repo)** — contributors / customizers:
  62. ```bash
  63. git clone https://github.com/<YOU>/n3mcmcp-lite
  64. cd n3mcmcp-lite
  65. pip install -e ".[dev]"
  66. ```
  67. **(c) Zero-install via uvx** — no global install, isolated env:
  68. ```bash
  69. # Just verify it runs; the actual launch is handled by your MCP client config:
  70. uvx --from n3memorycore-mcp-lite n3mc-workingmemory --help
  71. ```
  72. After step 2, the `n3mc-workingmemory` command is on your `PATH`. Run
  73. `where n3mc-workingmemory` (Windows) or `which n3mc-workingmemory`
  74. (macOS/Linux) to confirm.
  75. ### Step 3 — Wire it into your MCP client
  76. | Client | What to do |
  77. |---|---|
  78. | **Claude Code (CLI), this repo's working tree** | `.mcp.json` is already committed — just `cd` into the repo and run `claude`. The CLI auto-connects on next prompt. |
  79. | **Claude Code (CLI), a different project directory** | Copy [.mcp.json](./.mcp.json) into that project, or add the same `n3mc-workingmemory` block to its `.mcp.json`. See [Claude Code (standalone CLI)](#claude-code-standalone-cli). |
  80. | **Claude Desktop** (incl. its built-in "Code" tab) | Edit `claude_desktop_config.json` (path differs per OS). See [Claude Desktop](#claude-desktop-and-the-code-tab-inside-claude-desktop). |
  81. | **Claude Code with auto-tool-approval** | One extra block in `~/.claude/settings.json` so the AI never blocks on "Allow?" prompts. See [Auto-approve tool calls](#auto-approve-tool-calls-claude-code-only). |
  82. | **uvx-launched** (no global install needed) | Use the uvx-form `command`/`args` in your client config. See [Claude Code (standalone CLI)](#claude-code-standalone-cli). |
  83. That's it. Once Claude Code is connected, the server's behavioral
  84. instructions take over — `search_memory` runs at the start of every
  85. turn and `save_memory` runs after each meaningful exchange, all
  86. automatically.
  87. > First call may take 30–60 seconds the **first** time only — the
  88. > ~400 MB `intfloat/multilingual-e5-base` embedding model downloads to
  89. > `~/.cache/huggingface/`. Subsequent starts complete in seconds.
  90. ---
  91. ## ⚠️ Prerequisites (required before install)
  92. This server does **not** run out of the box — you must prepare two things first:
  93. 1. **Redis Stack on `localhost:6379`** — the Lite build stores memory in Redis + RediSearch. The easiest way is Docker:
  94. ```bash
  95. # First time only (creates the container):
  96. docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest
  97. # Every subsequent session (container already exists):
  98. docker start redis-stack
  99. ```
  100. Re-running the `docker run` command after the container exists fails with `Conflict. The container name "/redis-stack" is already in use`. Use `docker start` from the second session onward.
  101. > **Why no persistence flags on the docker line**: this build is
  102. > *deliberately volatile*. Ephemerality is a design feature, not a
  103. > missing capability — see the "Use cases" section below. Rather
  104. > than rely on fragile shell-quoting for `--save ""` (which breaks on
  105. > Windows PowerShell and cmd.exe), the MCP server **enforces** the
  106. > ephemeral state at startup by issuing `CONFIG SET appendonly no` and
  107. > `CONFIG SET save ""` on every connect. If you manually re-enable
  108. > persistence between sessions, it is reverted on the next Lite run.
  109. > The plain `docker run` above is sufficient — the server is the
  110. > source of truth for the ephemerality guarantee.
  111. >
  112. > **Use a dedicated Redis.** The server changes these settings only
  113. > when the Redis holds nothing but N3MC keys — in every database number,
  114. > since 1.11.1. If it finds other data
  115. > (a Redis you already use for something else), it leaves the
  116. > persistence settings alone and shows a `shared_redis` notice — so it
  117. > never makes another program lose data on the next Redis restart.
  118. > N3MC Lite also needs **Redis Stack** (RediSearch); with plain Redis
  119. > every tool answers with a hint to start Redis Stack.
  120. 2. **[`uv`](https://docs.astral.sh/uv/) on your `PATH`** — required only for the Claude Code plugin / `uvx` install path. Not needed if you install from source.
  121. The server refuses to start if Redis is unreachable, and the Claude Code plugin will fail to launch without `uv`. Install both before running `/plugin install` or any client-side config.
  122. ---
  123. ## Features
  124. - 💾 **Your own Redis** — Your memories are kept in the Redis you run (on your PC by default), not in any cloud service. Only the memories recalled for a turn are sent to the AI service, as part of the conversation ([details](#your-memory-stays-on-machines-you-control)).
  125. - 🔍 **Semantic search** — Finds relevant past conversations even when the exact words differ.
  126. - 🌐 **Multilingual out of the box** — CPU-only, no LLM/GPU required. NFKC fold (`アルファ`↔`アルファ`, `123`↔`123`, ligatures), bigram coverage for Japanese / Chinese / Korean / Thai / Lao / Myanmar / Khmer, diacritic cross-match for Latin scripts (`café`↔`cafe`).
  127. - 🛡️ **Encoding safety** — stdio UTF-8 reconfigure on Windows (cp932 → UTF-8), lone-surrogate sanitization on every input. Same defenses as the Free build.
  128. - 🔄 **Context across sessions** — Working memory that lasts **7 days** (auto-expires via Redis TTL; pair with any persistent memory backend if you need longer retention).
  129. - ⚡ **Works automatically** — Saving and searching happen automatically. The MCP `initialize` response ships behavioral instructions, so no user action is required.
  130. - 🤖 **Multi-agent ready** — Multiple AI agents share one Redis. The `b_local` and `b_session` biases prioritize each project's own memories while still surfacing the team's collective knowledge.
  131. - 🏢 **One person, one memory** — Memories are not shared between people: each `config.json` has its own `owner_id`, and search shows only that owner's records. Use one Redis per installation; clients share memories only when they use the same `config.json`.
  132. - 🧹 **Ephemerality is a design feature** — 7-day auto-expiry means failed attempts and abandoned designs don't bleed into the next task. `docker restart redis-stack` wipes everything instantly.
  133. - 💰 **Reduces token waste** — No more re-explaining past context. Memory search uses local embeddings (`intfloat/multilingual-e5-base`) and costs zero Claude tokens, and accurate context injection means fewer corrections and back-and-forth.
  134. ## How It Works
  135. ```
  136. User's message
  137. │
  138. ▼
  139. ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
  140. │ 1. Auto-save │────▶│ 2. Semantic │────▶│ 3. Context │
  141. │ Save last │ │ search │ │ injection │
  142. │ response to │ │ Find related │ │ Feed to │
  143. │ Redis │ │ memories │ │ Claude │
  144. └──────────────┘ └──────────────┘ └──────────────┘
  145. │
  146. ▼
  147. Claude responds
  148. with full context
  149. ```
  150. Everything runs automatically via the **behavioral instructions** shipped
  151. in the MCP `initialize` response. No Claude Code hooks are involved — the
  152. only client-side setup is adding the tools to `permissions.allow`. No user
  153. action required.
  154. ### Relationship with Claude's built-in auto-memory
  155. Claude Code has a built-in auto-memory system
  156. (`~/.claude/projects/.../memory/`). N3MemoryCore **complements it rather
  157. than competing with it**.
  158. | | Claude auto-memory | N3MemoryCore RAG |
  159. | --------------- | ------------------------------------------------------- | ---------------------------------------------------- |
  160. | **Strengths** | Reliable, loads every session, great for fixed facts | Conversation context, detailed history |
  161. | **Weaknesses** | Cannot capture conversation flow or context | Depends on search quality; not guaranteed to surface |
  162. | **Best for** | User profile, folder paths, stable settings | Conversation threads, past decisions, reasoning |
  163. **Recommended usage:**
  164. - **Fixed information needed every session** (folder paths, user preferences) → save to auto-memory
  165. - **Conversation context and history** (discussion threads, past decisions) → N3MemoryCore accumulates automatically (7-day window; pair with a persistent memory backend if you need longer retention)
  166. ---
  167. ## Your Memory Stays on Machines You Control
  168. An AI that remembers you is convenient, but it is natural to ask where those memories are kept. N3MC Lite keeps them in the Redis Stack you run: by default the one on your own PC, or a Redis server you choose.
  169. - **Your Redis, not an N3MC cloud** — Memories are stored in the Redis set by `redis_url` (default `redis://localhost:6379/0`; the `N3MC_REDIS_URL` environment variable takes precedence — see [Configuration](#configuration)). There is no N3MC account and no N3MC cloud service. Each entry expires 7 days after it was saved (`ttl_seconds`).
  170. - **Almost nothing on disk** — Besides Redis, N3MC writes only a small `config.json` (see [Data location](#data-location)). When the Redis holds nothing but N3MC data, the server turns off Redis's own saving to disk (RDB/AOF) at startup, so `docker restart redis-stack` wipes every memory. In a Redis that also holds other data, it leaves those settings alone and shows a `shared_redis` notice.
  171. - **Embeddings are made on your PC** — The embedding model (`intfloat/multilingual-e5-base`) runs locally on the CPU, and the search runs inside your Redis. Searching calls no external API.
  172. - **N3MC opens no port** — The MCP server talks to your AI client over stdio (standard input/output) and does not listen on any network port. The only connection it makes itself is to the Redis at `redis_url`. N3MC adds no password of its own: who can reach Redis (port 6379 in the `docker run` command above) depends on your Redis and firewall settings.
  173. - **No telemetry** — N3MC sends no usage data anywhere. The code is open, so you can check this yourself.
  174. - **You can see and remove everything** — `list_memories` shows the newest entries; `delete_memory` and `delete_memories_by_session` remove them (see [Tools exposed](#tools-exposed)).
  175. What does go over the network:
  176. - **Installing** — `pip` and `uvx` download the package and its dependencies from PyPI; the Claude Code marketplace path fetches the plugin from the `NeuralNexusNote/n3mcmcp-lite` GitHub repository.
  177. - **The Redis Stack image** — The first `docker run` downloads `redis/redis-stack-server` from Docker Hub.
  178. - **The embedding model download** — On the first start, `intfloat/multilingual-e5-base` (~440 MB) is downloaded from Hugging Face.
  179. - **A Redis on another machine** — If you point `redis_url` / `N3MC_REDIS_URL` at another machine (for example a team server), every memory you save and every search goes over the network to that machine.
  180. - **What the AI reads** — The results of `search_memory` become part of the conversation, so they are sent, together with your message, to the AI service behind your MCP client (Anthropic, for Claude Code). N3MC does not upload your Redis contents anywhere, but the parts the AI uses in a turn are part of that conversation.
  181. ## Use cases — when working memory is the right tool
  182. The 7-day TTL and volatile Redis storage are **design features, not
  183. limitations**. They make this server the right fit for:
  184. - **Agentic code-generation loops** — failed attempts and abandoned
  185. designs don't bleed into the next task; `docker restart redis-stack`
  186. wipes the slate clean.
  187. - **Multi-agent collaboration** — decisions made during one task don't
  188. contaminate unrelated follow-ups.
  189. - **Experimental / throwaway prototyping** — leave it alone and memory
  190. evaporates in 7 days, no pruning needed.
  191. - **Project-scoped working memory** — pin a `session_id` per task /
  192. project to keep contexts cleanly separated.
  193. If you need **long-term, persistent knowledge accumulation across
  194. months or years**, working memory is not the right layer. Pair this
  195. server with any persistent memory MCP — the official knowledge-graph
  196. server, your own SQLite-backed implementation, or an external
  197. service — to cover the long-term side.
  198. ## What is this?
  199. `n3memorycore-mcp-lite` is a local-only MCP server that gives Claude (and
  200. any other MCP-compatible client) short-lived memory across conversations.
  201. It stores text entries in a local Redis Stack instance with both a BM25
  202. full-text index and a 768-dimension vector index
  203. ([`intfloat/multilingual-e5-base`](https://huggingface.co/intfloat/multilingual-e5-base)), and
  204. returns hybrid-ranked results.
  205. Every operation runs on the user's machine. No API calls, no cloud
  206. storage.
  207. ## Tools exposed
  208. | Tool | Purpose |
  209. | ----------------------------- | -------------------------------------------------------------------------------- |
  210. | `search_memory` | Hybrid (vector + BM25) search, ranked & time-decayed, `session_id` boost |
  211. | `save_memory` | Persist a short entry (7d TTL, exact duplicates rejected) |
  212. | `list_memories` | Most-recent entries, newest first |
  213. | `delete_memory` | Remove a specific entry by id (cascades to chunks if id is a parent doc) |
  214. | `delete_memories_by_session` | Bulk-delete every memory tied to a `session_id` — wraps up a finished project |
  215. | `repair_memory` | Re-create the RediSearch index if missing |
  216. The server also ships **behavioral instructions** via MCP's `initialize`
  217. response, asking the client to `search_memory` at the start of each turn
  218. and `save_memory` after each meaningful exchange — so "auto-save" is
  219. preserved without any Claude Code hooks.
  220. ## ID hierarchy
  221. N3MemoryCore identifies the origin and context of every record with
  222. five ID fields. Most users only ever touch `session_id` (and rarely
  223. `agent_name`); the rest are filled in automatically.
  224. | ID | Stored in | Generated | Granularity | Purpose |
  225. |-----------------------|---------------------------------|--------------------------------------------|----------------------------------------|---------|
  226. | `id` (PK) | Redis hash | Per record (UUIDv7, time-ordered) | **One record** | Unique identifier for each memory — used for `delete_memory` and dedup. |
  227. | `owner_id` | `config.json` | First startup (UUIDv4) | **Owner / installation** | Identifies whose data this is. Validated on every `save_memory`; mismatched payloads are rejected with `owner_id mismatch`. Stored as a TAG field; filtering happens in Python (see spec §3.12). |
  228. | `local_id` (agent_id) | `config.json` | First startup (UUIDv4) | **Agent / install** | UUIDv4 identifier for this install. Stored on every row for forward-compatibility with future persistent variants, but **does NOT feed Lite's `b_local` ranking** — `b_local` is computed from `stored_importance + access_count` only (see Ranking formula). |
  229. | `session_id` | In-memory or supplied by client | Per task / project / conversation (string) | **Task / project / conversation** | Surfaces memories from the same task / project together. Drives the **`b_session` ranking bias** (`b_session_match=1.0`, `b_session_mismatch=0.6`) so the current chat's memories outrank unrelated cross-project rows in the same Redis instance. Also the filter key for `delete_memories_by_session`. Resolution order: per-call argument → `N3MC_SESSION_ID` env var → per-process UUIDv4 fallback. |
  230. | `agent_name` | Redis hash | Per `save_memory` call (free-form string) | **Agent display label** | Human-readable label (e.g. `"claude-code"`, `"claude-desktop"`). Not used in ranking — display/audit only. |
  231. ```
  232. owner_id (one N3MC server / data owner)
  233. └── session_id (one task / project / conversation)
  234. └── local_id (the agent speaking inside that session)
  235. ├── agent_name (its display name: "claude-code" etc.)
  236. └── id (one memory record)
  237. ```
  238. **Practical guidance:**
  239. - **You should pin `session_id`** when working on a named project or
  240. task. Pass the same string (e.g. `"proj-alpha"`, `"task-refactor-auth"`)
  241. to both `save_memory` and `search_memory`. This both ranks-up the
  242. project's own memories and gives you a one-shot
  243. `delete_memories_by_session` for project teardown.
  244. - **You can leave `agent_name` empty** for single-agent use. Set it
  245. (`"claude-code"`, `"cursor"`, …) when multiple agents share the same
  246. Redis so audit/list output stays readable.
  247. - **You should not pass `owner_id`** unless you specifically need to
  248. prove ownership (the server validates it against `config.json` and
  249. rejects mismatches; an empty value means "use my own").
  250. - **Use one Redis per installation.** Lite assumes one `owner_id` per
  251. Redis (one PC, a dedicated container). If several PCs or people point
  252. at the same Redis, or `config.json` is re-created with a new
  253. `owner_id` while old records remain: a body one owner saved is
  254. rejected as `duplicate` for the other until it expires (7 days), and
  255. one owner's records can fill the search candidates so the other's are
  256. not found. Nothing is deleted. Give each installation its own Redis.
  257. ## Prerequisites
  258. ### 1. Start Redis Stack
  259. The Lite build requires Redis Stack (Redis + RediSearch module). The
  260. easiest way is Docker:
  261. ```bash
  262. # First time only (creates the container):
  263. docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest
  264. # Every subsequent session (container already exists):
  265. docker start redis-stack
  266. ```
  267. That's it — the container exposes Redis on `localhost:6379` and the
  268. server will find it automatically. Re-running the `docker run` command
  269. after the first install produces `Conflict. The container name
  270. "/redis-stack" is already in use`; use `docker start redis-stack`
  271. thereafter.
  272. ### 2. Install the package
  273. **From PyPI (recommended):**
  274. ```bash
  275. pip install n3memorycore-mcp-lite
  276. ```
  277. Or zero-install via `uvx` (the Claude Code plugin uses this path):
  278. ```bash
  279. uvx --from n3memorycore-mcp-lite n3mc-workingmemory
  280. ```
  281. **From source** (if you want to edit the code):
  282. ```bash
  283. git clone https://github.com/NeuralNexusNote/n3mcmcp-lite
  284. cd n3mcmcp-lite
  285. pip install -e .
  286. ```
  287. The first run downloads the ~400 MB embedding model from Hugging Face
  288. into the standard `~/.cache/huggingface/` directory.
  289. > **First install requires internet access to three resources:**
  290. > 1. **github.com** — when `/plugin marketplace add NeuralNexusNote/n3mcmcp-lite`
  291. > registers the plugin (skip this step if you install via `uvx` or from
  292. > source instead).
  293. > 2. **pypi.org** — when `uvx --from n3memorycore-mcp-lite` (or `pip install`)
  294. > resolves the package.
  295. > 3. **huggingface.co** — when the server first starts and downloads
  296. > `intfloat/multilingual-e5-base` (~400 MB) into `~/.cache/huggingface/`.
  297. >
  298. > All three fail with explicit, time-bounded errors when offline; none
  299. > hang. Subsequent starts use only the local cache and require no
  300. > internet.
  301. ## Configure a client
  302. ### Claude Desktop (and the "Code" tab inside Claude Desktop)
  303. If you are using the **Claude Desktop application** — including its
  304. built-in **Code** tab — configure MCP via the desktop config file, NOT
  305. via `.mcp.json` (which is only read by the standalone `claude` CLI).
  306. Add to `~/Library/Application Support/Claude/claude_desktop_config.json`
  307. (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
  308. ```json
  309. {
  310. "mcpServers": {
  311. "n3mc-workingmemory": {
  312. "command": "n3mc-workingmemory",
  313. "args": []
  314. }
  315. }
  316. }
  317. ```
  318. **Windows tip:** if Claude Desktop fails to spawn the server with the
  319. bare command name above (the hammer/tool icon never appears), replace
  320. `"command"` with the absolute path to the installed `.exe`, for example:
  321. ```json
  322. "command": "C:\\Users\\<YOU>\\AppData\\Local\\Programs\\Python\\Python312\\Scripts\\n3mc-workingmemory.exe"
  323. ```
  324. Run `where n3mc-workingmemory` in a terminal to find the exact path on
  325. your machine.
  326. **After editing the config, fully quit Claude Desktop** — closing the
  327. window is not enough. Right-click the Claude icon in the system tray (or
  328. use Task Manager) and terminate every Claude process, then relaunch.
  329. ### Claude Code (standalone CLI)
  330. This section applies ONLY to the `claude` command-line tool, not to the
  331. Claude Desktop "Code" tab (see above for that).
  332. **`.mcp.json` is already included in this repository.** Clone the repo,
  333. install the package, and the Claude Code CLI connects automatically — no
  334. manual configuration needed.
  335. For other projects, add the following to that project's `.mcp.json`:
  336. ```json
  337. {
  338. "mcpServers": {
  339. "n3mc-workingmemory": {
  340. "type": "stdio",
  341. "command": "n3mc-workingmemory",
  342. "args": []
  343. }
  344. }
  345. }
  346. ```
  347. ### Auto-approve tool calls (Claude Code only)
  348. By default, Claude Code prompts the user for each MCP tool call. For a
  349. fully automatic memory loop — so the connected AI never blocks on an
  350. "Allow?" prompt — the `n3mc-workingmemory` tools must be listed under
  351. `permissions.allow` in Claude Code settings.
  352. **Plugin install auto-configures this** — when you install via
  353. `/plugin install n3mc-workingmemory@neuralnexusnote`, a `SessionStart`
  354. hook runs [`hooks/install_permissions.py`](plugins/n3mc-workingmemory/hooks/install_permissions.py),
  355. which idempotently adds two wildcard rules to `permissions.allow` in
  356. `~/.claude/settings.json`:
  357. - `mcp__plugin_n3mc-workingmemory_n3mc-workingmemory__*` — the tools as the
  358. plugin provides them (Claude Code names plugin MCP tools
  359. `mcp__plugin_<plugin>_<server>__<tool>`, and permission rules must use that
  360. form)
  361. - `mcp__n3mc-workingmemory__*` — the same tools for a directly registered
  362. server (`claude mcp add`, `.mcp.json`)
  363. The wildcards cover all seven tools, including `recall_thread`. The hook
  364. only writes when a rule is missing and never touches other entries. If
  365. `settings.json` is read-only, locked by policy or not valid JSON, the hook
  366. changes nothing and shows a warning with the rule to add yourself.
  367. (Up to v1.9.x the hook added plain `mcp__n3mc-workingmemory__<tool>` names,
  368. which do not match the plugin's tool names, so plugin users were asked for
  369. permission on every call.)
  370. The `hooks.json` command tries `python` → `py` (Windows Python Launcher) →
  371. `python3`. If none is on `PATH`, a Python-free last step shows a warning
  372. (`systemMessage`) telling you that the tools could not be pre-approved and
  373. what to add. A missing `uvx` (the plugin launches the MCP server via
  374. `uvx --from n3memorycore-mcp-lite n3mc-workingmemory`) is reported the same
  375. way, with install commands (`pipx install uv`,
  376. `curl -LsSf https://astral.sh/uv/install.sh | sh`).
  377. **If you installed without the plugin** (e.g. `claude mcp add` or a manual
  378. `.mcp.json`), add the rule below to `~/.claude/settings.json` (user-global,
  379. recommended) or `.claude/settings.json` (per-project). If you installed the
  380. plugin but have no Python, use `mcp__plugin_n3mc-workingmemory_n3mc-workingmemory__*`
  381. instead:
  382. ```json
  383. {
  384. "permissions": {
  385. "allow": [
  386. "mcp__n3mc-workingmemory__*"
  387. ]
  388. }
  389. }
  390. ```
  391. Without this, every `save_memory` / `search_memory` call surfaces an
  392. approval prompt and the AI blocks if the user is away. Claude Desktop
  393. has no per-tool permission gate, so this step is not needed there.
  394. ## Data location
  395. The Lite build does not store a database on disk — memories live in
  396. Redis and expire automatically. Only a small `config.json` sits in
  397. `~/.n3mc-workingmemory/` (Windows: `%USERPROFILE%\.n3mc-workingmemory\`).
  398. Override with the `N3MC_DATA_DIR` environment variable.
  399. Since v1.10.0 the file is in the home directory instead of the platform
  400. app-data directory: the Microsoft Store build of the Claude desktop app
  401. redirects `%LOCALAPPDATA%` for the MCP servers it starts, which gave one PC
  402. two configs and two `owner_id`s, so memories saved from the desktop app
  403. were invisible to `claude` in a terminal. On first start the old config is
  404. copied over once (the old file is left in place).
  405. ## Configuration
  406. On first run, `config.json` is auto-generated with random UUIDs for
  407. `owner_id` and `local_id`. Editable defaults:
  408. ```json
  409. {
  410. "owner_id": "<uuid>",
  411. "local_id": "<uuid>",
  412. "redis_url": "redis://localhost:6379/0",
  413. "ttl_seconds": 604800,
  414. "half_life_days": 3,
  415. "bm25_min_threshold": 0.1,
  416. "search_result_limit": 20,
  417. "min_score": 0.2,
  418. "vector_min_cos": 0.85,
  419. "relative_min_score_ratio": 0.6,
  420. "min_results": 3,
  421. "version_order_enabled": true,
  422. "version_sim_threshold": 0.98,
  423. "version_min_chars": 100,
  424. "search_query_max_chars": 2000,
  425. "chunk_threshold": 400,
  426. "chunk_overlap": 100,
  427. "access_count_enabled": false,
  428. "access_count_weight": 0.02,
  429. "access_count_max_boost": 0.5,
  430. "ttl_refresh_on_search": true,
  431. "ttl_refresh_top_k": 5,
  432. "lexical_rerank_enabled": true,
  433. "rerank_weight": 0.3,
  434. "rerank_phrase_weight": 0.2,
  435. "b_session_match": 1.0,
  436. "b_session_mismatch": 0.6,
  437. "skip_code_blocks": false
  438. }
  439. ```
  440. - `redis_url` — connection URL; `N3MC_REDIS_URL` env var takes precedence.
  441. - `ttl_seconds` — TTL on every new memory and sha-guard (default 7 d).
  442. - `vector_min_cos` — how close (cosine) a record must be to the query to become a vector candidate (default `0.85`). Lower it (e.g. 0.80–0.83) to recall records even when the wording differs, at the cost of more loosely related rows; raise it (e.g. 0.88) for shorter results, at the cost of dropping related rows more easily. A sensible range is 0.80–0.88; 0.85 was measured with `multilingual-e5-base`, so re-measure it if you change `embedding_model`.
  443. - `relative_min_score_ratio` — drop results scoring below this ratio × the top score (default `0.6`; `0.0` disables).
  444. - `min_results` (since 1.10.1) — when fewer results than this pass the floors, `search_memory` adds the closest of the rows it dropped, up to this total, under a separate heading `#### Possibly related (weak matches — may be unrelated)` (default `3`; `0` turns it off). The connected LLM is told to use them only when they are actually relevant. Weak rows never get their 7-day TTL reset, so showing them does not keep them alive. This keeps a question from getting no memory at all, at the cost of up to 3 extra, mostly unrelated rows per search.
  445. - `version_order_enabled` / `version_sim_threshold` / `version_min_chars` — when an updated version of a document or long entry is saved, both versions are kept; results whose content is ≥ 0.98 similar are treated as versions and listed newest first. Each hit shows its `saved=` time.
  446. - Settings take effect when the MCP server restarts (restart your MCP client). If `config.json` has a typo and cannot be read, it is left untouched and the server runs on defaults; the first `search_memory` result says so. Write numbers without quotes.
  447. - `chunk_threshold` / `chunk_overlap` — sliding-window size and overlap (chars). Bodies longer than the threshold trigger the parent-document + chunks path for verbatim recall.
  448. - `access_count_*` — access-frequency auto-importance; top-K search hits receive a capped boost on future queries. **Off by default since 2026-11-17** (`access_count_enabled: false`); the hits are still counted.
  449. - `ttl_refresh_on_search` / `ttl_refresh_top_k` — TTL reset for the top-K hits on each search (reset-only; no extension past a fresh save).
  450. - `lexical_rerank_*` / `rerank_weight` / `rerank_phrase_weight` — lightweight post-fusion lexical reranker (CPU-only).
  451. - `b_session_match` / `b_session_mismatch` — multiplicative ranking boost for rows whose stored `session_id` matches (default `1.0`) vs. rows from other projects (`0.6`). Pass the same `session_id` to `save_memory` and `search_memory` to surface a project's memories above unrelated cross-project rows in the same Redis instance. Set both to `1.0` to disable the bias.
  452. - `skip_code_blocks` — when `true`, `save_memory` rejects any payload containing a triple-backtick fence (```` ``` ````) and returns `status: "skipped_code"`. Default `false`: the body is saved with each code block replaced by `[code omitted]` (since 1.12.0). Set to `true` if you want FastAPI-era N3MemoryCore-style code exclusion (keep code out of the memory index entirely — useful when your workflow already has git/IDE history for code and you only want prose decisions/plans in Redis).
  453. See the spec §6 for the complete field-by-field reference.
  454. ## Multilingual support
  455. Built-in, CPU-only, no LLM and no GPU required. Search and dedup behave
  456. the same regardless of how the user types the same word:
  457. | Layer | What it does | Real-world example |
  458. |---|---|---|
  459. | **NFKC normalization** | Folds compatibility forms before SHA / embedding / BM25 | `アルファ` ↔ `アルファ`, `123` ↔ `123`, `fi` ↔ `fi` |
  460. | **Bigram BM25 side channel** | Overlapping bigrams emitted for space-less scripts | `記憶装置` → `記憶 憶装 装置`; same for Korean (`안녕하세요`), Thai (`สวัสดี`), Lao, Myanmar, Khmer |
  461. | **Diacritic fold** | Latin/Greek/Cyrillic words also indexed without combining marks | `café` matches `cafe`, `Ångström` matches `Angstrom` |
  462. | **multilingual-e5-base embedding** | Multilingual semantic space across 100+ languages | Cross-language paraphrase retrieval |
  463. These run automatically on every `save_memory` and `search_memory` call.
  464. None of them rewrites the stored `content`: a long body comes back whole
  465. (spec §3.11), as it was saved — see the two input rules under
  466. [Encoding safety](#encoding-safety).
  467. ## Encoding safety
  468. Two layers of defense run before any tool body executes (spec §3.13).
  469. Same guards as the Free build, ported one-to-one:
  470. 1. **stdio UTF-8 reconfigure** — at module import, `sys.stdin` /
  471. `sys.stdout` / `sys.stderr` are switched to `encoding="utf-8"`. On
  472. Windows-Japanese hosts the default console code page is cp932, which
  473. would otherwise mangle every non-ASCII byte on the MCP JSON-RPC
  474. channel. POSIX systems are already UTF-8, so the call is a safe no-op.
  475. 2. **Lone-surrogate sanitization** — every `save_memory.content` and
  476. `search_memory.query` is passed through `sanitize_surrogates()` before
  477. any `.encode("utf-8")` call. Lone UTF-16 surrogate halves
  478. (`U+D800`–`U+DFFF`) appear when Windows subprocess pipes deliver UTF-8
  479. bytes that Python's decoder maps with `errors="surrogateescape"` —
  480. they round-trip through `json.loads` but raise `UnicodeEncodeError` at
  481. SHA1 / Redis HSET / embedding time. Without the guard the entire write
  482. is silently lost. The function is recursive so JSON payloads with
  483. surrogates buried inside are cleaned in one pass.
  484. If a save payload consists entirely of surrogates, sanitization collapses
  485. it to the empty string and the regular empty-content rejection path
  486. applies — `{"status":"error","saved":false,"reason":"empty content"}`.
  487. Content with no visible character (only whitespace, control / format
  488. characters such as `\x00` or `U+200B`, separators or variation selectors) is
  489. rejected with `empty content (no visible characters)`.
  490. Two rules apply to everything that is saved:
  491. - **Outer whitespace is trimmed once** — `' \nAAA\n '` is saved as `AAA`.
  492. - **Code blocks are stored as `[code omitted]`** (since 1.12.0) — each
  493. fenced block (```` ``` ```` … ```` ``` ````, or an unclosed fence to the end)
  494. is replaced before saving; inline backticks stay. N3MemoryCore remembers
  495. what was said and decided; the code belongs in your project's files.
  496. Versions before 1.12.0 stored the code but always showed it as
  497. `[code omitted]`, so what you see does not change.
  498. Everything else is stored verbatim, including NUL and zero-width characters
  499. inside visible text.
  500. ## Ranking formula
  501. ```
  502. final_score = (0.7 * cosine_similarity + 0.3 * keyword_relevance) * time_decay * b_local * b_session
  503. time_decay = 2 ^ (-days_elapsed / half_life_days) (default half-life: 3 days)
  504. b_local = clamp(0.5, 2.0, stored_importance + access_boost)
  505. access_boost = min(0.5, access_count * 0.02)
  506. b_session = b_session_match (default 1.0) if row.session_id == effective_session
  507. = b_session_mismatch (default 0.6) otherwise
  508. ```
  509. With a default 3-day half-life (shorter than the 7-day TTL), `time_decay`
  510. is meaningful in the Lite build: a fresh memory scores 1.0, a 3-day-old
  511. one exactly 0.5, and a 7-day-old (near-expiry) entry ≈ 0.20 — pushing
  512. recent context ahead in the ranking.
  513. **Auto-importance (access-frequency boost, off by default since
  514. 2026-11-17)**: when `access_count_enabled` is `true`, each time `search_memory`
  515. returns a memory in its top 5 hits, that memory's `access_count` is
  516. incremented by 1 and `b_local` rises by 0.02 on future queries (capped at
  517. +0.5). No LLM judgement required — frequently-useful memories naturally
  518. float to the top through CPU-only self-tuning. It is off by default because,
  519. measured in N3MC-Pro, it lowered recall@3 (often-returned memories rose above
  520. more relevant ones).
  521. ## Development
  522. ```bash
  523. # Start Redis Stack first (see Prerequisites), then:
  524. pip install -e ".[dev]"
  525. pytest tests/ -q
  526. ```
  527. Tests target Redis DB index `0` (configurable via `N3MC_REDIS_TEST_URL`)
  528. and `FLUSHDB` it before/after each test. RediSearch refuses to create
  529. indexes outside DB 0 (`Cannot create index on db != 0`), so a separate
  530. test DB isn't an option — run the test suite against a **dedicated**
  531. Redis container, never one that holds data you care about. Tests refuse
  532. to run if Redis isn't reachable.
  533. ## Extending the Lite build
  534. If you want to modify behavior (change the ranking formula, drop in a cross-encoder reranker, plug in a Japanese morphological tokenizer, etc.), start from the design spec shipped in this repository:
  535. - [`N3MemoryCore_MCP_Spec_EN.md`](https://github.com/NeuralNexusNote/n3mcmcp-lite/blob/main/N3MemoryCore_MCP_Spec_EN.md) — full design document (English)
  536. - [`N3MemoryCore_MCP_Spec_JP.md`](https://github.com/NeuralNexusNote/n3mcmcp-lite/blob/main/N3MemoryCore_MCP_Spec_JP.md) — 日本語版
  537. Appendix A of the spec lists optional extensions (cross-encoder reranker, save-time chunking, HyDE, Japanese morphological analysis) with drop-in points and library candidates. Use it as reference when you want to edit the code without breaking the TTL, dedup, or RediSearch contracts.
  538. ## Why N3MemoryCore? (vs. built-in memory)
  539. The auto-save *reliability* of N3MemoryCore is no better than the memory
  540. features built into modern LLM products (e.g. Claude's built-in memory)
  541. — both depend on the LLM voluntarily calling a save tool, and both share
  542. the non-determinism described in *On compliance* below. The differentiation
  543. sits elsewhere:
  544. | Aspect | Built-in memory | N3MemoryCore (Lite) |
  545. |---|---|---|
  546. | **Data ownership** | Vendor-hosted | **Your own Redis Stack on your machine** |
  547. | **Client surface** | The vendor's product only | **Any MCP-compliant client** (Claude Code, Cursor, Cline, Goose, your own app) |
  548. | **Multi-AI collaboration** | One AI's memory | **`session_id` lets multiple agents share the same memory namespace; `delete_memories_by_session` wraps up a finished task** |
  549. | **Verbatim recall** | Opaque (may be summarized) | **Parent-document contract — the full text returned as saved (code blocks as `[code omitted]`)** |
  550. | **Search internals** | Black box | **Hybrid BM25 + e5 vectors + CJK bigram + time decay + lightweight reranker, all parameters visible and tunable** |
  551. | **Inspect / control** | UI only | **`list_memories` / `delete_memory` / `delete_memories_by_session` operate on raw records** |
  552. | **Persistence** | Tied to the vendor's service lifetime | **In-memory Redis with 7-day TTL** — short-lived by design, but you own the container; pair with any persistent memory backend for long-term storage |
  553. | **Tunability** | Fixed | `half_life_days`, `chunk_threshold`, `vector_min_cos`, rerank weights — all editable |
  554. So the value of running N3MemoryCore Lite is **not** "more reliable
  555. auto-save" — it is **owning a transparent, multi-client working-memory
  556. layer** that several AIs can collaborate on under a shared `session_id`,
  557. where search behaviour is editable and getting the full saved text back is
  558. part of the contract. (For long-term, persistent storage of user-invested artifacts,
  559. pair it with any persistent memory backend.)
  560. If those properties matter to your workflow, Lite earns its keep. If you
  561. only need "the LLM remembers something across sessions" inside one
  562. vendor's product, the built-in memory is simpler.
  563. ## On compliance — MCP can persuade, not force
  564. This server cannot make the LLM call its tools. The MCP protocol gives a
  565. server only three persuasion levers:
  566. 1. **Tool descriptions** in `tools/list` — visible to the LLM on every turn.
  567. 2. **The `instructions` field** sent at session start — usually surfaced to
  568. the LLM as a system-level hint.
  569. 3. **Tool response text** — read by the LLM when it does call a tool.
  570. We use all three: tool descriptions are explicit, `instructions` lays out a
  571. rule set, and `search_memory` / `save_memory` responses end with short
  572. reminders that re-anchor the auto-save discipline mid-turn. Even with all
  573. of that, **whether the LLM follows through is non-deterministic**.
  574. Compliance depends on the model's tool-calling bias, the MCP client's
  575. prompt construction (some clients summarize or drop the `instructions`
  576. field), and competing instructions from the user prompt, `CLAUDE.md`, etc.
  577. In practice: **most turns will auto-save correctly, but some won't** —
  578. especially short answers, fact-correction turns, or turns where the LLM is
  579. heavily focused on the user's question. If a fact you wanted saved is
  580. missing next session, just say "save this" — the server is still ready to
  581. take it.
  582. ### When you need a guaranteed save
  583. Within the MCP framing, three paths bypass this non-determinism:
  584. **Path 1 — ask the LLM explicitly in your prompt** (operational workaround,
  585. immediate). Write *"save this to N3MemoryCore"* or *"record this in
  586. memory"* into your prompt. LLMs almost always honour explicit user
  587. requests. Pros: zero infrastructure, works today, works with every MCP
  588. client. Cons: cognitive load — you must remember to say it; not automatic.
  589. ### Hook-based full-transcript saving
  590. **Path 2 — Claude Code hook that saves the full transcript** (Claude Code
  591. only, deterministic). Claude Code exposes harness-level hooks (`Stop`,
  592. etc.) that the harness runs deterministically — they do not depend on the
  593. LLM remembering anything. Setup is one prompt to Claude Code:
  594. > *"After every turn, automatically save the full Claude Code transcript
  595. > to Lite."*
  596. Claude Code then provisions:
  597. - A script at `~/.claude/hooks/save_transcript.py` that reads
  598. `transcript_path` from hook input, imports `n3mc_mcp.database.Database`
  599. directly, and calls `save_memory` on the Lite DB (no MCP round-trip).
  600. - A `hooks.Stop` block in `~/.claude/settings.json` that runs the script
  601. after every assistant turn with `async: true` (so model load never
  602. blocks the UI).
  603. Behavioral notes:
  604. - **Claude can never accidentally skip a save** — the harness fires the
  605. hook regardless of what the LLM does.
  606. - No MCP round-trip overhead; the hook talks to Redis directly.
  607. - Each turn's transcript is saved as a new entry (only exact repeats are
  608. rejected — near-duplicates are kept since v1.10.0, so no update is lost).
  609. `search_memory` lists the newest version first and shows `saved=` times;
  610. if the DB grows too fast, save only the latest exchange instead of the
  611. whole transcript.
  612. - Transcripts shorter than ~200 chars are skipped as noise.
  613. - Pros: deterministic / independent of model behavior / no save anxiety.
  614. - Cons: Claude Code only (Cursor / Windsurf need a different approach) /
  615. the hook process loads the embedding model each turn (async, so no UI
  616. block, but there is CPU/IO cost) /
  617. **Lite's 7-day TTL still applies**, so transcripts saved this way still
  618. expire within a week — point the same hook at any persistent memory
  619. backend when long-term retention matters.
  620. **Path 3 — bypass MCP and call the first-party Anthropic Messages API
  621. yourself** (architecture change). Step outside MCP clients (Claude Code,
  622. etc.) and drive `messages.create` `tool_use` directly from your own
  623. application code; you can then fire `save_memory` deterministically every
  624. turn regardless of what the LLM "decided" to do. Pros: deterministic /
  625. works with any model and any client. Cons: you have to write the
  626. orchestration application.
  627. The convenience of "MCP + LLM handles it for me" and the guarantee of
  628. "every turn saves" sit at opposite ends of a tradeoff. This server packs
  629. its persuasion levers as hard as the protocol allows; any stronger
  630. guarantee is your call as the user or client implementer (and if you're
  631. on Claude Code, Path 2 is by far the lowest-cost option).
  632. ## Forking & contributing
  633. This repository is **public and Apache-2.0 licensed** — fork, modify,
  634. and run it freely. The fork-and-run path is:
  635. ```bash
  636. git clone https://github.com/<YOU>/n3mcmcp-lite
  637. cd n3mcmcp-lite
  638. # Tests FLUSHDB their Redis: use a DEDICATED test container, never your memory Redis
  639. docker run -d --name redis-stack-test --restart=no -p 127.0.0.1:6390:6379 redis/redis-stack-server:latest
  640. python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
  641. pip install -e ".[dev]"
  642. N3MC_REDIS_TEST_URL=redis://localhost:6390/0 pytest tests/ -q
  643. ```
  644. CI runs the same matrix on every push and PR — see
  645. [`.github/workflows/test.yml`](./.github/workflows/test.yml). Read
  646. [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full developer guide
  647. (EN + JP) including coding conventions, the spec-as-contract policy,
  648. and PR checklist.
  649. **To actually use the fork from Claude Code**, you do NOT need any
  650. additional setup beyond the `pip install -e ".[dev]"` above:
  651. 1. The `n3mc-workingmemory` command is now on your `PATH` (run
  652. `which n3mc-workingmemory` to confirm).
  653. 2. The repository's [`.mcp.json`](./.mcp.json) already declares the
  654. server, so the moment you `cd n3mcmcp-lite && claude`, the CLI
  655. auto-connects.
  656. 3. For other client surfaces (Claude Desktop, a different project's
  657. `.mcp.json`, auto-tool-approval), the [Quickstart Step 3
  658. table](#-quickstart--connect-to-claude-code-in-3-steps) lists the
  659. exact action.
  660. If you intend to publish your fork under a new package name, also
  661. edit the `name`, `[project.urls]`, and console-script names in
  662. [`pyproject.toml`](./pyproject.toml) before re-uploading to PyPI.
  663. ## Troubleshooting
  664. ### Windows: `pip install --upgrade` fails with `WinError 32` (file in use)
  665. Symptom:
  666. ```
  667. ERROR: Could not install packages due to an OSError: [WinError 32]
  668. The process cannot access the file because it is being used by another process:
  669. '...\Scripts\n3mc-workingmemory.exe' -> '...\Scripts\n3mc-workingmemory.exe.deleteme'
  670. ```
  671. Cause: an MCP client (Claude Code / Claude Desktop) is currently holding
  672. `n3mc-workingmemory.exe` open as a child process, so pip cannot replace
  673. the binary.
  674. Fix — pick one:
  675. 1. **Fully quit the MCP client first.** Closing the window is not enough
  676. on Windows. Open Task Manager and end every `claude` /
  677. `n3mc-workingmemory.exe` / `python.exe` process whose command line
  678. includes `n3mc-workingmemory`, then re-run `pip install --upgrade`.
  679. 2. **Use `uvx` instead of a global install** — `uvx --from
  680. n3memorycore-mcp-lite n3mc-workingmemory` runs in an isolated
  681. ephemeral environment per session, so there is no system-level
  682. `.exe` to lock.
  683. This is a Windows file-locking quirk, not a packaging defect — the wheel
  684. itself installs cleanly into a fresh venv (`python -m venv .venv &&
  685. .venv/Scripts/pip install n3memorycore-mcp-lite`).
  686. ### `~3memorycore-mcp-lite` warnings during pip install
  687. If you see lines like:
  688. ```
  689. WARNING: Ignoring invalid distribution ~3memorycore-mcp-lite
  690. ```
  691. that is pip flagging a previous install that was interrupted mid-write
  692. (typically by the file-lock issue above). The leftover directory is
  693. named with a leading `~` and is harmless but noisy. Delete it manually:
  694. ```bash
  695. # Windows
  696. rmdir /s "%LOCALAPPDATA%\Programs\Python\Python312\Lib\site-packages\~3memorycore_mcp_lite-1.5.0.dist-info"
  697. ```
  698. (Adjust the path to match your Python installation.)
  699. ## License
  700. Apache License 2.0 — see [LICENSE](./LICENSE).
  701. ---
  702. <sub>MCP Registry: `mcp-name: io.github.NeuralNexusNote/n3mc-workingmemory`</sub>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.