liquid-loop 0.1.1

Self-Organizing Cognitive Memory for AI Agents — Liquid Loop theory implementation

Liquid Loop

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

---

核心理念

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

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

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

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

---

核心概念

概念	物理隐喻	作用
Anchor 锚点	晶种	认知关注点，有稳定性值 s ∈ [0,1]
Evidence 证据	附着粒子	锚点下的具体观察，权重指数衰减 w×0.95ᵗ
Memory 结晶	结晶体	2+ 条一致 Evidence 自动凝聚，有置信度 c
Entropy 熵值	流体无序度	四维加权：drift×0.25 + conflict×0.25 + fragmentation×0.25 + gap×0.25

状态判定：

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

---

快速开始

安装

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_entropy

# 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_entropy(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 认知状态                          │
# ├──────────┬──────┬────────┬────────┬────────┬──┤
# │ 锚点     │ 证据 │ 结晶   │ 冲突   │ 熵值   │  │
# ├──────────┼──────┼────────┼────────┼────────┼──┤
# │ 项目目标 │ 3    │ 1      │ 0      │ 0.2760 │ 🟢│
# ╰──────────┴──────┴────────┴────────┴────────┴──╯
# 锚点稳定性: 项目目标=0.88

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

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

---

架构对比

记忆管理光谱：

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

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

---

基准实验

实验	核心发现	关键指标
E1 认知负荷	100 证据 → 13 结晶，熵值维持 GREEN	熵值 0.035→0.194，单条 0.01ms
E2 噪声鲁棒性	0%/20%/50% 噪声下熵值完全相同	天然抗噪（精确匹配机制）
E3 遗忘曲线	5 轮衰减后权重保留 83.2%	平滑指数衰减，无灾难性遗忘
E4 扩展性	1000 证据延迟 0.179ms	500x 快于 LLM 调用

完整实验数据：experiment/liquid_benchmark_results/

---

理论来源

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

---

项目结构

liquid-loop/
├── liquid_loop/
│   ├── __init__.py      # 公共 API 导出
│   ├── workspace.py     # 核心数据模型
│   ├── storage.py       # JSON 持久化
│   ├── entropy.py       # 四维熵值计算
│   └── cli.py           # Click CLI (9 命令)
├── examples/
│   └── quickstart.py
├── tests/               # 待补充
├── pyproject.toml
├── README.md
├── LICENSE
└── CHANGELOG.md

---

开发

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

---

路线图

• 语义一致性结晶（嵌入相似度替代精确匹配）
• 多 Agent 液环耦合
• LX 扩展：世界模型预测纳入液环
• LoCoMo / LongMemEval 基准对比
• 边缘端部署优化（<50KB）

---

许可证

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}
}