# N3MemoryCore Lite (Working Memory)

> Ephemeral 7-day hybrid vector+BM25 working memory, multilingual, backed by Redis Stack.

- **Type:** MCP server
- **Install:** `agentstack add mcp-neuralnexusnote-n3mcmcp-lite`
- **Verified:** Pending review
- **Seller:** [NeuralNexusNote](https://agentstack.voostack.com/s/neuralnexusnote)
- **Installs:** 0
- **Latest version:** 1.6.2
- **License:** Apache-2.0
- **Upstream author:** [NeuralNexusNote](https://github.com/NeuralNexusNote)
- **Source:** https://github.com/NeuralNexusNote/n3mcmcp-lite

## Install

```sh
agentstack add mcp-neuralnexusnote-n3mcmcp-lite
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
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:

```bash
pip install n3memorycore-mcp-lite
```

**(b) From a fork (you cloned this repo)** — contributors / customizers:

```bash
git clone https://github.com//n3mcmcp-lite
cd n3mcmcp-lite
pip install -e ".[dev]"
```

**(c) Zero-install via uvx** — no global install, isolated env:

```bash
# 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.
2. **[`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**.

|                 | 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`](https://huggingface.co/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:

```b

…

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

## Pricing

- **Free** — Free

## Versions

- **1.6.2** — security scan: pending review — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-neuralnexusnote-n3mcmcp-lite
- Seller: https://agentstack.voostack.com/s/neuralnexusnote
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.