MesaFilesystem

標準の Mastra WorkspaceFilesystem インターフェースを介して、Workspace のファイルを Mesa リポジトリに保存します。

Agent にバージョン管理されたファイルストレージが必要な場合は、MesaFilesystem を使用します。ローカルディレクトリには LocalFilesystem、オブジェクトストレージには S3Filesystem、GCSFilesystem、AzureBlobFilesystem を使用してください。

情報

MesaFilesystem は Mastra プロセス内で動作します。

Mesa の POSIX マウント（Sandbox 内で Mesa Filesystem を使用する機能）は、まだ @mastra/mesa パッケージに含まれていません。今後対応予定です。

インストール

npm

npm install @mastra/mesa

pnpm

pnpm add @mastra/mesa

Yarn

yarn add @mastra/mesa

Bun

bun add @mastra/mesa

使用例

1つの Mesa リポジトリをマウントし、Filesystem を Workspace に渡します。

src/mastra/workspace.ts

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { MesaFilesystem } from '@mastra/mesa'

const workspace = new Workspace({
  filesystem: new MesaFilesystem({
    apiKey: process.env.MESA_API_KEY,
    org: 'acme',
    repos: [{ name: 'docs', bookmark: 'main' }],
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

apiKey を省略すると、MESA_API_KEY を使用します。

コンストラクターパラメーター

apiKey?:

string

Mesa API キー。省略した場合は MESA_API_KEY を使用します。

org?:

string

Mesa 組織の slug。省略した場合は Mesa SDK がデフォルトの組織を解決します。

repos:

RepoConfig[]

マウントする Mesa リポジトリ。

cache?:

{ diskCache?: { path: string; maxSizeBytes?: number } }

Mesa Filesystem のキャッシュ設定。

ttl?:

number

Mesa マウントトークンの有効期間（秒）。

readOnly?:

boolean

= false

すべてのリポジトリを読み取り専用でマウントするかどうか。

プロパティ

id:

string

Filesystem インスタンスの識別子。

name:

string

Provider 名（'MesaFilesystem'）。

provider:

string

Provider 識別子（'mesa'）。

readOnly:

boolean | undefined

書き込み操作を禁止するかどうか。

client:

Mesa | undefined

この Provider が作成した Mesa SDK クライアント。初期化前は undefined です。

filesystem:

MesaFileSystem

有効な Mesa Filesystem。Mesa SDK の未加工の Filesystem が必要な場合、初期化後にアクセスします。

change:

MesaFileSystem["change"]

マウント済み Filesystem の Mesa 変更管理操作。

bookmark:

MesaFileSystem["bookmark"]

マウント済み Filesystem の Mesa ブックマーク管理操作。

メソッド

MesaFilesystem は WorkspaceFilesystem インターフェースを実装します。

ファイル操作

readFile(path, options?)

Mesa からファイルを読み取ります。

const content = await filesystem.readFile('/acme/docs/README.md', {
  encoding: 'utf-8',
})

戻り値：Promise<string | Buffer>

writeFile(path, content, options?)

Mesa へファイルを書き込みます。

await filesystem.writeFile('/acme/docs/report.md', '# Report')

戻り値：Promise<void>

appendFile(path, content)

ファイルへ内容を追記します。

await filesystem.appendFile('/acme/docs/log.txt', 'new line\n')

戻り値：Promise<void>

deleteFile(path, options?)

ファイルを削除します。

await filesystem.deleteFile('/acme/docs/old-report.md')

戻り値：Promise<void>

copyFile(src, dest, options?)

ファイルをコピーします。

await filesystem.copyFile('/acme/docs/report.md', '/acme/docs/archive/report.md')

戻り値：Promise<void>

moveFile(src, dest, options?)

ファイルを移動または名前変更します。

await filesystem.moveFile('/acme/docs/draft.md', '/acme/docs/final.md')

戻り値：Promise<void>

ディレクトリ操作

mkdir(path, options?)

ディレクトリを作成します。

await filesystem.mkdir('/acme/docs/reports', { recursive: true })

戻り値：Promise<void>

rmdir(path, options?)

ディレクトリを削除します。

await filesystem.rmdir('/acme/docs/reports', { recursive: true })

戻り値：Promise<void>

readdir(path, options?)

ディレクトリのエントリを一覧表示します。

const entries = await filesystem.readdir('/acme/docs', {
  recursive: true,
  extension: '.md',
})

戻り値：Promise<FileEntry[]>

パス操作

exists(path)

パスが存在するか確認します。

const exists = await filesystem.exists('/acme/docs/README.md')

戻り値：Promise<boolean>

stat(path)

ファイルまたはディレクトリのメタデータを返します。

const stat = await filesystem.stat('/acme/docs/README.md')

戻り値：Promise<FileStat>

realpath(path)

Mesa の正規パスを返します。

const realPath = await filesystem.realpath('/acme/docs/README.md')

戻り値：Promise<string>

Mesa の操作

bash(options?)

この Filesystem 用に Mesa ベースの Bash ランタイムを作成します。

const bash = await filesystem.bash({
  cwd: '/acme/docs',
})

戻り値：Promise<Bash>

パスのセマンティクス

メソッドには絶対パスを指定します。MesaFilesystem のパスは Mesa マウントをルートとし、組織 slug とリポジトリ名を含める必要があります。

await filesystem.readFile('/acme/docs/README.md')

先頭のスラッシュを省略しないでください。

await filesystem.readFile('acme/docs/README.md') // Incorrect
await filesystem.readFile('/acme/docs/README.md') // Correct

組織はコンストラクターの org から取得します。org を省略した場合は、Mesa SDK のデフォルト組織の推論結果を使用します。組織は常にパスの最初のセグメントになります。

複数のリポジトリをマウントすると、各リポジトリを組織セグメント配下で利用できます。

const filesystem = new MesaFilesystem({
  org: 'acme',
  repos: [
    { name: 'docs', bookmark: 'main' },
    { name: 'website', bookmark: 'main' },
  ],
})

await filesystem.readFile('/acme/docs/README.md')
await filesystem.readFile('/acme/website/package.json')

Mesa のバージョン管理 API

Mesa 固有の変更操作とブックマーク操作には、基盤となる Mesa Filesystem へアクセスします。

await filesystem.writeFile('/acme/docs/draft.md', 'Draft')

const current = await filesystem.change.current({
  repo: 'docs',
})

await filesystem.bookmark.move({
  repo: 'docs',
  name: 'main',
  changeId: current.changeId,
})

バージョン管理のセマンティクスの詳細は、Mesa のドキュメントを参照してください。

読み取り専用モード

Mastra を介した書き込み操作を禁止するには、readOnly: true を設定します。

const filesystem = new MesaFilesystem({
  repos: [{ name: 'docs', bookmark: 'main' }],
  readOnly: true,
})

読み取り操作は引き続き動作します。書き込み操作は WorkspaceReadOnlyError をスローします。

並行処理

overwrite: false と expectedMtime は、書き込み前に事前チェックを行います。Mesa がアプリマウント向けのネイティブ条件付き書き込みに対応しない限り、これらのチェックはアトミックではありません。

関連項目

• WorkspaceFilesystem インターフェース
• Filesystem ドキュメント
• Workspace の概要
• Mesa ドキュメント