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

🚀 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

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:

   bash

   Copy

   # 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.

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

• 💾 Fully local — Your conversations stay in your own Redis instance. Nothing sent to the cloud.
• 🔍 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, 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.

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)

Use cases — when working memory is the right tool