Metadata-Version: 2.4
Name: amrita_plugin_memory
Version: 0.1.1
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 的工具系统中。

## 功能特点

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

## 工具函数

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

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

| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `content` | string | ✅ | 记忆内容，简洁明了 |
| `tags` | string | ✅ | 分类标签，如 `preference`、`project` |
| `importance` | `"low"` / `"medium"` / `"high"` | ✅ | 重要性等级 |

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

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

| 参数 | 类型 | 必需 | 默认值 | 描述 |
|------|------|------|--------|------|
| `query` | string | ✅ | — | 关键词字符串，空格分隔 |
| `top_k` | integer | ❌ | `5` | 返回结果数量 |
| `importance` | `"low"` / `"medium"` / `"high"` | ❌ | — | 按重要性过滤 |

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

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

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

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

删除指定 ID 的记忆。

| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `id` | string | ✅ | 要删除的记忆 ID |

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

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

| 参数 | 类型 | 必需 | 默认值 | 描述 |
|------|------|------|--------|------|
| `limit` | integer | ❌ | `5` | 返回数量限制 |

## 配置选项

### 文件配置（`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` | 嵌入模型协议 |

## 安装与使用

### 前置条件

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

