Memory MCP Server

Memory（MCP 记忆服务器）

Memory 是一个 MCP stdio server（Rust），用于为 AI 调用方提供“长期记忆”能力。

能力

• now：获取当前时间（本地 + UTC）。
• keywords_list：列出指定 namespace 下已存在的关键字（用于复用短关键字）。
• keywords_list_global：列出全局已存在的关键字（跨 namespace 汇总）。
• remember：记录记忆（关键字 + 重要内容切片 + AI 日记）。
• recall：按关键字与时间范围检索记忆，并返回最相关的若干条。

说明：Memory 只负责“存取与检索”。

• namespace 由调用方从项目上下文中获取后传入；必须为 {userId}/{projectId}（严格两段）。
• 何时记、如何提取关键字/时间范围由提示词与调用方策略决定。

与 MCP Client 集成（npx，推荐）

如果你的 MCP Client 支持以 command + args 启动 stdio server，推荐使用 npx 直接运行已发布的 npm 包（会按平台自动安装对应二进制）：

{
  "mcpServers": {
    "Memory": {
      "command": "npx",
      "args": ["-y", "@a157034816/memory-mcp"],
      "env": {
        "MEMORY_STORE_DIR": "C:\\path\\to\\MemoryStore"
      }
    }
  }
}

说明：

• 需要 Node.js（含 npx），建议 18+。
• Windows 下部分客户端可能需要将 command 写为 npx.cmd（取决于其进程启动方式与 PATH/PATHEXT 处理）。
• -y 用于非交互环境自动确认安装（很多客户端不会给你输入确认的机会）。
• MEMORY_STORE_DIR 可选；不设置会使用系统用户数据目录。
• 调试/脚本：可以把参数透传给二进制，例如：npx -y @a157034816/memory-mcp -- --cli recall --namespace "u1/p1" --keyword 项目 --text

与 MCP Client 集成（直接二进制）

也可以直接指定本机的可执行文件路径：

{
  "mcpServers": {
    "Memory": {
      "command": "C:\\path\\to\\memory.exe",
      "args": [],
      "env": {
        "MEMORY_STORE_DIR": "C:\\path\\to\\MemoryStore"
      }
    }
  }
}

Tool 参数

now

无入参。

返回：

• data.utc_rfc3339: string（UTC，RFC3339，秒级）
• data.utc_ts: integer（UTC，Unix 时间戳秒）
• data.local_rfc3339: string（本地时区，RFC3339，秒级）
• data.local_offset_seconds: integer（本地时区偏移秒，local - utc）
• data.local_offset_minutes: integer（本地时区偏移分钟，local - utc）

keywords_list

必填：

• namespace: string

返回：

• data.namespace: string
• data.total: integer
• data.keywords: string[]（已归一化：trim + lowercase；排序：长度优先）

keywords_list_global

无入参。

返回：

• data.total: integer
• data.scanned_namespaces: integer（扫描到的 namespace 数）
• data.keywords: { keyword: string, namespaces: integer, items: integer }[]

remember

必填：

• namespace: string（必须为 {userId}/{projectId}；严格两段，用于隔离不同用户/项目）
• keywords: string[]（至少 1 个；会做 trim+lowercase 并去重；时间类关键字会被忽略）
• slice: string
• diary: string

可选：

• occurred_at: string（RFC3339 或 YYYY-MM-DD）
• importance: integer（1~5）
• source: string

recall

必填：

• namespace: string

可选：

• keywords: string[]
• start: string（RFC3339 或 YYYY-MM-DD）
• end: string（RFC3339 或 YYYY-MM-DD）
• query: string（包含匹配 slice/diary/source；支持 time>=... / time<=... / time=a..b 时间表达式）
• limit: integer（默认 20，最大 100）
• include_diary: boolean（默认 false；为避免泄露/噪声，默认不返回 diary）

输出补充：

• 当传入 keywords 非空时，data.items[].matched_keywords 会返回该条记忆命中的关键字交集（便于调用方解释命中原因）。

存储设计（JSONL + 索引）

• 存储根目录：
  • 优先：环境变量 MEMORY_STORE_DIR
  • 否则：使用 OS 用户数据目录（例如 Windows 的 LocalAppData 下）
• 每个 namespace 单独一个目录（目录层级为 {userId}/{projectId}；会对路径非法字符做净化，防止路径穿越；并会将 \\ 归一化为 /，忽略空段与 ./..）。
  • 示例：namespace="u1/p1" → .../u1/p1/
• memories.jsonl：追加写（append-only），每行一条 JSON。
• index.json：索引文件，用于加速检索：
  • 倒排：keyword -> itemIndex[]
  • 时间排序：time_sorted[]（按 occurred_at ?? recorded_at 升序）
  • 定位：记录每条记忆在 memories.jsonl 中的 offset/length，召回时只读取命中行。

当前实现不做自动淘汰（TTL/上限）。后续可新增 forget/compact 等工具，在不破坏数据格式的前提下做清理/归档。

namespace 生成建议（示例）

建议在调用方统一生成稳定的 namespace（用于隔离不同用户/项目/工作区的记忆）。必须为 {userId}/{projectId}（严格两段）：

• userId：当前登录用户的唯一标识（例如用户 ID，或稳定的匿名化标识）
• projectId：当前项目/工作区/仓库/租户的唯一标识（例如 workspace id、repo 名称、tenant id）
• namespace：{userId}/{projectId}

多租户场景建议将 tenantId 纳入 projectId（或作为其一部分），避免不同租户/工作区间记忆串味。

开发与测试

快捷命令（推荐）

在仓库根目录执行：

& "./memory_tools.bat"

进入交互菜单后选择：测试 / Release 构建 / Windows 静态 CRT Release 构建 / 运行 Release 产物 / clean / 一键 remember / 一键 recall。

• 菜单“运行 Release 产物”会提示设置 MEMORY_STORE_DIR（回车使用默认：./.memory_store）。
• 为避免 bat 参数转发与中文兼容问题，memory_tools.bat 不再透传参数；如需透传参数或做 CI，请使用命令行模式或直接运行 cargo（见下文）。

命令行模式示例（可选）：

python -X utf8 "./tools/memory_tools.py" --cli test -- --nocapture
python -X utf8 "./tools/memory_tools.py" --cli run-release --store-dir ".memory_store" --backtrace

# 以运行参数方式调用两个 MCP tools（会自动设置 MEMORY_STORE_DIR）
python -X utf8 "./tools/memory_tools.py" --cli remember --store-dir ".memory_store" --namespace "u1/p1" --keyword 项目 --slice "我们做过 A 项目" --diary "（省略）" --pretty
python -X utf8 "./tools/memory_tools.py" --cli recall --store-dir ".memory_store" --namespace "u1/p1" --keyword 项目 --text

直接使用 cargo

在仓库根目录执行：

cargo test
cargo build --release

CLI 一键调用（非 MCP）

默认（不带 --cli）时，memory.exe 会作为 MCP stdio server 工作（即使传了其它参数也会忽略）；只有带 --cli 才是一键调用模式。

先准备可执行文件路径（示例）：

$exe = "./target/release/memory.exe"

now

& $exe --cli now --text

keywords（关键字管理）

& $exe --cli keywords list --namespace "u1/p1" --text
& $exe --cli keywords list-global --text

remember

& $exe --cli remember --namespace