> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# AgentFSFilesystem

通过 [AgentFS](https://github.com/nichochar/agentfs) SDK 将文件存储在 Turso/SQLite 数据库中。文件会跨 Session 持久保存在本地 SQLite 数据库中，无需外部云服务即可为 Agent 提供持久存储。有关接口详情，请参阅 [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)。

## 安装

**npm**:

```bash
npm install @mastra/agentfs
```

**pnpm**:

```bash
pnpm add @mastra/agentfs
```

**Yarn**:

```bash
yarn add @mastra/agentfs
```

**Bun**:

```bash
bun add @mastra/agentfs
```

## 用法

将 `AgentFSFilesystem` 添加到 Workspace，并将其分配给 Agent。实例化 `AgentFSFilesystem` 类时，必须提供 `agentId`、`path` 或 `agent` 中的至少一个。

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { AgentFSFilesystem } from '@mastra/agentfs'

const workspace = new Workspace({
  filesystem: new AgentFSFilesystem({
    agentId: 'my-agent',
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
})
```

### 使用显式数据库路径

默认情况下，数据库存储在 `.agentfs` 目录中，并以 `agentId` 作为文件名。你可以指定自定义数据库路径：

```typescript
import { AgentFSFilesystem } from '@mastra/agentfs'

const filesystem = new AgentFSFilesystem({
  path: '/data/my-agent.db',
})
```

### 使用预先打开的 AgentFS 实例

如果需要自行管理 AgentFS 生命周期：

```typescript
import { AgentFS } from 'agentfs-sdk'
import { AgentFSFilesystem } from '@mastra/agentfs'

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

const filesystem = new AgentFSFilesystem({
  agent, // caller manages open/close
})
```

## 构造函数参数

必须提供 `agentId`、`path` 或 `agent` 中的至少一个。

**agentId** (`string`): Agent ID——在 .agentfs/\<agentId>.db 创建数据库

**path** (`string`): 显式数据库文件路径（可替代 agentId）

**agent** (`AgentFS`): 预先打开的 AgentFS 实例。提供该实例后，其生命周期（打开/关闭）由调用方管理。

**id** (`string`): 此文件系统实例的唯一标识符 (Default: `自动生成`)

**displayName** (`string`): 在 UI 中显示的易读名称 (Default: `'AgentFS'`)

**icon** (`FilesystemIcon`): UI 的图标标识符 (Default: `'database'`)

**description** (`string`): 在 UI 中显示的此文件系统的简短描述

**readOnly** (`boolean`): 设为 true 时，阻止所有写入操作 (Default: `false`)

## 属性

**id** (`string`): 文件系统实例标识符

**name** (`string`): Provider 名称（'AgentFSFilesystem'）

**provider** (`string`): Provider 标识符（'agentfs'）

**readOnly** (`boolean | undefined`): 文件系统是否处于只读模式