Liquid Loop

Self-Organizing Cognitive Memory for AI Agents — Zero LLM dependency, pure Python implementation of the Liquid Loop theory.

30 秒理解：为什么禁向量？

向量检索没有「成核门槛」——单独一条陈述就能进入检索池，并因为"最新"而胜出。 所以一条噪声 / 幻觉 / 误录入就能改写系统的记忆。 液环要求 ≥2 条一致证据才结晶，单条噪声无法形成记忆。

这句话是可证伪的，有对照实验（同输入流、同种子、baseline 刻意做强）：

注意第三行：最强 baseline 在常规事实更新上已完全追平液环—— 如果你的场景只是"事实会更新"，用向量 + recency + 过滤就够了，不需要液环。 分野只在输入源不可信时出现：向量方案无法区分"真实更新"和"一条噪声"，液环可以。

python3 liquid_core.py                                    # 215 行零依赖内核，看清全部机制
python3 examples/experiments/vector_vs_liquid_drift.py    # 复现上表所有数字

两个脚本纯标准库，无需 pip install，Python 3.9+ 直接跑。 完整论证与液环的成本和适用边界 → WHY_NO_VECTOR.md

核心理念

当前所有 Agent 记忆系统的共同缺陷：依赖外部编辑。

• 图数据库 → 需要 LLM 诊断器做 Split/Merge/Update
• 向量检索 → 需要外部评分+排序
• LLM 摘要 → 需要外部提取+压缩
• 结构化 Schema → 需要外部设计+维护

Liquid Loop 提出第三条路：自组织记忆。

• 不需要外部编辑 → 证据一致性自动驱动结晶
• 不需要检索排序 → 熵值作为天然认知健康指标
• 不需要 LLM 介入管理 → LLM 只接触数据，不管理数据

核心概念

状态判定：

GREEN  (entropy < 0.3)  — 认知健康
YELLOW (0.3 ≤ entropy < 0.6) — 需关注
RED    (entropy ≥ 0.6)  — 需清理

关于 "Entropy" 的语义澄清 — Liquid Entropy Index (LEI)

本项目中的 entropy 是 Liquid Entropy Index (LEI): a system-stability deviation metric, inspired by entropy but NOT equivalent to thermodynamic entropy. 它不是物理熵 S = -k Σ pᵢ log pᵢ，而是对系统状态偏离稳定流形程度的综合度量——由八个可解释分量人工加权而成（锚点漂移 / 冲突密度 / 证据碎片 / 活跃间隔 / 价值衰减 / 锚定强度 + CPE 三维：回顾性衰退 / 策略漂移 / 泛化崩塌）。 代码层函数名保留 calculate()（历史连续性）；文档 / 论文层一律以 LEI 指称，避免与热力学熵混淆。

v0.8 反证轨 + 时间动力学（液态循环核心）

液环 v0.8 从"静态结晶"升级为自调节记忆动力学：记忆不是对象，而是过程。

反证轨（Contradiction Track）

证据可标记与记忆的关系，打破"一致即真"：

from liquid_loop import WorkspaceState

state = WorkspaceState()
a = state.add_anchor("用户偏好", "红还是蓝")
state.add_evidence(a, "用户喜欢红色")          # support (默认)
state.add_evidence(a, "用户喜欢红色")          # 2 次一致 -> 结晶, stability≈0.67
mem = state.memories[0]
state.add_evidence(a, "用户喜欢蓝色",
                   relation="contradiction",    # 冲突证据
                   target_memory_id=mem.id)     # 显式指向被反驳的记忆
# -> mem.stability 降到 ≈0.40（一致增稳 / 冲突降稳）

稳定性公式：stability = support / (support + 2·contradiction + 1)。 contradiction_weight=2.0 使单条冲突的降稳效力 ≈ 两条支持，直接对抗群体幻觉固化。

时间动力学 state.step(dt)

显式演化步（记忆随时间衰减 / 被新证据强化）：

# 无新支持证据时，时间推进使稳定性衰减
state.step(dt=10, decay_rate=0.05)
# M(t+1) = M(t) + reinforcement − decay − contradiction_penalty

• 每条证据权重按 (1−decay_rate)^dt 衰减（无强化则价值流失，下限 0.05）
• 记忆在自上次 step 以来获得新 support 时恢复到固有稳定性（强化）；否则时间衰减且不超过固有上限

实验验证（examples/experiments/，全部 PASS）

python3 examples/experiments/run_all.py                   # E1/E2/E3 → REPORT_v0.8.json
python3 examples/experiments/vector_vs_liquid_drift.py    # E4 向量对照（零依赖，独立可跑）

真实管线版 E4（推荐先看这个）：examples/faithful/faithful_e4.py 用真实 selfspin.LiquidSelfSpin + 真实 workspace.WorkspaceState（非裸内核），验证 "改写 + 噪声输入下的端到端行为"，并演示 selfspin「字符重叠聚类」的盲区边界 （词汇不重叠的同义 → 无法成核 → 事实流失）。stdlib-only、零依赖，直接用任意 python3 跑（无需 venv）：

python3 examples/faithful/faithful_e4.py

快速开始

安装

pip install liquid-loop
# 国内镜像自动加速：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple liquid-loop

3 分钟上手

from liquid_loop import WorkspaceState, load, save, calculate

# 1. 创建/加载工作区
state = WorkspaceState()  # 或 load(Path("."))

# 2. 添加锚点
anchor_id = state.add_anchor("核心使命", "系统的核心目标与约束")

# 3. 注入证据（自动触发：衰减 + 结晶 + 稳定性重算）
state.add_evidence(anchor_id, "用户偏好简洁输出，结论优先")
state.add_evidence(anchor_id, "用户偏好简洁输出，结论优先")  # 2次一致 -> 结晶
state.add_evidence(anchor_id, "用户厌恶过度工程化，够用就行")

# 4. 查看结晶记忆
for m in state.memories:
    print(f"结晶: {m.content[:50]}... (置信度={m.confidence:.2f})")

# 5. 监控认知健康
entropy = calculate(state)
print(f"熵值: {entropy:.4f} → {'🟢GREEN' if entropy < 0.3 else '🟡YELLOW' if entropy < 0.6 else '🔴RED'}")

# 6. 持久化
save(state, Path("."))

CLI 使用

# 初始化工作区（创建 .liquid/state.json）
liquid-loop init

# 添加锚点（支持自动三维分类：密度 / 认知阶段 / 流动性）
liquid-loop anchor_add "项目目标" "完成液环论文与开源"

# 注入证据
liquid-loop evidence_add "项目目标" "已完成 11 轮实验与 4 个实证包"

# 查看状态（含审计链哈希）
liquid-loop status

# 列出所有记忆结晶
liquid-loop memory_list

# 审计：验证链式哈希完整性
liquid-loop audit

# 查看审计日志（最近 20 条）
liquid-loop audit-log --tail 20

# 快照（记录当前认知基线）
liquid-loop snapshot

MESH 集成与 A2A 桥接（已移除）

⚠️ liquid_loop.mesh（多智能体共识协议）与 examples/trae_mesh_mcp（stdio MCP 桥接 demo）已于 v0.7.x 后从发行包移除（commit ac7260e，过度工程化过滤）。相关 API（validate_evidence / compute_cci / cognitive_health / fetch_state）与桥接代码当前不在仓库中；"多 Agent 共享认知"仍属理论目标，未随包发布。

定位：Self-Regulating Memory State Evolution

North-Star 公理（一切代码与论文围绕它校验）：

Liquid Loop is not a memory storage mechanism; it is a self-regulating memory state evolution mechanism.

（液环不是一种记忆存储机制，而是一种自调节的记忆状态演化机制。）

液环的本质不是"AI 意识 / 认知层"，而是一套 agent 系统的自调节持久记忆动力学（Self-Regulating Persistent Memory Dynamics for Agent Systems）。AuditChain + LEI(Entropy) + Memory decay + Contradiction Track 组合成闭环，使记忆从"外部管理"转向"内部自组织"。

边界（防止退化为"智能记忆管理器"）：记忆状态本身是一个演化对象，而非被管理的数据对象。市场已有的"记忆评分 / 自动删除 / 权重调整"范式把记忆当被管理的数据——液环要保护的是 memory homeostasis（记忆稳态）：记忆在变化环境中经 输入→吸收→凝聚→稳定→衰减→重构，自身维持一致性，而非被外部规则调度。

   Input Evidence
        ↓
   Memory State  ←──────────────┐
        ↓                        │
   LEI Evaluation (九维熵)        │
        ↓                        │
   Decay / Reinforcement ────────┘
        ↓
   AuditChain (SHA256 链式追溯)

这比单独的 memory store 更接近一个可被实验检验的动态系统：输入驱动状态、熵评估稳定性、衰减/强化回流状态、审计链保证来源可信。

架构对比

记忆管理光谱：

[外力编辑] ←──────────────── [混合/零LLM检索] ──────────────→ [自组织]
  All-Mem                         Mandol (零LLM检索)              Liquid Loop
  GRAVITY                        CoreMem (检索优化)              (零LLM管理)
  AnchorMem                      MemForest (索引)
  T-Mem, GAM                     HeLa-Mem (联想)
  APEX-MEM, Synthius             DimMem (维度压缩)

Liquid Loop 是唯一完全自组织 + 零 LLM 管理的系统。

基准实验

完整实验数据：experiment/liquid_benchmark_results/

理论来源

• 液环理论 — 飞哥原创，11 轮实验，4 个实证包
• 核心论文 — Liquid Loop: Self-Organizing Cognitive Memory for AI Agents
• 竞品调研 — 2024-2026 Agent Memory 50+ 篇论文全景扫描

项目结构

liquid-loop/
├── liquid_core.py       # ★ 215 行零依赖最小内核（单文件可跑，读它就懂全部机制）
├── WHY_NO_VECTOR.md     # ★ 禁向量的完整论证 + 对照实验数据 + 适用边界
├── liquid_loop/
│   ├── __init__.py      # 公共 API 导出
│   ├── workspace.py     # 核心数据模型 + AuditChain + auto_classify + decay
│   ├── storage.py       # JSON 持久化 + 审计链写入
│   ├── entropy.py       # 九维熵值计算（6 基础 + CPE 三维）
│   └── cli.py           # Click CLI (11 命令)
├── examples/
│   ├── quickstart.py
│   ├── experiments/
│   │   ├── e1_drift.py / e2_recovery.py / e3_conflict.py   # 液环自证实验
│   │   └── vector_vs_liquid_drift.py                        # ★ E4 向量对照（零依赖·核心机制 demo）
│   └── faithful/
│       └── faithful_e4.py   # ★ 真实管线 E4（selfspin→WorkspaceState，零依赖 无污染）
├── tests/
├── pyproject.toml
├── README.md
├── LICENSE
└── CHANGELOG.md

liquid_core.py 与完整版行为一致性已验证：结晶 / 反证 / 共识轨 / step 衰减 四场景 stability 数值完全相同（4/4 PASS）。内核是可信的教学与审计入口， 不是简化到失真的玩具。

开发

git clone https://gitee.com/feixubuke/liquid-loop.git
cd liquid-loop
pip install -e ".[dev]"
pytest -v

路线图

• 多 Agent 液环耦合（liquid_loop.mesh 已移除，见 commit ac7260e）
• [v0.8] 反证轨（Evidence Graph）：Evidence 分 support / contradiction，一致增稳、冲突降稳，驱动 memory stability score（不再"一致即真"）
• [v0.8] 显式时间动力学：M(t+1) = M(t) + reinforcement − decay − contradiction_penalty，让记忆成为"过程"而非"对象"（真正的液态循环）
• [v0.8] 三实验全 PASS：E2 错误记忆恢复 → E3 多 agent 冲突 → E1 长期漂移（见上节）
• [v0.9] 冲突检测 O(g²)→O(d²)：_detect_conflicts 按 content 去重后只对 distinct 内容求两两重叠（d≤g），overlap_cache 复用；语义更纯净（度量不同论点分歧），大规模高频写入性能提升（非正确性变更）
• [v0.9] 液态算法正式落地：时间动力学 / 反证轨 / 双轨成核在 v0.8 已实现并经 E1/E2/E3 三实验背书，v0.9 作为稳定版正式发布（README 顶部 Hero Banner 已上线）
• LoCoMo / LongMemEval 基准对比
• 边缘端部署优化（<50KB）

零向量是液环的硬约束：一致性判定永不引入 embedding / 相似度（这正是液环要替代的方案）。

许可证

MIT License — 详见 LICENSE

致谢

液环理论源自飞哥 2026 年 6-7 月对抗训练与实战项目的 11 轮实证沉淀。 感谢开源社区提供的竞品参考：All-Mem, Mandol, CoreMem, HeLa-Mem 等。

引用

@misc{liquid-loop-2026,
  title={Liquid Loop: Self-Organizing Cognitive Memory for AI Agents},
  author={Fei Ge},
  year={2026},
  url={https://gitee.com/feixubuke/liquid-loop}
}