# SzyMemory

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

## 架构

```
AI IDE (Cursor / Windsurf / Claude Code / Kiro / ...)
        │ MCP Protocol (stdio)
        ▼
   SzyMemory Server
   ├── remember / recall / forget    记忆管理
   ├── status / track / task         会话状态 & 任务跟踪
   ├── auto_save / readme            自动保存 & 文档生成
   ├── Embedding Engine (ONNX)       向量语义匹配
   └── SQLite + sqlite-vec           本地存储 ~/.szymemory/memory.db
```

## 安装

```bash
pip install szymemory

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

`run install` 会自动检测 IDE 并生成 MCP 配置、Steering 规则、Hooks，无需手动配置。

也可以用 `uvx` 免安装直接运行：

```bash
uvx szymemory install
```

### 手动配置

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

| IDE | 配置文件路径 |
|-----|------------|
| Cursor | `.cursor/mcp.json` |
| Windsurf | `.windsurf/mcp.json` |
| Claude Code | `.mcp.json` |
| VSCode | `.vscode/mcp.json` |
| Kiro | `.kiro/settings/mcp.json` |
| Trae | `.trae/mcp.json` |

## 8 个 MCP 工具

| 工具 | 功能 | 关键参数 |
|------|------|---------|
| **remember** | 存储记忆 | `content`、`tags`、`scope`（project/user） |
| **recall** | 语义搜索 | `query`、`tags`、`scope`、`top_k` |
| **forget** | 删除记忆 | `memory_id` / `memory_ids` |
| **status** | 会话状态 | 不传参=读取，传 `state`=更新 |
| **track** | 问题跟踪 | `action`（create/update/archive/list） |
| **task** | 任务管理 | `action`（batch_create/update/list/delete） |
| **readme** | 文档生成 | `action`（generate/diff）、`lang` |
| **auto_save** | 自动保存偏好 | `preferences`（跨项目） |

- 相似度 > 0.95 自动更新已有记忆，不产生重复
- 向量语义匹配，不同措辞也能找到相关记忆

## Web 管理面板

```bash
run web --port 9080
```

浏览器访问 `http://localhost:9080`，首次使用需点击"注册"创建账号。

功能：多项目切换、记忆浏览/搜索/编辑/导出导入、语义搜索、标签管理、3D 向量可视化、多语言支持。

## 国内用户

嵌入模型（~200MB）首次运行自动下载，如果速度慢可设置镜像：

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

或在 MCP 配置中添加：

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

## 技术栈

| 组件 | 技术 |
|------|------|
| 运行时 | Python >= 3.10 |
| 向量数据库 | SQLite + sqlite-vec |
| 嵌入模型 | ONNX Runtime + intfloat/multilingual-e5-small |
| 协议 | Model Context Protocol (MCP) |

## 许可证

Apache-2.0
