{"id":50553538,"url":"https://github.com/piexian/astrbot_plugin_simple_long_memory","last_synced_at":"2026-06-04T05:03:37.536Z","repository":{"id":355387998,"uuid":"1174170678","full_name":"piexian/astrbot_plugin_simple_long_memory","owner":"piexian","description":"为 AstrBot 提供简易的长期记忆能力，基于内置知识库实现用户偏好、历史交互和重要事实的记忆存储与召回。","archived":false,"fork":false,"pushed_at":"2026-05-13T22:13:24.000Z","size":347,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-14T00:39:29.708Z","etag":null,"topics":["astrbot-plugin","memory"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/piexian.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-06T06:25:34.000Z","updated_at":"2026-05-13T22:10:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/piexian/astrbot_plugin_simple_long_memory","commit_stats":null,"previous_names":["piexian/astrbot_plugin_simple_long_memory"],"tags_count":0,"template":false,"template_full_name":"Soulter/helloworld","purl":"pkg:github/piexian/astrbot_plugin_simple_long_memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piexian%2Fastrbot_plugin_simple_long_memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piexian%2Fastrbot_plugin_simple_long_memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piexian%2Fastrbot_plugin_simple_long_memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piexian%2Fastrbot_plugin_simple_long_memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piexian","download_url":"https://codeload.github.com/piexian/astrbot_plugin_simple_long_memory/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piexian%2Fastrbot_plugin_simple_long_memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33890052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astrbot-plugin","memory"],"created_at":"2026-06-04T05:03:36.812Z","updated_at":"2026-06-04T05:03:37.530Z","avatar_url":"https://github.com/piexian.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AstrBot 简单长期记忆插件\n\n为 AstrBot 提供长期记忆能力，基于内置知识库实现用户偏好、历史交互和重要事实的记忆存储与召回。\n\n## 功能特性\n\n- **自动记忆提取**：每隔 N 轮对话自动调用 LLM 从对话中提取值得记忆的信息\n- **记忆注入**：在每次 LLM 请求前，自动召回相关记忆并注入到对话上下文\n- **用户隔离**：通过 `user_id` 实现用户级记忆隔离，互不干扰\n- **群聊记忆作用域**：支持群聊场景下的记忆归属区分（个人记忆 vs 群共享记忆）\n- **LLM 工具**：提供 `memory_recall`、`memory_store`、`memory_forget` 工具供 AI 主动操作\n- **用户命令**：通过 `/memory` 指令组管理记忆\n- **知识库管理**：记忆直接存储在 AstrBot 内置知识库中，可在知识库管理界面直接查看、检索、删除记忆\n\n## 安装\n\n**方式一**：AstrBot 插件市场搜索「简单长期记忆」安装（待上架）。\n\n**方式二**：插件界面右下角加号 → 从链接安装，输入：\n```\nhttps://github.com/piexian/astrbot_plugin_simple_long_memory\n```\n\n安装后，在知识库管理中创建一个用于存储记忆的知识库（需配置嵌入模型），然后在插件设置中选该知识库。\n\n## 配置说明\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| kb_name | 记忆知识库（必填） | — |\n| extraction_provider_id | 记忆提取 LLM 模型 | 留空使用会话主 LLM |\n| summarization_provider_id | 记忆总结 LLM 模型（预留） | 留空使用会话主 LLM |\n| auto_memorize | 自动记忆模式开关 | `true` |\n| extraction_interval | 每 N 轮对话触发一次记忆提取 | `20` |\n| extraction_min_content_length | 对话总长度低于此值时跳过提取 | `150` |\n| global_memory | 全局记忆模式（跨会话召回） | `true` |\n| max_memories_per_inject | 每次 LLM 请求注入的最大记忆条数 | `5` |\n| max_memory_list_scan | 记忆列表扫描上限 | `200` |\n| memory_delete_scan_page_size | 记忆删除扫描分页大小 | `1000` |\n| memory_ttl_days | 记忆生命周期（天） | `30` |\n| use_reranker | 记忆召回时启用重排序（需知识库已配置重排序模型） | `true` |\n| optimize_recall_query | 启用检索优化（LLM 提炼关键词） | `false` |\n| optimize_recall_query_timeout | 检索优化超时（秒） | `10` |\n| enable_admin_global_memory_tool | 启用管理员全局记忆工具 | `false` |\n\n## 使用方法\n\n### 用户命令\n\n```\n/memory list [--all] [页码]            - 列出记忆（支持翻页）\n/memory search [--all] \u003c关键词\u003e        - 搜索记忆\n/memory stats [--all]                  - 查看记忆统计\n/memory test                           - 测试记忆读写功能（管理员）\n/memory forget \u003curi\u003e [--user \u003c用户ID\u003e] - 删除指定记忆\n/memory clear [--all] [--user \u003c用户ID\u003e] [--confirm \u003c确认码\u003e] - 清空记忆（管理员，需确认码）\n/memory rebuild [--to \u003c知识库名\u003e] [--confirm \u003c确认码\u003e] - 重建或迁移记忆（管理员，需确认码）\n/memory rebuild --clear-cache [--confirm \u003c确认码\u003e] - 清理重建缓存（管理员，需确认码）\n```\n\n- `test`、`clear`、`rebuild` 需要管理员权限\n- `forget`：普通用户可删除自己的记忆，管理员可删除任意记忆\n- `--all`：管理员可查看/搜索/统计/清空所有用户的记忆\n- `--user \u003c用户ID\u003e`：管理员可删除/清空指定用户的记忆（`--all` 与 `--user` 不可同时使用）\n\n### 群聊场景\n\n群聊中记忆按归属分为三种，机器人自动判断无需手动设置：\n\n| 作用域 | 说明 | 日常例子 |\n|--------|------|----------|\n| `global` | 全局记忆，所有会话可召回（仅管理员工具可写入） | \"机器人回答某项目问题时优先使用内部术语表\" |\n| `personal` | 个人记忆，仅自己可见 | \"我比较喜欢喝拿铁\"、\"下周要出差\" |\n| `group` | 群共享记忆，群友都可见 | \"群里约了每周五打游戏\"、\"这个群的固定梗\" |\n| `conversation` | 当前会话临时上下文 | \"刚才说的那个 bug 还没修完\" |\n\n私聊默认召回 `personal` 记忆，并可使用 `conversation` 记录当前私聊会话上下文。\n\n\u003e 从旧版本升级到 v0.3 后，请执行 `/memory rebuild`。运行时召回和列表只认新 metadata 结构；旧格式记录需要通过重建补齐 `memory_scope`、owner、visibility 等字段后才会进入新作用域模型。\n\u003e 重建只处理当前知识库 `kb_id` 下的记忆记录，避免误迁移其它知识库或无法可靠归属的数据。\n\n### 记忆重建与迁移\n\n`/memory rebuild` 提供两个能力：\n\n- **原地重建**：将所有记忆重新嵌入写入当前知识库，适用于修复损坏的向量数据\n- **迁移**：将所有记忆迁移到目标知识库，适用于切换知识库或更换嵌入模型（目标知识库需配置好新的嵌入模型）\n\n```\n/memory rebuild                        # 原地重建（重新嵌入）\n/memory rebuild --to \u003c知识库名\u003e        # 迁移到目标知识库\n/memory rebuild --clear-cache          # 清理重建缓存\n```\n\n**工作流程**：\n1. 拉取所有记忆到本地并持久化到 KV 数据库（防崩溃丢失）\n2. 原地重建：清空当前 KB → 重新嵌入写入；迁移：写入目标 KB → 清空源 KB\n3. 重建期间新产生的记忆会被缓冲，完成后批量语义去重写入\n4. 自动进行完整性校验，对比预期与实际记忆数量\n5. 确认数据无误后，手动执行 `--clear-cache` 清理缓存\n\n**安全机制**：\n- 本地优先：先拉全量数据再执行破坏性操作\n- 进程崩溃恢复：中间状态通过 KV 持久化，重启后自动恢复\n- 迁移安全保护：写入失败时不清空源知识库，防止数据丢失\n- 手动缓存清理：需用户确认数据无误后才清理缓存\n\n### LLM 工具\n\nAI 可以通过以下工具主动操作记忆：\n\n- `memory_recall(query)` — 搜索长期记忆\n- `memory_store(content, memory_type, disclosure)` — 存储记忆\n- `memory_store_global(content, memory_type, disclosure)` — 存储全局记忆（需开启 `enable_admin_global_memory_tool`，仅管理员可用）\n- `memory_forget(uri)` — 删除记忆\n\n### 记忆类型\n\n| memory_type | 说明 |\n|-------------|------|\n| `fact` | 用户主动告知的客观信息 |\n| `preference` | 用户表达的喜好、习惯、风格 |\n| `event` | 计划、纪念日、里程碑等事件 |\n| `context` | 正在进行的项目或当前状况 |\n\n## 工作原理\n\n1. **记忆注入**：在每次 LLM 请求前，根据用户输入通过 embedding 检索召回相关记忆；AstrBot v4.24+ 优先注入到临时用户内容区（仅本轮请求生效），旧版回退到最早的 `user` 上下文位置（不占用 system prompt，不覆盖当前输入）\n2. **自动提取**：每隔 `extraction_interval` 轮对话，将累积的对话内容发送给 LLM 提取值得记忆的信息并自动存储\n3. **用户隔离**：所有记忆操作通过 metadata 中的 `user_id` 字段过滤，确保用户间记忆完全隔离\n4. **记忆存储**：记忆以向量形式存储在知识库中，支持语义检索\n\n## 注意事项\n\n- 请确保先创建知识库并配置嵌入模型\n- 记忆数据存储在知识库中，删除知识库将丢失所有记忆\n- **请勿将记忆知识库挂载到 AstrBot 全局知识库配置中**。本插件通过 `user_id` 实现用户级记忆隔离，而 AstrBot 原生知识库检索不支持用户隔离，挂载后会导致所有用户共享彼此的记忆。仅个人独占使用时可忽略此限制\n\n\n### 启用方法\n\n1. 在「使用电脑能力」中将运行环境设置为 `local` 或 `sandbox`\n2. 在本插件配置中开启 **安装记忆 Skill**\n3. 重启或重载插件，Skill 将自动安装到 AstrBot 的 skills 目录并激活\n\n\n\u003cdiv align=\"center\"\u003e\n\n**如果这个插件对你有帮助，请给个 Star 支持一下！**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiexian%2Fastrbot_plugin_simple_long_memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiexian%2Fastrbot_plugin_simple_long_memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiexian%2Fastrbot_plugin_simple_long_memory/lists"}