yekeyu-666/ultron-memory

ultron-memory

ultron-memory 是一个轻量、可本地部署的 Python 组件，用于构建反馈驱动的行为记忆与 Skill 自进化能力。

它把用户反馈沉淀为可复用的规则、护栏、事实和偏好，使用词法/语义混合检索注入后续 Agent 上下文，并为每次变更保留不可变版本与来源记录。

注意：本项目改变的是 Agent 的外部行为上下文，不会训练模型参数，也不会让模型发生参数级“自学习”。宿主仍负责主 Agent Loop、工具、权限和模型调用。

特性

• 反馈进化：从下一轮用户反馈中抽取至多一个候选，并由 Maintainer 决定 add、merge 或 discard。
• 四类记忆：rule、guardrail、fact、preference 分开存储、检索和注入。
• 混合检索：SQLite FTS5/BM25-lite 词法检索 + 可选 embedding 语义检索，通过 RRF（Reciprocal Rank Fusion）融合排序。
• 版本与审计：每个语义变更生成 immutable version，记录 parent、provenance、决策和使用统计。
• 可回滚：明确负反馈或多个独立硬失败可触发回滚；冲突来源保留，不物理删除历史。
• 可评测：从 provenance 生成 replay 样本，支持程序规则和可选 LLM Judge，并对比演化前后版本。
• 隐私优先：默认只持久化有界、脱敏的 pending evidence；凭据不会主动写入存储。
• 无运行时依赖：使用 Python 标准库和 SQLite，支持 Python 3.10 及以上版本。

安装与快速验证

项目要求 Python 3.10 及以上版本（Python 3.9 不支持本项目使用的 dataclass slots）。推荐在项目目录创建独立虚拟环境；如果本机命令名不是 python3.11，请替换为任意可用的 Python 3.10+ 解释器：

python3.11 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python examples/evolution_demo.py

如果本地 Python/SQLite 提供 FTS5，组件会使用 SQLite FTS5；否则自动退回内置的 BM25-lite 风格词法评分器。单实例约 1 万条记录以内不需要向量数据库。

最小集成

宿主只需要提供模型回调；embedding 回调是可选的。未配置 embedding 回调时，记忆会以 bm25 状态正常落库并通过 BM25/FTS 检索；只有已经配置的 embedding 回调调用失败时，新候选才会进入 awaiting_embedding，待服务恢复后重试。

from ultron_memory import EvolutionMemory

memory = EvolutionMemory(
    storage_dir="./.ultron-memory",
    namespace="my-project",
    side_query=side_query,  # async (system_prompt, JSON_payload) -> JSON 字符串
    embed=embed,            # async (text) -> list[float]，可选
)

memory.record_turn({
    "conversation_id": "c1",
    "user": "修改 API",
    "assistant": "API 已修改。",
})
await memory.observe_feedback("c1", "每次修改 API 都要更新并运行测试")
retrieval = await memory.retrieve(
    "修改订单 API",
    top_k=3,
    conversation_id="c1",
)
memory.record_outcome("c1", "tests_passed", metadata={"command": "pytest"})
report = await memory.evaluate()
paths = memory.export_skills("./exported-skills")
memory.close()

在真实 Harness 中，应将 retrieval.prompt_context 注入主模型的 system context，并把实际采用的版本传给 record_outcome()。完整生命周期示例见 examples/minimal_harness.py 和 UltronMemoryAdapter。