TeamMemory
mcp-name: io.github.ysydhc/team-memory
让 AI 拥有团队记忆 — 跨会话积累经验,像资深成员一样理解你的项目。
这是我学 AI 时萌生的一个想法。市面上已有类似产品,但总觉得不太贴合自己的使用习惯。做这个项目,既想通过和 AI 一起写代码来加深对大模型的理解,也希望能按自己的工作流,打磨出真正顺手的功能。
给 Agent / 贡献者:AGENTS.md · · MCP 实现 · 分层约束见 ()
Agenten stärken
Der eigene Befehl des Herausgebers. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
uvx team_memory==0.1.2Claude Code hat keinen Installationslink für einen lokalen Befehl. Kopieren Sie den Befehl unten und führen Sie ihn in einem Terminal aus.
DATABASE_URL=<secret> TEAM_MEMORY_CONFIG=<value> claude mcp add io.github.ysydhc-team-memory -- uvx team_memory==0.1.2In einem Terminal ausführen.
{ "mcpServers": { "io.github.ysydhc-team-memory": { "command": "uvx", "args": [ "team_memory==0.1.2" ], "env": { "DATABASE_URL": "<secret>", "TEAM_MEMORY_CONFIG": "<value>" } } }}claude_desktop_config.json
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenVom Herausgeber
mcp-name: io.github.ysydhc/team-memory
让 AI 拥有团队记忆 — 跨会话积累经验,像资深成员一样理解你的项目。
这是我学 AI 时萌生的一个想法。市面上已有类似产品,但总觉得不太贴合自己的使用习惯。做这个项目,既想通过和 AI 一起写代码来加深对大模型的理解,也希望能按自己的工作流,打磨出真正顺手的功能。
给 Agent / 贡献者:AGENTS.md · · MCP 实现 · 分层约束见 ()
Team experience database - let AI accumulate, retrieve and apply team knowledge across chats.
scripts/harness_import_check.pyLAYER_MAP用 Cursor、Claude 等 AI 助手写代码时,往往会遇到三个问题:
TeamMemory 就是冲着这三个问题来的。 通过 MCP 把语义可搜索的经验库接进 AI:遇到问题自动查历史方案,解决后自动提炼并存下来,下次谁遇到同类问题,直接就能命中。既适合 3–10 人的技术团队共享,也适合部署在本地个人使用,配合 Cursor / Claude Desktop。
环境: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 登录即可。更完整的部署与用户流程见下文 按角色导航 与 快速开始。
除 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
# 显示当前生效配置及值来源 / 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 中配置)。
本仓库(克隆源码)推荐:不要把 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 无集成。
安装与获取
pip install team_memory(推荐用于部署或本地 MCP 客户端)。AI 助手在项目中可用的知识分为三层,每一层解决不同的问题:
┌─────────────────────────────────────────────────────────┐
│ Rules / Skills(静态层) │
│ 已确定的规范和成熟的工作流,手动维护,变化频率低 │
│ 例:代码风格规范、部署流程、API 用法 │
├─────────────────────────────────────────────────────────┤
│ TeamMemory(动态层) ← 本项目 │
│ 从日常开发中自动积累的团队经验,语义可搜索,持续演化 │
│ 例:Bug 根因分析、架构决策背景、接口的隐藏坑 │
├─────────────────────────────────────────────────────────┤
│ 代码 + 文档(基础层) │
│ 项目源码和文档,AI 可直接读取 │
│ 例:函数定义、README、注释 │
└─────────────────────────────────────────────────────────┘
三层之间存在自然的知识生命周期:
日常开发会话
│
▼
AI 自动提取经验 ──→ TeamMemory(动态积累)
│ │
│ ▼ 模式稳定后
│ 固化为 Rules / Skills
│ │
└──── 新问题 / 新变化 ←─┘
Rules/Skills 无法覆盖的知识,正是 TeamMemory 的价值所在:那些太碎、太多、变化太快,不适合写成规则,但恰恰是团队"老手"和"新手"之间最大差距的经验。
AI 从对话和文档中自动提取结构化经验,无需手动录入:
**memory_save(content=...)** 走 LLM 解析,从长对话中识别问题、方案、标签并写入(含质量门控);Web 上亦支持粘贴文档或 URL 解析**group_key**(MCP / HTTP)将相关经验归组;复杂编排可在 Web 完成多层检索管线,确保 AI 找到最相关的历史方案:
config.tag_synonyms)、短查询自动降低 min_similarity(0.45);FTS 使用 simple 分词器 + jieba 中文分词 + hybrid AND/OR 策略(前 2 词 AND 保证精度,其余 OR 提升召回)summary 字段,LLM 可生成简短摘要;单条(POST /experiences/{id}/summarize)与批量(POST /experiences/batch-summarize)生成;MCP 搜索结果中每条经验可包含 summary,便于节省 Tokenuser_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。保存时可根据内容自动推荐经验类型(general/feature/bugfix/tech_design/incident/best_practice/learning),减少手动选择。
自动评估经验的活跃度和价值,让高质量经验脱颖而出:
memory_recall / Web 搜索管线)+2 分,获 4 星以上评价 +1 分不是随意堆放的笔记,而是有类型、有层级、有评分的经验体系:
多人共建共享的团队知识库:
project 参数隔离不同项目的经验,避免跨项目污染原生 MCP 协议支持,AI 助手通过 stdio 接入:
memory_context、memory_recall、memory_get_archive、memory_archive_upsert、memory_save、memory_feedback、memory_submit_response(见 MCP 工具列表)/docs HTTP API 为准旧文若仍写 **tm_*** MCP 或任务看板等已下线能力,以 本文、AGENTS.md 与 src/team_memory/server.py 为准。
后台守护进程,自动从 Obsidian vault 和 Agent 对话中采集经验:
tm-daemon(即 python -m team_memory.daemon),make daemon-start / make daemon-stop(launchd 托管),日志 /tmp/tm-daemon.logsrc/team_memory/daemon/(原 scripts/daemon/)基于 RAGAS 思路,用 LLM Judge 评估搜索结果是否被 Agent 真实使用:
make stats(Faithfulness 面板)、make faithfulness-eval --show 10、curl localhost:3901/status/faithfulness--model glm-4-flash --base-url http://localhost:4000/v1从经验库自动编译知识 Wiki:
make wiki-compile、make entity-backfill、make detect-contradictions最小化上手成本:
make setup 一键完成全部安装以下从初次部署者(把 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"
首次登录
该 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
启动服务后,用该 api_key 在 Web 登录页选择「使用 API Key 登录」即可获得 admin。
若希望用「用户名 + 密码」登录、且不依赖引导 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 身份进入。
多人使用:
5. 可选:健康检查
make health
成功时输出 PostgreSQL: OK、Ollama: OK、Web: healthy 等。若 database 或 ollama 为 FAIL,按提示启动对应服务或执行迁移。
首次访问 Web 时可能显示 0 条经验,属正常。 可先添加一条测试经验验证流程。
日常再次启动只需:make dev(或先 docker compose up -d 再 make web)。更多命令见下方「运维」。
你已经从部署者拿到 API Key,TeamMemory 的数据库(和 Web)已就绪。只需在本机配置 MCP 并验证。
1. 安装(本机跑 MCP 时)
pip install team_memory
若通过 Cursor/Claude 的「MCP 市场」安装 TeamMemory,按客户端说明即可,可能无需本机再装。
2. 拿到 API Key 与数据库连接
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"
}
}
}
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"
}
}
}
}
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 compose up -d 启动(含数据库迁移)。在 .env 中设置 TEAM_MEMORY_API_KEY(默认 changeme 请修改)。生产环境必须修改默认 Key,禁止使用 changeme。访问 http://localhost:9111 。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)。克隆本仓库时:优先 **.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 场景与上一致即可。
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 的配置即可。
场景 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」类用法)。
更多管理员操作(审核、去重、配置)请用 Web 或 **GET/POST /api/v1/...**(见 /docs)。历史 **tm_*** 已不在 MCP 中暴露。
启动 Web 服务后访问 http://localhost:9111,提供经验的可视化管理:
档案馆、去重、个人记忆等以当前 Web 导航与 OpenAPI 为准。
创建经验支持三种模式:
API 参考(前缀 /api/v1):
http://localhost:9111/docshttp://localhost:9111/redocTeamMemory 的配置分为两层:服务端配置(部署者)和客户端配置(使用者),优先级从高到低为:
环境变量 > .env 文件 > config.toml > 代码默认值
env vars > .env file > config.toml > code defaults
统一配置文件:**~/.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 # 显示每个字段的值及其来源
在项目根目录放置 **.tm.toml**,声明项目名与别名:
# .tm.toml — 项目级配置 / Project-level config
[project]
name = "team_doc" # 项目名(优先于 git repo 名 / 目录名)
aliases = ["team_memory"] # 别名:历史项目名映射到当前名
项目名推断优先级 / Project name inference:
.tm.toml 中 [project].name — 显式声明零配置:大多数项目无需 .tm.toml,系统自动从 git 仓库名推断。有了 .tm.toml 后不再需要传 --project 参数。
仅保留两个环境配置文件(二选一,再结合环境变量覆盖):
# 开发(默认)
unset TEAM_MEMORY_ENV # 或 TEAM_MEMORY_ENV=development
# 正式
TEAM_MEMORY_ENV=production
auth.type 可选:db_api_key(多用户、推荐)、api_key(内存单 key)、none(无认证,仅测试)。
管理员通过 Web UI 设置页面管理 API Key 和角色分配。
embedding:
provider: ollama # ollama / openai / local / generic
ollama:
model: qwen3-embedding:0.6b
dimension: 1024
支持 Ollama(默认,本地运行,无需 API Key)、OpenAI API、本地 sentence-transformers 模型、generic 自定义端点。当前默认使用 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 dev 与 make web 会在启动前自动释放 9111 端口(停止占用该端口的 Docker 容器或本机进程),因此可重复执行而不会出现「address already in use」。
make health 或 GET http://localhost:9111/health。**dashboard_stats: FAIL** 及后面的 error / ops_hint,按提示排查(常见原因:数据库未启动、未执行迁移、或 config 中 database.url 错误)。docker compose up -d postgres),执行 alembic upgrade head 后再访问仪表盘。detail、ops_error_id、ops_hint。ops_error_id 搜索可定位对应异常。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
# 自动等待 PG、运行迁移、拉取 Ollama 模型、生成 admin key
docker compose up -d
# 统一端口: 9111
生产环境必须修改默认 Key,禁止使用 changeme。 含密码的 database.url 等敏感配置勿提交 Git,建议使用环境变量。
make health 或 GET /healthGET /readyTEAM_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。
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/。
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
推送至 main / develop 或向 main 提 PR 时,GitHub Actions 会执行 lint、测试与 Docker 构建。触发条件与各 job 说明见 .github/workflows/ci.yml。
Team experience database - let AI accumulate, retrieve and apply team knowledge across chats.
{ "mcpServers": { "io.github.ysydhc-team-memory": { "command": "uvx", "args": [ "team_memory==0.1.2" ], "env": { "DATABASE_URL": "<secret>", "TEAM_MEMORY_CONFIG": "<value>" } } }}Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Der Herausgeber nennt diese Umgebungsvariablen: DATABASE_URL, TEAM_MEMORY_CONFIG.
TeamMemory läuft lokal über stdio.
Zuletzt geprüft: 2026-11-10. Team experience database - let AI accumulate, retrieve and apply team knowledge across chats.