Metadata-Version: 2.4
Name: amrita_plugin_memory
Version: 0.1.4
Summary: Amrita长期记忆插件
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.13.3
Requires-Dist: aiologic>=0.16.0
Requires-Dist: amrita-core>=0.8.5
Requires-Dist: amrita>=1.3
Requires-Dist: chromadb>=1.5.8
Requires-Dist: nonebot-plugin-localstore>=0.7.4
Dynamic: license-file

# amrita_plugin_memory

Amrita 长期记忆插件 —— 基于 ChromaDB 向量数据库的智能记忆管理系统，让 AI 助手能够持久化地记住关于用户的重要信息。

## 技术栈

| 组件       | 技术                                                    |
| ---------- | ------------------------------------------------------- |
| 后端框架   | Python 3.10+ / NoneBot2 / Amrita Core                   |
| 向量数据库 | ChromaDB（支持本地 PersistentClient 与远程 HttpClient） |
| 嵌入模型   | OpenAI Embedding API / Ollama Embedding API             |
| 配置管理   | Pydantic + TOML                                         |
| 异步处理   | asyncio + aiologic + aiohttp                            |
| 代码质量   | Ruff + Pyright                                          |

## 架构概览

```
amrita_plugin_memory/
├── __init__.py    # 插件入口，注册依赖
├── config.py      # 配置模型（ConfigFile / EnvConfig / DataManager）
├── embed.py       # Ollama 嵌入适配器
├── vector.py      # ChromaDB 异步封装（WrappedClientAPI / AsyncUserMemory）
└── tools.py       # 工具函数定义与注册（write/read/update/delete/list）
```

- **config.py**: 定义配置文件（过期天数、记忆上限）和环境变量（数据库类型、嵌入模型地址等），通过 Pydantic 模型校验。
- **embed.py**: 实现 Ollama 协议的嵌入适配器，通过 HTTP API 调用 `/api/embed` 端点。
- **vector.py**: 对 ChromaDB 原生 API 进行 `asyncio.to_thread` 封装，提供异步的集合管理与记忆 CRUD。使用 `aiologic.Lock` 按用户粒度加锁，保证并发安全。
- **tools.py**: 定义 5 个 Function Calling 工具（`write_memory` / `read_memory` / `update_memory` / `delete_memory` / `list_memory`），注册到 Amrita 的工具系统中。通过 `scope` 参数支持群共享记忆与用户专属记忆的分区隔离。

## 功能特点

- **长期记忆存储**：将用户偏好、项目信息等持久化存入 ChromaDB 向量数据库
- **群/用户记忆隔离**：LLM 可通过 `scope` 参数选择存入群共享记忆（群内所有人可见）或用户专属记忆（仅自己可见）
- **语义检索**：基于嵌入向量的语义相似度检索，支持中英文关键词
- **智能标签**：支持使用自定义标签对记忆进行分类（如 `preference`、`project`）
- **重要性分级**：三级重要程度（`low` / `medium` / `high`），支持按级别过滤检索
- **完整 CRUD**：支持记忆的创建、查询、更新、删除和列表查看
- **并发安全**：按用户 ID 粒度加锁，确保同一用户的操作串行化
- **多租户支持**：通过 ChromaDB remote 模式支持远程向量数据库

## 工具函数

### 1. `write_memory` —— 写入记忆

将当前用户（或群组）的重要信息存入长期记忆。

| 参数         | 类型                            | 必需 | 描述                                                  |
| ------------ | ------------------------------- | ---- | ----------------------------------------------------- |
| `content`    | string                          | ✅   | 记忆内容，简洁明了                                    |
| `tags`       | string                          | ✅   | 分类标签，如 `preference`、`project`                  |
| `importance` | `"low"` / `"medium"` / `"high"` | ✅   | 重要性等级                                            |
| `scope`      | `"group"` / `"user"`            | ✅   | `group`=群共享，`user`=个人专属（私聊不可用 `group`） |

### 2. `read_memory` —— 检索记忆

从记忆库中按语义相似度检索用户相关信息。

| 参数         | 类型                            | 必需 | 默认值 | 描述                       |
| ------------ | ------------------------------- | ---- | ------ | -------------------------- |
| `query`      | string                          | ✅   | —      | 关键词字符串，空格分隔     |
| `top_k`      | integer                         | ❌   | `5`    | 返回结果数量               |
| `importance` | `"low"` / `"medium"` / `"high"` | ❌   | —      | 按重要性过滤               |
| `scope`      | `"group"` / `"user"`            | ✅   | —      | 检索范围：群共享或个人专属 |

### 3. `update_memory` —— 更新记忆

更新指定 ID 的记忆内容、标签或重要性。

| 参数         | 类型                            | 必需 | 描述            |
| ------------ | ------------------------------- | ---- | --------------- |
| `id`         | string                          | ✅   | 要更新的记忆 ID |
| `scope`      | `"group"` / `"user"`            | ✅   | 记忆所属范围    |
| `content`    | string                          | ❌   | 新的记忆内容    |
| `tags`       | string                          | ❌   | 新的标签        |
| `importance` | `"low"` / `"medium"` / `"high"` | ❌   | 新的重要性等级  |

### 4. `delete_memory` —— 删除记忆

删除指定 ID 的记忆。

| 参数    | 类型                 | 必需 | 描述            |
| ------- | -------------------- | ---- | --------------- |
| `id`    | string               | ✅   | 要删除的记忆 ID |
| `scope` | `"group"` / `"user"` | ✅   | 记忆所属范围    |

### 5. `list_memory` —— 列出记忆

列出当前用户的所有记忆（返回 scope、标签和 ID）。

| 参数    | 类型                 | 必需 | 默认值 | 描述                       |
| ------- | -------------------- | ---- | ------ | -------------------------- |
| `limit` | integer              | ❌   | `5`    | 返回数量限制               |
| `scope` | `"group"` / `"user"` | ✅   | —      | 列出范围：群共享或个人专属 |

## 配置选项

### 文件配置（`config/amrita_plugin_memory/config.toml`）

| 配置项                     | 类型 | 默认值 | 描述                   |
| -------------------------- | ---- | ------ | ---------------------- |
| `short_term_expiry_days`   | int  | `3`    | 短期记忆过期天数       |
| `long_term_expiry_days`    | int  | `30`   | 长期记忆过期天数       |
| `permanent_expiry_days`    | int  | `365`  | 永久记忆过期天数       |
| `per_session_memory_limit` | int  | `50`   | 每个会话的记忆数量上限 |

### 环境变量（`.env` 或系统环境变量）

| 变量                       | 类型                      | 默认值                   | 描述                      |
| -------------------------- | ------------------------- | ------------------------ | ------------------------- |
| `VECTOR_DB_TYPE`           | `local` / `remote`        | `local`                  | ChromaDB 数据库类型       |
| `VECTOR_DB_SERVER`         | string                    | `127.0.0.1`              | 远程 ChromaDB 地址        |
| `VECTOR_DB_PORT`           | int                       | `8000`                   | 远程 ChromaDB 端口        |
| `VECTOR_DB_SERVER_SSL`     | bool                      | `false`                  | 是否启用 SSL              |
| `VECTOR_DB_REMOTE_HEADERS` | dict                      | `{}`                     | 远程请求头                |
| `VECTOR_DB_TENANT`         | string                    | `default`                | 租户名称                  |
| `VECTOR_DB_DATABASE`       | string                    | `default`                | 数据库名称                |
| `EMBEDDING_MODEL_URL`      | string                    | `http://127.0.0.1:11434` | 嵌入模型地址              |
| `EMBEDDING_MODEL_NAME`     | string                    | `auto`                   | 嵌入模型名称              |
| `EMBEDDING_PROCTOL`        | `openai` / `ollama-embed` | `ollama-embed`           | 嵌入模型协议              |
| `EMBEDDING_MODEL_API_KEY`  | string                    | (空)                     | 嵌入模型 API 密钥（可选） |

## 安装与使用

### 前置条件

- Python 3.10 ~ 3.13
- 已部署的 [AmritaBot](https://github.com/AmritaBot) 实例
- （本地模式）无需额外组件
- （远程模式）已运行的 ChromaDB 服务端
- 已运行的嵌入模型服务（如 Ollama）

### 安装

```bash
ambot plugin install amrita_plugin_memory
```

### 配置

插件安装后会自动生成配置文件。你可以通过以下方式配置：

1. **WebUI 配置**：在 Amrita 的 Web 管理界面中直接修改
2. **手动编辑**：修改 `config/amrita_plugin_memory/config.toml`
3. **环境变量**：通过 `.env` 文件或系统环境变量设置数据库和嵌入模型参数

### 验证

启动后查看日志，确认向量数据库连接成功：

```
正在尝试向量数据库连接...
当前向量数据库类型: local
创建了向量数据库客户端！
向量数据库版本：x.x.x
完成。
```

## 开发

```bash
# 安装开发依赖
uv sync

# 代码格式化与检查
ruff format .
ruff check .

# 类型检查
pyright
```
