aivectormemory 0.1.0__tar.gz

aivectormemory-0.1.0/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(/Users/macos/item/run-memory-mcp-server/.venv/bin/python -c:*)",
+      "mcp__devmemory__recall",
+      "mcp__devmemory__status",
+      "mcp__devmemory__remember",
+      "mcp__devmemory__track",
+      "Bash(/Users/macos/item/run-memory-mcp-server/.venv/bin/python -m devmemory web:*)",
+      "Bash(.venv/bin/python -m devmemory web:*)"
+    ]
+  }
+}

aivectormemory-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environment
+.venv/
+
+# DevMemory data
+.devmemory/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test
+.pytest_cache/
+htmlcov/
+.coverage

aivectormemory-0.1.0/.kiro/hooks/dev-workflow-check.kiro.hook

@@ -0,0 +1,14 @@
+{
+  "enabled": true,
+  "name": "开发流程检查",
+  "description": "每次收到用户消息时，检查核心原则、问题处理原则、自测要求",
+  "version": "1",
+  "when": {
+    "type": "promptSubmit"
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "## ⚠️  IDENTITY & TONE\n\n- Role:你是首席工程师兼高级数据科学家\n- Voice:Professional,Concise,Result-Oriented.No\"I hope this helps\"\n- Authority: The user is the Lead Architect. Execute explicit commands immediately (not questions).\n\n---\n\n##⚠️  收到用户消息后，严谨认真理解用户消息的意思然后判断消息类型，询问仅限闲聊，进度、讨论规则、简单确认不记录问题文档，其他所有情况必须需要记录问题文档，然后告诉用户方案，等用户确认后再执行\n\n**⚠️ 回复时用自然语言说明判断结果**，例如：\n- \"这是个询问，直接回答\"\n- \"这是个问题，方案如下...\"\n- \"这个问题需要记录\"\n\n---\n\n## ⚠️ 核心原则\n\n1. **任何操作前必须验证，不能假设，不能靠记忆**。\n2. **遇到需要处理的问题时禁止盲目测试，必须查看问题对应的代码文件，必须找到问题的根本原因，必须与实际错误对应**。\n3. **禁止口头承诺，口头答应，一切以测试通过为准**。\n4. **任何文件修改前必须查看代码强制严谨思考**。\n5. **开发、自测过程中禁止让用户手动操作，能自己执行的不要让用户做**。\n\n---\n\n## ⚠️ IDE 卡死防范\n\n- **禁止** `$(...)` + 管道组合\n- **禁止** MySQL `-e` 执行多条语句\n- **正确做法**：SQL 写入 `.sql` 文件用 `< data/xxx.sql` 执行\n\n## ⚠️ 自测要求\n\n**禁止让用户手动操作** - 能自己执行的，不要让用户做\n\n- Python：`python -m pytest` 或直接运行脚本验证\n- MCP Server：通过 stdio 发送 JSON-RPC 消息验证\n- Web 看板：Playwright 验证\n- 自测通过后才能说\"等待验证\""
+  },
+  "shortName": "dev-workflow-check"
+}

aivectormemory-0.1.0/.kiro/memory-mcp-server/.config.kiro

@@ -0,0 +1 @@
+{"generationMode": "requirements-first"}

aivectormemory-0.1.0/.kiro/memory-mcp-server/design.md

@@ -0,0 +1,208 @@
+# 设计文档：DevMemory MCP Server
+
+## 项目结构
+
+```
+devmemory/
+├── __init__.py
+├── __main__.py              # 入口：python -m devmemory
+├── server.py                # MCP 协议层（JSON-RPC over stdio）
+├── protocol.py              # JSON-RPC 消息解析与响应构建
+├── tools/
+│   ├── __init__.py
+│   ├── remember.py          # 记忆存入
+│   ├── recall.py            # 记忆回忆
+│   ├── forget.py            # 记忆删除
+│   ├── status.py            # 会话状态
+│   ├── track.py             # 问题跟踪
+│   └── digest.py            # 记忆整理
+├── db/
+│   ├── __init__.py
+│   ├── connection.py        # SQLite 连接管理（WAL 模式、sqlite-vec 加载）
+│   ├── schema.py            # 建表语句
+│   ├── memory_repo.py       # memories + vec_memories 读写
+│   ├── state_repo.py        # session_state 读写
+│   └── issue_repo.py        # issues 读写
+├── embedding/
+│   ├── __init__.py
+│   └── engine.py            # ONNX Runtime 推理（tokenize → 推理 → pooling → 归一化）
+├── web/
+│   ├── __init__.py
+│   ├── app.py               # HTTP 服务（Python 标准库 http.server）
+│   ├── api.py               # REST API 路由
+│   └── static/
+│       ├── index.html        # 单页应用
+│       ├── style.css
+│       └── app.js
+├── config.py                # 配置：路径、默认值、模型名
+└── errors.py                # 统一错误格式
+pyproject.toml               # 包配置、依赖、入口点
+```
+
+## 架构设计
+
+### 分层架构
+
+```
+┌─────────────────────────────────┐
+│  MCP 协议层（server.py）         │  stdin/stdout JSON-RPC
+├─────────────────────────────────┤
+│  工具层（tools/*.py）            │  6 个工具的业务逻辑
+├─────────────────────────────────┤
+│  数据层（db/*.py）               │  SQLite + sqlite-vec
+├─────────────────────────────────┤
+│  Embedding 层（embedding/）      │  ONNX Runtime 推理
+└─────────────────────────────────┘
+
+┌─────────────────────────────────┐
+│  Web 看板（web/*.py）            │  独立 HTTP 服务，复用数据层
+└─────────────────────────────────┘
+```
+
+### MCP 协议层（server.py + protocol.py）
+
+自实现 JSON-RPC 2.0 over stdio：
+
+- `protocol.py`：消息解析（从 stdin 按行读取 JSON）、响应构建（JSON-RPC result/error）
+- `server.py`：主循环，路由分发到对应 handler
+  - `initialize` → 返回 server info + capabilities，递增 session_id
+  - `tools/list` → 返回 6 个工具的 name + description + inputSchema（JSON Schema）
+  - `tools/call` → 根据 tool name 分发到 tools/*.py
+
+消息格式遵循 MCP 规范：
+- 请求：`{"jsonrpc": "2.0", "id": N, "method": "tools/call", "params": {...}}`
+- 响应：`{"jsonrpc": "2.0", "id": N, "result": {...}}`
+- 错误：`{"jsonrpc": "2.0", "id": N, "error": {"code": N, "message": "..."}}`
+
+日志输出到 stderr（不干扰 stdout 的 JSON-RPC 通信）。
+
+### 数据层设计
+
+#### 双数据库管理
+
+- `ConnectionManager` 类管理两个数据库连接：
+  - `user_db`：`~/.devmemory/memory.db`
+  - `project_db`：`{project}/.devmemory/memory.db`
+- 启动时自动创建目录和数据库文件
+- 所有连接启用 WAL 模式（`PRAGMA journal_mode=WAL`）
+- 所有连接加载 sqlite-vec 扩展
+
+#### 表结构
+
+```sql
+-- memories 表（用户级和项目级各一份）
+CREATE TABLE IF NOT EXISTS memories (
+    id TEXT PRIMARY KEY,
+    content TEXT NOT NULL,
+    tags TEXT NOT NULL DEFAULT '[]',  -- JSON 数组
+    scope TEXT NOT NULL DEFAULT 'project',
+    session_id INTEGER NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+
+-- sqlite-vec 虚拟表
+CREATE VIRTUAL TABLE IF NOT EXISTS vec_memories USING vec0(
+    id TEXT PRIMARY KEY,
+    embedding FLOAT[384]
+);
+
+-- session_state 表（仅项目级）
+CREATE TABLE IF NOT EXISTS session_state (
+    id INTEGER PRIMARY KEY DEFAULT 1,
+    is_blocked INTEGER NOT NULL DEFAULT 0,
+    block_reason TEXT NOT NULL DEFAULT '',
+    next_step TEXT NOT NULL DEFAULT '',
+    current_task TEXT NOT NULL DEFAULT '',
+    progress TEXT NOT NULL DEFAULT '[]',      -- JSON 数组
+    recent_changes TEXT NOT NULL DEFAULT '[]', -- JSON 数组
+    pending TEXT NOT NULL DEFAULT '[]',        -- JSON 数组
+    updated_at TEXT NOT NULL
+);
+
+-- issues 表（仅项目级）
+CREATE TABLE IF NOT EXISTS issues (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    issue_number INTEGER NOT NULL,
+    date TEXT NOT NULL,
+    title TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    content TEXT NOT NULL DEFAULT '',
+    archive_content TEXT NOT NULL DEFAULT '',
+    migrated_to TEXT NOT NULL DEFAULT '',
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_issues_date ON issues(date);
+CREATE INDEX IF NOT EXISTS idx_issues_status ON issues(status);
+```
+
+#### Repository 模式
+
+每个 repo 封装对应表的 CRUD：
+
+- `MemoryRepo`：insert（含去重检查）、search_by_vector、delete、get_by_session_range
+- `StateRepo`：get、upsert（部分更新）
+- `IssueRepo`：create、update、migrate、archive、list_by_date
+
+### Embedding 层设计
+
+`EmbeddingEngine` 类，懒加载：
+
+1. 首次调用时通过 `huggingface-hub` 下载 ONNX 模型到 `~/.cache/huggingface/`
+2. 加载 `tokenizers` 分词器
+3. 创建 `onnxruntime.InferenceSession`
+4. 推理流程：text → tokenize → ONNX 推理 → mean pooling → L2 归一化 → 384 维 float 数组
+
+去重逻辑：remember 时先算 Embedding，在 vec_memories 中查相似度 > 0.95 的记录，有则更新，无则插入。
+
+### Web 看板设计
+
+独立命令 `devmemory web --project-dir . --port 9080`：
+
+- `app.py`：基于 `http.server.HTTPServer`，处理静态文件和 API 请求
+- `api.py`：REST API 路由，前缀 `/api/`
+  - `GET /api/memories` — 记忆列表（支持 query/tags/scope 参数）
+  - `GET /api/memories/:id` — 记忆详情
+  - `PUT /api/memories/:id` — 编辑记忆
+  - `DELETE /api/memories/:id` — 删除记忆
+  - `DELETE /api/memories` — 批量删除（body 传 ids）
+  - `GET /api/status` — 会话状态
+  - `PUT /api/status` — 更新状态
+  - `GET /api/issues` — 问题列表（支持 date/status 参数）
+  - `PUT /api/issues/:id` — 更新问题状态
+  - `GET /api/stats` — 统计概览
+- `static/`：纯 HTML + CSS + JS 单页应用
+
+数据库连接：只读连接用于查询，写操作通过独立连接。
+
+### 入口点设计
+
+`pyproject.toml` 配置两个命令：
+
+```toml
+[project.scripts]
+devmemory = "devmemory.__main__:main"
+```
+
+`__main__.py` 解析子命令：
+- `devmemory`（无子命令）或 `devmemory serve`：启动 MCP Server（stdio 模式）
+- `devmemory web`：启动 Web 看板
+
+### session_id 管理
+
+- `server.py` 维护一个内部计数器 `_session_id`
+- 每次收到 `initialize` 请求时 +1
+- 从项目级数据库 `memories` 表读取 `MAX(session_id)` 作为初始值
+- 所有 `remember` 调用使用当前 `_session_id`
+
+### 错误处理
+
+统一错误格式：
+
+```python
+{"success": False, "error": "错误类型", "details": "详细信息"}
+```
+
+MCP 协议层将业务错误包装为 JSON-RPC error response（code: -32000）。
+参数校验错误使用 JSON-RPC invalid params（code: -32602）。

aivectormemory-0.1.0/.kiro/memory-mcp-server/requirements.md

@@ -0,0 +1,334 @@
+# 需求文档：DevMemory MCP Server
+
+## 简介
+
+DevMemory 是一个轻量级 MCP Server，为 AI 编程助手提供跨会话持久记忆能力。采用 6 个工具覆盖三大功能：通用记忆（remember/recall/forget）、会话状态（status）、问题跟踪（track）、记忆整理（digest）。
+
+双层存储架构：
+- 用户级（`~/.devmemory/`）：个人习惯、编程偏好、通用踩坑记录，跨项目共享
+- 项目级（`{project}/.devmemory/`）：项目知识库、技术要点、会话状态、问题跟踪
+
+数据存储：SQLite + sqlite-vec，所有数据（记忆、向量索引、会话状态、问题跟踪）统一存储在 SQLite 数据库中。
+
+技术栈：Python，自实现 MCP 协议（JSON-RPC over stdio），兼容 Kiro IDE 和 opencode。
+
+## 术语表
+
+- **Memory**：一条记忆记录，包含内容、标签、作用域、来源、时间戳和向量嵌入
+- **Scope**：记忆作用域，`user`（跟人走，存用户目录）或 `project`（跟项目走，存项目目录）
+- **Tag**：自由标签，用于分类和过滤记忆（如 `git`、`习惯`、`php`、`踩坑`）
+- **Vector_Index**：SQLite + sqlite-vec 向量索引，存储 Embedding 用于语义搜索
+- **Embedding**：文本的向量表示，通过本地模型将文本转换为 384 维浮点数组
+- **Session_State**：会话状态记录，存储在项目级 SQLite 数据库的 `session_states` 表中，记录阻塞状态和任务进度
+- **Issue**：问题记录，存储在项目级 SQLite 数据库的 `issues` 表中，包含完整生命周期（待处理→进行中→已完成→已归档）
+- **Digest**：记忆整理，将多次会话积累的碎片记忆提取出来，由 AI 端归纳总结后写回
+
+## 技术调研结论
+
+### MCP 协议实现
+
+- 自实现 JSON-RPC over stdio，不依赖第三方 MCP 框架
+- 核心方法：`initialize`（握手）、`tools/list`（工具列表）、`tools/call`（工具调用）
+- 传输协议：stdio（从 stdin 读请求，往 stdout 写响应）
+- 启动方式：`python -m devmemory` 或 `uvx devmemory`
+- Kiro 配置：`.kiro/settings/mcp.json`
+- opencode 配置：`.opencode/mcp.json` 或 `~/.config/opencode/mcp.json`
+
+### sqlite-vec
+
+- PyPI 包：`sqlite-vec`（v0.1.0+）
+- 加载方式：`sqlite_vec.load(db)` 需要 `db.enable_load_extension(True)`
+- 向量维度：384（匹配 embedding 模型）
+- 距离度量：余弦距离（cosine distance），值越小越相似
+- macOS：本机 Homebrew Python 3.12.10 已支持 `enable_load_extension`，SQLite 3.49.2，无需额外处理
+
+### Embedding 模型
+
+- 推荐模型：`intfloat/multilingual-e5-small`
+  - 维度：384
+  - 大小：~118MB
+  - 中文支持：优秀（专为多语言设计，100+ 语言）
+  - 推理方案：ONNX Runtime（轻量，无需 torch）
+  - HuggingFace 已提供 ONNX 格式模型，无需手动转换
+  - 需自行实现 tokenize → 推理 → mean pooling → 归一化 流程
+- 备选模型：`all-MiniLM-L6-v2`（22MB，中文效果较差）
+- 首次加载会自动下载模型到 `~/.cache/huggingface/`
+- 国内网络建议配置 HuggingFace 镜像：`export HF_ENDPOINT=https://hf-mirror.com`
+
+### IDE Hook 兼容性
+
+| 能力 | Kiro | opencode |
+|------|------|----------|
+| 会话结束事件 | `agentStop` hook | `session.idle` plugin event |
+| 工具调用前/后 | `preToolUse`/`postToolUse` | `tool.execute.before`/`after` |
+| 会话压缩注入 | 不支持 | `session.compacting` hook |
+| 自定义工具 | 不支持 | 支持（plugin tool 导出） |
+
+### 竞品分析
+
+| 项目 | 存储 | 向量搜索 | 问题跟踪 | 用户级记忆 | 中文支持 |
+|------|------|---------|---------|-----------|---------|
+| OpenMemory (CaviraOSS) | SQLite/Postgres | ✅ | ❌ | ❌ | 未知 |
+| mcp-mem0 | PostgreSQL + OpenAI | ✅ | ❌ | ❌ | 依赖 API |
+| mcp-memory-keeper | 文件 | ❌ | ❌ | ❌ | ❌ |
+| mcp-memory (ebailey78) | Markdown + Lunr.js | 关键词 | ❌ | ❌ | 有限 |
+| **DevMemory（本项目）** | SQLite | ✅ 本地 | ✅ | ✅ | ✅ |
+
+---
+
+## 需求
+
+### 需求 1：MCP Server 启动与配置
+
+**用户故事：** 作为开发者，我希望 MCP Server 轻量启动，在 Kiro 和 opencode 中都能使用。
+
+#### 验收标准
+
+1. THE Server SHALL 自实现 MCP 协议（JSON-RPC over stdio），不依赖第三方 MCP 框架
+2. WHEN 启动时，THE Server SHALL 接受 `--project-dir` 参数指定项目根目录，默认使用当前工作目录
+3. WHEN 启动时，THE Server SHALL 自动检测并创建所需目录结构：
+   - 用户级：`~/.devmemory/`（memory.db）
+   - 项目级：`{project}/.devmemory/`（memory.db）
+4. WHEN 启动时，THE Server SHALL 初始化 SQLite 数据库（WAL 模式）和 sqlite-vec 扩展
+5. WHEN 启动时，THE Server SHALL 懒加载 Embedding 模型（首次调用 recall 或 remember 时才加载，避免启动延迟）
+6. IF sqlite-vec 扩展加载失败，THEN THE Server SHALL 报错退出
+7. IF Embedding 模型加载失败，THEN THE Server SHALL 报错退出
+
+### 需求 2：记忆存入（remember）
+
+**用户故事：** 作为 AI 助手，我希望将重要信息存入记忆，以便后续会话中回忆。
+
+#### 验收标准
+
+1. WHEN `remember` 工具被调用时，THE Server SHALL 接受以下参数：
+   - `content`（必填）：记忆内容，Markdown 格式文本
+   - `tags`（必填）：标签列表，如 `["git", "习惯"]`
+   - `scope`（可选）：`user` 或 `project`，默认 `project`
+2. WHEN 存入记忆时，THE Server SHALL 自动生成唯一 ID、记录创建时间、计算 Embedding 向量
+3. WHEN 存入记忆时，THE Server SHALL 将记忆写入对应 scope 的 SQLite 数据库（memory.db）
+4. WHEN 存入记忆时，THE Server SHALL 同步将 Embedding 向量写入 sqlite-vec 虚拟表
+5. WHEN 存入成功时，THE Server SHALL 返回 `{id, tags, scope, created_at}`
+6. WHEN 存入记忆时，THE Server SHALL 先检查是否存在相似度超过 0.95 的记忆，若存在则更新该记忆而非创建新记录
+7. THE Server SHALL 记录每条记忆的 `session_id`（自增会话计数器），用于 digest 功能
+
+### 需求 3：记忆回忆（recall）
+
+**用户故事：** 作为 AI 助手，我希望通过语义搜索找到相关记忆，即使搜索词与原文用词不同。
+
+#### 验收标准
+
+1. WHEN `recall` 工具被调用时，THE Server SHALL 接受以下参数：
+   - `query`（必填）：搜索内容
+   - `scope`（可选）：`user`、`project` 或 `all`，默认 `all`
+   - `tags`（可选）：按标签过滤
+   - `top_k`（可选）：返回结果数量，默认 5
+2. WHEN scope 为 `all` 时，THE Server SHALL 同时搜索用户级和项目级数据库，合并结果按相似度排序
+3. WHEN 向量搜索可用时，THE Server SHALL 将 query 转换为 Embedding，在 sqlite-vec 中执行余弦相似度搜索
+4. WHEN 返回结果时，THE Server SHALL 包含 `{id, content, tags, scope, similarity_score, created_at}`
+5. IF 没有匹配结果，THEN THE Server SHALL 返回空列表
+
+### 需求 4：记忆删除（forget）
+
+**用户故事：** 作为 AI 助手，我希望删除过时或错误的记忆。
+
+#### 验收标准
+
+1. WHEN `forget` 工具被调用时，THE Server SHALL 接受 `memory_id`（单个 ID）或 `memory_ids`（ID 列表）参数
+2. WHEN 删除记忆时，THE Server SHALL 同时删除 SQLite 记录和 sqlite-vec 向量索引
+3. WHEN 删除成功时，THE Server SHALL 返回 `{deleted_count, ids}`
+4. IF 指定的 ID 不存在，THEN THE Server SHALL 在返回结果中标注哪些 ID 未找到，不影响其他 ID 的删除
+
+### 需求 5：会话状态（status）
+
+**用户故事：** 作为 AI 助手，我希望读取和更新会话状态，以便跨会话保持任务连续性。
+
+#### 验收标准
+
+1. WHEN `status` 工具被调用且未提供 `state` 参数时，THE Server SHALL 从项目级数据库读取当前会话状态，返回结构化数据：`{is_blocked, block_reason, next_step, current_task, progress, recent_changes, pending, updated_at}`
+2. WHEN `status` 工具被调用且提供 `state` 参数时，THE Server SHALL 接受以下可选字段进行部分更新：
+   - `blocking_status`、`blocking_reason`、`next_step`
+   - `current_task`、`progress`（列表）、`recent_changes`（列表）、`pending`（列表）
+3. WHEN 更新状态时，THE Server SHALL 仅更新提供的字段，保留未提供字段的原有值
+4. WHEN 更新状态时，THE Server SHALL 自动更新 `updated_at` 时间戳
+5. IF 数据库中无状态记录，THEN THE Server SHALL 使用默认值创建
+
+### 需求 6：问题跟踪（track）
+
+**用户故事：** 作为 AI 助手，我希望通过统一工具管理问题的完整生命周期。
+
+#### 验收标准
+
+1. WHEN `track` 工具被调用时，THE Server SHALL 接受 `action` 参数，支持以下操作：
+
+**action = "create"**：
+2. SHALL 接受 `title`（必填）、`date`（可选，默认当天）
+3. SHALL 在数据库中创建新问题记录，状态为 `pending`，自动分配 ID（当日最大编号 + 1）
+4. SHALL 返回 `{issue_id, date}`
+
+**action = "update"**：
+5. SHALL 接受 `issue_id`（必填）、`date`（可选）、`status`（可选：pending/in_progress/completed）、`content`（可选：追加排查内容）
+6. SHALL 更新问题记录的对应字段
+7. IF issue_id 不存在，THEN SHALL 返回错误
+
+**action = "migrate"**：
+8. SHALL 接受 `source_date`（必填）、`target_date`（可选，默认当天）
+9. SHALL 将源日期的 `pending` 和 `in_progress` 问题迁移到目标日期，状态设为 `in_progress`，从 1 重新编号
+10. SHALL 将源日期被迁移的问题标记为 `completed`，备注 `→ 已迁移至 YYYY-MM-DD 问题 N`
+11. SHALL 返回 `{migrated_count, id_mapping}`
+
+**action = "archive"**：
+12. SHALL 接受 `issue_id`（必填）、`content`（必填：完整排查记录）、`date`（可选）
+13. SHALL 将问题状态更新为 `archived`，保存完整排查记录到 `archive_content` 字段
+14. SHALL 返回 `{issue_id, archived_at}`
+
+**action = "list"**：
+15. SHALL 接受 `date`（可选，默认当天）、`status`（可选：过滤状态）
+16. SHALL 返回指定日期的问题列表，按编号排序
+
+### 需求 7：记忆整理（digest）
+
+**用户故事：** 作为 AI 助手，我希望定期整理碎片记忆，由 AI 归纳总结后写回精炼版本。
+
+#### 验收标准
+
+1. WHEN `digest` 工具被调用时，THE Server SHALL 接受以下参数：
+   - `scope`（可选）：`user`、`project` 或 `all`，默认 `project`
+   - `since_sessions`（可选）：最近 N 次会话的记忆，默认 20
+   - `tags`（可选）：按标签过滤
+2. WHEN 提取记忆时，THE Server SHALL 返回符合条件的所有记忆原始列表，按时间排序
+3. WHEN 返回结果时，THE Server SHALL 包含 `{memories: [{id, content, tags, created_at}], total_count, session_range}`
+4. THE Server SHALL 不做任何总结或归纳（由 AI 端完成），仅提供原始数据
+5. THE Server SHALL 在每次 `initialize` 调用时递增内部 session_id 计数器（每次 IDE 建立新连接视为新会话）
+
+### 需求 8：数据存储
+
+**用户故事：** 作为开发者，我希望数据存储可靠且统一。
+
+#### 验收标准
+
+1. THE Server SHALL 使用 SQLite 存储所有数据，表结构：
+   - `memories`：id, content, tags(JSON), scope, session_id, created_at, updated_at
+   - `vec_memories`：sqlite-vec 虚拟表，存储 384 维 Embedding 向量
+   - `session_state`：id, is_blocked, block_reason, next_step, current_task, progress(JSON), recent_changes(JSON), pending(JSON), updated_at
+   - `issues`：id, issue_number, date, title, status(pending/in_progress/completed/archived), content, archive_content, migrated_to, created_at, updated_at
+2. `.devmemory/memory.db` SHALL 被添加到 `.gitignore` 建议（可通过 rebuild 重建向量索引）
+
+### 需求 9：错误处理
+
+**用户故事：** 作为 AI 助手，我希望 MCP Server 在异常情况下返回清晰的错误信息。
+
+#### 验收标准
+
+1. IF sqlite-vec 不可用，THEN THE Server SHALL 报错退出
+2. IF Embedding 模型不可用，THEN THE Server SHALL 报错退出
+3. IF 数据库读写失败，THEN THE Server SHALL 返回包含错误原因的错误信息
+4. IF 参数不合法，THEN THE Server SHALL 返回参数校验错误信息
+5. THE Server SHALL 所有错误返回统一格式 `{success: false, error: str, details: str}`
+
+### 需求 10：IDE 集成配置
+
+**用户故事：** 作为开发者，我希望在 Kiro 和 opencode 中都能快速配置使用。
+
+#### 验收标准
+
+1. THE Server SHALL 支持以下 Kiro 配置方式（`.kiro/settings/mcp.json`）：
+```json
+{
+  "mcpServers": {
+    "devmemory": {
+      "command": "uv",
+      "args": ["run", "--with", "devmemory", "devmemory", "--project-dir", "."]
+    }
+  }
+}
+```
+2. THE Server SHALL 支持以下 opencode 配置方式（`.opencode/mcp.json`）：
+```json
+{
+  "mcpServers": {
+    "devmemory": {
+      "type": "local",
+      "command": "uv",
+      "args": ["run", "--with", "devmemory", "devmemory", "--project-dir", "."]
+    }
+  }
+}
+```
+3. THE Server SHALL 支持通过 `pip install devmemory` 或 `uv pip install devmemory` 安装
+4. THE Server SHALL 支持通过 `uvx devmemory` 直接运行（无需预安装）
+
+### 需求 11：Web 看板
+
+**用户故事：** 作为开发者，我希望通过浏览器查看和管理 DevMemory 中的数据。
+
+#### 验收标准
+
+1. THE Server SHALL 提供 `devmemory web` 命令启动本地 Web 看板，默认监听 `http://localhost:9080`
+2. THE Server SHALL 支持 `--port` 参数自定义端口
+3. Web 看板 SHALL 提供以下页面：
+
+**记忆管理**：
+4. SHALL 展示记忆列表，支持按关键词搜索、按标签过滤、按 scope 过滤
+5. SHALL 支持查看记忆详情（内容、标签、创建时间、所属会话）
+6. SHALL 支持删除单条或批量删除记忆
+7. SHALL 支持编辑记忆内容和标签
+
+**会话状态**：
+8. SHALL 展示当前会话状态（阻塞状态、当前任务、进度、待处理项）
+9. SHALL 支持手动修改会话状态各字段
+
+**问题跟踪**：
+10. SHALL 展示问题列表，支持按日期和状态过滤
+11. SHALL 支持查看问题详情（排查内容、归档记录）
+12. SHALL 支持手动切换问题状态
+
+**统计概览**：
+13. SHALL 展示基本统计：记忆总数、标签分布、各状态问题数量
+
+**技术实现**：
+14. THE Server SHALL 使用内置 HTTP 服务（Python 标准库），不引入额外 Web 框架
+15. THE Server SHALL 前端使用纯 HTML + CSS + JavaScript，不引入前端框架
+16. THE Server SHALL 复用 MCP Server 的 SQLite 读写逻辑，以只读方式打开数据库（写操作通过独立连接）
+
+---
+
+## 工具速查表
+
+| 工具 | 用途 | 存储层 | 核心参数 |
+|------|------|--------|---------|
+| `remember` | 存入记忆 | SQLite + 向量 | content, tags, scope |
+| `recall` | 语义搜索回忆 | SQLite + 向量 | query, scope, tags, top_k |
+| `forget` | 删除记忆 | SQLite + 向量 | memory_id(s) |
+| `status` | 会话状态读写 | SQLite | state(可选) |
+| `track` | 问题跟踪 | SQLite | action, ... |
+| `digest` | 提取待总结记忆 | SQLite | scope, since_sessions |
+
+## 依赖清单
+
+| 包名 | 用途 | 版本要求 |
+|------|------|---------|
+| `sqlite-vec` | SQLite 向量搜索扩展 | >=0.1.0 |
+| `onnxruntime` | 本地模型推理 | >=1.16 |
+| `tokenizers` | HuggingFace 分词器 | >=0.15 |
+| `huggingface-hub` | 模型下载 | >=0.20 |
+| `numpy` | 向量计算 | >=1.24 |
+
+⚠️ macOS 注意：系统自带 Python 3.9.6 不支持 SQLite 扩展加载。本机已安装 Homebrew Python 3.12.10（`/opt/homebrew/Cellar/python@3.12/3.12.10_1/`），SQLite 3.49.2，`enable_load_extension` 可用，sqlite-vec 可直接使用。
+
+## Embedding 模型选择
+
+| 模型 | 维度 | 大小 | 中文支持 | 说明 |
+|------|------|------|---------|------|
+| `intfloat/multilingual-e5-small` | 384 | ~118MB | ✅ 优秀 | 推荐，100+ 语言 |
+| `all-MiniLM-L6-v2` | 384 | ~22MB | ⚠️ 较差 | 备选，英文为主 |
+
+首次使用时模型自动下载到 `~/.cache/huggingface/`，后续离线可用。
+
+## 资源占用预估
+
+| 状态 | 内存 | 说明 |
+|------|------|------|
+| 空闲（模型未加载） | ~20-30MB | Python 进程 + SQLite |
+| 模型已加载 | ~100-200MB | + ONNX Runtime + 模型 |
+
+安装体积：~200MB（onnxruntime ~30MB + 模型 ~118MB + 其他依赖）

aivectormemory-0.1.0/.kiro/memory-mcp-server/tasks.md

@@ -0,0 +1,66 @@
+# 任务文档：DevMemory MCP Server
+
+## 阶段 1：项目骨架与基础设施
+
+- [x] 1.1 创建 `pyproject.toml`（包名 devmemory、依赖、入口点配置）
+- [x] 1.2 创建目录结构（devmemory/、tools/、db/、embedding/、web/）
+- [x] 1.3 实现 `config.py`（路径常量、默认值、模型名）
+- [x] 1.4 实现 `errors.py`（统一错误格式 `{success, error, details}`）
+- [x] 1.5 实现 `__main__.py`（命令行参数解析：`--project-dir`、子命令 serve/web）
+
+## 阶段 2：数据层
+
+- [x] 2.1 实现 `db/connection.py`（ConnectionManager：双数据库连接、WAL 模式、sqlite-vec 加载）
+- [x] 2.2 实现 `db/schema.py`（建表语句：memories、vec_memories、session_state、issues）
+- [x] 2.3 实现 `db/memory_repo.py`（insert、search_by_vector、delete、get_by_session_range）
+- [x] 2.4 实现 `db/state_repo.py`（get、upsert 部分更新）
+- [x] 2.5 实现 `db/issue_repo.py`（create、update、migrate、archive、list_by_date）
+- [x] 2.6 测试数据层：验证建表、CRUD、WAL 模式、sqlite-vec 向量搜索（19 tests passed）
+
+## 阶段 3：Embedding 层
+
+- [x] 3.1 实现 `embedding/engine.py`（EmbeddingEngine：懒加载、模型下载、tokenize → ONNX 推理 → mean pooling → 归一化）
+- [x] 3.2 测试 Embedding：验证模型加载、向量维度 384、中文文本编码正确
+
+## 阶段 4：MCP 协议层
+
+- [x] 4.1 实现 `protocol.py`（JSON-RPC 消息解析、响应构建、错误码）
+- [x] 4.2 实现 `server.py`（主循环：stdin 读取 → 路由分发 → stdout 响应、session_id 管理）
+- [x] 4.3 实现 `initialize` handler（返回 server info + capabilities，递增 session_id）
+- [x] 4.4 实现 `tools/list` handler（返回 6 个工具的 JSON Schema）
+- [x] 4.5 实现 `tools/call` 路由分发
+- [x] 4.6 测试协议层：手动发送 JSON-RPC 消息验证握手和工具列表（4 tests passed）
+
+## 阶段 5：工具实现
+
+- [x] 5.1 实现 `tools/remember.py`（存入记忆 + 去重检查 + Embedding 计算）
+- [x] 5.2 实现 `tools/recall.py`（向量搜索 + 双库合并 + 标签过滤）
+- [x] 5.3 实现 `tools/forget.py`（删除记忆 + 向量索引）
+- [x] 5.4 实现 `tools/status.py`（读取/部分更新会话状态）
+- [x] 5.5 实现 `tools/track.py`（create/update/migrate/archive/list 五个 action）
+- [x] 5.6 实现 `tools/digest.py`（按 session_id 范围提取记忆）
+- [x] 5.7 集成测试：通过 stdio 调用每个工具，验证输入输出（5 tests passed）
+
+## 阶段 6：IDE 集成测试
+
+- [x] 6.1 配置 Kiro MCP（`.kiro/settings/mcp.json`），验证工具列表加载
+- [x] 6.2 在 Kiro 中测试 remember → recall 流程
+- [x] 6.3 在 Kiro 中测试 status 读写
+- [x] 6.4 在 Kiro 中测试 track 全生命周期（create → update → archive）
+- [x] 6.5 验证 `pip install -e .` 本地安装 + `devmemory --help` 可用
+
+## 阶段 7：Web 看板
+
+- [x] 7.1 实现 `web/app.py`（HTTP 服务、静态文件托管）
+- [x] 7.2 实现 `web/api.py`（REST API 路由：memories/status/issues/stats）
+- [x] 7.3 实现 `web/static/index.html`（页面结构：导航、记忆列表、状态、问题、统计）
+- [x] 7.4 实现 `web/static/style.css`（样式）
+- [x] 7.5 实现 `web/static/app.js`（交互逻辑：搜索、过滤、编辑、删除）
+- [x] 7.6 测试 Web 看板：启动服务，验证各页面功能
+
+## 阶段 8：打包发布
+
+- [x] 8.1 完善 `pyproject.toml`（版本号、描述、license、README）
+- [x] 8.2 创建 `.gitignore`（包含 `.devmemory/` 建议）
+- [x] 8.3 验证 `pip install .` 本地安装
+- [x] 8.4 验证 `uv pip install .` 安装