Metadata-Version: 2.4
Name: teamaivectormemory
Version: 0.1.1
Summary: 团队级 AI 记忆中枢 — 多人协作知识共享、用户隔离、跨会话持久记忆 MCP Server
Project-URL: Homepage, https://github.com/cmsyt/teamaivectormemory
Project-URL: Repository, https://github.com/cmsyt/teamaivectormemory
Author: TeamAIVectorMemory Contributors
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai,embedding,llm,mcp,memory,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: huggingface-hub>=0.20
Requires-Dist: jieba>=0.42
Requires-Dist: numpy>=1.24
Requires-Dist: onnxruntime>=1.16
Requires-Dist: sqlite-vec>=0.1.0
Requires-Dist: tokenizers>=0.15
Description-Content-Type: text/markdown

🌐 简体中文 | [繁體中文](docs/README.zh-TW.md) | [English](docs/README.en.md) | [Español](docs/README.es.md) | [Deutsch](docs/README.de.md) | [Français](docs/README.fr.md) | [日本語](docs/README.ja.md)

<p align="center">
  <h1 align="center">🧠 TeamAIVectorMemory</h1>
  <p align="center">
    <strong>给 AI 编程助手装上团队记忆 — 多人协作 · 知识共享 · 跨会话持久化 MCP Server</strong>
  </p>
  <p align="center">
    <a href="https://pypi.org/project/teamaivectormemory/"><img src="https://img.shields.io/pypi/v/teamaivectormemory?color=blue&label=PyPI" alt="PyPI"></a>
    <a href="https://pypi.org/project/teamaivectormemory/"><img src="https://img.shields.io/pypi/pyversions/teamaivectormemory" alt="Python"></a>
    <a href="https://github.com/cmsyt/teamaivectormemory/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-green" alt="License"></a>
    <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-purple" alt="MCP"></a>
  </p>
</p>

---

> **你是否也有这样的困扰？** 每开一个新会话，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 安装（推荐）

```bash
# 安装
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：
>   ```bash
>   brew install python
>   /opt/homebrew/bin/python3 -m pip install teamaivectormemory
>   ```

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

无需 `pip install`，直接运行：

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

> 需要先安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)，`uvx` 会自动下载并运行，无需手动安装包。

### 方式三：手动配置

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

<details>
<summary>📍 各 IDE 配置文件位置</summary>

| 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` |

</details>

## 🛠️ 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 看板

```bash
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 / 日本語）

<p align="center">
  <img src="docs/dashboard-projects.png" alt="项目选择" width="100%">
  <br>
  <em>项目选择</em>
</p>

<p align="center">
  <img src="docs/dashboard-overview.png" alt="统计概览 & 向量网络可视化" width="100%">
  <br>
  <em>统计概览 & 向量网络可视化</em>
</p>

## ⚡ Embedding 共享服务

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

```bash
# 启动 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 通过环境变量连接共享服务：

```json
{
  "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` |

<details>
<summary>📋 Steering 规则范例（自动生成）</summary>

```markdown
# 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` 自动生成）
```

</details>

<details>
<summary>🔗 Hooks 配置范例（Kiro 专属，自动生成）</summary>

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

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

</details>

## 🇨🇳 中国大陆用户

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

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

或在 MCP 配置中加 env：

```json
{
  "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
