liquid-loop 0.6.4__tar.gz → 0.7.1__tar.gz

{liquid_loop-0.6.4 → liquid_loop-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: liquid-loop
-Version: 0.6.4
+Version: 0.7.1
 Summary: Self-Organizing Cognitive Memory for AI Agents — Liquid Loop theory implementation
 Author: fishbook0001
 Maintainer: fishbook0001
@@ -72,7 +72,7 @@ Dynamic: license-file
 | **Anchor** 锚点 | 晶种 | 认知关注点，有稳定性值 s ∈ [0,1] |
 | **Evidence** 证据 | 附着粒子 | 锚点下的具体观察，权重指数衰减 w×0.95ᵗ |
 | **Memory** 结晶 | 结晶体 | 2+ 条一致 Evidence 自动凝聚，有置信度 c |
-| **Entropy** 熵值 | 流体无序度 | 八维加权（锚点漂移 / 冲突密度 / 碎片 / 活跃间隔 / 价值衰减 / 锚定强度 / CPE 三维） |
+| **Entropy** 熵值 (LEI) | 流体无序度 | 八维加权（锚点漂移 / 冲突密度 / 碎片 / 活跃间隔 / 价值衰减 / 锚定强度 / CPE 三维） |
 
 **状态判定：**
 ```
@@ -81,6 +81,12 @@ 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** 指称，避免与热力学熵混淆。
+
 ---
 
 ## 快速开始
@@ -93,7 +99,7 @@ pip install liquid-loop
 
 ### 3 分钟上手
 ```python
-from liquid_loop import WorkspaceState, load, save, calculate_entropy
+from liquid_loop import WorkspaceState, load, save, calculate
 
 # 1. 创建/加载工作区
 state = WorkspaceState()  # 或 load(Path("."))
@@ -111,7 +117,7 @@ for m in state.memories:
     print(f"结晶: {m.content[:50]}... (置信度={m.confidence:.2f})")
 
 # 5. 监控认知健康
-entropy = calculate_entropy(state)
+entropy = calculate(state)
 print(f"熵值: {entropy:.4f} → {'🟢GREEN' if entropy < 0.3 else '🟡YELLOW' if entropy < 0.6 else '🔴RED'}")
 
 # 6. 持久化
@@ -147,6 +153,46 @@ 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`。
+
+---
+
+## 定位：Self-Regulating Persistent Memory Dynamics
+
+液环的本质不是"AI 意识"，而是一套 **agent 系统的自调节持久记忆动力学（Self-Regulating Persistent Memory Dynamics for Agent Systems）**。`AuditChain + LEI(Entropy) + Memory decay` 三者组合形成闭环，使记忆从"外部管理"转向"内部自组织"：
+
+```
+   Input Evidence
+        ↓
+   Memory State  ←──────────────┐
+        ↓                        │
+   LEI Evaluation (八维熵)        │
+        ↓                        │
+   Decay / Reinforcement ────────┘
+        ↓
+   AuditChain (SHA256 链式追溯)
+```
+
+这比单独的 memory store 更接近一个可被实验检验的**动态系统**：输入驱动状态、熵评估稳定性、衰减/强化回流状态、审计链保证来源可信。
+
+---
+
 ## 架构对比
 
 ```
@@ -193,7 +239,8 @@ liquid-loop/
 │   ├── __init__.py      # 公共 API 导出
 │   ├── workspace.py     # 核心数据模型 + AuditChain + auto_classify + decay
 │   ├── storage.py       # JSON 持久化 + 审计链写入
-│   ├── entropy.py       # 四维熵值计算
+│   ├── entropy.py       # 八维熵值计算（含 CPE 三维）
+│   ├── mesh/            # MESH v2 多智能体共识协议集成（validate_evidence / compute_cci / ...）
 │   └── cli.py           # Click CLI (11 命令)
 ├── examples/
 │   └── quickstart.py
@@ -219,12 +266,15 @@ pytest -v
 
 ## 路线图
 
-- [ ] 语义一致性结晶（嵌入相似度替代精确匹配）
-- [ ] 多 Agent 液环耦合
-- [ ] LX 扩展：世界模型预测纳入液环
+- [x] 多 Agent 液环耦合（`liquid_loop.mesh` v2 共识协议，2026-07-15 落地）
+- [ ] **[v0.8] 反证轨（Evidence Graph）**：Evidence 分 support / contradiction，一致增稳、冲突降稳，驱动 memory stability score（不再"一致即真"）
+- [ ] **[v0.8] 显式时间动力学**：`M(t+1) = M(t) + reinforcement − decay − contradiction_penalty`，让记忆成为"过程"而非"对象"（真正的液态循环）
+- [ ] **[v0.8] 三实验**：E2 错误记忆恢复（核心）→ E3 多 agent 冲突（mesh 价值）→ E1 长期漂移（压力测试）
 - [ ] LoCoMo / LongMemEval 基准对比
 - [ ] 边缘端部署优化（<50KB）
 
+> 零向量是液环的硬约束：一致性判定永不引入 embedding / 相似度（这正是液环要替代的方案）。
+
 ---
 
 ## 许可证

{liquid_loop-0.6.4 → liquid_loop-0.7.1}/README.md

@@ -33,7 +33,7 @@
 | **Anchor** 锚点 | 晶种 | 认知关注点，有稳定性值 s ∈ [0,1] |
 | **Evidence** 证据 | 附着粒子 | 锚点下的具体观察，权重指数衰减 w×0.95ᵗ |
 | **Memory** 结晶 | 结晶体 | 2+ 条一致 Evidence 自动凝聚，有置信度 c |
-| **Entropy** 熵值 | 流体无序度 | 八维加权（锚点漂移 / 冲突密度 / 碎片 / 活跃间隔 / 价值衰减 / 锚定强度 / CPE 三维） |
+| **Entropy** 熵值 (LEI) | 流体无序度 | 八维加权（锚点漂移 / 冲突密度 / 碎片 / 活跃间隔 / 价值衰减 / 锚定强度 / CPE 三维） |
 
 **状态判定：**
 ```
@@ -42,6 +42,12 @@ 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** 指称，避免与热力学熵混淆。
+
 ---
 
 ## 快速开始
@@ -54,7 +60,7 @@ pip install liquid-loop
 
 ### 3 分钟上手
 ```python
-from liquid_loop import WorkspaceState, load, save, calculate_entropy
+from liquid_loop import WorkspaceState, load, save, calculate
 
 # 1. 创建/加载工作区
 state = WorkspaceState()  # 或 load(Path("."))
@@ -72,7 +78,7 @@ for m in state.memories:
     print(f"结晶: {m.content[:50]}... (置信度={m.confidence:.2f})")
 
 # 5. 监控认知健康
-entropy = calculate_entropy(state)
+entropy = calculate(state)
 print(f"熵值: {entropy:.4f} → {'🟢GREEN' if entropy < 0.3 else '🟡YELLOW' if entropy < 0.6 else '🔴RED'}")
 
 # 6. 持久化
@@ -108,6 +114,46 @@ 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`。
+
+---
+
+## 定位：Self-Regulating Persistent Memory Dynamics
+
+液环的本质不是"AI 意识"，而是一套 **agent 系统的自调节持久记忆动力学（Self-Regulating Persistent Memory Dynamics for Agent Systems）**。`AuditChain + LEI(Entropy) + Memory decay` 三者组合形成闭环，使记忆从"外部管理"转向"内部自组织"：
+
+```
+   Input Evidence
+        ↓
+   Memory State  ←──────────────┐
+        ↓                        │
+   LEI Evaluation (八维熵)        │
+        ↓                        │
+   Decay / Reinforcement ────────┘
+        ↓
+   AuditChain (SHA256 链式追溯)
+```
+
+这比单独的 memory store 更接近一个可被实验检验的**动态系统**：输入驱动状态、熵评估稳定性、衰减/强化回流状态、审计链保证来源可信。
+
+---
+
 ## 架构对比
 
 ```
@@ -154,7 +200,8 @@ liquid-loop/
 │   ├── __init__.py      # 公共 API 导出
 │   ├── workspace.py     # 核心数据模型 + AuditChain + auto_classify + decay
 │   ├── storage.py       # JSON 持久化 + 审计链写入
-│   ├── entropy.py       # 四维熵值计算
+│   ├── entropy.py       # 八维熵值计算（含 CPE 三维）
+│   ├── mesh/            # MESH v2 多智能体共识协议集成（validate_evidence / compute_cci / ...）
 │   └── cli.py           # Click CLI (11 命令)
 ├── examples/
 │   └── quickstart.py
@@ -180,12 +227,15 @@ pytest -v
 
 ## 路线图
 
-- [ ] 语义一致性结晶（嵌入相似度替代精确匹配）
-- [ ] 多 Agent 液环耦合
-- [ ] LX 扩展：世界模型预测纳入液环
+- [x] 多 Agent 液环耦合（`liquid_loop.mesh` v2 共识协议，2026-07-15 落地）
+- [ ] **[v0.8] 反证轨（Evidence Graph）**：Evidence 分 support / contradiction，一致增稳、冲突降稳，驱动 memory stability score（不再"一致即真"）
+- [ ] **[v0.8] 显式时间动力学**：`M(t+1) = M(t) + reinforcement − decay − contradiction_penalty`，让记忆成为"过程"而非"对象"（真正的液态循环）
+- [ ] **[v0.8] 三实验**：E2 错误记忆恢复（核心）→ E3 多 agent 冲突（mesh 价值）→ E1 长期漂移（压力测试）
 - [ ] LoCoMo / LongMemEval 基准对比
 - [ ] 边缘端部署优化（<50KB）
 
+> 零向量是液环的硬约束：一致性判定永不引入 embedding / 相似度（这正是液环要替代的方案）。
+
 ---
 
 ## 许可证

{liquid_loop-0.6.4 → liquid_loop-0.7.1}/liquid_loop/__init__.py

@@ -1,10 +1,10 @@
-"""Liquid Loop — Workspace Cognitive Runtime v0.6.1 (CPE-fused, proactive, rhythmic sampling)"""
-__version__ = "0.6.1"
+"""Liquid Loop — Workspace Cognitive Runtime v0.7.1 (CPE-fused, SEAL dual-opt, dual-track multi-agent, MESH v2 integration)"""
+__version__ = "0.7.1"
 
 from .workspace import (
     WorkspaceState, Anchor, Evidence, Memory, Conflict,
     AuditChain, CPERegularizer, SelfRefineEngine,
     rhythmic_retrieve,
 )
-from .storage import load, save
+from .storage import load, save, locked_state
 from .entropy import calculate, calculate_detail, calculate as calculate_entropy

liquid_loop-0.7.1/liquid_loop/mesh/__init__.py

@@ -0,0 +1,50 @@
+"""
+liquid_loop.mesh — 液环 MESH 进阶版（v2）共识协议集成
+=====================================================
+把"多智能体共识协议规范"从文档落地为可复用代码，作为 liquid-loop 的官方
+MESH 集成层。零向量哲学：一致性判定走结构化精确相等 + 审计链哈希，绝不引入
+任何 embedding / 相似度。
+
+职责（详见 .v2）：
+  - validate_evidence()    agent 侧契约自检（结构化证据 schema）
+  - check_contract()       双向契约合规检查（身份 / 写 / 消费 / 冲突）
+  - compute_cci()          主体间性共识指数（记忆层）
+  - cognitive_health()     统一认知健康仪表盘（CCI / drift / H_e / P_mem）
+  - detect_conflict()      同锚点冲突证据检测
+  - fetch_state()          从 8790 REST /list 拉取当前状态
+  - main()                 连接 8790 打印认知健康报告（CLI）
+
+快速使用：
+    from liquid_loop.mesh import validate_evidence, compute_cci, cognitive_health
+    from liquid_loop.mesh import fetch_state, main
+
+    ok, errs = validate_evidence({"agent_id": "vera", "content": "..."})
+    health = cognitive_health(fetch_state())
+"""
+from .v2 import (
+    REGISTRY,
+    CLAIM_TYPES,
+    SCOPES,
+    Evidence,
+    validate_evidence,
+    check_contract,
+    compute_cci,
+    cognitive_health,
+    detect_conflict,
+    fetch_state,
+    main,
+)
+
+__all__ = [
+    "REGISTRY",
+    "CLAIM_TYPES",
+    "SCOPES",
+    "Evidence",
+    "validate_evidence",
+    "check_contract",
+    "compute_cci",
+    "cognitive_health",
+    "detect_conflict",
+    "fetch_state",
+    "main",
+]

liquid_loop-0.7.1/liquid_loop/mesh/v2.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+liquid_loop_mesh_v2.py — 液环 MESH 进阶版（v2）参考实现
+======================================================
+把"共识协议规范"从文档落地为可复用代码。零向量哲学：一致性判定走
+结构化精确相等 + 审计链哈希，绝不引入任何 embedding / 相似度。
+
+职责：
+  1. validate_evidence()      — agent 侧契约自检（结构化证据 schema）
+  2. check_contract()         — 双向契约合规检查（身份/写/消费/冲突）
+  3. compute_cci()            — 主体间性共识指数（记忆层）
+  4. cognitive_health()       — 统一认知健康仪表盘（CCI / drift / H_e / P_mem）
+  5. detect_conflict()        — 同锚点冲突证据检测
+  6. fetch_state()            — 从 8790 REST /list 拉取当前状态
+
+依赖：标准库 + 可选 liquid_loop（仅类型提示）。可直接 import 使用，
+也可 `python3 liquid_loop_mesh_v2.py` 连 8790 打印健康报告。
+"""
+from __future__ import annotations
+import json
+import sys
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Optional
+
+# ── agent-mesh 注册表（接入 agent 的唯一 id 白名单）──────────────
+REGISTRY = {"workbuddy", "vera", "qwenpaw", "marvis", "parlant-ctrl", "cawpaw", "tabbit", "llama"}
+
+CLAIM_TYPES = {"fact", "conclusion", "preference", "conflict"}
+SCOPES = {"private", "consensus"}
+
+
+# ── 1. 结构化证据 schema 校验 ──────────────────────────────────
+@dataclass
+class Evidence:
+    agent_id: str
+    content: str
+    category: str = "fact"
+    claim_type: str = "fact"
+    value: Optional[float] = None
+    session_id: str = ""
+    prev_hash: str = ""
+    id: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "agent_id": self.agent_id,
+            "content": self.content,
+            "category": self.category,
+            "claim_type": self.claim_type,
+            "value": self.value,
+            "session_id": self.session_id,
+            "prev_hash": self.prev_hash,
+            "id": self.id,
+        }
+
+
+def validate_evidence(ev: dict) -> tuple[bool, list[str]]:
+    """agent 侧契约自检：返回 (ok, 错误列表)。"""
+    errs: list[str] = []
+    if not ev.get("agent_id"):
+        errs.append("agent_id 必填（共用机制要求声明写入者标识）")
+    elif ev["agent_id"] not in REGISTRY:
+        errs.append(f"agent_id '{ev['agent_id']}' 未在 mesh 注册表（禁止匿名污染）")
+    if not ev.get("content"):
+        errs.append("content 必填（一致性比对键）")
+    ct = ev.get("claim_type", "fact")
+    if ct not in CLAIM_TYPES:
+        errs.append(f"claim_type '{ct}' 非法，须为 {sorted(CLAIM_TYPES)}")
+    # content 精确相等判定 → 禁止任何 embedding/相似度
+    if ev.get("content") and not isinstance(ev["content"], str):
+        errs.append("content 必须为精确字符串（零向量一致性比对键）")
+    return (len(errs) == 0, errs)
+
+
+# ── 2. 双向契约合规检查 ────────────────────────────────────────
+def check_contract(agent_id: str, did_recall: bool, wrote_structured: bool) -> tuple[bool, list[str]]:
+    """①身份 ②结构化写 ③主动消费 ④冲突响应(由 detect_conflict 触发)。"""
+    errs: list[str] = []
+    if agent_id not in REGISTRY:
+        errs.append("① 身份未声明/未注册")
+    if not wrote_structured:
+        errs.append("② 未结构化写入（缺 claim_type/session_id/prev_hash）")
+    if not did_recall:
+        errs.append("③ 会话未主动消费 consensus 视图（退化成孤岛）")
+    return (len(errs) == 0, errs)
+
+
+# ── 3. CCI 主体间性共识指数（记忆层）────────────────────────────
+def compute_cci(items: list[dict]) -> dict:
+    """CCI_mem = |consensus| / (|consensus| + |private|)。"""
+    cons = [x for x in items if x.get("scope") == "consensus"]
+    priv = [x for x in items if x.get("scope") == "private"]
+    denom = len(cons) + len(priv)
+    cci = (len(cons) / denom) if denom else 0.0
+    # 共识强度 secondary：平均 contributors 基数
+    strengths = [len(x.get("contributors", [])) for x in cons] or [0]
+    avg_strength = sum(strengths) / len(strengths) if strengths else 0
+    return {
+        "cci": round(cci, 4),
+        "consensus": len(cons),
+        "private": len(priv),
+        "avg_contributors": round(avg_strength, 2),
+    }
+
+
+# ── 4. 统一认知健康仪表盘 ─────────────────────────────────────
+def cognitive_health(items: list[dict], drift_rate: float = 0.0,
+                     H_e: float = 0.0, P_mem: float = 0.0) -> dict:
+    cci = compute_cci(items)
+    evs = [x for x in items if x.get("type") == "evidence"]
+    from collections import Counter
+    by_agent = Counter(x.get("agent_id") for x in evs)
+    return {
+        "CCI": cci["cci"],
+        "consensus_crystals": cci["consensus"],
+        "private_crystals": cci["private"],
+        "drift_rate": drift_rate,
+        "H_e": H_e,
+        "P_mem": P_mem,
+        "total_evidence": len(evs),
+        "agents": dict(by_agent),
+    }
+
+
+# ── 5. 冲突检测 ───────────────────────────────────────────────
+def detect_conflict(items: list[dict]) -> list[dict]:
+    """同锚点下 claim_type=conflict 或同 content 反义 → 标记冲突 agent。"""
+    conflicts = []
+    by_cat = {}
+    for x in items:
+        if x.get("type") in ("evidence", "memory"):
+            by_cat.setdefault(x.get("category", "?"), []).append(x)
+    for cat, recs in by_cat.items():
+        conflict_recs = [r for r in recs if r.get("claim_type") == "conflict"]
+        if conflict_recs:
+            agents = sorted({r.get("agent_id") for r in conflict_recs if r.get("agent_id")})
+            conflicts.append({"anchor": cat, "conflict_agents": agents,
+                              "kind": "explicit_conflict"})
+    return conflicts
+
+
+# ── 6. 从 8790 拉取状态 ───────────────────────────────────────
+def fetch_state(base: str = "http://127.0.0.1:8790") -> list[dict]:
+    req = urllib.request.Request(base + "/list", data=b"{}",
+                                 headers={"Content-Type": "application/json"})
+    with urllib.request.urlopen(req, timeout=5) as r:
+        d = json.load(r)
+    return d if isinstance(d, list) else d.get("result", d.get("items", []))
+
+
+# ── CLI：打印健康报告 ──────────────────────────────────────────
+def main():
+    try:
+        items = fetch_state()
+    except Exception as e:
+        print(f"[ERR] 无法连接 8790: {e}")
+        sys.exit(1)
+    health = cognitive_health(items)
+    print("=== 液环 MESH v2 认知健康仪表盘 ===")
+    for k, v in health.items():
+        print(f"  {k:18}: {v}")
+    conf = detect_conflict(items)
+    if conf:
+        print("\n=== 冲突锚点 ===")
+        for c in conf:
+            print(" ", c)
+    else:
+        print("\n[OK] 无显式冲突")
+
+
+if __name__ == "__main__":
+    main()

{liquid_loop-0.6.4 → liquid_loop-0.7.1}/liquid_loop/storage.py

@@ -36,7 +36,12 @@ def _file_lock(filepath: str, mode: str = "w"):
         finally:
             fcntl.flock(f, fcntl.LOCK_UN)
 
+def _lock_path(workspace_root: Path) -> Path:
+    return _ensure_dir(workspace_root) / "state.lock"
+
+
 def load(workspace_root: Path) -> WorkspaceState:
+    """纯读取，无锁。并发安全由上层 locked_state 上下文保证。"""
     path = _ensure_dir(workspace_root) / STATE_FILE
     if not path.exists():
         return WorkspaceState()
@@ -46,6 +51,7 @@ def load(workspace_root: Path) -> WorkspaceState:
 
 
 def save(state: WorkspaceState, workspace_root: Path):
+    """原子写（temp+rename）：崩溃永不留下半截文件。锁由 locked_state 持有。"""
     state.updated_at = now()
     path = _ensure_dir(workspace_root) / STATE_FILE
     # 审计链：记录并回写哈希
@@ -59,8 +65,28 @@ def save(state: WorkspaceState, workspace_root: Path):
     data = asdict(state)
     # overlap_cache 仅为运行时熵计算缓存，键为 tuple，不可 JSON 序列化，且不具持久价值
     data.pop("overlap_cache", None)
-    with open(path, "w", encoding="utf-8") as f:
+    tmp = path.with_suffix(".tmp")
+    with open(tmp, "w", encoding="utf-8") as f:
         json.dump(data, f, indent=2, ensure_ascii=False)
+        f.flush()
+        os.fsync(f.fileno())
+    os.replace(tmp, path)  # POSIX 原子替换，读端永不看到半截文件
+
+
+@contextmanager
+def locked_state(workspace_root: Path):
+    """单一锁层：排他锁跨 load→modify→save 整段，根除并发丢写(P0)。
+    跨进程安全（fcntl 建议锁）；server 与批量喂入脚本共用同一把锁。"""
+    d = _ensure_dir(workspace_root)
+    lk = open(d / "state.lock", "w")
+    fcntl.flock(lk, fcntl.LOCK_EX)
+    try:
+        st = load(workspace_root)
+        yield st
+        save(st, workspace_root)
+    finally:
+        fcntl.flock(lk, fcntl.LOCK_UN)
+        lk.close()
 
 
 def _from_dict(data: dict) -> WorkspaceState:

{liquid_loop-0.6.4 → liquid_loop-0.7.1}/liquid_loop/workspace.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Optional, List, Dict, Any
@@ -153,6 +155,7 @@ class Evidence:
     weight: float = 1.0
     quality: str = "normal"
     archived: bool = False  # 预算超额冷归档标记（PEEK 落地，零丢失）
+    agent_id: str = ""  # 多智能体共用：写入者标识（共用机制，缺省=legacy/单实例）
 
 
 @dataclass
@@ -162,6 +165,8 @@ class Memory:
     formed_at: str = field(default_factory=now)
     evidence_ids: list[str] = field(default_factory=list)
     confidence: float = 0.0
+    scope: str = "private"  # 结晶来源: private(同 agent≥2一致) / consensus(跨 distinct owner≥2一致)
+    contributors: list[str] = field(default_factory=list)  # 参与成核的 agent_id 列表
 
 
 @dataclass
@@ -243,10 +248,17 @@ class WorkspaceState:
         self.updated_at = now()
         return a
 
-    def add_evidence(self, anchor: str, content: str, quality: float = 1.0) -> Optional[Evidence]:
+    def add_evidence(self, anchor, content: str, quality: float = 1.0, agent_id: str = "",
+                     dedup: bool = False) -> Optional[Evidence]:
         """向指定锚点添加一条证据。
 
         anchor 参数兼容：锚点名称(str) | 锚点ID(str) | Anchor对象
+        agent_id：多智能体共用写入者标识（缺省空=legacy/单实例）
+        dedup：幂等去重开关（默认 False）。
+            - False（默认，核心语义）：同内容可重复写入——"≥2 条一致证据自动结晶"依赖此行为
+              （README quickstart / 双轨成核 / 理论定义）。
+            - True（mesh/API 层显式启用）：同锚点+同内容+同 agent 已存在则复用，防网络重试/高频喂入膨胀。
+              幂等应由 mesh/API 层按需开启，核心模型默认不吞掉"重复观察"这一结晶信号。
         """
         target = None
         if isinstance(anchor, Anchor):
@@ -258,9 +270,14 @@ class WorkspaceState:
                 target = next((a for a in self.anchors if a.id == anchor), None)
         if not target:
             return None
+        # 幂等去重（仅当 dedup=True）：同锚点+同内容+同 agent 已存在则复用
+        if dedup:
+            for ex in self.evidences:
+                if ex.anchor_id == target.id and ex.content == content and ex.agent_id == agent_id:
+                    return ex
         e = Evidence(
             id=uid(), anchor_id=target.id, content=content,
-            quality=quality, timestamp=now(),
+            quality=quality, timestamp=now(), agent_id=agent_id,
         )
         self.evidences.append(e)
         target.evidence_ids.append(e.id)
@@ -289,31 +306,68 @@ class WorkspaceState:
                 e.weight = max(e.weight * 0.95, 0.1)
 
     def _nucleate(self, anchor_id: str):
-        """成核：同锚点下 >= 2 条一致证据形成记忆结晶。
+        """双轨成核（多智能体共用机制）：
+
+        - private 轨：同一 agent_id 下 >= 2 条一致证据 -> scope=private 结晶
+        - consensus 轨：同一 content 被 >= 2 个 distinct agent_id 证据支持 -> scope=consensus 结晶
 
-        复合键判定：查重限定在当前锚点内（(anchor_id, content)），避免跨锚点
-        同 content 证据被错误吞掉或并入同一结晶（P0 跨锚点误结晶修复, v0.6.2）。
+        复合键 (anchor_id, content, scope) 防跨锚点/跨轨污染。
+        兼容 legacy：agent_id 为空视为单实例私有（走 private 轨，contributors=["legacy"]）。
         """
         group = [e for e in self.evidences if e.anchor_id == anchor_id]
         if len(group) < 2:
             return
-        # 本锚点已结晶的 content 集合（复合键判定，杜绝跨锚点污染）
-        crystallized_contents: set[str] = set()
+        # 已结晶键集合（复合键判定，杜绝跨锚点/跨轨污染）
+        crystallized_keys: set = set()
         for m in self.memories:
             for eid in m.evidence_ids:
                 ev = next((e for e in self.evidences if e.id == eid), None)
                 if ev is not None and ev.anchor_id == anchor_id:
-                    crystallized_contents.add(m.content)
+                    crystallized_keys.add((m.content, m.scope))
                     break
-        content_counts = Counter(e.content for e in group)
-        for content, count in content_counts.items():
-            if count >= 2 and content not in crystallized_contents:
-                evidence_ids = [e.id for e in group if e.content == content]
-                confidence = min(count / len(group), 1.0)
+        from collections import defaultdict
+        # ── private 轨：按 agent_id 分组，组内同 content >= 2 ──
+        by_agent: dict = defaultdict(list)
+        for e in group:
+            by_agent[e.agent_id if e.agent_id else "legacy"].append(e)
+        for owner, evs in by_agent.items():
+            content_counts = Counter(e.content for e in evs)
+            for content, count in content_counts.items():
+                if count >= 2 and (content, "private") not in crystallized_keys:
+                    evidence_ids = [e.id for e in evs if e.content == content]
+                    confidence = min(count / len(evs), 1.0)
+                    self.memories.append(Memory(
+                        content=content,
+                        evidence_ids=evidence_ids,
+                        confidence=confidence,
+                        scope="private",
+                        contributors=[owner],
+                    ))
+        # ── consensus 轨：跨 distinct owner 同 content >= 2 ──
+        owners_by_content: dict = defaultdict(set)
+        for e in group:
+            if not e.agent_id:
+                continue  # legacy 不参与共识轨（无法跨主体）
+            owners_by_content[e.content].add(e.agent_id)
+        for content, owners in owners_by_content.items():
+            if len(owners) < 2:
+                continue
+            # 已存在的共识结晶：把新一致方并入 contributors（动态扩展，支撑三方+ CCI 计量）
+            existing = next((m for m in self.memories if m.scope == "consensus" and m.content == content), None)
+            if existing is not None:
+                merged = set(existing.contributors) | owners
+                if merged != set(existing.contributors):
+                    existing.contributors = sorted(merged)
+                continue
+            if (content, "consensus") not in crystallized_keys:
+                evidence_ids = [e.id for e in group if e.content == content and e.agent_id in owners]
+                confidence = min(len(owners) / 2.0, 1.0)
                 self.memories.append(Memory(
                     content=content,
                     evidence_ids=evidence_ids,
                     confidence=confidence,
+                    scope="consensus",
+                    contributors=sorted(owners),
                 ))
         # 成核后触发自动描述回流（仅当描述为空）
         self._auto_describe_anchor(anchor_id)

{liquid_loop-0.6.4 → liquid_loop-0.7.1}/liquid_loop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: liquid-loop
-Version: 0.6.4
+Version: 0.7.1
 Summary: Self-Organizing Cognitive Memory for AI Agents — Liquid Loop theory implementation
 Author: fishbook0001
 Maintainer: fishbook0001
@@ -72,7 +72,7 @@ Dynamic: license-file
 | **Anchor** 锚点 | 晶种 | 认知关注点，有稳定性值 s ∈ [0,1] |
 | **Evidence** 证据 | 附着粒子 | 锚点下的具体观察，权重指数衰减 w×0.95ᵗ |
 | **Memory** 结晶 | 结晶体 | 2+ 条一致 Evidence 自动凝聚，有置信度 c |
-| **Entropy** 熵值 | 流体无序度 | 八维加权（锚点漂移 / 冲突密度 / 碎片 / 活跃间隔 / 价值衰减 / 锚定强度 / CPE 三维） |
+| **Entropy** 熵值 (LEI) | 流体无序度 | 八维加权（锚点漂移 / 冲突密度 / 碎片 / 活跃间隔 / 价值衰减 / 锚定强度 / CPE 三维） |
 
 **状态判定：**
 ```
@@ -81,6 +81,12 @@ 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** 指称，避免与热力学熵混淆。
+
 ---
 
 ## 快速开始
@@ -93,7 +99,7 @@ pip install liquid-loop
 
 ### 3 分钟上手
 ```python
-from liquid_loop import WorkspaceState, load, save, calculate_entropy
+from liquid_loop import WorkspaceState, load, save, calculate
 
 # 1. 创建/加载工作区
 state = WorkspaceState()  # 或 load(Path("."))
@@ -111,7 +117,7 @@ for m in state.memories:
     print(f"结晶: {m.content[:50]}... (置信度={m.confidence:.2f})")
 
 # 5. 监控认知健康
-entropy = calculate_entropy(state)
+entropy = calculate(state)
 print(f"熵值: {entropy:.4f} → {'🟢GREEN' if entropy < 0.3 else '🟡YELLOW' if entropy < 0.6 else '🔴RED'}")
 
 # 6. 持久化
@@ -147,6 +153,46 @@ 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`。
+
+---
+
+## 定位：Self-Regulating Persistent Memory Dynamics
+
+液环的本质不是"AI 意识"，而是一套 **agent 系统的自调节持久记忆动力学（Self-Regulating Persistent Memory Dynamics for Agent Systems）**。`AuditChain + LEI(Entropy) + Memory decay` 三者组合形成闭环，使记忆从"外部管理"转向"内部自组织"：
+
+```
+   Input Evidence
+        ↓
+   Memory State  ←──────────────┐
+        ↓                        │
+   LEI Evaluation (八维熵)        │
+        ↓                        │
+   Decay / Reinforcement ────────┘
+        ↓
+   AuditChain (SHA256 链式追溯)
+```
+
+这比单独的 memory store 更接近一个可被实验检验的**动态系统**：输入驱动状态、熵评估稳定性、衰减/强化回流状态、审计链保证来源可信。
+
+---
+
 ## 架构对比
 
 ```
@@ -193,7 +239,8 @@ liquid-loop/
 │   ├── __init__.py      # 公共 API 导出
 │   ├── workspace.py     # 核心数据模型 + AuditChain + auto_classify + decay
 │   ├── storage.py       # JSON 持久化 + 审计链写入
-│   ├── entropy.py       # 四维熵值计算
+│   ├── entropy.py       # 八维熵值计算（含 CPE 三维）
+│   ├── mesh/            # MESH v2 多智能体共识协议集成（validate_evidence / compute_cci / ...）
 │   └── cli.py           # Click CLI (11 命令)
 ├── examples/
 │   └── quickstart.py
@@ -219,12 +266,15 @@ pytest -v
 
 ## 路线图
 
-- [ ] 语义一致性结晶（嵌入相似度替代精确匹配）
-- [ ] 多 Agent 液环耦合
-- [ ] LX 扩展：世界模型预测纳入液环
+- [x] 多 Agent 液环耦合（`liquid_loop.mesh` v2 共识协议，2026-07-15 落地）
+- [ ] **[v0.8] 反证轨（Evidence Graph）**：Evidence 分 support / contradiction，一致增稳、冲突降稳，驱动 memory stability score（不再"一致即真"）
+- [ ] **[v0.8] 显式时间动力学**：`M(t+1) = M(t) + reinforcement − decay − contradiction_penalty`，让记忆成为"过程"而非"对象"（真正的液态循环）
+- [ ] **[v0.8] 三实验**：E2 错误记忆恢复（核心）→ E3 多 agent 冲突（mesh 价值）→ E1 长期漂移（压力测试）
 - [ ] LoCoMo / LongMemEval 基准对比
 - [ ] 边缘端部署优化（<50KB）
 
+> 零向量是液环的硬约束：一致性判定永不引入 embedding / 相似度（这正是液环要替代的方案）。
+
 ---
 
 ## 许可证

{liquid_loop-0.6.4 → liquid_loop-0.7.1}/liquid_loop.egg-info/SOURCES.txt

@@ -14,7 +14,11 @@ liquid_loop.egg-info/dependency_links.txt
 liquid_loop.egg-info/entry_points.txt
 liquid_loop.egg-info/requires.txt
 liquid_loop.egg-info/top_level.txt
+liquid_loop/mesh/__init__.py
+liquid_loop/mesh/v2.py
+tests/test_consensus_expansion.py
 tests/test_entropy.py
+tests/test_nucleate_dual_track.py
 tests/test_peek_seal.py
 tests/test_seal_persistence.py
 tests/test_self_evolve.py

{liquid_loop-0.6.4 → liquid_loop-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "liquid-loop"
-version = "0.6.4"
+version = "0.7.1"
 description = "Self-Organizing Cognitive Memory for AI Agents — Liquid Loop theory implementation"
 readme = "README.md"
 license = {text = "MIT"}

liquid_loop-0.7.1/tests/test_consensus_expansion.py

@@ -0,0 +1,45 @@
+"""共识结晶 contributors 随新一致方动态扩展（三方+ CCI 计量）。"""
+from liquid_loop import WorkspaceState
+from liquid_loop.workspace import Anchor, Evidence, Memory
+
+
+def _add(st, name, content, agent_id):
+    a = next((x for x in st.anchors if x.name == name), None)
+    if a is None:
+        a = st.add_anchor(name)
+    e = Evidence(content=content, anchor_id=a.id, agent_id=agent_id)
+    st.add_evidence(a, content, agent_id=agent_id)
+    return a
+
+
+def test_consensus_expands_with_third_agent():
+    st = WorkspaceState()
+    # qwenpaw + vera 先达成共识
+    _add(st, "液环", "液环是零向量记忆", "qwenpaw")
+    _add(st, "液环", "液环是零向量记忆", "qwenpaw")  # qwenpaw >=2 -> private
+    _add(st, "液环", "液环是零向量记忆", "vera")      # +vera -> consensus[qwenpaw,vera]
+    cons = next(m for m in st.memories if m.scope == "consensus")
+    assert cons.contributors == ["qwenpaw", "vera"], cons.contributors
+    # marvis 也写同内容 -> 应并入三方共识
+    _add(st, "液环", "液环是零向量记忆", "marvis")
+    cons = next(m for m in st.memories if m.scope == "consensus")
+    assert cons.contributors == ["marvis", "qwenpaw", "vera"], cons.contributors
+
+
+def test_consensus_no_duplicate_on_repeat():
+    st = WorkspaceState()
+    _add(st, "fact", "X", "a")
+    _add(st, "fact", "X", "a")          # private[a]
+    _add(st, "fact", "X", "b")          # consensus[a,b]
+    _add(st, "fact", "X", "b")          # b 重复，不应扩
+    cons = next(m for m in st.memories if m.scope == "consensus")
+    assert cons.contributors == ["a", "b"], cons.contributors
+
+
+def test_private_untouched_by_consensus_expansion():
+    st = WorkspaceState()
+    _add(st, "fact", "Y", "qwenpaw")
+    _add(st, "fact", "Y", "qwenpaw")    # private[qwenpaw]
+    _add(st, "fact", "Y", "vera")       # consensus
+    priv = [m for m in st.memories if m.scope == "private"]
+    assert priv and priv[0].contributors == ["qwenpaw"], priv

liquid_loop-0.7.1/tests/test_nucleate_dual_track.py

@@ -0,0 +1,115 @@
+"""双轨成核 + 防污染回归测试（多智能体共用机制）。
+
+锁住行为：
+  - private 轨：同一 agent_id 内 >= 2 一致证据 -> scope=private
+  - consensus 轨：同一 content 跨 >= 2 distinct agent_id -> scope=consensus
+  - 防污染：不同 agent 不互相成私有晶；跨锚点同 content 不合并；复合键 (anchor,content,scope)
+"""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from liquid_loop.workspace import WorkspaceState
+
+
+def _add(st, name, content, agent_id=""):
+    a = next((x for x in st.anchors if x.name == name), None)
+    if a is None:
+        a = st.add_anchor(name)
+    return st.add_evidence(a, content, agent_id=agent_id)
+
+
+def test_private_nucleation_same_agent():
+    st = WorkspaceState()
+    _add(st, "topic", "液环是零向量记忆", agent_id="qwenpaw")
+    _add(st, "topic", "液环是零向量记忆", agent_id="qwenpaw")
+    priv = [m for m in st.memories if m.scope == "private"]
+    cons = [m for m in st.memories if m.scope == "consensus"]
+    assert len(priv) == 1
+    assert priv[0].contributors == ["qwenpaw"]
+    assert len(cons) == 0
+
+
+def test_private_isolation_diff_agents():
+    st = WorkspaceState()
+    _add(st, "topic", "同一结论", agent_id="qwenpaw")
+    _add(st, "topic", "同一结论", agent_id="vera")
+    # 各 agent 内仅 1 条 -> 不 privately 成核
+    assert all(m.scope != "private" for m in st.memories)
+    # 但跨 2 distinct owner -> consensus 成核
+    cons = [m for m in st.memories if m.scope == "consensus"]
+    assert len(cons) == 1
+    assert set(cons[0].contributors) == {"qwenpaw", "vera"}
+
+
+def test_consensus_requires_distinct_owner():
+    st = WorkspaceState()
+    _add(st, "topic", "共识结论", agent_id="qwenpaw")
+    _add(st, "topic", "共识结论", agent_id="qwenpaw")  # 同 owner 重复
+    # 同 owner 2 条 -> private，但不该有 consensus（只有 1 个 owner）
+    cons = [m for m in st.memories if m.scope == "consensus"]
+    assert len(cons) == 0
+    priv = [m for m in st.memories if m.scope == "private"]
+    assert len(priv) == 1
+
+
+def test_cross_anchor_no_pollution():
+    st = WorkspaceState()
+    _add(st, "A", "X", agent_id="qwenpaw")
+    _add(st, "A", "X", agent_id="qwenpaw")
+    _add(st, "B", "X", agent_id="qwenpaw")
+    _add(st, "B", "X", agent_id="qwenpaw")
+    # 两个锚点各成 1 个 private 晶，不合并
+    priv = [m for m in st.memories if m.scope == "private"]
+    assert len(priv) == 2
+
+
+def test_legacy_compat_no_agent_id():
+    st = WorkspaceState()
+    _add(st, "topic", "legacy 内容", agent_id="")
+    _add(st, "topic", "legacy 内容", agent_id="")
+    priv = [m for m in st.memories if m.scope == "private"]
+    assert len(priv) == 1
+    assert priv[0].contributors == ["legacy"]
+
+
+def test_dual_track_coexist():
+    st = WorkspaceState()
+    # 私有：qwenpaw 内 2 条独有结论
+    _add(st, "T", "qwenpaw 私有结论", agent_id="qwenpaw")
+    _add(st, "T", "qwenpaw 私有结论", agent_id="qwenpaw")
+    # 共识：qwenpaw + vera 各 1 条共享结论
+    _add(st, "T", "共享结论", agent_id="qwenpaw")
+    _add(st, "T", "共享结论", agent_id="vera")
+    priv = [m for m in st.memories if m.scope == "private"]
+    cons = [m for m in st.memories if m.scope == "consensus"]
+    assert len(priv) == 1 and priv[0].contributors == ["qwenpaw"]
+    assert len(cons) == 1 and set(cons[0].contributors) == {"qwenpaw", "vera"}
+
+
+def test_no_pollution_between_agents_private():
+    st = WorkspaceState()
+    _add(st, "T", "结论A", agent_id="qwenpaw")
+    _add(st, "T", "结论A", agent_id="qwenpaw")
+    _add(st, "T", "结论A", agent_id="vera")  # vera 只有 1 条 -> 不成私有
+    priv = [m for m in st.memories if m.scope == "private"]
+    cons = [m for m in st.memories if m.scope == "consensus"]
+    # qwenpaw 私有 1 晶；vera 仅 1 条不足私有；二者合计 2 distinct owner -> consensus 1 晶
+    assert len(priv) == 1 and priv[0].contributors == ["qwenpaw"]
+    assert len(cons) == 1 and set(cons[0].contributors) == {"qwenpaw", "vera"}
+
+
+def test_storage_roundtrip_agent_id_scope(tmp_path):
+    """持久化往返：agent_id / scope / contributors 必须无损保存加载。"""
+    from liquid_loop import storage
+    st = WorkspaceState()
+    _add(st, "T", "X", agent_id="qwenpaw")
+    _add(st, "T", "X", agent_id="qwenpaw")
+    storage.save(st, tmp_path)
+    st2 = storage.load(tmp_path)
+    assert len(st2.memories) == 1
+    m = st2.memories[0]
+    assert m.scope == "private"
+    assert m.contributors == ["qwenpaw"]
+    assert st2.evidences[0].agent_id == "qwenpaw"