Metadata-Version: 2.4
Name: liquid-loop
Version: 0.9.3
Summary: Self-Organizing Cognitive Memory for AI Agents — Liquid Loop theory implementation
Author: fishbook0001
Maintainer: fishbook0001
License: MIT
Project-URL: Homepage, https://github.com/fishbook0001/liquid-loop
Project-URL: Repository, https://github.com/fishbook0001/liquid-loop
Project-URL: Documentation, https://github.com/fishbook0001/liquid-loop#readme
Project-URL: Issues, https://github.com/fishbook0001/liquid-loop/issues
Project-URL: Changelog, https://github.com/fishbook0001/liquid-loop/blob/main/CHANGELOG.md
Keywords: agent-memory,cognitive-architecture,self-organizing,liquid-loop,entropy,ai-agents,memory-management
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.4.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Dynamic: license-file

# Liquid Loop

![Liquid Loop Hero Banner](docs/assets/06-hero-banner.jpg)

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

[![PyPI](https://img.shields.io/pypi/v/liquid-loop.svg)](https://pypi.org/project/liquid-loop/)
[![Python](https://img.shields.io/pypi/pyversions/liquid-loop.svg)](https://pypi.org/project/liquid-loop/)
[![License](https://img.shields.io/pypi/l/liquid-loop.svg)](https://opensource.org/licenses/MIT)
[![Gitee](https://img.shields.io/badge/Gitee-Mirror-orange)](https://gitee.com/feixubuke/liquid-loop)

---

## 核心理念

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

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

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

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

---

## 核心概念

| 概念 | 物理隐喻 | 作用 |
|------|---------|------|
| **Anchor** 锚点 | 晶种 | 认知关注点，有稳定性值 s ∈ [0,1] |
| **Evidence** 证据 | 附着粒子 | 锚点下的具体观察，权重指数衰减 w×0.95ᵗ |
| **Memory** 结晶 | 结晶体 | 2+ 条一致 Evidence 自动凝聚，有置信度 c |
| **Entropy** 熵值 (LEI) | 流体无序度 | 八维加权（锚点漂移 / 冲突密度 / 碎片 / 活跃间隔 / 价值衰减 / 锚定强度 / CPE 三维） |

**状态判定：**
```
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）

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

```python
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)`

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

```python
# 无新支持证据时，时间推进使稳定性衰减
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）

| 实验 | 问题 | 结论 |
|------|------|------|
| **E2 错误记忆恢复** | 能否主动遗忘错误并恢复？ | 80%错误+20%真实 → 反证轨使错误 stability 0.67→0.30、正确升至 0.69 主导 ✅ |
| **E3 多 Agent 冲突** | mesh v2 能否形成稳定共享认知？ | A support / B contradiction / C noise → 核心 claim 进入受争议稳定区(0.40)，噪声隔离 ✅ |
| **E1 长期漂移** | 1000 轮随机注入是否收敛？ | 300 轮压测 → 48 记忆(≤池×3)、plateau、LEI GREEN、avg_stab 0.80 ✅ |

```bash
python3 examples/experiments/run_all.py   # 生成 REPORT_v0.8.json
```

---

## 快速开始

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

### 3 分钟上手
```python
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 使用
```bash
# 初始化工作区（创建 .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 集成（多智能体共识）

液环从 v0.7.0 起内置官方 MESH 集成 `liquid_loop.mesh`，把"多智能体共识协议"落地为可复用代码，作为 agent-mesh 节点的标准接入层。

```python
from liquid_loop.mesh import validate_evidence, compute_cci, cognitive_health, fetch_state

# agent 写入前契约自检（零向量：content 必须精确字符串，禁 embedding）
ok, errs = validate_evidence({"agent_id": "vera", "content": "用户偏好简洁输出"})

# 从 8790 拉取记忆状态，算主体间性共识指数 CCI
items = fetch_state("http://127.0.0.1:8790")
health = cognitive_health(items)
print(health["CCI"], health["consensus_crystals"])
```

零向量哲学：一致性判定走**结构化精确相等 + 审计链哈希**，绝不引入任何 embedding / 相似度。规范详见 `mesh/liquid_loop_mesh_v2_spec.md`。

---

## 固态 A2A 通道（任意 MCP 客户端接入）

把共享液环后端（地址由环境变量 `LIQUID_LOOP_BASE` 决定，默认 `http://127.0.0.1:8790`）封装成一个
**stdio JSON-RPC 的 MCP server**，让任意支持 Model Context Protocol 的客户端（本例以 TRAE SOLO CN 演示）
**原生读写同一份共享记忆**——这就是多 agent 间的固化（solidified）A2A 通道。

> 后端说明：桥接只做协议翻译，**不内置 8790 服务**；后端由你自己部署（运行你自己的液环 SSE 服务，
> 把地址通过 `LIQUID_LOOP_BASE` 传给桥接）。成核 / 共识 / 审计链全部由后端按液环理论执行。

```bash
# 在你的 MCP 客户端注册该 server（以 TRAE 为例；其 code CLI 路径随安装而异，请替换为你的路径）
export PY=python3                                    # 任意 Python 3.10+ 解释器
export SVR=examples/trae_mesh_mcp/mcp_server.py      # 本仓库内路径
export LIQUID_LOOP_BASE=http://127.0.0.1:8790        # 改成你的后端地址
"<path-to-your-trae-code-cli>" \
  --add-mcp '{"servers":{"liquidloop-mesh":{"command":"'"$PY"'","args":["'"$SVR"'"]}}}'
```

桥接暴露 `liquidloop_remember` / `liquidloop_recall` / `liquidloop_metrics` 三个工具（写入**必须声明 `agent_id`**）。
压测脚本与运维说明见 [`examples/trae_mesh_mcp/README.md`](examples/trae_mesh_mcp/README.md)
（直连 + 经桥双路并发，零丢写 / 共识幂等 / 崩溃恢复三关全 PASS；所有路径走环境变量，适配不同部署拓扑）。

---

## 定位：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 管理的系统。
```

---

## 基准实验

| 实验 | 核心发现 | 关键指标 |
|------|----------|----------|
| **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](docs/液环论文框架.md)
- **竞品调研** — 2024-2026 Agent Memory 50+ 篇论文全景扫描

---

## 项目结构

```
liquid-loop/
├── liquid_loop/
│   ├── __init__.py      # 公共 API 导出
│   ├── workspace.py     # 核心数据模型 + AuditChain + auto_classify + decay
│   ├── storage.py       # JSON 持久化 + 审计链写入
│   ├── entropy.py       # 八维熵值计算（含 CPE 三维）
│   ├── mesh/            # MESH v2 多智能体共识协议集成（validate_evidence / compute_cci / ...）
│   └── cli.py           # Click CLI (11 命令)
├── examples/
│   └── quickstart.py
├── tests/               # 待补充
├── pyproject.toml
├── README.md
├── LICENSE
└── CHANGELOG.md
```

---

## 开发

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

---

## 路线图

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

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

---

## 许可证

MIT License — 详见 [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}
> }
> ```
