TeamMemory

mcp-name: io.github.ysydhc/team-memory

让 AI 拥有团队记忆 — 跨会话积累经验，像资深成员一样理解你的项目。

这是我学 AI 时萌生的一个想法。市面上已有类似产品，但总觉得不太贴合自己的使用习惯。做这个项目，既想通过和 AI 一起写代码来加深对大模型的理解，也希望能按自己的工作流，打磨出真正顺手的功能。

给 Agent / 贡献者：AGENTS.md · docs/README.md · MCP 实现 src/team_memory/server.py · 分层约束见 scripts/harness_import_check.py（LAYER_MAP）

为什么需要 TeamMemory？

用 Cursor、Claude 等 AI 助手写代码时，往往会遇到三个问题：

TeamMemory 就是冲着这三个问题来的。 通过 MCP 把语义可搜索的经验库接进 AI：遇到问题自动查历史方案，解决后自动提炼并存下来，下次谁遇到同类问题，直接就能命中。既适合 3–10 人的技术团队共享，也适合部署在本地个人使用，配合 Cursor / Claude Desktop。

快速开始（4 条命令 + 1 项配置）

环境：Docker Desktop、Python 3.11+、Make

# 1. 初始化（Docker + 依赖 + 数据库）
make setup

# 2. 设置 API Key（唯一必改项；与 Web 签发的原始密钥同为 64 位十六进制，见 docs/decision/auth-api-key-design.md）
export TEAM_MEMORY_API_KEY=$(openssl rand -hex 32)
echo "API Key: $TEAM_MEMORY_API_KEY"

# 3. 拉取 Embedding 模型（仅首次需要）
ollama pull qwen3-embedding:0.6b

# 4. 启动
make web

浏览器访问 http://localhost:9111 ，用上面的 API Key 登录即可。更完整的部署与用户流程见下文 按角色导航 与 快速开始。

CLI 工具

除 MCP 外，所有 memory_* 工具也可通过 tm-cli 命令行调用：

# 搜索团队知识
tm-cli recall --query "如何配置"

# 保存经验
tm-cli save --title "Bug fix" --problem "连接超时" --solution "增加重试"

# 获取上下文
tm-cli context --file-paths "src/server.py"

# 查看所有命令
tm-cli --help

前提：make dev 启动服务 + TEAM_MEMORY_API_KEY 环境变量已设置。

MCP 接入（Cursor / Claude）

本仓库（克隆源码）推荐：不要把 API Key 写进 mcp.json。在仓库根维护 .env（从 example/env.team-memory.example 复制），其中至少设置 TEAM_MEMORY_API_KEY、TEAM_MEMORY_PROJECT；MCP 配置为 bash + scripts/run_mcp_with_dotenv.sh + cwd= 仓库根。详见 docs/guide/mcp-server.md。Cursor 一般用 .cursor/mcp.json，Claude Code 可用根目录 .mcp.json，两处内容建议保持一致。

仅 pip install team_memory、无本地仓库目录时，可在 .cursor/mcp.json 里用本机 Python 与环境变量（数据库与 Key 仍需提供）：

{
  "mcpServers": {
    "team_memory": {
      "command": "python3",
      "args": ["-m", "team_memory.server"],
      "env": {
        "TEAM_MEMORY_DB_URL": "postgresql+asyncpg://developer:devpass@localhost:5433/team_memory",
        "TEAM_MEMORY_API_KEY": "你的 API Key"
      }
    }
  }
}

（MCP 未注册 Resources / Prompts；memory_* 七工具：memory_save、memory_recall、memory_context、memory_get_archive、memory_archive_upsert、memory_feedback、memory_submit_response。详情见下文 MCP 工具列表（当前） 与 docs/guide/mcp-server.md。）

本机直连数据库时需要配 TEAM_MEMORY_DB_URL（或通过 config）；从源码跑且项目里已有 config 的，可不单独设 DB_URL。

架构可视化（现状）

Web 内「架构」导航与 /api/v1/architecture/* 已移除（实现见 src/team_memory/web/static/js/pages.js）。若需要代码库图谱，请在本机单独使用 GitNexus（CLI / Bridge 等），与当前 TM Web 无集成。

按角色导航

目录

• 功能概览 · 快速开始 · CLI 工具 · MCP 接入 · Web 管理 · 配置 · 运维 · FAQ · 开发

安装与获取

• PyPI：pip install team_memory（推荐用于部署或本地 MCP 客户端）。
• MCP 官方注册表：在 MCP Registry 或 Cursor / Claude Desktop 的 MCP 市场中搜索「TeamMemory」或「team-memory」，可一键发现并安装（安装后仍需配置数据库连接与 API Key，见下文）。

TeamMemory 在 AI 知识体系中的位置

AI 助手在项目中可用的知识分为三层，每一层解决不同的问题：

┌─────────────────────────────────────────────────────────┐
│  Rules / Skills（静态层）                                │
│  已确定的规范和成熟的工作流，手动维护，变化频率低            │
│  例：代码风格规范、部署流程、API 用法                      │
├─────────────────────────────────────────────────────────┤
│  TeamMemory（动态层）          ← 本项目                  │
│  从日常开发中自动积累的团队经验，语义可搜索，持续演化

... [View full README on GitHub](https://github.com/ysydhc/team_memory#readme)