agentframe/README.md

# 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. 安装

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

### 2. 配置

```bash
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 使用

```bash
# 摄入知识
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

```bash
python3 -m agentframe.api.server 8090
```

```bash
# 创建会话
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 库方式

```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 服务
```

##  关键技术 (实测数据)

1. **吸收式 MLA**: 只缓存 576 维潜在向量 (512 kv_lora + 64 k_pe), 不展开 KV
   - 270KB → 30.4KB (8.9x) → INT8 15.2KB → **INT4 7.6KB (28.4x)**
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维潜在向量 + 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 的决策：

```json
{
  "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
```

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

##  许可证

GPL-3.0 © Cloud LTE Studio

---

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