模型上下文协议服务

存储器MCP

一种模型上下文协议（MCP）服务器，为AI编码代理提供关于代码库的持久、不断发展的知识。代理可以存储和检索有关架构、约定、陷阱和最近工作上下文的观察结果，而不是在每个会话中都冷启动。

工具

隐藏的工具 （仍然可调用，不在目录中——代理从提示/错误中学习它们）： memory_list_lobes （波瓣路径和统计数据）， memory_stats （入口计数、新鲜度、储存）， memory_diagnose （服务器运行状况、崩溃历史、恢复步骤）

知识主题

全球话题 (user, preferences)存储在共享的全局存储中 ~/.memory-mcp/global/ 并且可以从所有瓣叶进入。这意味着您的身份和编码偏好会在每个存储库中跟随您，而不会重复。

智能表面处理

• 除尘检测：当您存储条目时，响应会显示同一主题中类似的现有条目（关键字重叠>35%）以及合并说明
• 首选表面处理：存储非偏好条目会显示可能冲突的相关偏好
• 临时审查门：默认情况下，可能短暂的内容在持久化之前会被阻止。重新运行 memory_store(..., durabilityDecision: "store-anyway") 只有当你故意想保留它的时候。
• 小猪背提示: memory_correct 建议将更正存储为可重用的首选项
• memory_context：用自然语言描述你的任务，并通过基于主题的提升获得所有主题的排名结果（偏好1.8x，陷阱1.5x）

智能筛选器语法

memory_query 支持用于精确搜索的过滤器迷你语言：

过滤器使用词干匹配，因此 reducers 火柴 reducer 和 exceptions 火柴 exception.

快速开始

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

配置

配置文件（推荐）

创建一个 memory-config.json 内存MCP服务器旁边的文件：

{
  "lobes": {
    "workspace-mcp": {
      "root": "$HOME/git/personal/workspace-mcp",
      "budgetMB": 2
    },
    "workrail": {
      "root": "$HOME/git/personal/workrail",
      "budgetMB": 2
    }
  }
}

注： memoryDir 是可选的。如果省略，存储将自动检测 .git/memory/ 对于git repos。

什么是“裂片”？ 每个存储库都有自己的内存瓣——一个专用的知识范围。把它想象成大脑区域：“工作轨道叶”存储有关工作轨道的知识，“工作空间mcp叶”存储关于工作空间mcp的知识。

优点：

• 便携式($HOME 和 ~ 跨机器的扩展工作）
• 可发现（使用 memory_list_lobes 查看配置内容）
• 易于扩展（只需添加一个新的波瓣条目）

环境变量（回退）

如果没有 memory-config.json 如果找到，服务器将回退到环境变量：

添加新Lobe

1. 编辑 memory-config.json （如果不存在则创建）
2. 添加波瓣条目：
   复制

   {
   "my-project": {
     "root": "$HOME/git/my-project",
     "budgetMB": 2
   }
   }
   

3. 重新启动内存MCP服务器
4. 验证： 使用 memory_list_lobes 确认已加载

代理将在工具描述中看到新的瓣叶，并可以立即将其与 memory_store(lobe: "my-project", ...).

MCP客户端注册

随着 memory-config.json （推荐）：

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/memory-mcp/dist/index.js"]
    }
  }
}

服务器读取 memory-config.json 自动--不需要env变量。

环境变量模式

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/memory-mcp/dist/index.js"],
      "env": {
        "MEMORY_MCP_WORKSPACES": "{\"android\":\"/path/to/android\",\"ios\":\"/path/to/ios\"}"
      }
    }
  }
}

存储位置

知识以人类可读的Markdown文件存储-- 每个条目一个文件。存储位置为 自动检测 具有以下优先级：

1. 明确的 memoryDir 配置 --如果已设置 memory-config.json 或 MEMORY_MCP_DIR，使用该路径
2. Git原生 （默认）-- <git-common-dir>/memory/ 使用 git rev-parse --git-common-dir这确保了：
   • git不可见 -- .git/ 内容永远不会被跟踪，没有 .gitignore 需要
   • 跨工作树共享 --同一仓库的所有工作树共享一个内存存储
   • 工作树/子模块安全 --解决共同问题 .git/ 目录不管
3. 中央后备 -- ~/.memory-mcp/<lobe-name>/ 对于非git目录

使用 memory_stats 或 memory_list_lobes 查看每个波瓣的内存存储位置。

文件结构

每个条目都有自己的文件。最近的工作条目按分支进行范围划分。

.git/memory/
  architecture/
    arch-e8d4f012.md              # One entry per file
  conventions/
    conv-a1b2c3d4.md
  gotchas/
    gotcha-7k3m9p2q.md
  recent-work/
    main/                          # Branch-scoped
      recent-f5e6d7c8.md
    feature-messaging-refactor/    # Sanitized branch name
      recent-9i0j1k2l.md
  modules/
    messaging/
      mod-4d5e6f7g.md

~/.memory-mcp/global/              # Global store (shared across all lobes)
  user/
    user-3f7a2b1c.md              # Personal info
  preferences/
    pref-5c9b7e3d.md              # Coding opinions & corrections

并发安全

每个条目都是一个随机十六进制ID的文件。两个MCP进程（例如Firebender+Cursor）将不同的条目写入同一个仓库 从不冲突 --它们写入不同的文件。每次读取之前，存储都会从磁盘重新加载，以从其他进程中获取更改。

分支机构近期工作范围

最近的工作条目会自动标记为当前的git分支，并存储在名为子目录的分支中。 memory_query 默认情况下，将最近的工作筛选到当前分支。使用 branch: "*" 查看各部门最近的工作。

输入格式

# Build System & Language
- **id**: arch-3f7a2b1c
- **topic**: architecture
- **confidence**: 0.70
- **trust**: agent-inferred
- **created**: 2026-02-18T12:00:00.000Z
- **lastAccessed**: 2026-02-18T12:00:00.000Z

Detected: Node.js/TypeScript project (npm)

信任级别

韧性

服务器使用 退化阶梯 即使事情出错，也要保持有用：

• 跑步 --所有肺叶健康，功能齐全
• 退化 --一些裂片未能初始化，但健康的裂片继续工作。故障瓣通过以下方式报告特定的恢复步骤 memory_diagnose.
• 安全模式 --所有脑叶都衰竭了。仅 memory_diagnose 和 memory_list_lobes 工作，给你足够的信息来解决问题。

崩溃日志：对于未捕获的异常，服务器会将结构化的崩溃报告写入 ~/.memory-mcp/crashes/ 在退出之前。下一家初创公司将崩溃暴露出来 memory_context() （简报模式），带有恢复步骤。使用 memory_diagnose(showCrashHistory: true) 查看完整的历史。

参数规范化

代理经常猜错参数名称。服务器会自动解析常见别名，以避免浪费往返时间：

通配符作用域别名(all, everything, global, project)决心 *.

建筑

types.ts          Domain types (discriminated unions, parse functions)
store.ts          MarkdownMemoryStore (CRUD, search, bootstrap, briefing)
text-analyzer.ts  Keyword extraction, stemming, similarity (stateless)
normalize.ts      Argument alias resolution (pure)
formatters.ts     Response formatters for tool handlers (pure)
config.ts         3-tier config loading (file > env > default)
git-service.ts    Git operations boundary (injectable for testing)
crash-journal.ts  Crash report lifecycle (build, write, read, format)
index.ts          MCP server, tool handlers, startup, migration

设计

看 ideas/codebase-memory-mcp-design-thinking.md 完整的设计思维文档，包含67个想法、5个概念包、尸检分析和测试计划。