N3MemoryCore Lite (Working Memory)

N3MemoryCore MCP — Lite（临时）

N3MC-MCP-Lite 是一种“外部记忆服务”，供 Claude Code、Cursor 和 Windsurf 等兼容 MCP 的编辑器使用。 它以 MCP 服务的形式运行，让 AI 能够跨会话保存和搜索对话及代码上下文。

NeuralNexusNote™ 产品 — 免费 Lite 版本：临时混合记忆（向量 + BM25），通过 Model Context Protocol 服务提供，并由 Redis Stack 提供支持，每条记忆的 TTL 为 7 天。

💬 MCP 协议只能提醒大模型调用 save_memory，因此最终哪些对话会被保存，取决于大模型。但如果你向 Claude Code 提出要求，它也可以配置基于钩子的自动保存功能，保存每段对话。 只需说“每轮结束后，自动将完整的 Claude Code transcript 保存到 Lite”，Claude Code 就会在 ~/.claude/hooks/ 下创建脚本，并向 ~/.claude/settings.json 添加一个 Stop 钩子。 执行环境会确定性地运行该钩子——它不依赖大模型记得调用 save_memory，因此 Claude 绝不会意外漏掉保存。详情请参阅下文的 基于钩子的完整 transcript 保存部分。

🇯🇵 日语版请见此处 🛡️ 开发理念

---

🚀 快速开始 — 3 步连接到 Claude Code

从“什么都没安装”到“Claude Code 正在使用 N3MC 记忆”的最快路径。选择适合你的安装方式（PyPI / fork / uvx），然后将服务添加到客户端配置中。涵盖 Claude Code CLI 和 Claude Desktop。

步骤 1 — 启动 Redis Stack

docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest
# (Subsequent sessions: `docker start redis-stack`)

步骤 2 — 安装软件包（任选一种）

最快方式 — Claude Code marketplace。 只需两条命令即可完成安装和 MCP 配置。在 Claude Code 中运行：

/plugin marketplace add NeuralNexusNote/n3mcmcp-lite
/plugin install n3mc-workingmemory@neuralnexusnote

然后运行 /reload-plugins，并跳过步骤 3 — 插件清单会处理 MCP 配置。 以下手动选项仍适用于 fork、自定义配置和 Claude Desktop。

---

(a) 从 PyPI 安装 — 适用于大多数用户：

pip install n3memorycore-mcp-lite

(b) 从 fork 安装（你已克隆此仓库） — 适用于贡献者 / 定制者：

git clone https://github.com/<YOU>/n3mcmcp-lite
cd n3mcmcp-lite
pip install -e ".[dev]"

(c) 通过 uvx 零安装 — 无需全局安装，使用隔离环境：

# Just verify it runs; the actual launch is handled by your MCP client config:
uvx --from n3memorycore-mcp-lite n3mc-workingmemory --help

完成步骤 2 后，n3mc-workingmemory 命令已添加到你的 PATH。运行 where n3mc-workingmemory（Windows）或 which n3mc-workingmemory （macOS/Linux）进行确认。

步骤 3 — 将其接入 MCP 客户端

客户端	操作
Claude Code（CLI），此仓库的工作树	已提交 .mcp.json — 只需 cd 进入仓库并运行 claude。CLI 会在下次提示时自动连接。
Claude Code（CLI），其他项目目录	将 .mcp.json 复制到该项目，或将相同的 n3mc-workingmemory 配置块添加到其 .mcp.json。参见 Claude Code（独立 CLI）。
Claude Desktop（包括其内置的“Code”选项卡）	编辑 claude_desktop_config.json（路径因操作系统而异）。参见 Claude Desktop。
启用了工具自动批准的 Claude Code	在 ~/.claude/settings.json 中额外添加一个配置块，这样 AI 就不会被“Allow?”提示阻塞。参见 自动批准工具调用。
通过 uvx 启动（无需全局安装）	在客户端配置中使用 uvx 形式的 command/args。参见 Claude Code（独立 CLI）。

完成。连接 Claude Code 后，服务的行为指令便会生效 — search_memory 会在每轮开始时运行，save_memory 会在每次有意义的交流后运行，全部自动执行。

仅首次调用可能需要 30–60 秒 — ~400 MB 的 intfloat/multilingual-e5-base 嵌入模型会下载到 ~/.cache/huggingface/。后续启动只需几秒钟。

---

⚠️ 前置条件（安装前必须满足）

此服务无法开箱即用——你必须先准备好两项内容：

1. 在 localhost:6379 上运行 Redis Stack——Lite 版本会将记忆存储在 Redis + RediSearch 中。最简单的方式是使用 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
   

   容器已存在后再次运行 docker run 命令会失败，并提示 Conflict. The container name "/redis-stack" is already in use。从第二个会话开始，请使用 docker start。

   为什么 docker 命令行中没有持久化标志：此版本是 刻意设计为易失的。短暂性是一项设计特性，而非缺失的 功能——请参阅下方的“使用场景”部分。为避免依赖脆弱的 shell 引号处理来设置 --save ""（这会在 Windows PowerShell 和 cmd.exe 中出问题），MCP 服务会在每次连接时通过执行 CONFIG SET appendonly no 和 CONFIG SET save ""，在启动时强制启用易失状态。如果你在 会话之间手动重新启用持久化，下次运行 Lite 时会将其恢复。 上方的普通 docker run 命令已足够——易失性保证以服务本身的 设置为准。

2. 确保 uv 位于你的 PATH 中——仅 Claude Code 插件 / uvx 安装方式需要。如果从源代码安装，则不需要。

如果无法访问 Redis，服务会拒绝启动；如果没有 uv，Claude Code 插件将无法启动。在运行 /plugin install 或配置任何客户端之前，请先安装这两项。

---

功能

• 💾 完全本地运行——对话保存在你自己的 Redis 实例中。不会向云端发送任何内容。
• 🔍 语义搜索——即使具体用词不同，也能找到相关的过往对话。
• 🌐 开箱即用的多语言支持——仅使用 CPU，无需 LLM/GPU。NFKC 折叠（ｱﾙﾌｧ↔アルファ、１２３↔123、连字），支持日语 / 中文 / 韩语 / 泰语 / 老挝语 / 缅甸语 / 高棉语双字覆盖率，并支持拉丁文字的变音符号交叉匹配（café↔cafe）。
• 🛡️ 编码安全——在 Windows 上重新配置 stdio UTF-8（cp932 → UTF-8），并对每个输入进行孤立代理项清理。与 Free 版本采用相同的防护措施。
• 🔄 跨会话上下文——工作记忆可保留 7 天（通过 Redis TTL 自动过期；如需更长保留时间，可搭配任何持久化记忆后端）。
• ⚡ 自动运行——记忆的保存和搜索均会自动进行。MCP initialize 响应会附带行为指令，因此无需用户操作。
• 🤖 支持多 Agent——多个 AI Agent 可共用一个 Redis。b_local 和 b_session 偏置会优先显示各项目自己的记忆，同时也会展示团队的集体知识。
• 🏢 支持团队和组织——在共享服务上部署 Redis，并将 N3MC_REDIS_URL 指向该服务，即可共享团队记忆（⚠️ 必须在 Redis 层处理身份验证）。
• 🧹 易失性是一项设计特性——7 天自动过期意味着失败的尝试和放弃的设计不会影响下一个任务。docker restart redis-stack 可立即清除所有内容。
• 💰 减少令牌浪费——无需再重复解释过去的上下文。记忆搜索使用本地嵌入模型（intfloat/multilingual-e5-base），不消耗任何 Claude 令牌；准确注入上下文也意味着更少的更正和来回沟通。

工作原理

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

所有操作都会通过 MCP initialize 响应中附带的行为指令自动运行。不涉及 Claude Code 钩子——客户端只需将工具添加到 permissions.allow 即可。无需用户操作。

与 Claude 内置自动记忆的关系

Claude Code 内置了自动记忆系统 （~/.claude/projects/.../memory/）。N3MemoryCore 是对它的补充，而非竞争者。

	Claude 自动记忆	N3MemoryCore RAG
优势	可靠，每次会话都会加载，非常适合固定事实	对话上下文、详细历史记录
劣势	无法捕获对话流程或上下文	依赖搜索质量；不保证一定能检索到
最适合	用户资料、文件夹路径、稳定设置	对话线程、过往决策、推理过程

推荐用法：

• 每次会话都需要的固定信息（文件夹路径、用户偏好）→ 保存到自动记忆中
• 对话上下文和历史记录（讨论线程、过往决策）→ 由 N3MemoryCore 自动累积（保留 7 天；若需更长时间保留，请搭配持久化记忆后端）

---

使用场景——工作记忆适用的情况

7 天 TTL 和易失性 Redis 存储是设计特性，而非限制。它们让此服务特别适用于：

• Agent 式代码生成循环——失败的尝试和放弃的设计不会影响下一个任务；docker restart redis-stack 可以清空所有记录。
• 多 Agent 协作——某个任务期间做出的决策不会污染无关的后续任务。
• 实验性／一次性原型开发——无需处理，记忆会在 7 天后自动消失，无需清理。
• 项目范围内的工作记忆——为每个任务／项目指定一个 session_id，以清晰地隔离上下文。

如果你需要跨越数月或数年的长期持久知识积累，工作记忆并不适合承担这一层。将此服务与任意持久化记忆 MCP 搭配使用——官方知识图谱服务、自行实现的 SQLite 后端，或外部服务——即可满足长期记忆需求。

这是什么？

n3memorycore-mcp-lite 是一款仅在本地运行的 MCP 服务，为 Claude（以及任何其他兼容 MCP 的客户端）提供跨对话的短期记忆。 它会将文本条目存储在本地 Redis Stack 实例中，并同时建立 BM25 全文索引和 768 维向量索引 （intfloat/multilingual-e5-base），然后返回混合排序结果。

所有操作都在用户的计算机上运行。不会调用 API，也不会使用云存储。

提供的工具

工具	用途
search_memory	混合搜索（向量 + BM25），按相关性和时间衰减排序，并提升 session_id 匹配结果
save_memory	保存一条简短记录（TTL 为 7 天，去重：精确匹配 + 近似重复）
list_memories	按时间倒序列出最近的记录
delete_memory	按 ID 删除指定记录（如果 ID 属于父文档，则会级联删除其分块）
delete_memories_by_session	批量删除与某个 session_id 关联的所有记忆——用于结束已完成的项目
repair_memory	在 RediSearch 索引缺失时重新创建

该服务还会通过 MCP 的 initialize 响应提供行为指令，要求客户端在每轮开始时调用 search_memory， 并在每次有意义的交流后调用 save_memory——这样无需使用任何 Claude Code 钩子，也能保留“自动保存”功能。

ID 层级

N3MemoryCore 使用五个 ID 字段标识每条记录的来源和上下文。大多数用户只会接触 session_id（偶尔会用到 agent_name）；其余字段都会自动填充。

ID	存储位置	生成方式	粒度	用途
id (PK)	Redis 哈希	每条记录生成（UUIDv7，按时间排序）	一条记录	每条记忆的唯一标识符——用于 delete_memory 和去重。
owner_id	config.json	首次启动时生成（UUIDv4）	所有者 / 安装	标识数据归谁所有。每次 save_memory 时都会验证；不匹配的载荷会被拒绝，并报错 owner_id mismatch。作为 TAG 字段存储；筛选在 Python 中进行（参见规范 §3.12）。
local_id (agent_id)	config.json	首次启动时生成（UUIDv4）	Agent / 安装	此安装的 UUIDv4 标识符。每行都会存储该字段，以兼容未来的持久化变体，但不会参与 Lite 的 b_local 排序——b_local 仅根据 stored_importance + access_count 计算（参见排序公式）。
session_id	内存中或由客户端提供	每个任务 / 项目 / 对话一个（字符串）	任务 / 项目 / 对话	将同一任务 / 项目的记忆集中呈现。影响 b_session 排序偏置（b_session_match=1.0，b_session_mismatch=0.6），使当前聊天的记忆在同一个 Redis 实例中排在无关跨项目记录之前。也是 delete_memories_by_session 的筛选键。解析顺序：单次调用参数 → N3MC_SESSION_ID 环境变量 → 每个进程的 UUIDv4 备用值。
agent_name	Redis 哈希	每次 save_memory 调用时生成（自由格式字符串）	Agent 显示标签	便于人类识别的标签（例如 "claude-code"、"claude-desktop"）。不用于排序——仅用于显示 / 审计。

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)

实用建议：

• 处理有名称的项目或任务时，建议固定使用 session_id。 将同一个字符串（例如 "proj-alpha"、"task-refactor-auth"）同时传给 save_memory 和 search_memory。这样既能提高项目自身记忆的排序优先级，也能在项目结束时一次性调用 delete_memories_by_session 删除记忆。
• 单 Agent 使用时，agent_name 可以留空。 多个 Agent 共用同一个 Redis 时，请设置此字段（"claude-code"、"cursor"、…），以便审计 / 列表输出更易读。
• 除非确实需要证明所有权，否则不要传入 owner_id。 服务会根据 config.json 验证该字段并拒绝不匹配的值；值为空表示“使用我自己的”。

前置条件

1. 启动 Redis Stack

Lite 构建需要 Redis Stack（Redis + RediSearch 模块）。最简单的方法是使用 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

就这么简单——容器会在 localhost:6379 上开放 Redis，服务会自动找到它。首次安装后再次运行 docker run 命令会出现 Conflict. The container name "/redis-stack" is already in use；此后请使用 docker start redis-stack。

2. 安装软件包

从 PyPI 安装（推荐）：

pip install n3memorycore-mcp-lite

也可以通过 uvx 零安装运行（Claude Code 插件使用此方式）：

uvx --from n3memorycore-mcp-lite n3mc-workingmemory

从源代码安装（如果你想编辑代码）：

git clone https://github.com/NeuralNexusNote/n3mcmcp-lite
cd n3mcmcp-lite
pip install -e .

首次运行时，会从 Hugging Face 下载约 400 MB 的嵌入模型， 并将其放入标准的 ~/.cache/huggingface/ 目录。

首次安装需要访问以下三个资源：

1. github.com — 添加 /plugin marketplace add NeuralNexusNote/n3mcmcp-lite 时，用于注册插件（如果通过 uvx 或从源代码安装，则可跳过此步骤）。
2. pypi.org — 执行 uvx --from n3memorycore-mcp-lite（或 pip install）时，用于解析软件包。
3. huggingface.co — 服务首次启动并将 intfloat/multilingual-e5-base（约 400 MB）下载到 ~/.cache/huggingface/ 时需要访问。

离线时，以上三项都会以明确且有时间限制的错误失败；不会卡住。后续启动只使用本地缓存，无需联网。

配置客户端

Claude Desktop（以及 Claude Desktop 内的“Code”标签页）

如果你使用 Claude Desktop 桌面应用（包括其内置的 Code 标签页），请通过桌面配置文件配置 MCP，而不是使用 .mcp.json（该文件仅由独立的 claude CLI 读取）。

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "n3mc-workingmemory": {
      "command": "n3mc-workingmemory",
      "args": []
    }
  }
}

**Windows 提示：**如果 Claude Desktop 无法通过上方的裸命令名称启动服务（锤子/工具图标始终不出现），请将 "command" 替换为已安装 .exe 的绝对路径，例如：

"command": "C:\\Users\\<YOU>\\AppData\\Local\\Programs\\Python\\Python312\\Scripts\\n3mc-workingmemory.exe"

在终端中运行 where n3mc-workingmemory，即可找到你电脑上的确切路径。

编辑配置后，请彻底退出 Claude Desktop — 仅关闭窗口还不够。右键点击系统托盘中的 Claude 图标（或使用任务管理器），终止所有 Claude 进程，然后重新启动。

Claude Code（独立 CLI）

本节仅适用于 claude 命令行工具，不适用于 Claude Desktop 的“Code”标签页（相关说明见上文）。

**此代码库已包含 .mcp.json。**克隆代码库、安装软件包后，Claude Code CLI 会自动连接，无需手动配置。

对于其他项目，将以下内容添加到该项目的 .mcp.json 中：

{
  "mcpServers": {
    "n3mc-workingmemory": {
      "type": "stdio",
      "command": "n3mc-workingmemory",
      "args": []
    }
  }
}

自动批准工具调用（仅适用于 Claude Code）

默认情况下，Claude Code 会针对每次 MCP 工具调用提示用户。若要实现完全自动化的记忆循环，让已连接的 AI 不再被“允许？”提示阻断，必须在 Claude Code 设置的 permissions.allow 中列出 n3mc-workingmemory 工具。

安装插件时会自动配置此项——通过 /plugin install n3mc-workingmemory@neuralnexusnote 安装时，SessionStart 钩子会运行 hooks/install_permissions.py，以幂等方式将六个 mcp__n3mc-workingmemory__* 工具添加到 ~/.claude/settings.json。无需手动编辑。只有在至少缺少一项时，钩子才会写入文件，并且绝不会改动无关字段。hooks.json 命令会通过 || 回退链依次尝试 python → py（Windows Python Launcher）→ python3，因此只要其中任意一个位于 PATH 中，钩子就能运行。只有当三者全部缺失时，钩子才会以非零状态退出，并显示在 Claude Code 的 /plugins Errors 标签页中，避免静默失败。

同一个钩子还会执行 uvx 预检查——插件清单通过 uvx --from n3memorycore-mcp-lite n3mc-workingmemory 启动 MCP 服务，因此如果缺少 uvx，原本只会在 MCP 启动器中显示难以理解的 ENOENT 错误。钩子会调用 shutil.which("uvx")，如果未找到，则向 stderr 写入中英双语的安装提示（pipx install uv、curl -LsSf https://astral.sh/uv/install.sh | sh 以及文档 URL），以便用户在 /plugins Errors 标签页中看到可执行的提示。钩子仍会以 0 状态退出，因为权限安装本身已成功。

如果你未通过插件安装（例如使用 claude mcp add 或手动配置 .mcp.json），或者完全没有可用的 Python 解释器，请手动将以下代码块添加到 ~/.claude/settings.json（用户全局设置，推荐）或 .claude/settings.json（项目设置）中：

{
  "permissions": {
    "allow": [
      "mcp__n3mc-workingmemory__search_memory",
      "mcp__n3mc-workingmemory__save_memory",
      "mcp__n3mc-workingmemory__list_memories",
      "mcp__n3mc-workingmemory__delete_memory",
      "mcp__n3mc-workingmemory__delete_memories_by_session",
      "mcp__n3mc-workingmemory__repair_memory"
    ]
  }
}

否则，每次调用 save_memory / search_memory 都会弹出审批提示；如果用户不在场，AI 就会被阻断。Claude Desktop 没有针对单个工具的权限控制，因此无需执行此步骤。

数据位置

Lite 版本不会在磁盘上存储数据库——记忆保存在 Redis 中并会自动过期。只有一个小型 config.json 文件位于平台标准的用户数据目录中：

OS	路径
Windows	%LOCALAPPDATA%\n3mc-workingmemory\
macOS	~/Library/Application Support/n3mc-workingmemory/
Linux	~/.local/share/n3mc-workingmemory/

使用环境变量 N3MC_DATA_DIR 指定其他位置。

配置

首次运行时，会自动生成 config.json，并为 owner_id 和 local_id 分配随机 UUID。可编辑的默认值：

{
  "owner_id":                 "<uuid>",
  "local_id":                 "<uuid>",
  "redis_url":                "redis://localhost:6379/0",
  "ttl_seconds":              604800,
  "dedup_threshold":          0.95,
  "half_life_days":           3,
  "bm25_min_threshold":       0.1,
  "search_result_limit":      20,
  "context_char_limit":       3000,
  "min_score":                0.2,
  "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 — 连接 URL；N3MC_REDIS_URL 环境变量优先。
• ttl_seconds — 每条新记忆和 sha-guard 的 TTL（默认 7 d）。
• chunk_threshold / chunk_overlap — 滑动窗口大小和重叠长度（字符）。正文超过阈值时，会采用父文档 + 分块路径，以便逐字回忆。
• access_count_* — 基于访问频率的自动重要性；排名靠前的 K 个搜索结果会在后续查询中获得有上限的加权提升。
• ttl_refresh_on_search / ttl_refresh_top_k — 每次搜索时重置排名靠前的 K 个结果的 TTL（仅重置；不会延长至超过刚保存时的期限）。
• lexical_rerank_* / rerank_weight / rerank_phrase_weight — 轻量级融合后词法重排器（仅使用 CPU）。
• b_session_match / b_session_mismatch — 对存储的 session_id 与当前会话匹配的行（默认 1.0）和来自其他项目的行（0.6）进行乘法排名加权。在调用 save_memory 和 search_memory 时传入相同的 session_id，即可在同一 Redis 实例中优先显示某个项目的记忆，而非无关的跨项目行。将两者都设为 1.0 可禁用此偏置。
• skip_code_blocks — 设为 true 时，save_memory 会拒绝任何包含三个反引号围栏（```）的载荷，并返回 status: "skipped_code"。默认值为 false。如果希望采用 FastAPI 时代 N3MemoryCore 的代码排除方式（完全不将代码纳入记忆索引——适用于工作流中已有代码的 git/IDE 历史，且只想将文字决策/计划存入 Redis 的情况），请设为 true。

完整的逐字段参考请参阅规范 §6。

多语言支持

内置功能，仅使用 CPU，无需 LLM 或 GPU。无论用户以何种方式输入同一个词，搜索和去重的表现都相同：

层	功能	实际示例
NFKC 规范化	在 SHA / embedding / BM25 处理前折叠兼容形式	ｱﾙﾌｧ ↔ アルファ，１２３ ↔ 123，fi ↔ fi
双字母 BM25 辅助通道	为不使用空格的文字生成重叠双字母组合	記憶装置 → 記憶 憶装 装置；韩语（안녕하세요）、泰语（สวัสดี）、老挝语、缅甸语和高棉语也同样适用
变音符号折叠	拉丁字母、希腊字母和西里尔字母的词也会以去除组合附加符后的形式建立索引	café 可匹配 cafe，Ångström 可匹配 Angstrom
multilingual-e5-base embedding	覆盖 100 多种语言的多语言语义空间	跨语言释义检索

这些处理会在每次调用 save_memory 和 search_memory 时自动运行。 原始 content 字段绝不会被改写——逐字回忆（规范 §3.11） 仍会逐字节返回原始内容。

编码安全

在任何工具主体执行前，都会运行两层防护（规范 §3.13）。 与 Free 版本采用相同的防护，并以一对一方式移植：

1. stdio UTF-8 重新配置 — 在模块导入时，将 sys.stdin / sys.stdout / sys.stderr 切换为 encoding="utf-8"。在 Windows 日语主机上，默认控制台代码页为 cp932，否则会破坏 MCP JSON-RPC 通道中的所有非 ASCII 字节。POSIX 系统已使用 UTF-8，因此此调用不会产生影响。
2. 孤立代理项清理 — 每个 save_memory.content 和 search_memory.query 都会在任何 .encode("utf-8") 调用前经过 sanitize_surrogates() 处理。当 Windows 子进程管道传递 UTF-8 字节，而 Python 解码器使用 errors="surrogateescape" 映射这些字节时，就会出现孤立的 UTF-16 代理项（U+D800–U+DFFF）——它们可以通过 json.loads 往返处理，但在 SHA1 / Redis HSET / embedding 阶段会引发 UnicodeEncodeError。没有这层防护，整个写入会被悄然丢弃。该函数会递归处理，因此可一次性清理嵌套在 JSON 载荷中的代理项。

如果保存载荷完全由代理项组成，清理会将其转换为空字符串，并进入常规的空内容拒绝流程——{"status":"error","saved":false,"reason":"empty content"}。

排名公式

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

默认半衰期为 3 天（短于 7 天的 TTL）时，time_decay 在 Lite 版本中很有意义：新记忆的得分为 1.0，存储 3 天的记忆得分恰好为 0.5，而存储 7 天、接近过期的条目得分约为 0.20——让近期上下文在排名中更靠前。

自动重要性（访问频率加权）：每当 search_memory 在前 5 个命中结果中返回某条记忆，该记忆的 access_count 就会加 1，且后续查询中的 b_local 会提高 0.02（最多提高 +0.5）。无需 LLM 判断——常用且有价值的记忆会通过仅依赖 CPU 的自我调节自然排到前面。

开发

# Start Redis Stack first (see Prerequisites), then:
pip install -e ".[dev]"
pytest tests/ -q

测试针对 Redis DB 索引 0（可通过 N3MC_REDIS_TEST_URL 配置），并会在每项测试前后对其执行 FLUSHDB。RediSearch 拒绝在 DB 0 以外的数据库中创建索引（Cannot create index on db != 0），因此无法使用单独的测试 DB——请使用专用的 Redis 容器运行测试套件，切勿使用存有重要数据的容器。如果无法连接 Redis，测试将拒绝运行。

扩展 Lite 版本

如果你想修改行为（更改排名公式、加入 cross-encoder 重排器、接入日语形态分析分词器等），请从本仓库附带的设计规范开始：

• N3MemoryCore_MCP_Spec_EN.md — 完整设计文档（英文）
• N3MemoryCore_MCP_Spec_JP.md — 日文版

规范的附录 A 列出了可选扩展（cross-encoder 重排器、保存时分块、HyDE、日语形态分析），并说明了可直接接入的位置和候选库。修改代码时可将其作为参考，避免破坏 TTL、去重或 RediSearch 契约。

为什么选择 N3MemoryCore？（与内置记忆相比）

N3MemoryCore 自动保存的可靠性并不优于现代大模型产品内置的记忆功能（例如 Claude 的内置记忆）——两者都依赖 LLM 主动调用保存工具，也都存在下文遵循情况中描述的非确定性。两者的差异体现在其他方面：

方面	内置记忆	N3MemoryCore（Lite）
数据所有权	由供应商托管	你自己机器上的 Redis Stack
客户端范围	仅供应商的产品	任何符合 MCP 标准的客户端（Claude Code、Cursor、Cline、Goose 或你自己的应用）
多 AI 协作	一个 AI 的记忆	session_id 允许多个 Agent 共享同一记忆命名空间；delete_memories_by_session 可用于清理已完成的任务
逐字回忆	不透明（可能会被总结）	父文档契约——返回逐字节精确的全文
搜索机制	黑箱	混合使用 BM25、e5 向量、CJK 二元词组、时间衰减和轻量级重排器，所有参数均可见且可调
检查 / 控制	仅限 UI	list_memories / delete_memory / delete_memories_by_session 可直接操作原始记录
持久化	取决于供应商服务的生命周期	带 7 天 TTL 的内存型 Redis——有意设计为短期存储，但容器由你掌控；可搭配任何持久化记忆后端进行长期存储
可调节性	固定	half_life_days、chunk_threshold、dedup_threshold、重排权重——均可编辑

因此，运行 N3MemoryCore Lite 的价值并非“更可靠的自动保存”，而是拥有一个透明的多客户端工作记忆层，让多个 AI 能在共享的 session_id 下协作；搜索行为可编辑，且逐字回忆有契约保证。（如需长期保存用户投入的内容，可搭配任何持久化记忆后端。）

如果这些特性对你的工作流很重要，Lite 就物有所值。如果你只需要在某个供应商的产品中实现“LLM 能跨会话记住某些内容”，内置记忆会更简单。

关于合规性 — MCP 可以劝说，不能强制

此服务无法让大模型调用它的工具。MCP 协议只为服务提供了三种劝说手段：

1. tools/list 中的工具描述——每轮都会显示给大模型。
2. 会话开始时发送的 instructions 字段——通常会作为系统级提示呈现给大模型。
3. 工具响应文本——大模型调用工具时会读取这些文本。

我们会用好这三种手段：工具描述明确具体，instructions 列出了一套规则，而 search_memory / save_memory 的响应会以简短提醒收尾，在一轮对话中重新强调自动保存的规范。即便如此，大模型是否会照做仍是非确定性的。是否遵守取决于模型调用工具的倾向、MCP 客户端构造提示词的方式（有些客户端会概述或丢弃 instructions 字段），以及用户提示词、CLAUDE.md 等内容中的其他指令。

实际上：大多数轮次都会正确自动保存，但也有一些不会——尤其是简短回答、事实更正轮次，或大模型高度专注于用户问题的轮次。如果下次会话时发现想保存的事实不见了，只需说“保存这个”——服务仍会随时接收。

需要确保保存时

在 MCP 框架下，有三种方式可以绕过这种非确定性：

方式 1 — 在提示词中明确要求大模型（操作层面的变通方案，立即生效）。在提示词中写上 “save this to N3MemoryCore” 或 “record this in memory”。大模型几乎总会遵从明确的用户请求。优点：无需任何基础设施，现在就能用，适用于所有 MCP 客户端。缺点：需要费心记住提出要求；并非自动执行。

基于 Hook 的完整转录保存

路径 2 — 保存完整转录的 Claude Code Hook（仅限 Claude Code，确定性执行）。Claude Code 提供 harness 级别的 Hook（Stop 等），由 harness 确定性地运行——不依赖大模型记住任何事情。只需向 Claude Code 提示一次即可完成设置：

“每轮对话结束后，自动将完整的 Claude Code 转录保存到 Lite。”

随后，Claude Code 会创建：

• ~/.claude/hooks/save_transcript.py 脚本，从 Hook 输入中读取 transcript_path，直接导入 n3mc_mcp.database.Database，并在 Lite 数据库上调用 save_memory（不经过 MCP 往返）。
• 在 ~/.claude/settings.json 中添加 hooks.Stop 配置块，每轮助手对话结束后运行该脚本，并设置 async: true（因此模型加载不会阻塞 UI）。

行为说明：

• Claude 绝不会意外跳过保存——无论大模型做什么，harness 都会触发 Hook。
• 没有 MCP 往返开销；Hook 会直接与 Redis 通信。
• 随着会话变长，每轮转录会通过近似重复检测（dedup_threshold）发生碰撞，因此数据库中会保持每个会话接近一条记录，而不是每轮一条。
• 短于约 200 个字符的转录会作为噪声跳过。
• 优点：确定性执行／独立于模型行为／无需担心是否保存。
• 缺点：仅限 Claude Code（Cursor／Windsurf 需要采用其他方式）／Hook 进程每轮都会加载嵌入模型（异步执行，因此不会阻塞 UI，但会消耗 CPU／IO）／ Lite 的 7 天 TTL 仍然适用，因此通过这种方式保存的转录仍会在一周内过期——需要长期保留时，将同一个 Hook 指向任意持久化记忆后端即可。

路径 3 — 绕过 MCP，直接调用 Anthropic 第一方 Messages API（架构变更）。跳出 MCP 客户端（Claude Code 等），在自己的应用代码中直接调用 messages.create tool_use；这样无论大模型“决定”做什么，你都可以在每轮确定性地触发 save_memory。优点：确定性执行／适用于任何模型和客户端。缺点：你需要编写编排应用。

“MCP + 大模型替我处理一切”的便利性与“每轮都保存”的保证，处于权衡的两端。此服务已在协议允许的范围内尽可能强化了说服机制；若要获得更强保证，就由你作为用户或客户端实现者自行决定（如果你使用 Claude Code，路径 2 远远是成本最低的选项）。

分叉与贡献

此仓库是公开的，并采用 Apache-2.0 许可证——你可以自由分叉、修改和运行。分叉并运行的步骤如下：

git clone https://github.com/<YOU>/n3mcmcp-lite
cd n3mcmcp-lite
docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"
pytest tests/ -q                                      # 105 tests, ~30s warm

每次推送和 PR 时，CI 都会运行相同的测试矩阵——参见 .github/workflows/test.yml。请阅读 CONTRIBUTING.md，了解完整的开发指南 （EN + JP），其中包括编码约定、规范即契约政策和 PR 检查清单。

要在 Claude Code 中实际使用这个分叉，除上述 pip install -e ".[dev]" 之外，无需进行任何额外设置：

1. n3mc-workingmemory 命令现在已位于你的 PATH 中（运行 which n3mc-workingmemory 进行确认）。
2. 仓库的 .mcp.json 已声明该服务，因此只要你运行 cd n3mcmcp-lite && claude，CLI 就会自动连接。
3. 对于其他客户端界面（Claude Desktop、其他项目的 .mcp.json、自动批准工具），快速入门第 3 步 的表格列出了 具体操作。

如果你打算以新的软件包名称发布这个分叉，还需要在重新上传到 PyPI 之前，编辑 pyproject.toml 中的 name、[project.urls] 和控制台脚本名称。

故障排除

Windows：pip install --upgrade 因 WinError 32 失败（文件正在使用）

症状：

ERROR: Could not install packages due to an OSError: [WinError 32]
The process cannot access the file because it is being used by another process:
'...\Scripts\n3mc-workingmemory.exe' -> '...\Scripts\n3mc-workingmemory.exe.deleteme'

原因：MCP 客户端（Claude Code / Claude Desktop）当前正将 n3mc-workingmemory.exe 作为子进程打开，因此 pip 无法替换 该二进制文件。

解决方法——任选其一：

1. 先彻底退出 MCP 客户端。 在 Windows 上，仅关闭窗口并不足够。 打开任务管理器，结束所有命令行中包含 n3mc-workingmemory 的 claude / n3mc-workingmemory.exe / python.exe 进程，然后重新运行 pip install --upgrade。
2. 改用 uvx，而非全局安装——uvx --from n3memorycore-mcp-lite n3mc-workingmemory 会在每个会话中运行于隔离的 临时环境，因此不会有系统级的 .exe 被锁定。

这是 Windows 文件锁定机制导致的问题，并非打包缺陷——wheel 本身可以顺利安装到全新的 venv 中（python -m venv .venv && .venv/Scripts/pip install n3memorycore-mcp-lite）。

pip install 期间出现 ~3memorycore-mcp-lite 警告

如果你看到类似以下内容：

WARNING: Ignoring invalid distribution ~3memorycore-mcp-lite

说明 pip 检测到先前有一次安装在写入过程中被中断 （通常是由上述文件锁定问题导致）。遗留目录的名称以 ~ 开头， 虽然无害，但会产生干扰。请手动删除：

# Windows
rmdir /s "%LOCALAPPDATA%\Programs\Python\Python312\Lib\site-packages\~3memorycore_mcp_lite-1.5.0.dist-info"

（请调整路径以匹配你的 Python 安装位置。）

许可证

Apache License 2.0——详见 LICENSE。

---

_{MCP Registry：mcp-name: io.github.NeuralNexusNote/n3mc-workingmemory}