TeamMemory MCP server

TeamMemory

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

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

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

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

为什么需要 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 工具 / CLI Tools

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

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

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

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

# 查看所有命令 / Show all commands
tm-cli --help

配置命令 / Configuration Commands

# 显示当前生效配置及值来源 / Show effective config with source annotations
tm-cli config show

# 交互式生成 ~/.config/tm/config.toml / Interactive config init
tm-cli config init

# 一键配置平台 Hook / One-command hook setup
tm-cli setup --platform claude-code
tm-cli setup --platform cursor
tm-cli setup --platform hermes
tm-cli setup --platform all

# 仅检查当前状态 / Check status only
tm-cli setup --platform all --check

前提：make dev 启动服务 + TEAMMEMORYAPI_KEY 环境变量已设置（或已在 ~/.config/tm/config.toml 中配置）。

MCP 接入（Cursor / Claude）

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

项目名零配置：在项目根放置 .tm.toml（见 配置说明），或系统自动从 git 仓库名推断，无需传 --project 或设 TEAMMEMORYPROJECT。

仅 pip install teammemory、无本地仓库目录**时，可在 .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"
      }
    }
  }
}

也可使用客户端配置 ~/.config/tm/config.toml（tm-cli config init 生成），避免在 JSON 中写入密钥。

（MCP 未注册 Resources / Prompts；memory 七工具：memorysave、memoryrecall、memorycontext、memorygetarchive、memoryarchiveupsert、memoryfeedback、memorysubmitresponse。详情见下文 MCP 工具列表（当前） 与 docs/guide/mcp-server.md。）

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

架构可视化（现状）

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

按角色导航

Shortened. The full README is on GitHub.