ljsysfurry/AgentFrame-v4

AgentFrame — Agent 专用上下文保持框架

脑 = DeepSeek · 手 = 工具执行 · 记忆 = 四层上下文保持

版本 4.6.0 · GPL-3.0 · Cloud LTE Studio

---

架构

┌─────────────────────────────────────────────────────────┐
│                    ContextEngine 引擎                    │
│  ┌─────────┐  ┌──────────────┐  ┌───────────┐  ┌──────┐ │
│  │ L1 认知  │→ │ L2 路由      │→ │ L3 存储    │→ │ L4 物理│ │
│  │ MetaCog │  │LandmarkRouter│  │AbsorbedMLA│  │KVPager│ │
│  │任务分解  │  │ landmark检索 │  │ 吸收式MLA  │  │三级换页│ │
│  │信息缺口  │  │ 分层软max    │  │ INT4量化   │  │遗忘曲线│ │
│  └─────────┘  └──────────────┘  └───────────┘  └──────┘ │
│         ↕ 检索指令      ↕ 摘要        ↕ 压缩块   ↕ 热度    │
│  ┌──────────────────────────────────────────────────┐   │
│  │  LLM Provider (DeepSeek, 支持 thinking+工具循环)  │   │
│  │  Embedding Provider (哈希/API, 文本→向量)          │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

核心能力

能力	说明	验证状态
KV 压缩	真 INT4 打包: 576维→288B q4+64B scales = 29.1x (cos 0.998)	✓ 有测试 + L40S 实测
Top-K 保护	路由命中块 16bit 高精度, 其余 4bit; latent 无损检索	✓ L40S 实测 0/20 翻转
Top-K 保护	关键块 16bit + 其余 4bit = 0/100 翻转	✓ 实测 (独立实验, 未接入主流程)
分层组织	Sector(16)-Block(256)-Module(1024) 硬件对齐	⚠️ 设计未接入
Aura 遗忘	S(t)=I·2^(-t/τ) 指数遗忘 + 访问增强	✓ 有测试
LFRU 滞回	历史热块信用折减驱逐分数, 防抖动 (colibrì #441/#497)	✓ 有测试
Couple 预取	跨轮共现预取: 检索到 A 后预取常与 A 共现的 B (colibrì couple)	✓ 有测试
KV 增量持久化	每轮 append 不重写全量, crash-safe 坏行跳过 (colibrì kv_persist)	✓ 有测试
checksum 防损坏	每行 content checksum, 篡改/静默损坏整行跳过 (memory-system 启发)	✓ 有测试
前缀复用	相同前缀 query 复用上次检索, 保持热块 (colibrì kv_prefix)	✓ 有测试
认知层接线	directive.required_chunks 参与路由加权 (任务标签→命中提升)	✓ 有测试
L0/L1/L2 分层摘要	写入时生成三层, 读取按需展开 (OpenViking 启发)	✓ 有测试
脑+手	function calling 工具循环, Agent 自验证代码	✓ 有测试 + 安全拦截
多会话	每会话独立引擎, 状态可持久化	✓

快速开始

1. 安装

pip install -e /root/.openclaw/workspace/agentframe
# 或直接用 (无需安装):
export PYTHONPATH=/root/.openclaw/workspace

2. 配置

export AGENTFRAME_API_KEY="sk-xxx"          # DeepSeek key
export AGENTFRAME_MODEL="deepseek-v4-pro"    # 主模型
export AGENTFRAME_FAST_MODEL="deepseek-v4-flash"
export AGENTFRAME_PORT=8090

# 或生成配置文件
python3 -m agentframe.cli config

3. CLI 使用

# 摄入知识
python3 -m agentframe.cli ingest "KV 压缩 28.4x L40S 实测" --tags "kv"

# 查询 (带 DeepSeek 生成)
python3 -m agentframe.cli ask "KV 压缩多少倍？"

# 状态 / 遗忘
python3 -m agentframe.cli stats
python3 -m agentframe.cli forget --threshold 0.1

# 离线演示 (无需 API key)
python3 -m agentframe.cli demo

4. REST API

python3 -m agentframe.api.server 8090

# 创建会话
SID=$(curl -s -X POST http://localhost:8090/v1/sessions | jq -r .session_id)

# 摄入知识
curl -X POST http://localhost:8090/v1/sessions/$SID/ingest \
  -H "Content-Type: application/json" \
  -d '{"text":"吸收式 MLA 缓存 576 维潜在向量","tags":["method"]}'

# 查询+生成
curl -X POST http://localhost:8090/v1/sessions/$SID/ask \
  -H "Content-Type: application/json" \
  -d '{"query":"MLA 怎么压缩 KV？","chat":true}'

# 带工具循环查询 (Agent 可执行代码验证)
curl -X POST http://localhost:8090/v1/sessions/$SID/ask_hands \
  -H "Content-Type: application/json" \
  -d '{"query":"验证 dict 合并操作符 | 的语义"}'

# 状态 / 遗忘 / 持久化
curl http://localhost:8090/v1/sessions/$SID/stats
curl -X POST http://localhost:8090/v1/sessions/$SID/forget -d '{"threshold":0.1}'
curl -X POST http://localhost:8090/v1/sessions/$SID/save

5. Python 库方式

from agentframe.config import AgentFrameConfig
from agentframe.core.engine import ContextEngine

cfg = AgentFrameConfig.from_env()
eng = ContextEngine(cfg)

eng.ingest("AgentFrame KV 压缩设计", ["kv"])
result = eng.ask("KV 压缩多少倍？")
print(result.answer)          # DeepSeek 回答
print(result.retrieved)       # 检索到的知识块
eng.save("/tmp/state.json")   # 持久化

项目结构

agentframe/
├── __init__.py          # 版本 + 导出
├── config.py            # 配置系统 (env/JSON)
├── core/
│   ├── quad.py          # 四层核心 (KV/分层/路由/分页/认知)
│   └── engine.py        # ContextEngine 主引擎
├── llm/                 # LLM Provider (deepseek/mock)
├── embed/               # Embedding Provider (hash/api)
├── memory/              # 持久化 (JSON 快照)
├── api/server.py        # REST API v1 (多会话)
├── cli.py               # 命令行工具
├── tests/               # 核心测试 (离线)
└── deploy/              # systemd 服务

关键技术 (实测数据)

1. 吸收式 MLA + 真 INT4 打包: 只缓存 576 维潜在向量 (512 kv_lora + 64 k_pe), 不展开 KV
   • 270KB → 30.4KB (8.9x) → INT4 打包 352B/层 (29.1x) — 对齐 L40S 真实推理实测 (DeepSeek-V2-Lite 15.7B, 28.4x)
   • 对称量化 + per-channel scale + nibble 打包 (colibrì quant.h 移植), 往返余弦相似度 0.998
2. Top-K 自适应精度保护 (实测, 未接入主流程): 路由层已知 Top-K → 关键块 16bit + 其余 4bit
   • 1bit 符号补偿 × (17/50 翻转) / 排序保护 × (29/100) / Top-K 块 16bit ✓ (0/100)
3. Sector-Block-Module (设计, 未接入): 16 token=Sector, 16 Sector=Block(256), 4 Block=Module(1024)
   • 结构做骨架 / 价值做决策 / 粒度分层
4. Aura 遗忘曲线: S(t) = I·2^(-t/τ) + log2(access+1)×0.1
5. 注意力分数 ≠ 任务重要性 (3-Agent 讨论室 v3 产出):
   • Agent 场景 L2 验证必须用任务感知权重 (工具名/参数键/错误码), 非注意力分数
   • 蒙特卡洛模拟: 95.22% 概率按注意力采样误删首轮关键 token

语义压缩 vs 物理压缩 (双轨压缩体系)

AgentFrame 的压缩不是单一技术，而是两个正交维度的叠加——一个管「内容」，一个管「体积」：

维度	语义压缩 (MemoryDirector)	物理压缩 (AbsorbedMLA)
管什么	哪些 token 值得留	留下的 token 怎么存得小
机制	LLM 语义判断驱逐	576维潜在向量 + 量化
决策者	DeepSeek (懂语义)	量化器 (确定性)
压缩比	~3.2x (闲聊剔除, 实测)	28.4x (L40S 实测)
失败历史	数值启发式全被证伪	浮点精度经 Top-K 保护
能否叠加	正交, 相乘	正交, 相乘

为什么物理压缩管不了「内容」

物理压缩（INT4/INT8/低秩）只能把每个 token 的字节数变小，但闲聊 token 本身就该删——"今天天气不错"压缩 35 倍依然是垃圾。

语义压缩在源头解决问题：模型判断这段对话值不值得存，从根上减少 token 数量。两者相乘才是真正的总压缩。

相乘的本质 (100 Token 例子)

语义压缩 (3.2x) — 砍的是数量: 原本要存 100 个 Token 的上下文, LLM 判断后只保留 31 个。这是内容层面的筛选。

物理压缩 (28.4x) — 砍的是体积: 这 31 个 Token 的 KV Cache, 原本占 270KB, 通过 INT4 量化 + MLA, 硬塞进 7.6KB (L40S 实测)。这是存储层面的瘦身。

相乘: 原本存 100 个 Token 要占 100 × 270KB = 27MB, 现在只存 31 × 7.6KB ≈ 235KB — 算下来是 ~115 倍 (物理侧基于 L40S 实测值)。

100 tokens × 270KB = 27MB   (原始)
      ↓ 语义压缩 3.2x (砍数量: 100 → 31)
31 tokens × 270KB = 8.4MB   (内容筛选后)
      ↓ 物理压缩 28.4x (砍体积: 270KB → 7.6KB, L40S 实测)
31 tokens × 7.6KB ≈ 235KB   (存储瘦身后)
      = ~115x 总压缩

实测数据 (真实决策)

输入一段 67 token 的对话（含 4 条关键信息 + 2 条闲聊）：

用户: 我的生产服务器是 98.142.241.130，SSH 端口 44123。
      项目代码在 /root/.openclaw/workspace，数据库 MySQL 库名 ljsys_db。
      今天天气不错，中午吃了面。

MemoryDirector 的决策：

{
  "remember": [
    "生产服务器IP: 98.142.241.130",
    "SSH端口: 44123",
    "项目代码路径: /root/.openclaw/workspace",
    "MySQL数据库名: ljsys_db"
  ],
  "forget": ["今天天气不错", "中午吃了面"],
  "promote_importance": 0.8
}

指标	数值	说明
输入	67 tokens	含关键信息+闲聊
语义保留	21 tokens	4 条关键信息
语义压缩	3.2x	闲聊被模型自动剔除
物理压缩	28.4x	L40S 实测 270KB→7.6KB/token
总压缩	~113x	17.7MB → 159KB

语义压缩的安全意识 (意外收获)

实测中模型自主拒绝记录密码：

"密码不宜存储" — 模型自主涌现安全意识 (非硬编码规则)

场景	模型决策	正确性
域名+密码+路径+闲聊	✓ 记域名/路径, 拒绝记密码, 忘天气	100%
重申已有信息	✓ 去重, 0 条重复入库	100%
纯闲聊	✓ 全忘, 不浪费缓存	100%

与物理压缩的叠加公式

总压缩 = 语义压缩 × 物理压缩
       = (输入token / 保留token) × (原始字节 / 压缩字节)
       ≈ 3.2 × 28.4 (28.4x 为 L40S 实测)
       ≈ 113x

结论: 物理压缩是「省空间的放大器」，语义压缩是「减内容的过滤器」——先滤后压，缺一不可。

---

Changelog

v4.6.0 (2026-08-20) — L0/L1/L2 分层摘要 (OpenViking 启发)

新增

• TieredSummarizer (core/tiers.py): 每个知识块写入时生成三层摘要
  • L0 (~40 字符): 一句话速览, 快速相关性检查
  • L1 (≤5 条关键子句): 概述, 规划用
  • L2: 完整原文, 按需读取
• ask()/ask_with_hands() 上下文改为分层构建: 【知识速览 L0】→【详情概述 L1】, 结构化且省 token
• 零额外 LLM 成本: 确定性启发式 (句切分 + 关键词提取), 与双轨压缩正交 (语义×物理×分层)

测试: 核心测试 21 项 (+test_tiered_summarization / test_tiers_in_engine)

v4.5.1 (2026-08-20) — checksum 防静默损坏

新增 (memory-system 协议启发)

• IncrementalKVStore 每行 content checksum: MD5 前 8 位, append 时写入, load 时验证
  • 篡改/静默损坏的行整行跳过 — 杜绝 "corruption is silent and permanent"
  • 旧格式兼容: 无 checksum 的历史行仍接受, 新写入全部带校验

测试: 核心测试 19 项 (+test_checksum_protection: 篡改检测 + 旧格式兼容)

v4.5.0 (2026-08-19) — 认知层指令接线

新增

• directive.required_chunks 参与检索: 认知层按标签匹配的"任务需要"块, 在路由打分时加权 (boost_weight=0.5), 任务需求真正影响命中排序 (之前构建后丢弃)
• LandmarkRouter.route() 新增 boost_chunks/boost_weight 参数

验证: 无 boost Top5=[4,0,1,2,3] → 有 boost Top5=[0,2,4,1,3] (method 标签块被提升)

测试: 核心测试 18 项 (+test_directive_boost)

v4.4.1 (2026-08-19) — 死代码清理 + 配置修复

修复

• vram_limit_mb/ram_limit_mb 配置真实传入 KVPager (之前 QuadLayerAgent 用默认值, 配置改不生效)

清理 (删除 6 处死代码)

• gqa_group_select / analyze_gap / rollback_compensate / addr_to_token / module_range
• 保留 two_stage_evict (讨论室设计的驱逐方案, 有思想价值, 待接入)

测试: 核心测试 17 项 + 配置生效验证

v4.4.0 (2026-08-19) — Top-K 保护 + 无损检索 (L40S 实测驱动)

动机: L40S 真实模型实测发现 — INT4 打包余弦相似度 0.9952 极高, 但 Top-8 检索翻转率 95% (量化误差虽小, 足以翻转接近竞争的候选排名)。

修复

• latent 存原始无损 float32 (不再存 INT4 解包值): 路由摘要/检索不受量化影响
• protect_topk 接入主流程 (colibrì #441 落地): ask() 路由命中块标记 16bit 高精度 (size 1152B), 其余保持 4bit (352B)
• q4/scales 真 INT4 打包保持: 持久化压缩 29.1x 不变 (存储与检索解耦)
• storage_stats(): 混合精度统计 (protected 比例)

L40S 实测验证 (DeepSeek-V2-Lite 15.7B MLA 真实 KV)

• latent 无损: max_diff=0.00 ✅
• 引擎 vs 原始基准 Top-8 翻转率: 0/20 (0%) ✅ (修复前 95%)
• Top-K 保护激活: 88/100 块 16bit
• 对照: INT4 解包路径 9/10 翻转 (证明保护必要性)

测试: 核心测试 17 项 (+test_topk_protection)

v4.3.0 (2026-08-18) — KV 增量持久化 + 前缀复用

新增

• IncrementalKVStore (移植 colibrì kv_persist.h): 每轮 ingest 新 chunk 追加一行 JSON, 不重写全量快照; 行级独立 = crash-safe (坏行跳过); enable_incremental() 开启, load_incremental() 重启恢复
• 查询前缀复用 (移植 colibrì kv_prefix.h): 新 query 与上一条共享 ≥70% 前缀 → 直接复用上次检索结果 (跳过重新路由) + 保持热块; _prefix_hits 统计
• engine.ingest() 自动 append 到增量日志

测试: 核心测试 16 项 (+test_incremental_persist / test_prefix_reuse / test_incremental_engine)

v4.2.0 (2026-08-18) — 真 INT4 打包 (28.4x 落地)

新增

• 真 INT4 打包存储 (移植 colibrì quant.h pack_int4): 对称量化 (absmax/7) + per-channel scale + nibble 打包
  • 576 维 latent → 288B q4 + 64B scales = 352B/块 (原 float32 2304B)
  • 每 token 27 层 9.28KB → 29.1x 真实压缩 (对齐 L40S 实测 28.4x)
  • 往返精度: 余弦相似度 0.9979
• ReversibleQuantizer.quantize_int4()/dequant_int4(): 打包/解包接口
• CompressedKV 新增 q4/scales 字段: 真实存储 + save/load 持久化
• n_ch 默认 32→16 (每通道 36 维, 压缩比与精度平衡)

测试: 核心测试 11 项 (+test_int4_packing: 往返精度 cos>0.99 + 压缩比>25x)

v4.1.0 (2026-08-18) — Couple 跨轮共现预取

新增

• CouplePrefetcher (移植 colibrì couple_prefetch): 学习跨轮检索共现表 (检索到 A 后下一轮往往检索 B), 运行时预测下轮所需块
• KVPager.prefetch(): 预测块从 disk 提升到 RAM 温层 (不占 VRAM 热层); RAM 满时用 LFRU 有效分数驱逐最冷块腾位
• ask() 主流程接线: 每轮检索后 record + predict + prefetch
• MemoryConfig.couple_k (默认 8, 对应 colibrì COUPLE_K)

测试: 核心测试 10 项 (+test_couple_prefetch: 学习/预测/提升/腾位)

v4.0.0 (2026-08-18) — LFRU 滞回 + 安全加固

新增

• LFRU 滞回驱逐 (吸收 colibrì #441/#497): 历史峰值热度 (max_heat) 作为信用分折减驱逐分数, 曾热过的块获得保护; 信用随时间衰减 (每 2 半衰期折半), 完全冷透后照常驱逐
• effective_eviction_score(): LFRU 打分接口
• API Bearer token 认证: 配置 AGENTFRAME_API_TOKEN 后全端点校验 (除 /health); 未配置仅本机回环可访问
• 工具执行安全防护: 危险模式黑名单 (rm -rf/shutdown/反弹shell/读密钥等) + 4096 字符长度上限
• 请求体上限 2MB

修复

• forget() 内存计数泄漏 (删块同步扣减 vram_used/ram_used)
• memory_bytes() 重复乘 n_layers 错误
• 新摄入知识 heat 设置无效 (place 加 force_hot, 新块优先进 VRAM)
• summaries 反序列化类型漂移 (list→tuple)
• dim 迷惑写法 → store.DIM; ask_with_hands 命名清理

测试: 核心测试 9 项 (新增 LFRU 滞回 / 工具安全 / API 认证)

v3.0.0-preview — 整合 DeepSeek Harness + dsh 插件

• 四层上下文保持 (认知×路由×存储×物理) + MemoryDirector 自主记忆 + 脑手一体

---

来源与致谢 (Credits)

AgentFrame 的部分设计与实现借鉴了以下开源项目，特此致谢：

🐦 colibrì (JustVugg/colibri, Apache-2.0)

colibrì 是用纯 C 在消费级硬件上推理 MoE 大模型的推理引擎（GLM-5.2 744B / 25GB 内存）。AgentFrame 从中移植/借鉴了以下技术：

AgentFrame 模块	来源	说明
ReversibleQuantizer.quantize_int4/dequant_int4	c/quant.h pack_int4	真 INT4 打包: 对称量化 (absmax/7) + per-channel scale + nibble 打包 (v+8)|((v1+8)<<4)
KVPager.effective_eviction_score (LFRU 滞回)	#441/#497 LFRU eviction guard	历史峰值热度 (max_heat) 信用折减驱逐分数, 防高频块反复横跳
CouplePrefetcher	couple_prefetch + .coli_pairs	跨轮共现预取: 检索到 A 后预测常与 A 共现的 B
IncrementalKVStore	c/kv_persist.h	KV 增量追加持久化, 行级 crash-safe, 重启恢复不用重算
查询前缀复用 _prefix_reuse	c/kv_prefix.h	相同前缀 prompt 跳过重复处理, 保持热状态

📚 memory-system (HeiCha1231414/memory-system, MIT)

memory-system 是长期运行 AI Agent 的记忆持久化协议。AgentFrame 借鉴了：

AgentFrame 模块	来源	说明
IncrementalKVStore checksum 校验	备份 + 校验和验证规则	每行 content checksum (MD5), 篡改/静默损坏整行跳过, 杜绝 silent corruption

🧭 OpenViking (volcengine/OpenViking, AGPL-3.0)

OpenViking 是字节开源的 Agent 上下文数据库 (viking:// 虚拟文件系统 + 分层加载)。AgentFrame 借鉴了：

AgentFrame 模块	来源	说明
TieredSummarizer (L0/L1/L2)	分层加载 L0 abstract / L1 overview / L2 details	写入时生成三层摘要, 读取时按任务深度加载, 省 token

注: AgentFrame 采用确定性启发式实现 (零额外 LLM 调用), 非代码复制。

🧠 DeepSeek-V2 MLA (deepseek-ai)

• 吸收式 MLA 缓存概念 (只存 576 维潜在向量 512 kv_lora + 64 k_pe, 不展开 KV) 源自 DeepSeek-V2 论文架构。
• 28.4x 压缩比实测基于 DeepSeek-V2-Lite-Chat (15.7B) 在 L40S 上的真实推理验证。

🌱 Project-Aura

• ForgettingCurve 遗忘曲线公式 S(t) = I·2^(-t/τ) 源自 Project-Aura 项目。

---

许可证

AgentFrame 本体: GPL-3.0 © Cloud LTE Studio

移植代码许可说明:

• colibrì (Apache-2.0) → 移植部分保持 Apache-2.0 兼容 (GPL-3.0 与 Apache-2.0 兼容)
• memory-system (MIT) → 借鉴思想, 非代码复制
• DeepSeek-V2 / Project-Aura → 仅借鉴论文/思想

---

AgentFrame · 脑手一体 · 上下文永不丢失