使用说明

项目内存MCP服务器

用于企业LLM的结构化、基于磁盘的项目内存。无缝集成M365。零数据库。

问题

企业团队失去了机构知识。 项目背景分散在：

电子邮件线程（Outlook）——难以搜索，与个人绑定
SharePoint文档——版本控制但孤立
团队消息——短暂的、依赖于上下文的
会议记录——经常被遗忘或卡在个人笔记本中
决策和架构——很少记录，经常重新讨论

当法学硕士需要了解一个项目时，它要么：

读取所有内容（缓慢、昂贵、嘈杂）
什么都不读（无用，盲目）
重复重新同步M365源（浪费配额和令牌）

Project Memory MCP解决了这个问题： 把你的项目记忆当作 单一事实来源 --一个所有知识都存在的中心位置，一次处理，永远重复使用。

解决方案

企业团队需要：

✅ 当地第一知识 --处理M365源代码一次，在本地存储摘要，避免重新获取
✅ 结构化存储器 --LLM理解的可预测、可导航的文件夹布局
✅ 本地RAG+语义搜索 --使用 --rag-backend embeddings 用于MCP写操作上的自动索引语义检索
✅ M365同步 --从Outlook、Teams、SharePoint自动或手动摄取
✅ 代币效率 --基于清单 read_when 提示引导LLM只加载所需的内容
✅ 人类可读和可编辑 --纯Markdown和YAML文件，无专有格式，可在任何文本编辑器中编辑
✅ 完全控制 --磁盘上的普通文件，没有供应商锁定，git版本可调
✅ 零数据库 --无需迁移，无需ORM，无需复杂的模式

项目内存MCP 是一个模型上下文协议该服务器使LLM（尤其是Claude）能够维护和查询与M365集成的结构化项目内存。

运作原理

每个项目都组织成一个 可导航文件夹层次结构 在普通磁盘上：

projects/databuddy/
├── _status.md        # Current blockers, wins, next steps (read first)
├── decisions.md      # Append-only decision log with rationale
├── knowledge/        # Processed knowledge from M365 sources
│   ├── deployment.md       # [sp:sp-contracts/deployment-reqs.pdf]
│   └── architecture.md     # Generated from [tm:teams-arch/msg-123]
├── correspondence/   # Summaries of emails, calls, messages
├── updates/          # Chronological change log (append-only)
└── people.md         # Team members (auto-updated from global links)

关键创新： 每个知识条目都存储 它从哪里来的:

source: "[sp:sp-contracts/deployment-reqs.pdf]"  # Points back to SharePoint
processed: 2026-03-29
method: summary

LLM读取本地摘要，而不是重新获取。代币成本下降了80%+。

专为M365+LLM工作流构建

三种集成模式：

自动同步管道 --计划作业读取M365，通过LLM进行汇总，并在本地存储
手动提取 --LLM在需要时调用M365 MCP，处理并存储结果
混合 --两者混合（最常见）

所有模式都将知识输入到同一个本地存储中。处理后，LLM仅使用本地摘要。

M365集成

服务器跟踪来自三个M365服务的源：

自动同步流水线 --专用VM上的计划作业：

从Outlook读取（电子邮件、线程）
来自团队的阅读（频道、消息）
从SharePoint读取（文档、库）
通过Claude API总结
在本地存储源代码参考

手动提取 --LLM启动（按需）：

LLM调用M365 MCP获取原始内容
LLM过程和总结
LLM通过带有源跟踪的存储器MCP存储

结果： 所有M365数据都会被索引，永远不会被重新获取。在第一次处理后，LLM仅使用本地摘要。

安装

pip install -r requirements.txt
python src/server.py --rag-backend embeddings

要求： Python 3.13+， fastmcp>=2.0.0, pyyaml>=6.0, pydantic>=2.0

快速开始

1.安装

pip install -r requirements.txt
python src/server.py --rag-backend embeddings  # Recommended

2.联系克劳德

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "project-memory": {
      "command": "python",
      "args": ["/path/to/src/server.py", "--rag-backend", "embeddings"]
    }
  }
}

3.尝试MCP检查器

npx @modelcontextprotocol/inspector python src/server.py --rag-backend embeddings
# Visit http://localhost:5173

HTTP传输和互联网曝光

服务器支持HTTP传输模式，用于在互联网上公开它（例如，用于远程Claude客户端）。为了安全暴露，需要进行承载令牌身份验证。

设置

复制环境模板并设置令牌：

cp .env.example .env
# Generate a strong random token:
python -c "import secrets; print(secrets.token_hex(32))"
# Paste the result as AUTH_TOKEN in .env

以HTTP模式启动服务器：

python src/server.py--后端嵌入--传输http--主机0.0.0.0--端口8000


The server prints `[auth] Bearer token auth enabled` when the token is loaded.

1. **Recommended: use a tunnel instead of direct port forwarding.**

[cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/) provides a secure, zero-config HTTPS tunnel:

```bash
# Install cloudflared (once)
# https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/

# Expose the local HTTP server
cloudflared tunnel --url http://localhost:8000

Cloudflared打印一个公共 https://…trycloudflare.com URL。在MCP客户端配置中使用该URL-- 无需端口转发或防火墙规则.

连接远程Claude客户端

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "project-memory": {
      "type": "streamable-http",
      "url": "https://<your-tunnel-url>/mcp/",
      "headers": {
        "Authorization": "Bearer <your-auth-token>"
      }
    }
  }
}

注：仅使用带有隧道（cloudflared）或终止TLS的反向代理的HTTP传输。切勿将普通HTTP端口直接暴露给互联网。

核心功能

1.结构化项目记忆

每个项目都是一个结构可预测的文件夹：

要素	目的
`_status.md`	始终为当前状态（LLM首先读取）
`decisions.md`	仅附加决策日志
`knowledge/`	来自M365或手动输入的处理知识
`correspondence/`	电子邮件、电话、带日期的消息摘要
`updates/`	按时间顺序更新日志（仅可追加）
`people.md`	团队成员（由链接自动生成）

2.M365源跟踪

每个知识入口都指向其来源：

source: "[sp:sp-contracts/msa.pdf]"  # SharePoint file
        # or "[tm:teams-sales/msg-123]"  # Teams message
        # or "[ol:outlook-sales/thread-456]"  # Outlook email
processed: 2026-03-29
method: summary

LLM使用本地摘要。无需重新取回。节省80%以上的代币。

3.自动管理交叉引用

服务器维护三个索引：

索引	它跟踪什么
`_index.yaml`	文件描述+ `read_when` 提示（每个文件夹）
`_projects-index.json`	快速项目列表
`_refs-index.json`	`@person`, `@company`, `[[link]]` 参考文献

4.智能清单提示

这 read_when 现场指南LLM加载：

knowledge/deployment.md:
  description: "Deployment requirements and SLA"
  read_when: "When planning releases or understanding constraints"

LLM跳过不需要的文件→ 更便宜，更快。

5.全文RAG索引

所有项目文件（除 _index.yaml)使用TF-IDF（或嵌入）自动索引对于快速语义搜索：

{
  "_rag_index.json": {
    "docs": {
      "projects/databuddy/knowledge/architecture.md": {
        "tf": { "snowflake": 0.045, "migration": 0.032, ... },
        "mtime": 1774796858.3323283,
        "indexed_at": "2026-03-29T18:49:17.855188+00:00"
      }
    }
  }
}

这些目录中的每个文件都会自动索引和搜索：

目录	索引	目的
`_global/people/`	✅ 全部 `.md` 文件	团队成员配置文件（自动索引）
`_global/companies/`	✅ 全部 `.md` 文件	合作伙伴和客户信息
`projects/{slug}/knowledge/`	✅ 全部 `.md` 文件	已处理的知识和摘要
`projects/{slug}/correspondence/`	✅ 全部 `.md` 文件	电子邮件、电话和消息摘要
`projects/{slug}/updates/`	✅ 全部 `.md` 文件	按时间顺序更新项目
`projects/{slug}/decisions.md`	✅ 单个文件	决策日志（仅可追加）
`_index.yaml` 文件	❌ 从不	自动管理清单（不包括）

文件更改时，索引会自动更新。使用索引：

语义搜索 --按含义而非关键字查找相关上下文
链接发现 --无需阅读所有内容，即可理解相关内容
上下文路由 --将LLM查询路由到最相关的文件
代币效率 --只阅读对当前任务重要的内容

文档

服务器包括 5个内置MCP资源 （自动送达）：

资源	目的
`memory://quick-reference`	令牌语法、文件系统规则、参数
`memory://guide`	完整的服务器指南和工具清单
`memory://m365`	M365同步流水线和源注册
`memory://skill`	新用户飞行前检查表
`memory://new-project`	12步项目设置演练

所有资源都存在 skill/ 并在编辑时自动更新。

项目结构

project-memory-mcp/
├── src/
│   ├── server.py              # MCP server + tools + resources
│   ├── filesystem.py          # MemoryFS class + all file operations
│   ├── guide.py               # Resource generators
│   ├── models.py              # Pydantic data models for all schemas
│   └── templates.py           # Template strings for scaffolded files
├── skill/                     # Claude skill documentation (upload as .zip)
│   ├── SKILL.md               # Skill frontmatter + pre-flight checklist
│   └── references/
│       ├── quick-reference.md # Token syntax, filesystem rules, parameters
│       ├── guide.md           # Server guide, tool inventory, folder routing
│       ├── m365-guide.md      # M365 sync pipeline and integration
│       └── creating-new-project.md  # 12-step project setup guide
├── scripts/
│   └── migrate_newlines.py    # Fix escaped newlines in markdown files (one-time use)
├── tests/
│   ├── conftest.py            # Test configuration
│   └── tests.py               # Full test suite (130+ tests)
├── docs/
│   ├── tool-reference.md      # Complete tool reference (legacy, see skill/ instead)
│   ├── memory-root-schema.md  # File/folder schemas with examples
│   └── filesystem-rules.md    # Enforcement rules and triggers
├── memory-root/               # Example projects and global entities
├── README.md
├── LICENSE                    # MIT License
└── requirements.txt

文档

主要文档现在位于 skill/ 文件夹为 Markdown资源 由服务器自动提供服务：

资源	来源	主题
`memory://quick-reference`	`skill/references/quick-reference.md`	令牌语法、文件系统规则、工具参数
`memory://guide`	`skill/references/guide.md`	完整的服务器指南、文件夹路由、工具清单
`memory://m365`	`skill/references/m365-guide.md`	M365同步管道、源代码注册、参考语法
`memory://skill`	`skill/SKILL.md`	新用户飞行前检查表
`memory://new-project`	`skill/references/creating-new-project.md`	12步项目初始化演练

参考文档（为向后兼容而保留）：

文档	内容
docs/tool-reference.md	刀具参数和返回形状（被资源取代）
docs/memory-root-schema.md	带有YAML示例的文件和文件夹模式定义
docs/filesystem-rules.md	执行规则：触发错误与警告的原因

包装克劳德技能

这 skill/ 文件夹是一个独立的Claude技能。与Claude一起使用：

步骤1：创建ZIP存档

# Windows PowerShell
Compress-Archive -Path .\skill\* -DestinationPath .\project-memory-mcp-skill.zip -Force

# macOS / Linux
cd skill && zip -r ../project-memory-mcp-skill.zip . && cd ..

第二步：上传至Claude

转到Claude.ai
打开设置(⚙️) → 管理自定义技能
点击“创建技能”→ 上传ZIP
选择生成的 project-memory-mcp-skill.zip

该技能现在可以在所有克劳德对话中使用。

数据维护

修复转义的换行符（一次性迁移）

如果你不小心写了带有转义换行序列的文件(\n 而不是实际的换行符）：

python scripts/migrate_newlines.py --dry-run  # Preview changes
python scripts/migrate_newlines.py              # Apply fixes

规范化也会自动在所有 write_file 和 append_to_file 行动向前。

测试

# Install test dependencies
pip install -r requirements.txt pytest

# Run all tests
python -m pytest tests/ -v

# Run specific test suite
python -m pytest tests/tests.py::TestGuideResource -v

# Run with coverage
python -m pytest tests/ --cov=src

建筑与设计

为什么是普通文件？

普通Markdown和YAML文件是：

人类可读 --在任何文本编辑器中直接编辑或阅读
Git 版本 --完整的审计跟踪，轻松协作
架构稳定 --需求更改时不进行数据库迁移
LLM本地 --克劳德可以直接读写

为什么 `_index.yaml` 清单？

清单存储 read_when 每个文件的提示。这是LLM用来决定加载什么的主要信号：

无舱单：每个呼叫要么读取所有内容（缓慢、昂贵），要么什么也不读取（盲目）
有清单：LLM跳过不需要的文件，减少延迟和令牌成本
RAG兼容：清单成为语义搜索的预过滤器--嵌入 description + read_when，缩小范围，仅加载相关文件

为什么要软删除(`_trash/`)?

文件已移动到 _trash/ 是：

可恢复的 --还原错误删除的文件
可审计的 --删除内容和时间的完整历史
可逆的 --与永久删除不同，这是一个MCP操作（不需要磁盘级操作）

为什么要进行代币优化？

服务器旨在最大限度地减少令牌使用：

舱单引导加载 --LLM使用 read_when 跳过不必要文件的提示
地方优先原则 --在本地存储处理过的知识；避免重新获取相同的M365内容
快速查阅 --合并 memory://quick-reference 资源取代了分散的文档
仅附加日志 --只有更改的条目会被重新读取，而不是整个文件

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

请包括新功能的测试，并根据需要更新文档。

许可证

该项目根据 MIT许可证 --看许可证文件以获取详细信息。

支持

GitHub问题 --报告错误或请求功能这里
讨论 --提问或分享想法这里
文档 --请参阅 skill/ 详细参考资料指南

致谢

内置于 FastMCP 设计用于克劳德通过Anthropic。

制作❤️ 法学硕士辅助项目管理