AgentFS 深度研究：把整个 Agent 的状态装进一个 SQLite 文件

> GitHub: https://github.com/tursodatabase/agentfs

> 博客: https://turso.tech/blog/agentfs

> 公司: Turso（SQLite 云数据库公司）

> 研究时间: 2026-03-19

🎯 一句话版本

AgentFS 是一个 Agent 专用文件系统，把 Agent 的所有状态（文件、配置、操作日志）存进一个 SQLite 文件。 就像给 Agent 一个"存档"——可以快照、回滚、复制到别的机器、用 SQL 查询任何历史操作。

🤔 要解决什么问题？

AI Agent 是不可预测的。它可能：

• 做出你没想到的决策
• 调用你没预期的 API
• 创建你不知道的文件
• 进入你没测试过的状态

你需要的不是限制 Agent 能做什么（那太死板了），而是事后能看到 Agent 做了什么。

现有方案的问题：

• 数据库存状态 + 日志系统存操作 + 文件系统存文件 → 状态碎片化
• 沙箱环境可能没有持久化文件系统
• 持久卷在规模化运维时很痛苦

AgentFS 的答案：一切都在一个 SQLite 文件里。

🏗️ 架构设计

三个核心接口

┌─────────────────────────────────────────┐
│           AgentFS (一个 .db 文件)          │
├─────────────────────────────────────────┤
│  1. Filesystem  │  POSIX-like 虚拟文件系统  │
│                 │  文件/目录 CRUD           │
├─────────────────────────────────────────┤
│  2. Key-Value   │  Agent 状态和上下文       │
│                 │  set/get/delete          │
├─────────────────────────────────────────┤
│  3. Tool Calls  │  操作审计追踪            │
│                 │  时间线、状态、耗时        │
└─────────────────────────────────────────┘

使用示例

# 初始化
agentfs init my-agent
# → .agentfs/my-agent.db

# 查看文件
agentfs fs ls my-agent
agentfs fs cat my-agent hello.txt

# 查看操作时间线
agentfs timeline my-agent
# ID  TOOL          STATUS   DURATION  STARTED
# 4   execute_code  pending  --        09:44:20
# 3   api_call      error    300ms     09:44:15
# 2   read_file     success  50ms      09:44:10

# FUSE 挂载（Linux）/ NFS 挂载（macOS）
agentfs mount my-agent ./mnt
echo "hello" > ./mnt/hello.txt

# 沙箱运行
agentfs run /bin/bash
# Agent 的文件系统挂载在 /agent/

SDK

import { AgentFS } from 'agentfs-sdk';

const agent = await AgentFS.open({ id: 'my-agent' });

// KV 操作
await agent.kv.set('user:preferences', { theme: 'dark' });
const prefs = await agent.kv.get('user:preferences');

// 文件操作
await agent.fs.writeFile('/output/report.pdf', pdfBuffer);
const files = await agent.fs.readdir('/output');

// 工具调用追踪
await agent.tools.record(
  'web_search',
  startTime, endTime,
  { query: 'AI' },
  { results: [...] }
);

🎯 三大核心优势

1. 可审计 — SQL 查询一切

-- 查看所有失败的工具调用
SELECT * FROM tool_calls WHERE status = 'error';

-- 最近1小时的文件变更
SELECT * FROM files WHERE modified > datetime('now', '-1 hour');

-- Agent 决策路径分析
SELECT tool, input, output, duration 
FROM tool_calls ORDER BY started;

2. 可快照 — 复制一个文件

# 快照当前状态
cp .agentfs/my-agent.db snapshots/before-risky-operation.db

# 出问题了？恢复
cp snapshots/before-risky-operation.db .agentfs/my-agent.db

3. 可移植 — 一个文件走天下

整个 Agent 状态是一个 .db 文件：

• Git 版本控制 ✅
• SSH 传到另一台机器 ✅
• Firecracker VM 里挂载 ✅
• Cloudflare Workers Durable Objects ✅

🔧 集成生态

已有的框架集成示例：

SDK 支持：TypeScript / Python / Rust

👥 背景：Turso 公司

Turso 是做 libSQL（SQLite fork）和 Turso Database（SQLite 云端托管）的公司。AgentFS 是他们把 SQLite 推向 AI Agent 场景的战略产品。

逻辑很清晰：

• SQLite 是世界上部署量最大的数据库
• Agent 状态管理需要轻量、便携、可审计的存储
• SQLite 完美匹配 → Turso 成为 Agent 基础设施

⚠️ 注意事项

1. Beta 阶段：官方警告可能有 bug，生产数据请备份

2. SQLite 并发限制：单写多读，高并发场景需注意

3. 大文件不适合：SQLite 存二进制大文件性能差（>100MB 不推荐）

4. FUSE/NFS 实验性：挂载功能还不稳定

5. 锁定风险：虽然开源，但深度集成 Turso 生态

💡 与我们的关联

1. OpenClaw Agent 状态持久化

目前 OpenClaw 的 Agent 状态靠 MEMORY.md 等文本文件。AgentFS 提供了更结构化的方案：

• 每个 Agent session 一个 .db 文件
• 工具调用自动记录（不用手动写日志）
• SQL 查询分析 Agent 行为

2. 调试和回放

"这个 Agent 为什么做了这个决定？" — 查 SQL 就知道。

"能不能回到出错之前？" — cp 一个文件。

3. 沙箱 + AgentFS

如果未来做 Agent 沙箱隔离（Firecracker/gVisor），AgentFS 提供了现成的状态挂载方案。

4. 与 ClickMem 对比

ClickMem = 语义记忆（类人记忆模型）

AgentFS = 结构化状态存储（操作系统级抽象）

两者互补，不冲突。

5. 实际采用建议

短期：不急需。MEMORY.md + 本地文件系统够用。

中期：当 Agent 复杂度上升（多步骤、多工具、需要审计），值得引入。

长期：Agent 基础设施标准化后，类似抽象会成为标配。

📊 评分

报告由深度研究助手自动生成 | 2026-03-19

来源: https://github.com/tursodatabase/agentfs