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](#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//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.

---

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

| | 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)

---

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

| Tool | Purpose | | ----------------------------- | -------------------------------------------------------------------------------- | | search_memory | Hybrid (vector + BM25) search, ranked & time-decayed, session_id boost | | save_memory | Persist a short entry (7d TTL, dedup: exact + near-duplicate) | | 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_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:

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [NeuralNexusNote](https://github.com/NeuralNexusNote)
- **Source:** [NeuralNexusNote/n3mcmcp-lite](https://github.com/NeuralNexusNote/n3mcmcp-lite)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.