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 助手写代码时，往往会遇到三个问题：

盲区	现象
无记忆	上周刚帮你修过的 Bug，这周遇到类似的，它完全不记得
只见代码，不懂决策	能看懂「是什么」，却不知道「为什么这么写」「上次踩过什么坑」
静态知识不够用	Rules、Skills 管得了规范，管不住每天冒出来的隐性经验（接口坑、故障根因、被否掉的方案）

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 复制），其中至少设置 **TEAM_MEMORY_API_KEY**；MCP 配置为 **bash** + **scripts/run_mcp_with_dotenv.sh** + **cwd= 仓库根。详见 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 无集成。

---

按角色导航

角色	目标	入口
初次部署者	跑起 Web、拿到 API Key	快速开始 → 一、初次部署者
初级使用者	在 Cursor/Claude 里接入	快速开始 → 二、初级使用者
贡献者	改代码、提 PR	开发

目录

• 功能概览 · 快速开始 · 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 的价值所在：那些太碎、太多、变化太快，不适合写成规则，但恰恰是团队"老手"和"新手"之间最大差距的经验。

术语表

术语	说明
经验	单条问题-方案对，可被检索和复用
经验库	经验的集合
scope	作用域：global（全局）、team（团队）、personal（个人）
Embedding	向量嵌入，用于语义搜索；配置项为 embedding
MCP	Model Context Protocol，让 AI 客户端调用 memory_recall、memory_save 等工具

功能概览

自动学习

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 とエージェントの会話から経験を自動収集します。

• 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 を使用して検索結果がエージェントに実際に使用されたかを評価します。

• 自動キャプチャ：Daemon の after_response hook が (query, response, result_ids) を response_buffer に自動キャッシュします
• 一括評価：buffer がしきい値（デフォルト 5 件）に達すると、LLM Judge（glm-4-flash）が自動的に起動します
• 評価ロジック：エージェントの返信を 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-4-flash --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 から既存のサービスに接続する人）の 2 つの役割に分けて、最小限の手順を説明します。

前提条件

依存関係	確認方法
Docker Desktop	docker --version
Python 3.11+	python3 --version
Make	make --version（macOS/Linux には通常標準で付属しています）
Ollama	ollama --version（初回の make web 前にモデルを取得するために使用します。下記を参照）

一、初回デプロイ担当者：ワンクリックデプロイ

チームに初めてデプロイする場合の目標は、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 と同様です）。サービスの再起動後も、同じ環境変数を使えばこの Key で再度ログインできます。「ユーザー名 + パスワード」でログインして長期的に使用する場合は、下記の「任意：自分用の永続的な Admin アカウントを作成する」を参照してください。

方法二：設定ファイル

config.development.yaml（または TEAM_MEMORY_CONFIG_PATH が示すファイル）に次のように設定します。

auth:
  type: db_api_key
  api_key: "${TEAM_MEMORY_API_KEY}"   # 从环境变量读取
  user: admin

または、平文で直接記載します（ローカル環境／テスト環境のみ。Git にコミットしないでください。本番環境では禁止です）。

auth:
  type: db_api_key
  api_key: "你的 API Key"
  user: admin

サービスの起動後、Web のログインページで「API Key でログイン」を選択し、この api_key を使用すると admin 権限でログインできます。

任意：自分用の永続的な Admin アカウントを作成する

「ユーザー名 + パスワード」でログインし、初期設定用 Key に依存しないようにするには、次の手順を実行します。

1. 初期設定用 Key を使い、Web に admin としてログインします。
2. 設定 → ユーザー管理に移動し、「ユーザーを追加」をクリックします。
3. 次の項目を入力します。

• ユーザー名：admin または自分の英語名など
  • ロール：admin
  • 初期パスワード：強力なパスワードを設定します（Web ログインに使用します）

4. 「作成」をクリックします。システムが API Key（MCP クライアント用）を生成して表示するので、コピーして保存してください。
5. 以降は次の方法で利用できます。

• Web：設定したユーザー名 + パスワードでログインします。
  • MCP：Cursor/Claude の mcp.json で、生成した API Key を TEAM_MEMORY_API_KEY として使用します。

初期設定用 Key（環境変数または config 内の key）とデータベース内のユーザーは、それぞれ独立しています。初期設定用 Key は、初回に admin 権限を取得するためだけに使用します。以降は、日常的にデータベース内の admin アカウント（ユーザー名 + パスワード + 自分用の API Key）を使用できます。

デフォルトの Docker データベースを使用する場合は、database.url を変更する必要はありません。それ以外の場合は、PostgreSQL の接続文字列に変更してください。

3. Embedding モデルを取得する（初回のみ）

make setup によって Ollama コンテナが起動します。初回の make web より前に、次を実行してください。

ollama pull qwen3-embedding:0.6b

4. Web を起動する

make web

ブラウザーで http://localhost:9111 を開きます。

初回ログイン：「API Key でログイン」に切り替え、前の手順で設定した TEAM_MEMORY_API_KEY を入力すると、admin としてログインできます。

複数人での利用

• チームメンバーがログインページで「登録」をクリックし、ユーザー名とパスワードを入力します
• Admin が「設定 > ユーザー管理」で登録申請を承認すると、システムが API Key を自動生成します
• Admin が API Key をメンバーに配布し、MCP クライアント（Cursor/Claude Desktop）の接続に使用します
• 以降、メンバーは Web にはユーザー名 + パスワードでログインし、MCP には API Key を使用します

5. 任意：ヘルスチェック

make health

成功すると、PostgreSQL: OK、Ollama: OK、Web: healthy などが出力されます。database または ollama が FAIL の場合は、案内に従って該当するサービスを起動するか、マイグレーションを実行してください。

Web に初めてアクセスしたときに経験が 0 件と表示されても、正常です。 まずテスト用の経験を 1 件追加し、手順が正しく動くことを確認できます。

次回以降の日常的な起動には、make dev を実行するだけです（または、先に docker compose up -d を実行してから make web を実行します）。その他のコマンドについては、下記の「運用」を参照してください。

---

二、初级使用者：在 Cursor / Claude 里接入

你已经从部署者拿到 API Key，TeamMemory 的数据库（和 Web）已就绪。只需在本机配置 MCP 并验证。

1. 安装（本机跑 MCP 时）

pip install team_memory

若通过 Cursor/Claude 的「MCP 市场」安装 TeamMemory，按客户端说明即可，可能无需本机再装。

2. 拿到 API Key 与数据库连接

• 向部署者索取 TEAM_MEMORY_API_KEY。
• 若你本机直连团队 PostgreSQL（即 MCP 进程自己连库），还需 TEAM_MEMORY_DB_URL（如 postgresql+asyncpg://用户:密码@主机:5432/team_memory）。若你使用「从源码运行」且项目目录下已有正确配置，可不设 DB_URL，由 config 提供。
• 或运行 tm-cli config init 交互式生成 ~/.config/tm/config.toml，后续无需再设环境变量。

3. 配置 MCP

在 Cursor 中编辑项目或用户下的 .cursor/mcp.json；在 Claude Desktop 中编辑 MCP Servers 对应配置。MCP 的当前用户由 TEAM_MEMORY_API_KEY 解析（与 Web 同账号即同一人）；TEAM_MEMORY_USER 仅在不设 Key 或解析失败时作为回退，可选。

• 从源码运行本仓库（推荐：TEAM_MEMORY_* 进 .env，密钥不进 JSON）：将 example/env.team-memory.example 复制为仓库根 .env 并填写；执行 chmod +x scripts/run_mcp_with_dotenv.sh；把 example/cursor-mcp-team-memory.example.json 里的绝对路径换成你的目录后写入 .cursor/mcp.json / .mcp.json：

{
  "mcpServers": {
    "team_memory": {
      "command": "bash",
      "args": ["/ABSOLUTE/PATH/TO/team_doc/scripts/run_mcp_with_dotenv.sh"],
      "cwd": "/ABSOLUTE/PATH/TO/team_doc"
    }
  }
}

• 从 pip 安装、无项目目录：用本机 Python + env 块（无需 cwd）：

{
  "mcpServers": {
    "team_memory": {
      "command": "python3",
      "args": ["-m", "team_memory.server"],
      "env": {
        "TEAM_MEMORY_DB_URL": "postgresql+asyncpg://用户:密码@主机:5432/team_memory",
        "TEAM_MEMORY_API_KEY": "你的 API Key"
      }
    }
  }
}

• 备选（不建议提交到 Git）：仍可在 mcp.json 的 env 里写 TEAM_MEMORY_API_KEY / TEAM_MEMORY_PROJECT；多仓库时更易分叉泄露，优先用 .env + 包装脚本。

4. 验证

重启 Cursor 或 Claude Desktop，在对话里请 Agent 使用 **memory_recall**（或 **memory_context**）搜索与 Docker 相关的经验。若配置正确，会返回 JSON 结果。约定见 mcp-lite-default.md。

---

其他安装方式

• 仅 Docker、不克隆源码：若你只想跑 Web 不跑本地 MCP，可用 docker compose up -d 启动（含数据库迁移）。在 .env 中设置 TEAM_MEMORY_API_KEY（默认 changeme 请修改）。生产环境必须修改默认 Key，禁止使用 changeme。访问 http://localhost:9111 。
• 从 PyPI 部署、无 Make：pip install team_memory 后，需自备 PostgreSQL（pgvector）并在项目根目录执行 alembic upgrade head，再通过 TEAM_MEMORY_CONFIG_PATH 或 TEAM_MEMORY_DB_URL 启动 team-memory-web 或 **team-memory**（MCP）。入口命令：team-memory-web（Web）、team-memory（MCP）、tm-cli（CLI）、tm-daemon（Daemon）。

---

MCP 接入指南（配置参考）

克隆本仓库时：优先 **.env + scripts/run_mcp_with_dotenv.sh**，mcp.json 不写密钥；完整步骤见 docs/guide/mcp-server.md。

Cursor（.cursor/mcp.json）— 从 pip 安装、无项目目录：

{
  "mcpServers": {
    "team_memory": {
      "command": "python3",
      "args": ["-m", "team_memory.server"],
      "env": {
        "TEAM_MEMORY_DB_URL": "postgresql+asyncpg://用户:密码@主机:5432/team_memory",
        "TEAM_MEMORY_API_KEY": "你的 API Key"
      }
    }
  }
}

从源码目录运行且不用包装脚本时（备选）：将 command 指向项目 .venv/bin/python，设 "cwd" 为仓库根，env 中提供 TEAM_MEMORY_API_KEY 等（数据库可由项目内 config 提供）。

Claude Desktop：在 MCP 设置中添加同名 team_memory 条目；源码场景推荐与上文相同的 bash + run_mcp_with_dotenv.sh，pip 场景与上一致即可。

变量	必填	说明
TEAM_MEMORY_DB_URL	是（或由 config 提供）	PostgreSQL 连接串，postgresql+asyncpg://...，库需启用 pgvector
TEAM_MEMORY_API_KEY	推荐	与 Web 同账号的 API Key；MCP 据此解析为当前用户，与 Web 身份统一
TEAM_MEMORY_USER	否	项目级 mcp.json 中配置：写入经验的归属用户（你的 Web 账号），避免「不知谁写入」；不设 API Key 时也作回退，默认 anonymous
TEAM_MEMORY_PROJECT	否	项目级 mcp.json 中配置：写入经验的归属项目名；不设则用服务端 default_project
TEAM_MEMORY_CONFIG_PATH	否	配置文件路径，设置则优先从该文件加载

MCP 身份与 Web 统一：MCP 的当前用户（current_user）优先由 TEAM_MEMORY_API_KEY 经服务端 AuthProvider 解析得到，与 Web 使用同一套用户体系。配置与 Web 同账号的 API Key 后，在 Cursor 里写入的 personal 经验在同一 Cursor 会话内可被检索到，且 Web 用该账号登录后也能看到。推荐只配置 TEAM_MEMORY_API_KEY（与 Web 同账号的 Key），无需再设 TEAM_MEMORY_USER。

项目级归属（用户 / 项目名）：推荐使用 **.tm.toml** 声明项目名（见 配置说明 / Project Config），系统也会自动从 git 仓库名推断——大多数情况下无需手动配置。若需显式指定，可在仓库根 **.env** 中设置 TEAM_MEMORY_PROJECT（及按需 TEAM_MEMORY_USER），与包装脚本一起使用。解析顺序：.tm.toml > **TEAM_MEMORY_PROJECT** > git 仓库名 > 目录名 > 配置 default。

Docker/Helm：若通过容器或编排部署，在配置中注入上述环境变量；生产环境禁止使用占位或默认 Key（如 changeme）。

回滚说明：MCP 身份解析逻辑无 DB 变更。若需回滚，仅还原 src/team_memory/server.py 中相关改动，并通知用户恢复依赖 TEAM_MEMORY_USER 的配置即可。

实际场景：AI 如何使用 TeamMemory

场景 1：遇到问题，AI 先查团队经验

你：这个 Docker 容器的网络一直不通，帮我看看

AI 的推荐行为：
  1. 调用 memory_recall(problem="Docker 容器网络不通", framework="docker")
  2. 命中团队经验：「上次是 bridge 网络 DNS 解析问题，需要指定 --dns」
  3. 基于命中结果给出步骤，并在合适时 memory_save 沉淀新结论

场景 2：问题解决后保存

排查结束后，可由 AI 调用 memory_save(title=..., problem=..., solution=...)
或 memory_save(content="…长对话…") 走解析后写入（常为草稿，视服务配置而定）。

场景 3：打开文件时带一点上下文

AI 可调用 memory_recall(file_path="k8s/deployment.yaml", framework="kubernetes")
按路径/框架取相关经验（等价于旧文档中的「suggest」类用法）。

MCP 工具列表（当前）

工具	功能	输入要点
memory_context	任务开始拉上下文 + 用户画像摘要 + 相关经验	file_paths 等（以工具 schema 为准）
memory_recall	统一检索：problem / query / file_path 等	至少提供其一；可选 include_archives、include_user_profile
memory_get_archive	档案 L2 全文	archive_id（通常在 recall 命中 type=archive 后调用）
memory_archive_upsert	创建/更新档案馆（与 POST /api/v1/archives 一致）	title、solution_doc 等；大文件见 mcp-server 档案馆流程（HTTP / tm-cli upload）
memory_save	保存或长文解析保存	title+problem 或 content；勿使用已移除的 scope=archive
memory_feedback	对结果评分	experience_id、rating 等
memory_submit_response	提交回复用于 Faithfulness 评估	query、response、result_ids（可选）

更多管理员操作（审核、去重、配置）请用 Web 或 **GET/POST /api/v1/...**（见 /docs）。历史 **tm_*** 已不在 MCP 中暴露。

Web 管理インターフェース

Web サービスを起動した後、http://localhost:9111 にアクセスすると、ナレッジを視覚的に管理できます。

ページ	機能
ナレッジ一覧（ダッシュボード統計を含む）	ナレッジの総数、最近の傾向、人気のタグ、タイプの分布を表示；タイプ／タグ／プロジェクト／進捗状況で多角的に絞り込み
下書き	AI が自動抽出した、レビュー待ちの下書きを確認
レビューキュー	チームメンバーが投稿したナレッジをレビュー
重複検出	類似したナレッジを検出して統合
システム設定	検索パラメーター、検索設定など

アーカイブ、重複排除、個人メモリなどについては、現在の Web ナビゲーションと OpenAPI を参照してください。

ナレッジの作成は、次の 3 つのモードに対応しています。

• 手動入力：タイトル、問題、解決策をフィールドごとに入力します
• ドキュメント解析：ドキュメントまたは Markdown を貼り付けると、AI がフィールドを自動抽出します
• URL インポート：リンクを入力すると、AI がコンテンツを自動取得して解析します

API リファレンス（プレフィックス /api/v1）：

• Swagger UI: http://localhost:9111/docs
• ReDoc: http://localhost:9111/redoc

設定の説明 / Configuration

TeamMemory の設定は、サーバー設定（デプロイ担当者）とクライアント設定（利用者）の 2 層に分かれています。優先順位は高い順に次のとおりです。

环境变量 > .env 文件 > config.toml > 代码默认值
env vars > .env file > config.toml > code defaults

クライアント設定（利用者） / Client Config

共通設定ファイル：**~/.config/tm/config.toml**。CLI、MCP、Daemon、Hooks のすべてのクライアントコンポーネントで共有されます。

tm-cli config init を使って対話形式で生成するか、手動で作成できます。

# ~/.config/tm/config.toml — 统一客户端配置 / Unified client config

[server]
url = "http://localhost:9111"       # TM Web 服务地址 / Web server URL
api_key = ""                         # 或由 TEAM_MEMORY_API_KEY 环境变量提供

[llm]
base_url = "http://localhost:4000/v1"  # LLM API 地址（用于 Faithfulness 评估等）
model = "DeepSeek-V3"                   # LLM 模型名
api_key_env = "LITELLM_MASTER_KEY"      # LLM API Key 的环境变量名（推荐）
timeout = 30                             # 请求超时（秒）

[conversation]
db_path = "~/.cache/tm-pipeline/drafts.db"  # 本地对话缓存路径

[wiki]
enabled = false
db_path = "~/.cache/tm-pipeline/wiki.db"

[daemon]
host = "127.0.0.1"
port = 3901
log_level = "INFO"

優先順位 / Priority：環境変数 TM_SERVER_URL > .env ファイル > config.toml > コードのデフォルト値。

現在有効な設定を確認 / Show effective config：

tm-cli config show     # 显示每个字段的值及其来源

プロジェクト単位の設定 / Project Config

プロジェクトのルートディレクトリに **.tm.toml** を配置して、プロジェクト名と別名を宣言します。

# .tm.toml — 项目级配置 / Project-level config
[project]
name = "team_doc"           # 项目名（优先于 git repo 名 / 目录名）
aliases = ["team_memory"]   # 别名：历史项目名映射到当前名

プロジェクト名の推定優先順位 / Project name inference：

1. .tm.toml の [project].name — 明示的な宣言
2. Git リポジトリ名（basename → snake_case）— 80% 以上のケースをカバー
3. ディレクトリ名（basename → snake_case）— フォールバック

設定不要：ほとんどのプロジェクトでは .tm.toml は不要です。システムが Git リポジトリ名から自動的に推定します。.tm.toml を設定すると、--project パラメーターを渡す必要はありません。

サーバー設定（デプロイ担当者） / Server Config

環境設定ファイルは2 つのみです（どちらか一方を選択し、環境変数で上書きします）。

ファイル	用途
config.development.yaml	ローカル／デフォルト（TEAM_MEMORY_ENV が未設定、または development／test／dev／local の場合）
config.production.yaml	本番／ステージング（TEAM_MEMORY_ENV=production または prod）
TEAM_MEMORY_CONFIG_PATH	オプション：任意の単一ファイルを指定すると、上記 2 つのファイルを環境名に基づいて解決しなくなります
環境変数 TEAM_MEMORY_*	最優先。同名の YAML フィールドを上書きします

マルチ環境設定（サーバー） / Multi-Environment (Server)

# 开发（默认）
unset TEAM_MEMORY_ENV   # 或 TEAM_MEMORY_ENV=development

# 正式
TEAM_MEMORY_ENV=production

認証タイプ

auth.type では、db_api_key（複数ユーザー対応、推奨）、api_key（メモリ内の単一キー）、none（認証なし、テスト専用）を選択できます。

RBAC ロール権限

ロール	権限
admin	すべての操作（ユーザー管理、設定変更、監査ログ）
editor	ナレッジの作成、編集、削除、レビュー
viewer	読み取り専用（検索、閲覧、フィードバック）

管理者は Web UI の設定ページで API Key とロールの割り当てを管理します。

Embedding 設定 / Embedding Config

embedding:
  provider: ollama  # ollama / openai / local / generic
  ollama:
    model: qwen3-embedding:0.6b
    dimension: 1024

Ollama（デフォルト、ローカルで実行、API Key 不要）、OpenAI API、ローカルの sentence-transformers モデル、汎用のカスタムエンドポイントに対応しています。現在のデフォルトは qwen3-embedding:0.6b（1024 次元）で、中国語への対応に優れています。モデルを切り替えた後は、make embedding-backfill を実行してベクトルを再生成する必要があります。

Embedding の自動復旧 / Auto-recovery：Ollama の再起動後、Web サービスの embedding キャッシュが無効になる場合があります。/health のヘルスチェックが embedding の初期化を自動的に再試行します。失敗を検知すると、設定から provider を再作成し、成功した場合はキャッシュを置き換えます。Web サービスを手動で再起動する必要はありません。

運用

よく使うコマンド

# 基础
make setup         # 首次安装（Docker + 依赖 + 数据库）
make dev           # 启动全部服务
make web           # 仅启动 Web（9111）
make health        # 一键健康检查
make backup        # 备份数据库 (PG + SQLite)
make clean         # 清理 Python 缓存

# 测试
make test               # 运行全部单元测试
make test-acceptance    # 管道验收测试 (21 tests, Tier 2+3)
make test-regression    # 完整回归 (acceptance + e2e + pipeline)
make test-llm           # 测试 LLM 连通性
make e2e-verify         # 端到端链路验证 (模拟 AI 对话)

# 代码质量
make lint          # Ruff 代码检查
make lint-fix      # Ruff 自动修复
make verify        # 标准验收：import + lint + 全量测试
make verify-web    # Web 验收：lint + web 测试 + smoke

# 搜索与质量
make stats         # 搜索质量报告
make search-eval   # 搜索质量评估 (precision/recall)
make faithfulness-eval  # Faithfulness 批量评估 (RAGAS)
make verify-pipeline    # 人工验证数据链路 (15项检查)
make diagnose-pipeline  # 诊断数据链路详细状态

# Wiki
make wiki-compile  # Wiki 编译
make wiki-status   # Wiki 编译状态
make entity-backfill    # 实体提取回填
make entity-dedup       # 实体去重合并
make detect-contradictions  # 矛盾经验检测

# 数据维护
make migrate       # 数据库迁移
make migrate-fts   # 补齐 FTS 字段
make embedding-backfill # 重新生成 embedding
make solution-backfill  # 补跑无 solution 的经验

# Daemon
make daemon-start  # 启动 Daemon (launchd)
make daemon-stop   # 停止 Daemon
make daemon-run    # 前台运行 Daemon (调试用)
make daemon-reload # 代码变更自动重启
make daemon-install   # 安装 launchd plist (开机自启)
make daemon-uninstall # 卸载 launchd plist

# Watchdog
make watchdog-start  # 启动 Watchdog (launchd)
make watchdog-stop   # 停止 Watchdog
make watchdog-status # Watchdog 运行状态

# 运维工具
make logs              # 查看/过滤 daemon 日志
make metrics-push      # 推送指标到飞书
make hooks-install     # 安装 Git hooks

Make コマンドの説明（手動での同等手順）

問題の切り分けや、手動で段階的に起動する際の参考にしてください。

コマンド	意味	手動での同等手順
make help	すべての make ターゲットを一覧表示	`grep -E '^[a-zA-Z_-]+:.*?## ' Makefile
make release-9111	9111 ポートを解放	9111 を使用している Docker コンテナ（例：team-memory-web）とローカルプロセスを停止します： docker compose stop team-memory-web `docker ps -q --filter "publish=9111"
make setup	初回インストール	docker compose up -d → PG の準備完了を待つ → データベースを作成（存在しない場合）→ 必要に応じて Ollama コンテナを起動 → pip install -e ".[dev]" → alembic upgrade head
make dev	すべてのサービスを起動	先に make release-9111 を実行（9111 の使用を防止）→ docker compose up -d postgres redis → 11434 が使用されていない場合は docker compose --profile ollama up -d → python -m team_memory.web.app をフォアグラウンドで実行
make web	Web のみ起動	先に make release-9111 を実行 → python -m team_memory.web.app をフォアグラウンドで実行（デフォルトは http://0.0.0.0:9111）
make mcp	MCP を起動	bash scripts/run_mcp_with_dotenv.sh（リポジトリルートに .env が必要；stdio、**memory_* の 6 つのツール**）、設定については docs/guide/mcp-server.md を参照
make mcp-verify	MCP ツールの登録を検証	TestLiteToolRegistration におけるツールの数と名前を実行して確認します（MCP プロセスを常駐させる必要はありません）
make health	ヘルスチェック	./scripts/healthcheck.sh（DB、Web、Ollama などを確認）
make migrate	データベースのマイグレーション	alembic upgrade head
make migrate-fts	経験テーブルの FTS フィールドを補完（既存データのマイグレーション）	python scripts/migrate_fts.py；--dry-run で更新対象件数を事前に確認できます

説明：make dev と make web は起動前に 9111 ポートを自動的に解放します（そのポートを使用している Docker コンテナまたはローカルプロセスを停止します）。そのため、「address already in use」が発生することなく、繰り返し実行できます。

ダッシュボードに「ダッシュボードの読み込みに失敗しました」と表示される場合

1. まずヘルスチェックを確認します：make health または GET http://localhost:9111/health。

• 出力に **dashboard_stats: FAIL** とその後の error / ops_hint がある場合は、ヒントに従って原因を調べてください（よくある原因：データベースが起動していない、マイグレーションが実行されていない、または config の database.url が誤っている）。
• database が FAIL の場合：まずデータベースを起動し（例：docker compose up -d postgres）、alembic upgrade head を実行してからダッシュボードにアクセスしてください。

2. API エラーは JSON を返します：バックエンドで 500 エラーが発生すると、インターフェースは detail、ops_error_id、ops_hint を返します。

• フロントエンドはこれらの情報をエラーメッセージに含めます；
• サーバーのログで ops_error_id を検索すると、該当する例外を特定できます。

3. ローカルでの簡易診断：python scripts/smoke/smoke_web_dashboard.py [--api-key KEY] は /health と /api/v1/stats にリクエストを送信して結果を表示するため、データベース、設定、認証のどれに問題があるかを確認できます。

バックアップと復元

# 备份（输出到 backups/ 目录，命名格式 team_memory_YYYYMMDD_HHMMSS.sql.gz）
make backup
# 或: ./scripts/backup.sh [output_dir]

# 恢复（在项目根目录执行）
./scripts/restore.sh backups/team_memory_20260209_120000.sql.gz

Docker によるデプロイ

# 自动等待 PG、运行迁移、拉取 Ollama 模型、生成 admin key
docker compose up -d
# 统一端口: 9111

本番環境ではデフォルトの Key を必ず変更し、changeme は使用しないでください。 パスワードを含む database.url などの機密設定を Git にコミットしないでください。環境変数の使用を推奨します。

監視

• 組み込みダッシュボード：Web UI のホームページ
• ヘルスチェック：make health または GET /health
• レディネスプローブ：GET /ready

可观测性 / 日志

• I/O 日志：启用 TEAM_MEMORY_LOG_IO_ENABLED=1 可记录 MCP 工具调用、检索管道、服务层等内部节点日志，便于排查与性能分析。粒度由 LOG_IO_DETAIL（mcp/service/pipeline/full）控制。
• 文件输出：启用 LOG_FILE_ENABLED 或 TEAM_MEMORY_LOGGING__FILE_ENABLED=1，日志写入 LOG_FILE_PATH（默认 logs/team_memory.log），支持按大小轮转。
• 热加载：运行时通过 GET /api/v1/config/logging 查询、PUT /api/v1/config/logging 更新日志配置（需认证），无需重启即可生效；持久化需写入当前使用的 YAML（如 config.development.yaml）。

日志 JSON 形态与脱敏逻辑见 src/team_memory/bootstrap.py（_JsonFormatter、_SENSITIVE_KEYS）及 tests/test_logging_json.py。

技术栈 / Tech Stack

层面	技术选型
MCP	FastMCP
Web	FastAPI + Uvicorn
数据库	PostgreSQL + pgvector
ORM	SQLAlchemy 2.0 (async)
嵌入	qwen3-embedding:0.6b (Ollama) / OpenAI / 本地模型
搜索	向量 + 全文检索(jieba+hybrid AND/OR) + RRF 融合 + Reranker
缓存	内存 LRU / Redis
配置	Pydantic Settings + YAML（服务端）/ TOML + ClientConfig（客户端）
迁移	Alembic
Daemon	TM Daemon (launchd) — Obsidian watcher + RefinementWorker
评估	Faithfulness (RAGAS LLM Judge) + search_eval

入口点 / Entry Points

命令	模块	用途
team-memory	team_memory.server:main	MCP Server（stdio）
team-memory-web	team_memory.web.app:main	Web 服务
tm-cli	team_memory.cli:main	CLI 兼容层 + 配置管理
tm-daemon	team_memory.daemon.__main__:main	TM Daemon 守护进程

代码组织 / Code Organization

src/team_memory/                  # Python 包（PYTHONPATH 只需 src/）
  server.py                       # MCP Server（memory_* 工具）
  cli.py                          # CLI（tm-cli）+ config/setup 子命令
  client_config.py                # ClientConfig — 统一客户端配置
  project_resolver.py             # 项目名零配置推断 + 别名注册
  daemon/                         # TM Daemon（原 scripts/daemon/）
  hooks/                          # 平台 Hook（原 scripts/hooks/）
  web/                            # Web 服务（FastAPI）
  services/                       # 业务逻辑层
  storage/                        # 数据访问层
  ...

旧路径 scripts/daemon/ → src/team_memory/daemon/，scripts/hooks/ → src/team_memory/hooks/。PYTHONPATH 不再需要 scripts/，只需 src/。

FAQ

Q: TeamMemory 和 Cursor Rules 有什么区别？

A: Rules 是静态的、手动维护的规范文件，适合"已经确定的"知识（代码风格、架构约束）。TeamMemory 是动态的、AI 自动积累的经验库，适合"还在演化的"知识（Bug 根因、方案权衡、实际踩坑）。两者互补：经验在 TeamMemory 中积累，当某个模式足够稳定后，可以将其固化为 Rule。

Q: 经验库越来越大，AI 上下文会不会爆？

A: 不会。TeamMemory 有多层机制控制输出体量：语义搜索本身只返回最相关的 Top-N 结果；Token 预算控制会自动裁剪过长的输出；Reranker 会过滤低相关度结果；PageIndex-Lite 对长文档做节点级检索而非全文返回。经验库从 100 条增长到 10000 条，AI 每次实际读取的内容量不会显著增加。

Q: 团队成员不想手动录入经验怎么办？

A: 这正是 TeamMemory 的设计重点。让 AI 在适当时机调用 **memory_save(content=...)** 可把长对话交给服务端解析并写入（常为草稿，视配置而定）；也可在 Web 中粘贴文档或 URL 生成经验后再审核发布。

Q: 切换 Embedding 模型后需要做什么？

A: 需要重新生成所有 embedding。步骤：1) 更新 config.development.yaml 中 embedding.ollama.model 和 dimension；2) 执行 alembic upgrade head（如有维度迁移）；3) 执行 make embedding-backfill 重新生成向量。

Q: 存量数据如何支持全文检索（FTS）？

A: 若经验表存在 fts 为空的记录，可执行 make migrate-fts 或 python scripts/migrate_fts.py 回填；先用 --dry-run 可预览待更新条数。

Q: 没有 Ollama 可以使用吗？

A: 可以。将 embedding.provider 改为 openai 并配置 API Key，或使用 local 加载本地 sentence-transformers 模型。

Q: 多个项目的经验会混在一起吗？

A: 不会。项目名通过 .tm.toml > git 仓库名 > 目录名自动推断，无需手动配置。也可通过 TEAM_MEMORY_PROJECT 环境变量或工具入参 project 显式指定。每个项目的经验独立存储和检索，不会互相干扰。别名机制（.tm.toml 的 aliases）确保项目重命名后历史经验仍可检索。

开发

运行测试

# 全部测试
pytest -v

# 带覆盖率
pytest --cov=team_memory

代码检查

# 检查
ruff check src/

# 自动修复
ruff check src/ --fix

CI/CD

推送至 main / develop 或向 main 提 PR 时，GitHub Actions 会执行 lint、测试与 Docker 构建。触发条件与各 job 说明见 .github/workflows/ci.yml。

文档同步约定

• 功能或代码变更后，须同步更新本 README；文档不同步不得视为任务完成。

文档结构

• 设计文档：docs/（索引：docs/README.md）