amrita_plugin_memory 0.1.0__tar.gz → 0.1.2__tar.gz

amrita_plugin_memory-0.1.2/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: amrita_plugin_memory
+Version: 0.1.2
+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` | 嵌入模型协议 |
+
+## 安装与使用
+
+### 前置条件
+
+- 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
+```
+

amrita_plugin_memory-0.1.2/README.md

@@ -0,0 +1,172 @@
+# 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` | 嵌入模型协议 |
+
+## 安装与使用
+
+### 前置条件
+
+- 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
+```
+

{amrita_plugin_memory-0.1.0 → amrita_plugin_memory-0.1.2}/amrita_plugin_memory/config.py

@@ -14,6 +14,8 @@ PLUGIN_IM = "amrita_plugin_memory"
 
 
 class ConfigFile(BaseModel):
+    """配置文件"""
+
     short_term_expiry_days: int = Field(
         default=3, description="短期记忆的过期天数，默认为3天"
     )
@@ -60,12 +62,13 @@ class EnvConfig(BaseModel):
         default="http://127.0.0.1:11434", description="Embedding模型地址"
     )
     embedding_model_name: str = Field(default="auto", description="Embedding模型名称")
-    embedding_proctol: Literal["openai-embed", "ollama-embed"] = Field(
+    embedding_proctol: Literal["openai", "ollama-embed"] = Field(
         default="ollama-embed", description="Embedding模型协议"
     )
 
 
 class DataManager(BaseDataManager[ConfigFile]):
+    _owner_name = PLUGIN_IM
     config: ConfigFile
 
 

{amrita_plugin_memory-0.1.0 → amrita_plugin_memory-0.1.2}/amrita_plugin_memory/embed.py

@@ -1,13 +1,14 @@
-from collections.abc import Iterable, Sequence
+from collections.abc import Iterable, Sequence  # noqa: I001
 from typing import Any, Literal
+from typing_extensions import override
 
 import aiohttp
-from amrita_core.protocol import ModelAdapter
+from amrita_core.base.adapter import ModelAdapter
 from amrita_core.types import EmbeddingChunk
-from openai import AsyncOpenAI
 
 
 class OllamaEmbeddingAdapter(ModelAdapter):
+    @override
     async def call_embed(
         self, texts: Iterable[str], **kwargs
     ) -> Sequence[EmbeddingChunk]:
@@ -43,28 +44,3 @@ class OllamaEmbeddingAdapter(ModelAdapter):
     @staticmethod
     def get_type() -> Literal["embed"]:
         return "embed"
-
-
-class OpenAIEmbeddingAdapter(ModelAdapter):
-    async def call_embed(
-        self, texts: Iterable[str], **kwargs
-    ) -> Sequence[EmbeddingChunk]:
-        ps = self.preset
-        client = AsyncOpenAI(
-            base_url=ps.base_url, api_key=ps.api_key, max_retries=5, timeout=60
-        )
-        if isinstance(texts, str):
-            texts = [texts]
-        texts = list(texts)
-        embedd = await client.embeddings.create(
-            input=texts, model=ps.model, **kwargs, timeout=60
-        )
-        return [EmbeddingChunk.model_validate(data) for data in embedd.data]
-
-    @staticmethod
-    def get_adapter_protocol() -> Literal["openai-embed"]:
-        return "openai-embed"
-
-    @staticmethod
-    def get_type() -> Literal["embed"]:
-        return "embed"