N3MemoryCore Lite (Working Memory)

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.

🇯🇵 [日本語版はこちら](./README_JP.md)

🛡️ [Development Philosophy](./PHILOSOPHY.md)

---

🚀 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:

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

1. [`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.

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

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

| delete_memory