amrita_plugin_memory

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

技术栈

架构概览

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 —— 写入记忆

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

2. read_memory —— 检索记忆

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

3. update_memory —— 更新记忆

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

4. delete_memory —— 删除记忆

删除指定 ID 的记忆。

5. list_memory —— 列出记忆

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

配置选项

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

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

安装与使用

前置条件

• Python 3.10 ~ 3.13
• 已部署的 AmritaBot 实例
• （本地模式）无需额外组件
• （远程模式）已运行的 ChromaDB 服务端
• 已运行的嵌入模型服务（如 Ollama）

安装

ambot plugin install amrita_plugin_memory

配置

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

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

验证

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

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

开发

# 安装开发依赖
uv sync

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

# 类型检查
pyright