README.md

---
language:
  - zh
  - en
license: gpl-3.0
tags:
  - agent
  - kv-cache
  - compression
  - memory-management
  - deepseek
  - autonomous-agent
---

# AgentFrame v2 — 自主记忆 Agent 框架

**脑 = DeepSeek · 手 = 工具执行 · 记忆 = 模型自主管理**

> v2 核心升级: **MemoryDirector 自主记忆** — 模型自己决定记什么、忘什么
> 存储层仍保持 35.6x KV 压缩 (吸收式 MLA + INT4, L40S 实测)

---

## 🆕 v2 新特性: 模型自主记忆 (MemoryDirector)

传统 KV 压缩靠**数值启发式**驱逐 (L2范数/Δh/注意力入度) — 全部被反例证伪, 因为它们不懂语义。
v2 让 **LLM 自己当驱逐决策器**: 每轮对话后分析"什么值得记, 什么该撇了"。

### 实测效果

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

**惊喜**: 模型自主涌现安全意识 — "密码不宜存储", 拒绝把密码写入记忆 (非硬编码规则)。

### 压缩比 (三层叠加)

```
输入对话 67 tokens (4条关键信息 + 2条闲聊)
  ↓ ① 语义蒸馏 (自主记忆): 3.2x   模型剔除闲聊, 只留关键
  ↓ ② KV 物理压缩 (MLA+INT4): 35.6x  270KB→7.6KB/token (L40S实测)
  ↓ ③ 总压缩: ~113x (17.7MB → 159KB)
```

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

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

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

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

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

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

### 相乘的本质 (100 Token 例子)

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

**物理压缩 (35.6x) — 砍的是体积**: 这 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   (内容筛选后)
      ↓ 物理压缩 35.6x (砍体积: 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** | 闲聊被模型自动剔除 |
| 物理压缩 | 35.6x | 270KB→7.6KB/token |
| **总压缩** | **~113x** | 17.7MB → 159KB |

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

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

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

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

### 与物理压缩的叠加公式

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

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

## 🏗️ 架构

```
┌─────────────────────────────────────────────┐
│             ContextEngine 引擎               │
│  ┌────────┐ ┌──────────┐ ┌────────┐ ┌─────┐ │
│  │L1 认知  │→│L2 路由    │→│L3 存储  │→│L4 物理│ │
│  │MetaCog │ │Landmark  │ │Absorbed│ │Pager│ │
│  │任务分解 │ │检索top-k  │ │MLA压缩  │ │换页  │ │
│  └────────┘ └──────────┘ └────────┘ └─────┘ │
│         ↕           ↕           ↕        ↕  │
│  ┌───────────────────────────────────────┐   │
│  │  MemoryDirector (v2): 模型自主记/忘     │   │
│  │  LLM Provider (DeepSeek, thinking+工具) │   │
│  │  Embedding (哈希/API, 文本→向量)         │   │
│  └───────────────────────────────────────┘   │
└─────────────────────────────────────────────┘
```

## 🚀 快速开始

```bash
pip install -e agentframe/
export AGENTFRAME_API_KEY="sk-xxx"
```

### CLI
```bash
python3 -m agentframe.cli demo                  # 离线演示
python3 -m agentframe.cli ingest "知识" --tags kv
python3 -m agentframe.cli ask "问题"
```

### Python
```python
from agentframe.config import AgentFrameConfig
from agentframe.core.engine import ContextEngine

eng = ContextEngine(AgentFrameConfig.from_env())
r = eng.ask_autopilot("我的服务器 IP 是 98.142.241.130, SSH 端口 44123")
print(r.meta["memory_decision"])   # 自主记忆决策: 记住/遗忘/重要性
```

### REST API
```bash
python3 -m agentframe.api.server 8090
# POST /v1/sessions
# POST /v1/sessions/<sid>/ask         查询
# POST /v1/sessions/<sid>/autopilot   自主记忆决策
# POST /v1/sessions/<sid>/ingest      摄入
# POST /v1/sessions/<sid>/forget      遗忘
```

## 📁 结构

```
agentframe/
├── config.py          # 配置 (env/JSON)
├── core/
│   ├── quad.py        # 四层核心 (KV压缩/分层/路由/遗忘)
│   └── engine.py      # ContextEngine + MemoryDirector
├── llm/               # DeepSeek Provider (thinking+工具循环)
├── embed/             # 哈希/API 嵌入
├── memory/            # JSON 快照持久化
├── api/               # REST API v1
└── cli.py             # 命令行
```

## 🔬 底层技术 (实测)

1. **吸收式 MLA**: 576维潜在向量, 270KB→7.6KB/token = **35.6x** (L40S)
2. **Top-K 精度保护**: 关键块16bit+其余4bit = **0/100翻转**
3. **Sector-Block-Module**: 16/256/1024 分层硬件对齐
4. **Aura 遗忘曲线**: S(t)=I·2^(-t/τ) + log2(access+1)×0.1
5. **MemoryDirector**: LLM 语义判断驱逐 (替代被证伪的数值启发式)

## 📜 License

GPL-3.0 © Cloud LTE Studio

*AgentFrame v2 · 模型自主记忆 · 上下文永不丢失*