amrita_plugin_memory

Amrita Harness 记忆增强插件 — 双层架构：表层 Function Calling 记忆工具 + 底层常驻推理循环 Agent。

表层 — LLM 对话中按需调用 5 个记忆工具（读写删改列），基于 ChromaDB 语义检索。 底层 — 后台 Agent 定时自动扫描、去重、合并、压缩记忆库，基于 Core Agent 框架 + Harness 模式复用 ChatObject。

双层架构

flowchart TB
    subgraph Surface["表层：Long-Term Memory Tools"]
        S_LLM["对话 LLM"] -->|"write_memory"| S_Write["写入记忆"]
        S_LLM -->|"read_memory"| S_Read["语义检索"]
        S_LLM -->|"update/delete/list"| S_Mut["更新 / 删除 / 列表"]
        S_Write --> ChromaDB[("ChromaDB<br/>向量数据库")]
        S_Read --> ChromaDB
        S_Mut --> ChromaDB
    end

    subgraph Subconscious["底层：Subconscious Reasoning Loop"]
        APScheduler["APScheduler<br/>定时触发"] --> Runner["SubconsciousRunner"]
        Runner --> ChatObject["ChatObject<br/>(Harness 容器)"]
        ChatObject --> WF["Workflow 管线"]
        WF --> LM["LIMITING_MEMORY<br/>Core MemoryLimiter"]
        LM --> Build["BUILD_MESSAGE"]
        Build --> Init["STRATEGY_INIT"]
        Init --> AgentLoop["ReAct Agent Loop<br/>WHILE(SINGLE_STRATEGY_CALL)"]
        AgentLoop -->|"工具调用"| STools["subconscious_* 工具"]
        STools --> ChromaDB
        AgentLoop -->|"subconscious_iter_stop"| APScheduler
    end

    Surface -.->|"共享 ChromaDB"| Subconscious
    Runner -->|"持久化状态"| CachedRepo["CachedUserDataRepository<br/>uid=user_00000000"]
    Runner -->|"usage 统计"| Insights["InsightsModel<br/>全局 Token 统计"]

Harness 模式

SubconsciousRunner 不自己管理推理循环，而是将 ChatObject 作为数据容器，注入自定义 SubconsciousBackend + Core ReActAgentStrategy，通过替换 _workflow / _interpreter 复用完整的 Core Agent 管线：

LOAD_STATE → JINJA2_RENDER → LIMITING_MEMORY → BUILD_MESSAGE → STRATEGY_INIT
  → AGENT_ENTRY → WHILE(SINGLE_STRATEGY_CALL).ACTION(REACT_COUNTER)

LIMITING_MEMORY 在 Agent Loop 之前运行 Core MemoryLimiter：消息截断 → token 限制 → 自动生成摘要。摘要通过 Core Jinja2 模板 <SUMMARY> 标签注入 prompt。

暂停时 dump_interpreter()，恢复时 rebase_context()，毫秒级断点续推理。

技术栈

功能

表层：长期记忆

底层：常驻推理循环

工具

表层工具（tools.py）

LLM 在对话中按需调用，受 scope 分区隔离：

潜意识工具（rethinking/tools.py）

仅供 Subconscious Agent 使用，不暴露给对话 LLM：

配置

config/amrita_plugin_memory/config.toml

# 记忆过期
short_term_expiry_days = 3
long_term_expiry_days = 30
permanent_expiry_days = 365
per_session_memory_limit = 50

# 常驻推理循环
[subconscious]
enabled = false               # 是否启用
experimental = true           # 实验性标注
target_user_id = ""           # 目标用户 ID（为空则不启用）
allowed_tools = []            # 额外可用工具
max_iterations = 10           # 单轮 ReAct 最大步数
loop_detect_threshold = 3     # 连续同工具触发警告阈值
initial_delay_seconds = 60    # 启动后首轮延迟
default_interval_seconds = 600# LLM 未指定时默认间隔
pause_on_user_chat = true     # 用户聊天时自动暂停
pause_wakeup_min_seconds = 180# 暂停后最小唤醒延迟
pause_wakeup_max_seconds = 480# 暂停后最大唤醒延迟
prompt_file = "subconscious_prompt.txt"
enable_memory_compress = true # 启用 MemoryLimiter 上下文压缩
allow_send_to_user = false    # 允许 Agent 主动发消息
memory_warn_threshold = 100   # ChromaDB 超此数量注入压缩提示
max_abstracts = 5             # 摘要滑动窗口大小

提示词模板

两个 Jinja2 模板文件位于 config/amrita_plugin_memory/：

subconscious_prompt.txt — Agent 系统提示词（由 prompt_file 配置指定）

subconscious_send_prompt.txt — 主动消息生成模板

环境变量（.env）

安装

ambot plugin install amrita_plugin_memory

前置：Python 3.11+ / AmritaBot 实例 / Ollama 或 OpenAI 嵌入服务 / ChromaDB。

开发

uv sync                       # 安装依赖
ruff format . && ruff check . # 格式化 + 检查
pyright                       # 类型检查