Server data from the Official MCP Registry
Ephemeral 7-day hybrid vector+BM25 working memory, multilingual, backed by Redis Stack.
About
Ephemeral 7-day hybrid vector+BM25 working memory, multilingual, backed by Redis Stack.
Security Report
N3MemoryCore MCP Lite is a well-architected memory server with proper authentication via owner_id validation and appropriate permissions scoping. Code quality is generally sound with good input validation and error handling. However, several moderate findings warrant attention: environment variable credential exposure, incomplete input validation on some paths, and use of `eval()` in the ranking formula code. These issues do not pose critical security risks but should be remediated before production deployment. Supply chain analysis found 3 known vulnerabilities in dependencies (0 critical, 3 high severity). Package verification found 1 issue.
3 files analyzed · 12 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"n3memorycore-mcp-lite": {
"command": "uvx",
"args": [
"n3memorycore-mcp-lite==1.6.2"
]
}
}
}Some servers take additional arguments. See the repository for details.
Documentation
View on GitHubFrom the project's GitHub README.
N3MemoryCore MCP — Lite (Ephemeral)
N3MC-MCP-Lite is an "external memory server" used by MCP-compatible editors such as Claude Code, Cursor, and Windsurf. It runs as an MCP Server so AI can save and search conversation and code context across sessions.
A NeuralNexusNote™ product — free Lite build: ephemeral hybrid (vector + BM25) memory exposed as a Model Context Protocol server, backed by Redis Stack with a 7-day TTL per entry.
💬 The MCP protocol can only nudge the LLM to call
save_memory, so which conversations actually get saved is ultimately up to the LLM. But if you ask Claude Code, it can also wire up hook-based auto-saving of every conversation. Just say "after every turn, automatically save the full Claude Code transcript to Lite" and Claude Code will drop a script under~/.claude/hooks/and add aStophook to~/.claude/settings.json. The harness runs the hook deterministically — it does not depend on the LLM remembering to callsave_memory, so Claude can never accidentally skip a save. See the Hook-based full-transcript saving section below for details.
Lite or Free? Which one to use
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 is easier.
| N3MC MCP Lite (this repository) | N3MC Free | |
|---|---|---|
| Works with | MCP clients: Claude Code, Claude Desktop, Cursor, Windsurf, … | Claude Code only |
| What gets saved | What the AI decides to save (save_memory) | Every message, automatically (hooks) |
| How long it is kept | 7 days, then deleted automatically | Until you delete it |
| What you need | Python 3.10+, Docker (Redis Stack), and the MCP client settings | Python 3.10+ |
| Setup | Start Redis Stack, install, then register the server in your MCP client | pip install n3memorycore-free, then n3mc --init |
| Good for | Users who know MCP and Docker; short-lived working memory for a project | Beginners; long-term memory for Claude Code |
- Choose Lite if you use an MCP client other than Claude Code, or you want memory that forgets by itself after a short project.
- Choose Free if you use Claude Code and want it to remember your conversations without Docker or MCP settings.
🚀 Quickstart — connect to Claude Code in 3 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 into that project, or add the same n3mc-workingmemory block to its .mcp.json. See 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 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. |
| uvx-launched (no global install needed) | Use the uvx-form command/args in your client config. See 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-baseembedding model downloads to~/.cache/huggingface/. Subsequent starts complete in seconds.
⚠️ Prerequisites (required before install)
This server does not run out of the box — you must prepare two things first:
-
Redis Stack on
localhost:6379— the Lite build stores memory in Redis + RediSearch. The easiest way is Docker:# First time only (creates the container): docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest # Every subsequent session (container already exists): docker start redis-stackRe-running the
docker runcommand after the container exists fails withConflict. The container name "/redis-stack" is already in use. Usedocker startfrom the second session onward.Why no persistence flags on the docker line: this build is deliberately volatile. Ephemerality is a design feature, not a missing capability — see the "Use cases" section below. Rather than rely on fragile shell-quoting for
--save ""(which breaks on Windows PowerShell and cmd.exe), the MCP server enforces the ephemeral state at startup by issuingCONFIG SET appendonly noandCONFIG SET save ""on every connect. If you manually re-enable persistence between sessions, it is reverted on the next Lite run. The plaindocker runabove is sufficient — the server is the source of truth for the ephemerality guarantee.Use a dedicated Redis. The server changes these settings only when the Redis holds nothing but N3MC keys. If it finds other data (a Redis you already use for something else), it leaves the persistence settings alone and shows a
shared_redisnotice — so it never makes another program lose data on the next Redis restart. N3MC Lite also needs Redis Stack (RediSearch); with plain Redis every tool answers with a hint to start Redis Stack. -
uvon yourPATH— required only for the Claude Code plugin /uvxinstall path. Not needed if you install from source.
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.
Features
- 💾 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).
- 🔍 Semantic search — Finds relevant past conversations even when the exact words differ.
- 🌐 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). - 🛡️ Encoding safety — stdio UTF-8 reconfigure on Windows (cp932 → UTF-8), lone-surrogate sanitization on every input. Same defenses as the Free build.
- 🔄 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).
- ⚡ Works automatically — Saving and searching happen automatically. The MCP
initializeresponse ships behavioral instructions, so no user action is required. - 🤖 Multi-agent ready — Multiple AI agents share one Redis. The
b_localandb_sessionbiases prioritize each project's own memories while still surfacing the team's collective knowledge. - 🏢 Team & organization support — Deploy Redis on a shared server and point
N3MC_REDIS_URLto it for team-wide memory sharing (⚠️ authentication must be handled at the Redis layer). - 🧹 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-stackwipes everything instantly. - 💰 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.
How It Works
User's message
│
▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 1. Auto-save │────▶│ 2. Semantic │────▶│ 3. Context │
│ Save last │ │ search │ │ injection │
│ response to │ │ Find related │ │ Feed to │
│ Redis │ │ memories │ │ Claude │
└──────────────┘ └──────────────┘ └──────────────┘
│
▼
Claude responds
with full context
Everything runs automatically via the behavioral instructions shipped
in the MCP initialize response. No Claude Code hooks are involved — the
only client-side setup is adding the tools to permissions.allow. No user
action required.
Relationship with Claude's built-in auto-memory
Claude Code has a built-in auto-memory system
(~/.claude/projects/.../memory/). N3MemoryCore complements it rather
than competing with it.
| Claude auto-memory | N3MemoryCore RAG | |
|---|---|---|
| Strengths | Reliable, loads every session, great for fixed facts | Conversation context, detailed history |
| Weaknesses | Cannot capture conversation flow or context | Depends on search quality; not guaranteed to surface |
| Best for | User profile, folder paths, stable settings | Conversation threads, past decisions, reasoning |
Recommended usage:
- Fixed information needed every session (folder paths, user preferences) → save to auto-memory
- 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)
Your Memory Stays on Machines You Control
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.
- Your Redis, not an N3MC cloud — Memories are stored in the Redis set by
redis_url(defaultredis://localhost:6379/0; theN3MC_REDIS_URLenvironment variable takes precedence — see Configuration). There is no N3MC account and no N3MC cloud service. Each entry expires 7 days after it was saved (ttl_seconds). - Almost nothing on disk — Besides Redis, N3MC writes only a small
config.json(see Data location). When the Redis holds nothing but N3MC data, the server turns off Redis's own saving to disk (RDB/AOF) at startup, sodocker restart redis-stackwipes every memory. In a Redis that also holds other data, it leaves those settings alone and shows ashared_redisnotice. - 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. - 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 thedocker runcommand above) depends on your Redis and firewall settings. - No telemetry — N3MC sends no usage data anywhere. The code is open, so you can check this yourself.
- You can see and remove everything —
list_memoriesshows the newest entries;delete_memoryanddelete_memories_by_sessionremove them (see Tools exposed).
What does go over the network:
- Installing —
pipanduvxdownload the package and its dependencies from PyPI; the Claude Code marketplace path fetches the plugin from theNeuralNexusNote/n3mcmcp-liteGitHub repository. - The Redis Stack image — The first
docker rundownloadsredis/redis-stack-serverfrom Docker Hub. - The embedding model download — On the first start,
intfloat/multilingual-e5-base(~440 MB) is downloaded from Hugging Face. - A Redis on another machine — If you point
redis_url/N3MC_REDIS_URLat another machine (for example a team server), every memory you save and every search goes over the network to that machine. - What the AI reads — The results of
search_memorybecome 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.
Use cases — when working memory is the right tool
The 7-day TTL and volatile Redis storage are design features, not limitations. They make this server the right fit for:
- Agentic code-generation loops — failed attempts and abandoned
designs don't bleed into the next task;
docker restart redis-stackwipes the slate clean. - Multi-agent collaboration — decisions made during one task don't contaminate unrelated follow-ups.
- Experimental / throwaway prototyping — leave it alone and memory evaporates in 7 days, no pruning needed.
- Project-scoped working memory — pin a
session_idper task / project to keep contexts cleanly separated.
If you need long-term, persistent knowledge accumulation across months or years, working memory is not the right layer. Pair this server with any persistent memory MCP — the official knowledge-graph server, your own SQLite-backed implementation, or an external service — to cover the long-term side.
What is this?
n3memorycore-mcp-lite is a local-only MCP server that gives Claude (and
any other MCP-compatible client) short-lived memory across conversations.
It stores text entries in a local Redis Stack instance with both a BM25
full-text index and a 768-dimension vector index
(intfloat/multilingual-e5-base), and
returns hybrid-ranked results.
Every operation runs on the user's machine. No API calls, no cloud storage.
Tools exposed
| Tool | Purpose |
|---|---|
search_memory | Hybrid (vector + BM25) search, ranked & time-decayed, session_id boost |
save_memory | Persist a short entry (7d TTL, exact duplicates rejected) |
list_memories | Most-recent entries, newest first |
delete_memory | Remove a specific entry by id (cascades to chunks if id is a parent doc) |
delete_memories_by_session | Bulk-delete every memory tied to a session_id — wraps up a finished project |
repair_memory | Re-create the RediSearch index if missing |
The server also ships behavioral instructions via MCP's initialize
response, asking the client to search_memory at the start of each turn
and save_memory after each meaningful exchange — so "auto-save" is
preserved without any Claude Code hooks.
ID hierarchy
N3MemoryCore identifies the origin and context of every record with
five ID fields. Most users only ever touch session_id (and rarely
agent_name); the rest are filled in automatically.
| ID | Stored in | Generated | Granularity | Purpose |
|---|---|---|---|---|
id (PK) | Redis hash | Per record (UUIDv7, time-ordered) | One record | Unique identifier for each memory — used for delete_memory and dedup. |
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). |
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). |
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. |
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. |
owner_id (one N3MC server / data owner)
└── session_id (one task / project / conversation)
└── local_id (the agent speaking inside that session)
├── agent_name (its display name: "claude-code" etc.)
└── id (one memory record)
Practical guidance:
- You should pin
session_idwhen working on a named project or task. Pass the same string (e.g."proj-alpha","task-refactor-auth") to bothsave_memoryandsearch_memory. This both ranks-up the project's own memories and gives you a one-shotdelete_memories_by_sessionfor project teardown. - You can leave
agent_nameempty for single-agent use. Set it ("claude-code","cursor", …) when multiple agents share the same Redis so audit/list output stays readable. - You should not pass
owner_idunless you specifically need to prove ownership (the server validates it againstconfig.jsonand rejects mismatches; an empty value means "use my own").
Prerequisites
1. Start Redis Stack
The Lite build requires Redis Stack (Redis + RediSearch module). The easiest way is Docker:
# First time only (creates the container):
docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest
# Every subsequent session (container already exists):
docker start redis-stack
That's it — the container exposes Redis on localhost:6379 and the
server will find it automatically. Re-running the docker run command
after the first install produces Conflict. The container name "/redis-stack" is already in use; use docker start redis-stack
thereafter.
2. Install the package
From PyPI (recommended):
pip install n3memorycore-mcp-lite
Or zero-install via uvx (the Claude Code plugin uses this path):
uvx --from n3memorycore-mcp-lite n3mc-workingmemory
From source (if you want to edit the code):
git clone https://github.com/NeuralNexusNote/n3mcmcp-lite
cd n3mcmcp-lite
pip install -e .
The first run downloads the ~400 MB embedding model from Hugging Face
into the standard ~/.cache/huggingface/ directory.
First install requires internet access to three resources:
- github.com — when
/plugin marketplace add NeuralNexusNote/n3mcmcp-literegisters the plugin (skip this step if you install viauvxor from source instead).- pypi.org — when
uvx --from n3memorycore-mcp-lite(orpip install) resolves the package.- huggingface.co — when the server first starts and downloads
intfloat/multilingual-e5-base(~400 MB) into~/.cache/huggingface/.All three fail with explicit, time-bounded errors when offline; none hang. Subsequent starts use only the local cache and require no internet.
Configure a client
Claude Desktop (and the "Code" tab inside Claude Desktop)
If you are using the Claude Desktop application — including its
built-in Code tab — configure MCP via the desktop config file, NOT
via .mcp.json (which is only read by the standalone claude CLI).
Add to ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"n3mc-workingmemory": {
"command": "n3mc-workingmemory",
"args": []
}
}
}
Windows tip: if Claude Desktop fails to spawn the server with the
bare command name above (the hammer/tool icon never appears), replace
"command" with the absolute path to the installed .exe, for example:
"command": "C:\\Users\\<YOU>\\AppData\\Local\\Programs\\Python\\Python312\\Scripts\\n3mc-workingmemory.exe"
Run where n3mc-workingmemory in a terminal to find the exact path on
your machine.
After editing the config, fully quit Claude Desktop — closing the window is not enough. Right-click the Claude icon in the system tray (or use Task Manager) and terminate every Claude process, then relaunch.
Claude Code (standalone CLI)
This section applies ONLY to the claude command-line tool, not to the
Claude Desktop "Code" tab (see above for that).
.mcp.json is already included in this repository. Clone the repo,
install the package, and the Claude Code CLI connects automatically — no
manual configuration needed.
For other projects, add the following to that project's .mcp.json:
{
"mcpServers": {
"n3mc-workingmemory": {
"type": "stdio",
"command": "n3mc-workingmemory",
"args": []
}
}
}
Auto-approve tool calls (Claude Code only)
By default, Claude Code prompts the user for each MCP tool call. For a
fully automatic memory loop — so the connected AI never blocks on an
"Allow?" prompt — the n3mc-workingmemory tools must be listed under
permissions.allow in Claude Code settings.
Plugin install auto-configures this — when you install via
/plugin install n3mc-workingmemory@neuralnexusnote, a SessionStart
hook runs hooks/install_permissions.py,
which idempotently adds two wildcard rules to permissions.allow in
~/.claude/settings.json:
mcp__plugin_n3mc-workingmemory_n3mc-workingmemory__*— the tools as the plugin provides them (Claude Code names plugin MCP toolsmcp__plugin_<plugin>_<server>__<tool>, and permission rules must use that form)mcp__n3mc-workingmemory__*— the same tools for a directly registered server (claude mcp add,.mcp.json)
The wildcards cover all seven tools, including recall_thread. The hook
only writes when a rule is missing and never touches other entries. If
settings.json is read-only, locked by policy or not valid JSON, the hook
changes nothing and shows a warning with the rule to add yourself.
(Up to v1.9.x the hook added plain mcp__n3mc-workingmemory__<tool> names,
which do not match the plugin's tool names, so plugin users were asked for
permission on every call.)
The hooks.json command tries python → py (Windows Python Launcher) →
python3. If none is on PATH, a Python-free last step shows a warning
(systemMessage) telling you that the tools could not be pre-approved and
what to add. A missing uvx (the plugin launches the MCP server via
uvx --from n3memorycore-mcp-lite n3mc-workingmemory) is reported the same
way, with install commands (pipx install uv,
curl -LsSf https://astral.sh/uv/install.sh | sh).
If you installed without the plugin (e.g. claude mcp add or a manual
.mcp.json), add the rule below to ~/.claude/settings.json (user-global,
recommended) or .claude/settings.json (per-project). If you installed the
plugin but have no Python, use mcp__plugin_n3mc-workingmemory_n3mc-workingmemory__*
instead:
{
"permissions": {
"allow": [
"mcp__n3mc-workingmemory__*"
]
}
}
Without this, every save_memory / search_memory call surfaces an
approval prompt and the AI blocks if the user is away. Claude Desktop
has no per-tool permission gate, so this step is not needed there.
Data location
The Lite build does not store a database on disk — memories live in
Redis and expire automatically. Only a small config.json sits in
~/.n3mc-workingmemory/ (Windows: %USERPROFILE%\.n3mc-workingmemory\).
Override with the N3MC_DATA_DIR environment variable.
Since v1.10.0 the file is in the home directory instead of the platform
app-data directory: the Microsoft Store build of the Claude desktop app
redirects %LOCALAPPDATA% for the MCP servers it starts, which gave one PC
two configs and two owner_ids, so memories saved from the desktop app
were invisible to claude in a terminal. On first start the old config is
copied over once (the old file is left in place).
Configuration
On first run, config.json is auto-generated with random UUIDs for
owner_id and local_id. Editable defaults:
{
"owner_id": "<uuid>",
"local_id": "<uuid>",
"redis_url": "redis://localhost:6379/0",
"ttl_seconds": 604800,
"half_life_days": 3,
"bm25_min_threshold": 0.1,
"search_result_limit": 20,
"min_score": 0.2,
"vector_min_cos": 0.85,
"relative_min_score_ratio": 0.6,
"min_results": 3,
"version_order_enabled": true,
"version_sim_threshold": 0.98,
"version_min_chars": 100,
"search_query_max_chars": 2000,
"chunk_threshold": 400,
"chunk_overlap": 100,
"access_count_enabled": true,
"access_count_weight": 0.02,
"access_count_max_boost": 0.5,
"ttl_refresh_on_search": true,
"ttl_refresh_top_k": 5,
"lexical_rerank_enabled": true,
"rerank_weight": 0.3,
"rerank_phrase_weight": 0.2,
"b_session_match": 1.0,
"b_session_mismatch": 0.6,
"skip_code_blocks": false
}
redis_url— connection URL;N3MC_REDIS_URLenv var takes precedence.ttl_seconds— TTL on every new memory and sha-guard (default 7 d).vector_min_cos— how close (cosine) a record must be to the query to become a vector candidate (default0.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 withmultilingual-e5-base, so re-measure it if you changeembedding_model.relative_min_score_ratio— drop results scoring below this ratio × the top score (default0.6;0.0disables).min_results(since 1.10.1) — when fewer results than this pass the floors,search_memoryadds the closest of the rows it dropped, up to this total, under a separate heading#### Possibly related (weak matches — may be unrelated)(default3;0turns 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.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 itssaved=time.- Settings take effect when the MCP server restarts (restart your MCP client). If
config.jsonhas a typo and cannot be read, it is left untouched and the server runs on defaults; the firstsearch_memoryresult says so. Write numbers without quotes. chunk_threshold/chunk_overlap— sliding-window size and overlap (chars). Bodies longer than the threshold trigger the parent-document + chunks path for verbatim recall.access_count_*— access-frequency auto-importance; top-K search hits receive a capped boost on future queries.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).lexical_rerank_*/rerank_weight/rerank_phrase_weight— lightweight post-fusion lexical reranker (CPU-only).b_session_match/b_session_mismatch— multiplicative ranking boost for rows whose storedsession_idmatches (default1.0) vs. rows from other projects (0.6). Pass the samesession_idtosave_memoryandsearch_memoryto surface a project's memories above unrelated cross-project rows in the same Redis instance. Set both to1.0to disable the bias.skip_code_blocks— whentrue,save_memoryrejects any payload containing a triple-backtick fence (```) and returnsstatus: "skipped_code". Defaultfalse. Set totrueif 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).
See the spec §6 for the complete field-by-field reference.
Multilingual support
Built-in, CPU-only, no LLM and no GPU required. Search and dedup behave the same regardless of how the user types the same word:
| Layer | What it does | Real-world example |
|---|---|---|
| NFKC normalization | Folds compatibility forms before SHA / embedding / BM25 | アルファ ↔ アルファ, 123 ↔ 123, fi ↔ fi |
| Bigram BM25 side channel | Overlapping bigrams emitted for space-less scripts | 記憶装置 → 記憶 憶装 装置; same for Korean (안녕하세요), Thai (สวัสดี), Lao, Myanmar, Khmer |
| Diacritic fold | Latin/Greek/Cyrillic words also indexed without combining marks | café matches cafe, Ångström matches Angstrom |
| multilingual-e5-base embedding | Multilingual semantic space across 100+ languages | Cross-language paraphrase retrieval |
These run automatically on every save_memory and search_memory call.
The raw content field is never rewritten — verbatim recall (spec §3.11)
still returns the original bytes byte-for-byte.
Encoding safety
Two layers of defense run before any tool body executes (spec §3.13). Same guards as the Free build, ported one-to-one:
- stdio UTF-8 reconfigure — at module import,
sys.stdin/sys.stdout/sys.stderrare switched toencoding="utf-8". On Windows-Japanese hosts the default console code page is cp932, which would otherwise mangle every non-ASCII byte on the MCP JSON-RPC channel. POSIX systems are already UTF-8, so the call is a safe no-op. - Lone-surrogate sanitization — every
save_memory.contentandsearch_memory.queryis passed throughsanitize_surrogates()before any.encode("utf-8")call. Lone UTF-16 surrogate halves (U+D800–U+DFFF) appear when Windows subprocess pipes deliver UTF-8 bytes that Python's decoder maps witherrors="surrogateescape"— they round-trip throughjson.loadsbut raiseUnicodeEncodeErrorat SHA1 / Redis HSET / embedding time. Without the guard the entire write is silently lost. The function is recursive so JSON payloads with surrogates buried inside are cleaned in one pass.
If a save payload consists entirely of surrogates, sanitization collapses
it to the empty string and the regular empty-content rejection path
applies — {"status":"error","saved":false,"reason":"empty content"}.
Content with no visible character (only whitespace, control / format
characters such as \x00 or U+200B, separators or variation selectors) is
rejected with empty content (no visible characters). Everything else is
stored verbatim, including NUL and zero-width characters inside visible text.
Ranking formula
final_score = (0.7 * cosine_similarity + 0.3 * keyword_relevance) * time_decay * b_local * b_session
time_decay = 2 ^ (-days_elapsed / half_life_days) (default half-life: 3 days)
b_local = clamp(0.5, 2.0, stored_importance + access_boost)
access_boost = min(0.5, access_count * 0.02)
b_session = b_session_match (default 1.0) if row.session_id == effective_session
= b_session_mismatch (default 0.6) otherwise
With a default 3-day half-life (shorter than the 7-day TTL), time_decay
is meaningful in the Lite build: a fresh memory scores 1.0, a 3-day-old
one exactly 0.5, and a 7-day-old (near-expiry) entry ≈ 0.20 — pushing
recent context ahead in the ranking.
Auto-importance (access-frequency boost): each time search_memory
returns a memory in its top 5 hits, that memory's access_count is
incremented by 1 and b_local rises by 0.02 on future queries (capped at
+0.5). No LLM judgement required — frequently-useful memories naturally
float to the top through CPU-only self-tuning.
Development
# Start Redis Stack first (see Prerequisites), then:
pip install -e ".[dev]"
pytest tests/ -q
Tests target Redis DB index 0 (configurable via N3MC_REDIS_TEST_URL)
and FLUSHDB it before/after each test. RediSearch refuses to create
indexes outside DB 0 (Cannot create index on db != 0), so a separate
test DB isn't an option — run the test suite against a dedicated
Redis container, never one that holds data you care about. Tests refuse
to run if Redis isn't reachable.
Extending the Lite build
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:
N3MemoryCore_MCP_Spec_EN.md— full design document (English)N3MemoryCore_MCP_Spec_JP.md— 日本語版
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.
Why N3MemoryCore? (vs. built-in memory)
The auto-save reliability of N3MemoryCore is no better than the memory features built into modern LLM products (e.g. Claude's built-in memory) — both depend on the LLM voluntarily calling a save tool, and both share the non-determinism described in On compliance below. The differentiation sits elsewhere:
| Aspect | Built-in memory | N3MemoryCore (Lite) |
|---|---|---|
| Data ownership | Vendor-hosted | Your own Redis Stack on your machine |
| Client surface | The vendor's product only | Any MCP-compliant client (Claude Code, Cursor, Cline, Goose, your own app) |
| 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 |
| Verbatim recall | Opaque (may be summarized) | Parent-document contract — byte-exact full text returned |
| Search internals | Black box | Hybrid BM25 + e5 vectors + CJK bigram + time decay + lightweight reranker, all parameters visible and tunable |
| Inspect / control | UI only | list_memories / delete_memory / delete_memories_by_session operate on raw records |
| 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 |
| Tunability | Fixed | half_life_days, chunk_threshold, vector_min_cos, rerank weights — all editable |
So the value of running N3MemoryCore Lite is not "more reliable
auto-save" — it is owning a transparent, multi-client working-memory
layer that several AIs can collaborate on under a shared session_id,
where search behaviour is editable and verbatim recall is contractually
guaranteed. (For long-term, persistent storage of user-invested artifacts,
pair it with any persistent memory backend.)
If those properties matter to your workflow, Lite earns its keep. If you only need "the LLM remembers something across sessions" inside one vendor's product, the built-in memory is simpler.
On compliance — MCP can persuade, not force
This server cannot make the LLM call its tools. The MCP protocol gives a server only three persuasion levers:
- Tool descriptions in
tools/list— visible to the LLM on every turn. - The
instructionsfield sent at session start — usually surfaced to the LLM as a system-level hint. - Tool response text — read by the LLM when it does call a tool.
We use all three: tool descriptions are explicit, instructions lays out a
rule set, and search_memory / save_memory responses end with short
reminders that re-anchor the auto-save discipline mid-turn. Even with all
of that, whether the LLM follows through is non-deterministic.
Compliance depends on the model's tool-calling bias, the MCP client's
prompt construction (some clients summarize or drop the instructions
field), and competing instructions from the user prompt, CLAUDE.md, etc.
Documentation truncated — see the full README on GitHub.
Reviews
No reviews yet
Be the first to review this server!
More AI & ML MCP Servers
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
MCP Marketplace
Freeby mcp-marketplace · Developer Tools
Search and install MCP servers from inside your AI client.
mcp-creator-python
Freeby mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Lharries · Communication
Read, search, and send WhatsApp messages through your AI assistant
FinAgent
Freeby mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.
Memory
Freeby Modelcontextprotocol · Productivity
Knowledge graph-based persistent memory across sessions
