Back to Browse

N3mcmcp Lite MCP Server

AI & MLUse Caution4.2MCP RegistryLocal
Free

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

4.2
Use Caution4.2High Risk

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.

HTTP Network Access

Connects to external APIs or services over the internet.

env_vars

Check that this permission is expected for this type of plugin.

File System Read

Reads files on your machine. Normal for tools that analyze or process local data.

File System Write

Writes or modifies files on your machine. Check that this is expected for the tool.

process_spawn

Check that this permission is expected for this type of plugin.

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 GitHub

From 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 a Stop hook to ~/.claude/settings.json. The harness runs the hook deterministically — it does not depend on the LLM remembering to call save_memory, so Claude can never accidentally skip a save. See the Hook-based full-transcript saving section below for details.

🇯🇵 日本語版はこちら 🛡️ Development Philosophy

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 withMCP clients: Claude Code, Claude Desktop, Cursor, Windsurf, …Claude Code only
What gets savedWhat the AI decides to save (save_memory)Every message, automatically (hooks)
How long it is kept7 days, then deleted automaticallyUntil you delete it
What you needPython 3.10+, Docker (Redis Stack), and the MCP client settingsPython 3.10+
SetupStart Redis Stack, install, then register the server in your MCP clientpip install n3memorycore-free, then n3mc --init
Good forUsers who know MCP and Docker; short-lived working memory for a projectBeginners; 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

ClientWhat 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 directoryCopy .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-approvalOne 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-base embedding 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:

  1. 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-stack
    

    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.

    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 issuing CONFIG SET appendonly no and CONFIG SET save "" on every connect. If you manually re-enable persistence between sessions, it is reverted on the next Lite run. The plain docker run above 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_redis notice — 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.

  2. uv on your PATH — required only for the Claude Code plugin / uvx install 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 initialize response ships behavioral instructions, so no user action is required.
  • 🤖 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.
  • 🏢 Team & organization support — Deploy Redis on a shared server and point N3MC_REDIS_URL to 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-stack wipes 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-memoryN3MemoryCore RAG
StrengthsReliable, loads every session, great for fixed factsConversation context, detailed history
WeaknessesCannot capture conversation flow or contextDepends on search quality; not guaranteed to surface
Best forUser profile, folder paths, stable settingsConversation 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 (default redis://localhost:6379/0; the N3MC_REDIS_URL environment 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, 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.
  • 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 the docker run command 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_memories shows the newest entries; delete_memory and delete_memories_by_session remove them (see Tools exposed).

What does go over the network:

  • 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.
  • The Redis Stack image — The first docker run downloads redis/redis-stack-server from 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_URL at 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_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.

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-stack wipes 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_id per 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

ToolPurpose
search_memoryHybrid (vector + BM25) search, ranked & time-decayed, session_id boost
save_memoryPersist a short entry (7d TTL, exact duplicates rejected)
list_memoriesMost-recent entries, newest first
delete_memoryRemove a specific entry by id (cascades to chunks if id is a parent doc)
delete_memories_by_sessionBulk-delete every memory tied to a session_id — wraps up a finished project
repair_memoryRe-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.

IDStored inGeneratedGranularityPurpose
id (PK)Redis hashPer record (UUIDv7, time-ordered)One recordUnique identifier for each memory — used for delete_memory and dedup.
owner_idconfig.jsonFirst startup (UUIDv4)Owner / installationIdentifies 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.jsonFirst startup (UUIDv4)Agent / installUUIDv4 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_idIn-memory or supplied by clientPer task / project / conversation (string)Task / project / conversationSurfaces 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_nameRedis hashPer save_memory call (free-form string)Agent display labelHuman-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_id when working on a named project or task. Pass the same string (e.g. "proj-alpha", "task-refactor-auth") to both save_memory and search_memory. This both ranks-up the project's own memories and gives you a one-shot delete_memories_by_session for project teardown.
  • You can leave agent_name empty 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_id unless you specifically need to prove ownership (the server validates it against config.json and 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:

  1. github.com — when /plugin marketplace add NeuralNexusNote/n3mcmcp-lite registers the plugin (skip this step if you install via uvx or from source instead).
  2. pypi.org — when uvx --from n3memorycore-mcp-lite (or pip install) resolves the package.
  3. 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 tools mcp__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_URL env 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 (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.
  • relative_min_score_ratio — drop results scoring below this ratio × the top score (default 0.6; 0.0 disables).
  • 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.
  • 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.
  • 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.
  • 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 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.
  • skip_code_blocks — when true, save_memory rejects any payload containing a triple-backtick fence (```) and returns status: "skipped_code". Default false. 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).

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:

LayerWhat it doesReal-world example
NFKC normalizationFolds compatibility forms before SHA / embedding / BM25アルファ ↔ アルファ, 123 ↔ 123, fi ↔ fi
Bigram BM25 side channelOverlapping bigrams emitted for space-less scripts記憶装置 → 記憶 憶装 装置; same for Korean (안녕하세요), Thai (สวัสดี), Lao, Myanmar, Khmer
Diacritic foldLatin/Greek/Cyrillic words also indexed without combining markscafé matches cafe, Ångström matches Angstrom
multilingual-e5-base embeddingMultilingual semantic space across 100+ languagesCross-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:

  1. stdio UTF-8 reconfigure — at module import, sys.stdin / sys.stdout / sys.stderr are switched to encoding="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.
  2. Lone-surrogate sanitization — every save_memory.content and search_memory.query is passed through sanitize_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 with errors="surrogateescape" — they round-trip through json.loads but raise UnicodeEncodeError at 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:

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:

AspectBuilt-in memoryN3MemoryCore (Lite)
Data ownershipVendor-hostedYour own Redis Stack on your machine
Client surfaceThe vendor's product onlyAny MCP-compliant client (Claude Code, Cursor, Cline, Goose, your own app)
Multi-AI collaborationOne AI's memorysession_id lets multiple agents share the same memory namespace; delete_memories_by_session wraps up a finished task
Verbatim recallOpaque (may be summarized)Parent-document contract — byte-exact full text returned
Search internalsBlack boxHybrid BM25 + e5 vectors + CJK bigram + time decay + lightweight reranker, all parameters visible and tunable
Inspect / controlUI onlylist_memories / delete_memory / delete_memories_by_session operate on raw records
PersistenceTied to the vendor's service lifetimeIn-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
TunabilityFixedhalf_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:

  1. Tool descriptions in tools/list — visible to the LLM on every turn.
  2. The instructions field sent at session start — usually surfaced to the LLM as a system-level hint.
  3. 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!