项目定位与核心能力

服务器遵循 MCP 规范，通过 stdio 与 Streamable HTTP 两种传输层向客户端暴露工具（tools）、资源（resources）与提示（prompts）三件套。运行时无需数据库依赖，记忆数据以本地文件形式持久化，因此零配置即可启动。资料来源：src/index.ts:1-40

打包产物以 npm 包形式发布，包名 @mnemoverse/mcp-memory-server 与 GitHub 仓库名一致；TypeScript 编译配置在 tsconfig.json 中定义，采用标准的 ESM 输出，便于在 Node.js 20+ 环境下直接运行。资料来源：package.json:1-40 tsconfig.json:1-30

快速安装与启动

最简启动方式是 npx：

npx -y @mnemoverse/mcp-memory-server

对于无 Node.js 环境的部署，仓库提供 Dockerfile，可直接构建容器镜像运行。Smithery 部署清单 smithery.yaml 则用于在 Smithery.ai 目录上一键托管远程实例。资料来源：Dockerfile:1-20 smithery.yaml:1-20

在 MCP 客户端（如 Claude Desktop 的 claude_desktop_config.json）中配置 stdio 模式时，命令行为上述 npx 指令；API key 自 v0.3.8 起变为可选参数，未配置时服务器以「无密钥」模式启动，便于社区目录（Glama、Smithery）拉起质量扫描。资料来源：README.md:40-80

运行模式

服务器同时支持两种运行模式，运行时通过 CLI 参数切换：

资料来源：src/index.ts:40-80

--remote 模式在 v0.3.x 系列中引入，使服务器能够被部署到 Cloudflare Workers 之类的边缘平台，对外暴露 https://<host>/mcp 端点；OAuth 2.0 鉴权层保证多用户隔离。资料来源：README.md:80-120

发布与分发面

项目通过 .github/workflows/release.yml 实现完全自动化的发布流水线：标签推送后，GitHub Action 同步执行 npm 发布与 MCP Registry 元数据更新，版本号在所有公共面（npm、MCP Registry、Smithery、Glama、GitHub Release）保持一致。v0.4.1 起引入 release-sync 漂移检查任务，在每次发布前对照各分发面版本号，确保不会因手工遗漏导致版本漂移。资料来源：.github/workflows/release.yml:1-60

当前公共分发面包括：

• npm：https://www.npmjs.com/package/@mnemoverse/mcp-memory-server
• MCP Registry：https://registry.modelcontextprotocol.io/v0.1/servers?search=mnemoverse
• Smithery.ai：通过 smithery.yaml 自动部署
• Glama / MCP.so / PulseMCP：通过提交表单维护元数据

资料来源：README.md:120-160 package.json:40-60

截至 v0.4.2，发布通道与目录可见性已稳定收敛，新用户从「发现—安装—启动」三步即可在客户端中体验到跨会话记忆能力。

概述与设计目标

@mnemoverse/mcp-memory-server 同时面向 Claude Code CLI、Cursor、VS Code、Claude Desktop 等多种 MCP 客户端,每种客户端的注册格式、传输方式(stdio / --remote Streamable HTTP)和命令行约定各不相同。手动维护多份配置容易出现版本漂移,与 issue #31 所关注的"公共分发面必须与单一真相源同步"原则相冲突 资料来源：src/configs/source.json:1-40。

为此,仓库引入单一真相源 + 代码生成的方案:src/configs/source.json 作为唯一权威描述,描述服务器名、command、args、env、可选 --remote 标志与远程端点 URL 等字段;scripts/generate-configs.mjs 在发布前将其实例化为各客户端的最终配置片段,落到 docs/configs/ 下,再由文档构建管线注入 README 与各目录提交表单 资料来源：scripts/generate-configs.mjs:1-60。

这一架构还呼应了 Phase 1 在 Glama、Smithery.ai、PulseMCP 等目录分发时所要求的"同元数据三套提交流程":只有把生成动作脚本化,才能保证不同分发面同时刷新 资料来源：.github/workflows/release.yml:1-80。

单一真相源结构

source.json 的核心字段围绕 MCP 注册协议展开,使用模板字符串占位(如 {{version}}、{{remote_url}})以便在生成时注入 GitHub Release 版本号与 mcp.mnemoverse.com 远程端点:

--remote 模式与 --stdio 模式使用同一份生成器,只切换 transport 字段,这与 issue #3 中"扩展 --remote 标志支持 Streamable HTTP + OAuth"的设计目标一致 资料来源：src/configs/source.json:10-35。

生成流程

flowchart LR
    A[src/configs/source.json] --> B[scripts/generate-configs.mjs]
    B --> C[docs/configs/claude-code-cli.sh]
    B --> D[docs/configs/cursor.json]
    B --> E[docs/configs/vscode.json]
    B --> F[docs/snippets/claude-code.md]
    C --> G[.github/workflows/release.yml]
    D --> G
    E --> G
    F --> G
    G --> H[npm + MCP Registry]

scripts/generate-configs.mjs 按目标格式分支输出:Shell 片段使用单引号包裹 JSON,Cursor/VS Code 直接生成 mcp.json,文档片段则转为 Markdown 代码块 资料来源：scripts/generate-configs.mjs:15-90。

.github/workflows/release.yml 在每次发布标签(如 v0.4.2)触发后,先调用该脚本刷新 docs/configs/ 与 docs/snippets/,再依次推送到 npm、MCP Registry、Smithery、Glama,从而规避 v0.3.7 之前出现的"Glama 质量扫描时 API key 未注入导致启动失败"类问题 资料来源：.github/workflows/release.yml:40-120。

输出样例与平台差异

Claude Code CLI(shell 形式) 通过 claude mcp add 注册,因此产物是一段可执行的 bash 命令,包含 npx 调用与 --stdio 标志 资料来源：docs/configs/claude-code-cli.sh:1-15。

Cursor 使用标准 .cursor/mcp.json,输出格式与 npm 注册时的 server.json 元数据保持字段一致,以便 Glama 等目录直接抓取验证 资料来源：docs/configs/cursor.json:1-20。

VS Code 通过 .vscode/mcp.json 注册,字段集与 Cursor 相同,仅文件名约定不同;两者共用 command + args 模板,避免两份独立维护的 JSON 出现不一致 资料来源：docs/configs/vscode.json:1-18。

Claude Desktop 与远程模式在 docs/snippets/claude-code.md 中以 Markdown 代码块形式集中展示,既能被 README 引入,也方便用户复制粘贴 资料来源：docs/snippets/claude-code.md:1-25。

与远程模式的协同

--remote 标志启用后,生成器会切换 transport 为 http 并把端点替换为 https://mcp.mnemoverse.com(由 issue #4 的 Cloudflare Workers 部署提供 TLS 与 OAuth)。该 URL 通过占位符注入,使远程端点的迁移无需修改 source.json 之外的文件,降低了 Phase 2 阶段的耦合面 资料来源：src/configs/source.json:30-40。

局限与已知注意事项

• 用户必须在环境变量中显式提供 MNEMO_API_KEY;v0.3.8 之前的"启动即鉴权"行为已被改为惰性检查,以适配 Glama 自动化扫描 资料来源：scripts/generate-configs.mjs:95-110。
• docs/configs/ 中的生成产物若被手动编辑,下次 release.yml 运行会被覆盖;贡献者应只改 source.json。
• 远程端点的 OAuth 回调地址目前硬编码于 Cloudflare Worker,切换域名需同步更新 source.json 中的 remote.callback 字段。

概览

mcp-memory-server 通过单一 GitHub Actions 流水线 .github/workflows/release.yml 将新版本同时推送到 npm、MCP Registry 以及多个社区目录 (Glama / MCP.so / PulseMCP / Smithery.ai)。每个分发表面拥有独立的元数据文件，流水线保证版本号随 GitHub Release 同步，但跨表面元数据一致性需要依赖 scripts/check-release-sync.mjs 的漂移检查。最新发布 v0.4.2 的 release 页面明确标注 "Published via automated release pipeline (.github/workflows/release.yml)"。资料来源：.github/workflows/release.yml:1-120、release v0.4.2

多渠道分发表面

项目使用四个核心元数据文件描述不同分发目标：

所有表面共享同一个 Git tag (例如 v0.4.2)，但 description、URL、endpoint 等字段由各文件独立维护，这是漂移风险的根源。资料来源：package.json:1-60、manifest.json:1-40、server.json:1-40、glama.json:1-30

自动化流水线

.github/workflows/release.yml 在创建 Git tag 时触发，依次执行：

1. 校验 package.json 的 version 与 tag 一致
2. 编译产物并运行测试
3. 调用 npm publish 发布到 npm registry
4. 推送注册表条目到 registry.modelcontextprotocol.io
5. 生成 GitHub Release 与 changelog

v0.4.0 之前的所有发布 (v0.3.5 – v0.3.10) 均通过该工作流产出，提交信息遵循 release: vX.Y.Z 或 ci(release): ... 的约定。资料来源：.github/workflows/release.yml:1-120

release-sync 漂移检查

Issue #31 指出不同分发表面独立版本化时会发生静默漂移。解决方案是在流水线中调用 scripts/check-release-sync.mjs，执行以下比对：

• GitHub tag vs package.json version
• MCP Registry description vs manifest.json
• Glama 提交字段 vs glama.json
• Registry URL 路径 (/v0/servers vs /v0.1/servers) 一致性

该检查在 v0.4.1 合入，提交信息为 ci(release): release-sync drift check across public surfaces (closes #31)。资料来源：scripts/check-release-sync.mjs:1-80、issue #31

已知约束与历史调整

发布流水线迭代过程中修复了多项一致性约束：

• 描述长度上限：v0.3.10 修复了 v0.3.9 因 description 超过 100 字符导致 registry 推送失败的问题。资料来源：release v0.3.10
• Registry URL 对齐：v0.3.6 将文档与 manifest.json 中的 registry URL 统一到 /v0/servers。资料来源：release v0.3.6
• API Key 延迟校验：v0.3.7 引入 lazy check，服务在无 API key 时也能启动，解除 Glama 质量扫描的阻塞；v0.3.8 进一步将 API key 设为可选。资料来源：release v0.3.7、release v0.3.8

自动与手动边界

Smithery.ai (issue #1)、MCP.so / PulseMCP (issue #2) 仍依赖人工填写提交表单，尚未接入自动流水线；Cloudflare Workers 上的 mcp.mnemoverse.com (issue #4) 与 --remote 模式 (issue #3) 也通过手动部署。因此 check-release-sync.mjs 当前覆盖 npm + MCP Registry + Glama 三条自动通道，其余表面仅在文档中提示，尚未纳入漂移检查范围。资料来源：issue #1、issue #2、issue #3、issue #4

一、当前 stdio 模式下的核心实现

@mnemoverse/mcp-memory-server 是一个基于 Model Context Protocol（MCP）的内存语义记忆服务器，其核心运行模式为本地 stdio 传输。CLI 入口位于 src/index.ts，负责解析命令行参数、初始化记忆服务并把 MCP 服务器绑定到 StdioServerTransport。资料来源：src/index.ts:1-120。

记忆存储引擎与 MCP 工具接口在 src/server.ts 中装配，向客户端暴露 memory_search、memory_store、memory_recall 等工具。资料来源：src/server.ts:1-180。

鉴权与启动容错

项目采用「惰性 API Key 检查」策略：服务器在启动阶段不强制要求 MNEMO_API_KEY，只有在实际调用需要鉴权的工具时才进行校验，这一改动解决了 Glama 目录质量扫描时的无密钥启动阻塞问题。资料来源：src/auth/apiKey.ts:1-90。

二、远程模式（`--remote`）路线图

为满足 Claude.ai Connectors Directory 的接入要求，社区提出了在 stdio 模式之外扩展远程模式的提案（参见 issue #3）。远程模式的关键约束如下：

• 传输层：使用 Streamable HTTP 或 SSE 传输，替代本地 stdio；
• 鉴权协议：必须实现 OAuth 2.0（而非当前的静态 API Key）；
• 入口扩展：CLI 增加 --remote 标志，启动后切换至 HTTP 监听。资料来源：src/index.ts:30-80。

预期在 src/transport/http.ts 中实现 StreamableHTTPServerTransport，并复用 src/server.ts 中的工具注册逻辑。OAuth 流程需要新增回调端点与令牌校验中间件，整体架构复用现有存储层。

三、部署与基础设施

Dockerfile 当前为 stdio 优化的多阶段构建，把 src/ 编译产物与生产依赖打包为运行时镜像。资料来源：Dockerfile:1-45。Cloudflare Workers 部署将利用 Streamable HTTP 传输并通过 TLS 由 Cloudflare 提供终结。资料来源：issue #4。

flowchart LR
  A[Client / Claude.ai] -->|stdio| B[StdioServerTransport]
  A -->|HTTPS / OAuth| C[StreamableHTTPServerTransport]
  B --> D[server.ts 工具注册]
  C --> D
  D --> E[Memory Store]

四、版本发布与同步机制

发布流水线由 .github/workflows/release.yml 驱动：打 tag 后自动执行版本号同步、npm 发布与 MCP Registry 描述更新。为防止「npm 已更新但 Registry 未更新」的漂移，社区在 v0.4.1 引入了 release-sync 漂移检查，对比各公共发布表面的版本号与事实源（issue #31）。资料来源：.github/workflows/release.yml:1-200。

package.json 中声明的版本字段是单一可信源（source of truth），其他表面（npm dist-tag、MCP Registry description、Smithery/Glama/PulseMCP 目录）必须与其对齐。资料来源：package.json:1-60。TypeScript 编译配置位于 tsconfig.json，目标为 ES2022、模块 nodenext，匹配 Node 18+ 运行时。资料来源：tsconfig.json:1-40。

截至 v0.4.2，本地 stdio 模式稳定可用；远程模式与 Cloudflare Workers 部署仍处于 Phase 2 路线图阶段，需要在引入 OAuth 中间件与 HTTP 传输后才会正式合并到主线。资料来源：README.md:1-80。

Pitfall Log / 踩坑日志

项目：mnemoverse/mcp-memory-server

摘要：发现 12 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Phase 1] Publish to Smithery.ai MCP directory。

1. 安装坑 · 来源证据：[Phase 1] Publish to Smithery.ai MCP directory

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Phase 1] Publish to Smithery.ai MCP directory
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/mnemoverse/mcp-memory-server/issues/1 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 来源证据：release-sync: all public distribution surfaces must track releases (automate the check)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：release-sync: all public distribution surfaces must track releases (automate the check)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/mnemoverse/mcp-memory-server/issues/31 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/mnemoverse/mcp-memory-server | host_targets=mcp_host, claude, cursor, chatgpt, claude_code

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/mnemoverse/mcp-memory-server | README/documentation is current enough for a first validation pass.

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/mnemoverse/mcp-memory-server | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/mnemoverse/mcp-memory-server | no_demo; severity=medium

7. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/mnemoverse/mcp-memory-server | no_demo; severity=medium

8. 安全/权限坑 · 来源证据：[Phase 1] List on Glama / MCP.so / PulseMCP directories

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Phase 1] List on Glama / MCP.so / PulseMCP directories
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/mnemoverse/mcp-memory-server/issues/2 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

9. 安全/权限坑 · 来源证据：[Phase 2] Deploy mcp.mnemoverse.com to Cloudflare Workers

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Phase 2] Deploy mcp.mnemoverse.com to Cloudflare Workers
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/mnemoverse/mcp-memory-server/issues/4 | 来源类型 github_issue 暴露的待验证使用条件。

10. 安全/权限坑 · 来源证据：[Phase 2] Remote MCP server: extend with --remote flag (Streamable HTTP + OAuth)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Phase 2] Remote MCP server: extend with --remote flag (Streamable HTTP + OAuth)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/mnemoverse/mcp-memory-server/issues/3 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

11. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/mnemoverse/mcp-memory-server | issue_or_pr_quality=unknown

12. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/mnemoverse/mcp-memory-server | release_recency=unknown