szyjiyi 0.2.4

轻量级 MCP Server，为 AI 编程助手提供跨会话持久记忆能力

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

🧠 AIVectorMemory

给 AI 编程助手装上记忆 — 跨会话持久化记忆 MCP Server

---

问题：AI 助手每次新会话都"失忆"，反复踩同样的坑、忘记项目约定、丢失开发进度。更糟的是，为了补偿失忆，你不得不在每次对话中重复注入大量上下文，白白浪费 Token。

AIVectorMemory：通过 MCP 协议为 AI 提供本地向量记忆库，让它记住一切 — 项目知识、踩坑记录、开发决策、工作进度 — 跨会话永不丢失。语义检索按需召回，不再全量注入，大幅降低 Token 消耗。

✨ 核心特性

特性	说明
🔍 语义搜索	基于向量相似度，搜"数据库超时"能找到"MySQL 连接池踩坑"
🏠 完全本地	ONNX Runtime 本地推理，无需 API Key，数据不出本机
🔄 智能去重	余弦相似度 > 0.95 自动更新，不会重复存储
📊 Web 看板	内置管理界面，3D 向量网络可视化
🔌 全 IDE 支持	OpenCode / Claude Code / Cursor / Kiro / Windsurf / VSCode / Trae 等
📁 项目隔离	多项目共用一个 DB，通过 project_dir 自动隔离
🏷️ 标签体系	记忆分类管理，支持标签搜索、重命名、合并
💰 节省 Token	语义检索按需召回，替代全量上下文注入，减少 50%+ 重复 Token 消耗
📋 问题追踪	轻量级 issue tracker，AI 自动记录和归档
🔐 Web 认证	看板支持 Token 认证，防止未授权访问
⚡ Embedding 缓存	相同内容不重复计算向量，提升写入性能
📤 导出/导入	记忆数据 JSON 导出导入，支持迁移和备份
🎯 操作反馈	Toast 提示、空状态引导，交互体验完整
➕ 看板添加项目	前端直接添加项目，支持目录浏览器选择

🏗️ 架构

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

🚀 快速开始

方式一：pip 安装

pip install aivectormemory
pip install --upgrade aivectormemory  # 升级到最新版
cd /path/to/your/project
run install          # 交互式选择 IDE，一键配置

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 aivectormemory
  

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

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

方式三：手动配置

{
  "mcpServers": {
    "aivectormemory": {
      "command": "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

🛠️ 7 个 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)   排查内容

digest — 记忆摘要

scope          (string)    范围
since_sessions (integer)   最近 N 次会话
tags           (string[])  标签过滤

auto_save — 自动保存

decisions[]      关键决策
modifications[]  文件修改摘要
pitfalls[]       踩坑记录
todos[]          待办事项

每次对话结束自动分类存储，打标签，去重。

📊 Web 看板

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

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

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

项目选择

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

⚡ 配合 Steering 规则

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

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

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

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

# AIVectorMemory - 跨会话持久记忆

## 启动检查

每次新会话开始时，按以下顺序执行：

1. 调用 `status`（不传参数）读取会话状态，检查 `is_blocked` 和 `block_reason`
2. 调用 `recall`（tags: ["项目知识"], scope: "project"）加载项目知识
3. 调用 `recall`（tags: ["preference"], scope: "user"）加载用户偏好

## 何时调用

- 新会话开始时：调用 `status` 读取上次的工作状态
- 遇到踩坑/技术要点时：调用 `remember` 记录，标签加 "踩坑"
- 需要查找历史经验时：调用 `recall` 语义搜索
- 发现 bug 或待处理事项时：调用 `track`（action: create）
- 任务进度变化时：调用 `status`（传 state 参数）更新
- 对话结束前：调用 `auto_save` 保存本次对话

## 会话状态管理

status 字段：is_blocked, block_reason, current_task, next_step,
progress[], recent_changes[], pending[]

⚠️ **阻塞防护**：提出方案等待确认、修复完成等待验证时，必须同步调用 `status` 设置 `is_blocked: true`。这可以防止会话转移时新会话误判为"已确认"而擅自执行。

## 问题追踪

1. `track create` → 记录问题
2. `track update` → 更新排查内容
3. `track archive` → 归档已解决问题

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

会话结束自动保存（.kiro/hooks/auto-save-session.kiro.hook）：

{
  "enabled": true,
  "name": "会话结束自动保存",
  "version": "1",
  "when": { "type": "agentStop" },
  "then": {
    "type": "askAgent",
    "prompt": "调用 auto_save，将本次对话的决策、修改、踩坑、待办分类保存"
  }
}

开发流程检查（.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.2.4

• 🔇 Stop hook prompt 改为直接指令，消除 Claude Code 重复回复
• 🛡️ Steering 规则 auto_save 规范增加短路防护，会话结束场景跳过其他规则
• 🐛 _copy_check_track_script 幂等性修复（返回变更状态避免误报"已同步"）
• 🐛 issue_repo delete 中 row.get() 对 sqlite3.Row 不兼容修复（改用 row.keys() 判断）
• 🐛 Web 看板项目选择页面滚动修复（项目多时无法滚动）
• 🐛 Web 看板 CSS 污染修复（strReplace 全局替换导致 6 处样式异常）
• 🔄 Web 看板所有 confirm() 弹窗替换为自定义 showConfirm 模态框（记忆/问题/标签/项目删除）
• 🔄 Web 看板删除操作增加 API 错误响应处理（toast 提示替代 alert）
• 🧹 .gitignore 补充 .devmemory/ 旧版残留目录忽略规则
• 🧪 pytest 临时项目数据库残留自动清理（conftest.py session fixture）

v0.2.3

• 🛡️ PreToolUse Hook：Edit/Write 前强制检查 track issue，无活跃问题则拒绝执行（Claude Code / Kiro / OpenCode 三端支持）
• 🔌 OpenCode 插件升级为 @opencode-ai/plugin SDK 格式（tool.execute.before hook）
• 🔧 run install 自动部署 check_track.sh 检查脚本并动态填充路径
• 🐛 issue_repo archive/delete 中 row.get() 对 sqlite3.Row 不兼容修复
• 🐛 session_id 从 DB 读取最新值再递增，避免多实例竞态
• 🐛 track date 参数格式校验（YYYY-MM-DD）+ issue_id 类型校验
• 🐛 Web API 请求解析安全加固（Content-Length 校验 + 10MB 上限 + JSON 异常捕获）
• 🐛 Tag 过滤 scope 逻辑修复（filter_dir is not None 替代 falsy 判断）
• 🐛 Export 向量数据 struct.unpack 字节长度校验
• 🐛 Schema 版本化迁移（schema_version 表 + v1/v2/v3 增量迁移）
• 🐛 __init__.py 版本号同步修复

v0.2.2

• 🔇 Web 看板 --quiet 参数屏蔽请求日志
• 🔄 Web 看板 --daemon 参数后台运行（macOS/Linux）
• 🔧 run install MCP 配置生成修复（sys.executable + 完整字段）
• 📋 问题跟踪增删改归档（Web 看板添加/编辑/归档/删除 + 记忆关联）
• 👆 全部列表页点击行任意位置弹出编辑弹窗（记忆/问题/标签）
• 🛡️ Hook 链式触发防护（agentStop + promptSubmit 组合不再重复注入规则）
• 🔒 会话延续/上下文转移时阻塞规则强制生效（跨会话必须重新确认）

v0.2.1

• ➕ Web 看板前端添加项目（目录浏览器 + 手动输入）
• 🏷️ 标签跨项目污染修复（标签操作限定当前项目 + 全局记忆范围）
• 📐 弹窗分页省略号截断 + 弹窗宽度 80%
• 🔌 OpenCode install 自动生成 auto_save 插件（session.idle 事件触发）
• 🔗 Claude Code / Cursor / Windsurf install 自动生成 Hooks 配置（会话结束自动保存）
• 🎯 Web 看板交互体验补全（Toast 操作反馈、空状态引导、导出/导入工具栏）
• 🔧 统计概览卡片点击跳转（点击记忆数/问题数直接弹窗查看）
• 🏷️ 标签管理页区分项目/全局标签来源（📁/🌐 标记）
• 🏷️ 项目卡片标签数合并全局记忆标签

v0.2.0

• 🔐 Web 看板 Token 认证机制
• ⚡ Embedding 向量缓存，相同内容不重复计算
• 🔍 recall 支持 query + tags 组合查询
• 🗑️ forget 支持批量删除（memory_ids 参数）
• 📤 记忆导出/导入（JSON 格式）
• 🔎 Web 看板语义搜索
• 🗂️ Web 看板项目删除按钮
• 📊 Web 看板性能优化（消除全表扫描）
• 🧠 digest 智能压缩
• 💾 session_id 持久化
• 📏 content 长度限制保护
• 🏷️ version 动态引用（不再硬编码）

v0.1.x

• 初始版本：7 个 MCP 工具、Web 看板、3D 向量可视化、多语言支持

License

MIT