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

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

版本 1.0.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 压缩	吸收式 MLA + INT4 = 28.4x (270KB→7.6KB/token)	✓ L40S 实测
Top-K 保护	关键块 16bit + 其余 4bit = 0/100 翻转	✓ 实测
分层组织	Sector(16)-Block(256)-Module(1024) 硬件对齐	✓
Aura 遗忘	S(t)=I·2^(-t/τ) 指数遗忘 + 访问增强	✓
脑+手	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 实测" --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 压缩 28.4x", ["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 服务

关键技术 (实测数据)

吸收式 MLA: 只缓存 576 维潜在向量 (512 kv_lora + 64 k_pe), 不展开 KV
- 270KB → 30.4KB (8.9x) → INT8 15.2KB → INT4 7.6KB (28.4x)
Top-K 自适应精度保护: 路由层已知 Top-K → 关键块 16bit + 其余 4bit
- 1bit 符号补偿 × (17/50 翻转) / 排序保护 × (29/100) / Top-K 块 16bit ✓ (0/100)
Sector-Block-Module: 16 token=Sector, 16 Sector=Block(256), 4 Block=Module(1024)
- 结构做骨架 / 价值做决策 / 粒度分层
Aura 遗忘曲线: S(t) = I·2^(-t/τ) + log2(access+1)×0.1
注意力分数 ≠ 任务重要性 (3-Agent 讨论室 v3 产出):
- Agent 场景 L2 验证必须用任务感知权重 (工具名/参数键/错误码), 非注意力分数
- 蒙特卡洛模拟: 95.22% 概率按注意力采样误删首轮关键 token

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

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

维度	语义压缩 (MemoryDirector)	物理压缩 (AbsorbedMLA)
管什么	哪些 token 值得留	留下的 token 怎么存得小
机制	LLM 语义判断驱逐	576维潜在向量 + INT4
决策者	DeepSeek (懂语义)	量化器 (确定性)
压缩比	~3.2x (闲聊剔除)	28.4x (270KB→7.6KB)
失败历史	数值启发式全被证伪	浮点精度经 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。这是存储层面的瘦身。

相乘: 原本存 100 个 Token 要占 100 × 270KB = 27MB, 现在只存 31 × 7.6KB ≈ 235KB — 算下来确实是 ~115 倍。

100 tokens × 270KB = 27MB   (原始)
      ↓ 语义压缩 3.2x (砍数量: 100 → 31)
31 tokens × 270KB = 8.4MB   (内容筛选后)
      ↓ 物理压缩 28.4x (砍体积: 270KB → 7.6KB)
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	270KB→7.6KB/token
总压缩	~113x	17.7MB → 159KB

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

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

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

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

与物理压缩的叠加公式

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

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

许可证

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