teamaivectormemory 0.1.1

团队级 AI 记忆中枢 — 多人协作知识共享、用户隔离、跨会话持久记忆 MCP Server

🌐 简体中文 | 繁體中文 | English | Español | Deutsch | Français | 日本語

🧠 TeamAIVectorMemory

给 AI 编程助手装上团队记忆 — 多人协作 · 知识共享 · 跨会话持久化 MCP Server

---

你是否也有这样的困扰？ 每开一个新会话，AI 就像换了个人 — 昨天刚教会它的项目规范今天又忘了，踩过的坑还会再踩一遍，开发到一半的进度全部归零。团队里每个人都在重复踩同样的坑，知识无法沉淀，经验无法传承。

TeamAIVectorMemory 是为团队打造的 AI 记忆中枢。 不只是个人记忆 — 团队踩坑经验自动共享，架构知识一人沉淀全员受益，多用户数据严格隔离互不干扰。支持多 worker 共享 Embedding 模型，N 个进程只需 1 份内存。新会话自动恢复上下文，语义搜索精准召回，Token 消耗直降 50%+。

✨ 核心特性

特性	说明
👥 团队知识共享	一人踩坑全员受益 — 团队记忆自动共享，架构知识、踩坑经验沉淀为团队资产，新人即刻获得老手的全部经验
🔐 多用户数据隔离	同一台服务器多人协作，个人记忆严格隔离互不可见，团队记忆按项目共享，隐私与协作兼得
⚡ Embedding 共享服务	N 个 MCP worker 共享一个 Embedding 模型，200MB × N → 200MB × 1，服务器部署内存直降 90%
🧠 跨会话记忆	AI 终于能记住你的项目了 — 踩过的坑、做过的决策、定下的规范，换个会话照样记得
🔍 语义搜索	不用记原文怎么写的，搜"数据库超时"就能找到"MySQL 连接池踩坑"
💰 省 50%+ Token	不再每次对话都复制粘贴项目背景，语义检索按需召回，告别全量上下文注入
🔗 任务驱动开发	问题追踪 → 任务拆分 → 状态同步 → 联动归档，AI 自动管理完整开发流程
📊 Web 看板	可视化管理所有记忆和任务，3D 向量网络一眼看清知识关联
🏠 完全本地	零依赖云服务，ONNX 本地推理，无需 API Key，数据不出你的电脑
🔌 全 IDE 通吃	Cursor / Kiro / Claude Code / Windsurf / VSCode / OpenCode / Trae — 一键安装，开箱即用
📁 多项目隔离	一个 DB 管所有项目，自动隔离互不干扰，切换项目无感知
🔄 智能去重	相似度 > 0.95 自动合并更新，记忆库永远干净，不会越用越乱

🏗️ 架构

┌─────────────────────────────────────────────────┐
│                   AI IDE                         │
│  OpenCode / Claude Code / Cursor / Kiro / ...   │
└──────────────────────┬──────────────────────────┘
                       │ MCP Protocol (stdio)
┌──────────────────────▼──────────────────────────┐
│              TeamAIVectorMemory Server                    │
│                                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ remember │ │  recall   │ │   auto_save      │ │
│  │ forget   │ │  task     │ │   status/track   │ │
│  └────┬─────┘ └────┬─────┘ └───────┬──────────┘ │
│       │            │               │             │
│  ┌────▼────────────▼───────────────▼──────────┐  │
│  │         Embedding Engine (ONNX)            │  │
│  │      intfloat/multilingual-e5-small        │  │
│  └────────────────────┬───────────────────────┘  │
│                       │                          │
│  ┌────────────────────▼───────────────────────┐  │
│  │     SQLite + sqlite-vec (向量索引)          │  │
│  │     ~/.teamaivectormemory/memory.db                 │  │
│  └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

🚀 快速开始

方式一：pip 安装（推荐）

# 安装
pip install teamaivectormemory

# 升级到最新版
pip install --upgrade teamaivectormemory

# 进入你的项目目录，一键配置 IDE
cd /path/to/your/project
team-run install

team-run install 会交互式引导你选择 IDE，自动生成 MCP 配置、Steering 规则和 Hooks，无需手动编写。

macOS 用户注意：

• 遇到 externally-managed-environment 错误，加 --break-system-packages
• 遇到 enable_load_extension 错误，说明当前 Python 不支持 SQLite 扩展加载（macOS 自带 Python 和 python.org 官方安装包均不支持），请改用 Homebrew Python：

  brew install python
  /opt/homebrew/bin/python3 -m pip install teamaivectormemory
  

方式二：uvx 运行（零安装）

无需 pip install，直接运行：

cd /path/to/your/project
uvx teamaivectormemory install

需要先安装 uv，uvx 会自动下载并运行，无需手动安装包。

方式三：手动配置

{
  "mcpServers": {
    "teamaivectormemory": {
      "command": "team-run",
      "args": ["--project-dir", "/path/to/your/project"]
    }
  }
}

📍 各 IDE 配置文件位置

IDE	配置文件路径
Kiro	.kiro/settings/mcp.json
Cursor	.cursor/mcp.json
Claude Code	.mcp.json
Windsurf	.windsurf/mcp.json
VSCode	.vscode/mcp.json
Trae	.trae/mcp.json
OpenCode	opencode.json
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json

🛠️ 8 个 MCP 工具

remember — 存入记忆

content (string, 必填)   记忆内容，Markdown 格式
tags    (string[], 必填)  标签，如 ["踩坑", "python"]
scope   (string)          "project"（默认）/ "user"（跨项目）

相似度 > 0.95 自动更新已有记忆，不重复存储。

recall — 语义搜索

query   (string)     语义搜索关键词
tags    (string[])   标签精确过滤
scope   (string)     "project" / "user" / "all"
top_k   (integer)    返回数量，默认 5

向量相似度匹配，用词不同也能找到相关记忆。

forget — 删除记忆

memory_id  (string)     单个 ID
memory_ids (string[])   批量 ID

status — 会话状态

state (object, 可选)   不传=读取，传=更新
  is_blocked, block_reason, current_task,
  next_step, progress[], recent_changes[], pending[]

跨会话保持工作进度，新会话自动恢复上下文。

track — 问题跟踪

action   (string)   "create" / "update" / "archive" / "list"
title    (string)   问题标题
issue_id (integer)  问题 ID
status   (string)   "pending" / "in_progress" / "completed"
content  (string)   排查内容

task — 任务管理

action     (string, 必填)  "batch_create" / "update" / "list" / "delete" / "archive"
feature_id (string)        关联功能标识（list 时必填）
tasks      (array)         任务列表（batch_create，支持子任务）
task_id    (integer)       任务 ID（update）
status     (string)        "pending" / "in_progress" / "completed" / "skipped"

通过 feature_id 关联 spec 文档，update 自动同步 tasks.md checkbox 并联动问题状态。

readme — README 生成

action   (string)    "generate"（默认）/ "diff"（差异对比）
lang     (string)    语言：en / zh-TW / ja / de / fr / es
sections (string[])  指定章节：header / tools / deps

从 TOOL_DEFINITIONS / pyproject.toml 自动生成 README 内容，支持多语言。

auto_save — 自动保存偏好

preferences  (string[])  用户表达的技术偏好（固定 scope=user，跨项目通用）
extra_tags   (string[])  额外标签

每次对话结束自动提取并存储用户偏好，智能去重。

📊 Web 看板

team-run web --port 9080
team-run web --port 9080 --quiet          # 屏蔽请求日志
team-run web --port 9080 --quiet --daemon  # 后台运行（macOS/Linux）

浏览器访问 http://localhost:9080

• 多项目切换，记忆浏览/搜索/编辑/删除/导出/导入
• 语义搜索（向量相似度匹配）
• 项目数据一键删除
• 会话状态、问题追踪
• 标签管理（重命名、合并、批量删除）
• Token 认证保护
• 3D 向量记忆网络可视化
• 🌐 多语言支持（简体中文 / 繁體中文 / English / Español / Deutsch / Français / 日本語）

项目选择

统计概览 & 向量网络可视化

⚡ Embedding 共享服务

多个 MCP worker 共享一个 Embedding 模型，避免每个进程各加载一份（200MB × N → 200MB × 1）。

# 启动 Embedding 共享服务（默认端口 8900）
team-run embed-server
team-run embed-server --port 8900              # 指定端口
team-run embed-server --port 8900 --daemon     # 后台运行（macOS/Linux）
team-run embed-server --bind 0.0.0.0           # 允许远程访问

MCP worker 通过环境变量连接共享服务：

{
  "mcpServers": {
    "teamaivectormemory": {
      "command": "team-run",
      "args": ["--project-dir", "/path/to/your/project"],
      "env": { "EMBEDDING_SERVER_URL": "http://127.0.0.1:8900" }
    }
  }
}

• 设置 EMBEDDING_SERVER_URL 后，EmbeddingEngine 自动切换为远程模式，通过 HTTP 调用共享服务
• 共享服务不可用时自动回退到本地模式，不影响正常使用
• HTTP 接口：GET /health（健康检查）、POST /encode（单文本编码）、POST /encode_batch（批量编码）

⚡ 配合 Steering 规则

TeamAIVectorMemory 是存储层，通过 Steering 规则告诉 AI 何时、如何调用这些工具。

运行 team-run install 会自动生成 Steering 规则和 Hooks 配置，无需手动编写。

IDE	Steering 位置	Hooks
Kiro	.kiro/steering/teamaivectormemory.md	.kiro/hooks/*.hook
Cursor	.cursor/rules/teamaivectormemory.md	.cursor/hooks.json
Claude Code	CLAUDE.md（追加）	.claude/settings.json
Windsurf	.windsurf/rules/teamaivectormemory.md	.windsurf/hooks.json
VSCode	.github/copilot-instructions.md（追加）	—
Trae	.trae/rules/teamaivectormemory.md	—
OpenCode	AGENTS.md（追加）	.opencode/plugins/*.js

📋 Steering 规则范例（自动生成）

# TeamAIVectorMemory - 工作规则

## 1. 新会话启动（必须按顺序执行）

1. `recall`（tags: ["项目知识"], scope: "project", top_k: 100）加载项目知识
2. `recall`（tags: ["preference"], scope: "user", top_k: 20）加载用户偏好
3. `status`（不传 state）读取会话状态
4. 有阻塞 → 汇报并等待；无阻塞 → 进入处理流程

## 2. 收到消息后的处理流程

- 步骤 A：`status` 读取状态，有阻塞则等待
- 步骤 B：判断消息类型（闲聊/纠正/偏好/代码问题）
- 步骤 C：`track create` 记录问题
- 步骤 D：排查（`recall` 查踩坑 + 查看代码 + 找根因）
- 步骤 E：向用户说明方案，设阻塞等确认
- 步骤 F：修改代码（修改前 `recall` 查踩坑）
- 步骤 G：运行测试验证
- 步骤 H：设阻塞等待用户验证
- 步骤 I：用户确认 → `track archive` + 清阻塞

## 3. 阻塞规则

提方案等确认、修复完等验证时必须 `status({ is_blocked: true })`。
用户明确确认后才能清除阻塞，禁止自行清除。

## 4-9. 问题追踪 / 代码检查 / Spec 任务管理 / 记忆质量 / 工具速查 / 开发规范

（完整规则由 `team-run install` 自动生成）

🔗 Hooks 配置范例（Kiro 专属，自动生成）

会话结束自动保存已移除，开发流程检查（.kiro/hooks/dev-workflow-check.kiro.hook）：

{
  "enabled": true,
  "name": "开发流程检查",
  "version": "1",
  "when": { "type": "promptSubmit" },
  "then": {
    "type": "askAgent",
    "prompt": "核心原则：操作前验证、禁止盲目测试、自测通过才能说完成"
  }
}

🇨🇳 中国大陆用户

首次运行自动下载 Embedding 模型（~200MB），如果慢：

export HF_ENDPOINT=https://hf-mirror.com

或在 MCP 配置中加 env：

{
  "env": { "HF_ENDPOINT": "https://hf-mirror.com" }
}

📦 技术栈

组件	技术
运行时	Python >= 3.10
向量数据库	SQLite + sqlite-vec
Embedding	ONNX Runtime + intfloat/multilingual-e5-small
分词器	HuggingFace Tokenizers
协议	Model Context Protocol (MCP)
Web	原生 HTTPServer + Vanilla JS

📋 更新日志

v0.1.1

Embedding 共享服务

• ⚡ 新增 team-run embed-server 子命令，启动独立的 Embedding HTTP 服务（支持 --port/--bind/--daemon 参数）
• ⚡ HTTP 接口：GET /health（健康检查）、POST /encode（单文本编码）、POST /encode_batch（批量编码）
• ⚡ EmbeddingEngine 支持远程/本地双模式：设置 EMBEDDING_SERVER_URL 环境变量自动切换远程模式
• ⚡ 远程服务不可用时自动回退到本地 ONNX 推理，零感知降级
• ⚡ N 个 MCP worker 共享一个 Embedding 模型，200MB × N → 200MB × 1，内存直降 90%

License

Apache-2.0