TeamMemory

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 工具 / 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 启动服务 + TEAM_MEMORY_API_KEY 环境变量已设置（或已在 ~/.config/tm/config.toml 中配置）。

MCP 接入（Cursor / Claude）

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

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

仅 `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" } } } }

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

（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（动态层） ← 本项目 │ │ 从日常开发中自动积累的团队经验，语义可搜索，持续演化 │ │ 例：Bug 根因分析、架构决策背景、接口的隐藏坑 │ ├─────────────────────────────────────────────────────────┤ │ 代码 + 文档（基础层） │ │ 项目源码和文档，AI 可直接读取 │ │ 例：函数定义、README、注释 │ └─────────────────────────────────────────────────────────┘

三层之间存在自然的知识生命周期：

日常开发会话

│ ▼ AI 自动提取经验 ──→ TeamMemory（动态积累） │ │ │ ▼ 模式稳定后 │ 固化为 Rules / Skills │ │ └──── 新问题 / 新变化 ←─┘

Rules/Skills 无法覆盖的知识，正是 TeamMemory 的价值所在：那些太碎、太多、变化太快，不适合写成规则，但恰恰是团队"老手"和"新手"之间最大差距的经验。

术语表

功能概览

自动学习

AI 从对话和文档中自动提取结构化经验，无需手动录入：

• 对话提取：通过 MCP **memory_save(content=...) 走 LLM 解析，从长对话中识别问题、方案、标签并写入（含质量门控）；Web** 上亦支持粘贴文档或 URL 解析
• 文档解析：上传文档或输入 URL，AI 自动解析为标题、问题描述、解决方案、标签
• 经验组：保存时可选 **group_key**（MCP / HTTP）将相关经验归组；复杂编排可在 Web 完成
• 默认草稿模式：AI 提取的内容默认为草稿，经人工审核后发布，保证质量

智能检索

多层检索管线，确保 AI 找到最相关的历史方案：

• 语义搜索：基于向量嵌入（Ollama / OpenAI / 本地模型），理解查询意图
• 混合检索：向量搜索 + 全文检索 + RRF 融合排序
• 查询优化：同义词扩展（config.tag_synonyms）、短查询自动降低 min_similarity（0.45）；FTS 使用 simple 分词器 + jieba 中文分词 + hybrid AND/OR 策略（前 2 词 AND 保证精度，其余 OR 提升召回）
• Reranker：支持服务端 LLM 精排，或客户端 AI 自行判断结果相关性
• Token 预算控制：自动裁剪输出长度，避免经验库增大后撑爆 AI 上下文
• 记忆压缩与摘要：经验支持 summary 字段，LLM 可生成简短摘要；单条（POST /experiences/{id}/summarize）与批量（POST /experiences/batch-summarize）生成；MCP 搜索结果中每条经验可包含 summary，便于节省 Token
• PageIndex-Lite：长文档自动分块建立节点索引，支持节点级精准检索
• 个人扩写：per-user tag_synonyms 在检索前生效（词表替换 + LLM 扩写），MCP 搜索返回后自动维护；Web 设置 → 个人扩写
• 个人记忆 / 用户画像：按 user_id 隔离；Lite 下由 **memory_save(..., content=...) 解析等路径可写入；`memory_context` 返回 `profile.static` / `profile.dynamic`（字符串列表）。Web 设置 → 用户画像 可分组查看、过滤 static/dynamic 并 删除** 错误条目（还可调 HTTP API profile_kind）。
• 文件位置绑定：保存经验时可传 file_locations（路径 + 行范围，可选 snippet/file_mtime/file_content_hash）；检索时可传 current_file_locations，与当前编辑位置匹配的经验会获得 location 加分，详见 src/team_memory/server.py 工具参数与 docs/guide/mcp-server.md。

三层作用域

• global：全局共享知识
• team：团队/项目级经验
• personal：个人笔记与草稿

经验类型自动分类

保存时可根据内容自动推荐经验类型（general/feature/bugfix/tech_design/incident/best_practice/learning），减少手动选择。

经验质量打分系统

自动评估经验的活跃度和价值，让高质量经验脱颖而出：

• 阶梯衰减：新经验 100 分起步，10 天保护期后未被引用每天 -1 分（低于 50 分后 -0.5/天）
• 引用加分：每次被检索命中（含 memory_recall / Web 搜索管线）+2 分，获 4 星以上评价 +1 分
• 质量等级：Gold (≥120) / Silver (≥60) / Bronze (≥20) / Outdated (≤0)
• 置顶免衰：手动置顶的经验永不衰减（年度发布流程等长期有效经验）
• Outdated 管理：分值归零的经验仍可搜索到，但在管理面板提示处理（恢复/删除/置顶）
• 规则可配：初始分值、衰减速率、加分幅度、等级阈值均可在设置页调整

结构化管理

不是随意堆放的笔记，而是有类型、有层级、有评分的经验体系：

• 7 种经验类型：通用、需求、Bug、技术方案、故障、最佳实践、学习笔记，每种类型有专属结构化字段
• 父子层级存储：支持将相关经验组织为经验组（如：一个需求从评审到上线的全过程）
• 完整度评分：0-100 分自动评分，鼓励团队逐步完善经验
• 生命周期管理：草稿 → 审核 → 发布 → 过期检测 → 去重合并

团队协作

多人共建共享的团队知识库：

• RBAC 权限：admin / editor / viewer 三级角色
• 反馈评分：1-5 星评分影响搜索排序，低分经验自动降权
• 版本历史：就地编辑 + 版本快照，支持回滚
• 去重检测：保存前自动检测相似经验，避免重复录入
• 合并建议：设置页标记建议合并的相似经验对，三栏 Git-Conflict 风格 diff 对比 + 合并预览
• 多项目隔离：通过 project 参数隔离不同项目的经验，避免跨项目污染

无缝集成

原生 MCP 协议支持，AI 助手通过 stdio 接入：

• MCP 工具（7 个）：memory_context、memory_recall、memory_get_archive、memory_archive_upsert、memory_save、memory_feedback、memory_submit_response（见 MCP 工具列表）
• 当前 MCP 未注册 Resources / Prompts；补齐体验以 Web、/docs HTTP API 为准
• Web 管理界面：浏览、搜索、审核、档案馆、配置等

旧文若仍写 **tm_* MCP 或任务看板等已下线能力，以 本文**、AGENTS.md 与 src/team_memory/server.py 为准。

TM Daemon（自动采集与精炼）

后台守护进程，自动从 Obsidian vault 和 Agent 对话中采集经验：

• Obsidian Watcher：监听 vault 文件变更，自动创建 draft（同文件去重，更新而非重复创建）
• RefinementWorker：每 30 秒扫描 pending draft，调用 LLM（GLM-5-Turbo）提取结构化字段（title/problem/solution/tags），自动发布
• 学习卡片跳过：识别学习类内容（卡片-、主题-、Layer 等），直接发布不走 LLM 抽取
• 入口命令：tm-daemon（即 python -m team_memory.daemon），make daemon-start / make daemon-stop（launchd 托管），日志 /tmp/tm-daemon.log
• 代码位置：src/team_memory/daemon/（原 scripts/daemon/）

Faithfulness 评估系统

基于 RAGAS 思路，用 LLM Judge 评估搜索结果是否被 Agent 真实使用：

• 自动捕获：Daemon 的 after_response hook 自动缓存 (query, response, result_ids) 到 response_buffer
• 批量评估：buffer 积累到阈值（默认 5 条）后自动触发 LLM Judge（GLM-5-Turbo）
• 评估逻辑：拆解 Agent 回复为 claims → 逐条检查是否能从检索结果推断 → 输出 faithfulness score
• 结果回流：score ≥ 0.5 自动标记 search_log 为 was_used，影响 use_rate 统计
• 查看方式：make stats（Faithfulness 面板）、make faithfulness-eval --show 10、curl localhost:3901/status/faithfulness
• 模型可配：--model GLM-5-Turbo --base-url http://localhost:4000/v1

Wiki 编译与实体关系

从经验库自动编译知识 Wiki：

• 实体提取：LLM 从经验中提取工具、概念、人物等实体（L2.5 层）
• 关系发现：建立实体间的 uses/depends/conflicts 关系
• 主题发现：自动聚类经验为主题，LLM 生成主题名
• 矛盾检测：规则 + LLM 双重验证，发现相互矛盾的经验对
• 命令：make wiki-compile、make entity-backfill、make detect-contradictions

一键部署

最小化上手成本：

• make setup 一键完成全部安装
• 最小配置模板只需改 2 项即可启动
• Docker Compose 自动拉取所需模型
• 统一端口 9111，健康检查一键诊断

快速开始

以下从初次部署者（把 TeamMemory 跑起来的人）和初级使用者（在 Cursor/Claude 里连上已有服务的人）两种角色，按最小步骤说明。

前提条件

一、初次部署者：一键部署

你是第一次在团队里部署，目标是：跑起 Web、拿到 API Key、并交给同事用。

1. 一键初始化

克隆仓库后，在项目根目录执行：

make setup

会完成：启动 Docker（PostgreSQL+pgvector、Ollama、Redis）、安装 Python 依赖、执行数据库迁移。成功时输出 ✔ Setup complete!。常见失败原因：Docker 未启动、5432/11434 端口被占用、pip 安装失败。

2. 改配置

默认使用仓库根目录 config.development.yaml。确认 database.url 与本地 Postgres 一致；auth.api_key 建议用环境变量注入：

设置环境变量作为管理员引导密钥（首次部署必须；勿提交 Git、勿明文写入配置文件）：

export TEAM_MEMORY_API_KEY=$(openssl rand -hex 32)

echo "你的管理员 API Key: $TEAM_MEMORY_API_KEY"

首次登录

• 打开 http://localhost:9111
• 点击「使用 API Key 登录」
• 将上面的 TEAM_MEMORY_API_KEY 粘贴到输入框，点击「登录」
• 登录成功后即为 admin，右上角显示当前用户名

该 Key 仅在内存中生效（与 config 中的 auth.api_key 一样），重启服