Skip to main content
Build stateful AI agents with the AgentFS TypeScript SDK, supporting both Node.js and browser environments.

​
Installation

bun add agentfs-sdk

​
Quick Start

import { AgentFS } from 'agentfs-sdk';

// Persistent storage with identifier
const agent = await AgentFS.open({ id: 'my-agent' });
// Creates: .agentfs/my-agent.db

// Or use ephemeral in-memory database
const ephemeralAgent = await AgentFS.open();

// Use the three main APIs
// Key-value store
await agent.kv.set('key', 'value');
// Filesystem
await agent.fs.writeFile('/file.txt', 'data');
// Tool tracking
await agent.tools.record(...);

​
Core APIs

​
AgentFS Class

The main entry point for all AgentFS operations.

​
AgentFS.open(options?: AgentFSOptions)

Creates or opens an AgentFS database. 
interface AgentFSOptions {
  /**
   * Optional unique identifier for the agent.
   * - If provided: Creates persistent storage at `.agentfs/{id}.db`
   * - If omitted: Uses ephemeral in-memory database
   */
  id?: string;
}

// Persistent storage
const agent = await AgentFS.open({ id: 'my-agent' });
// Creates: .agentfs/my-agent.db

// Ephemeral in-memory database
const ephemeralAgent = await AgentFS.open();

​
Properties

  • kv: Key-value store interface
  • fs: Filesystem interface
  • tools: Tool call tracking interface
  • db: Direct access to the underlying Turso database

​
Key-Value Store API

Fast, typed storage for agent state and configuration.

​
kv.set(key: string, value: any)

Store a value with automatic JSON serialization. 
await agent.kv.set('user:123', {
  name: 'Alice',
  preferences: { theme: 'dark' }
});

await agent.kv.set('session:current', 'abc-123');
await agent.kv.set('counter', 42);

​
kv.get<T>(key: string): Promise<T | undefined>

Retrieve a value with automatic deserialization. 
interface UserData {
  name: string;
  preferences: { theme: string };
}

const user = await agent.kv.get<UserData>('user:123');
if (user) {
  console.log(user.name); // Type-safe access
}

​
kv.delete(key: string)

Remove a key-value pair. 
await agent.kv.delete('session:expired');

​
kv.list(prefix: string): Promise<{ key: string, value: any }[]>

List keys matching a prefix. 
// List all user keys
const userEntries = await agent.kv.list('user:');
for (const { key, value } of userEntries) {
  console.log(key, value);
}

// List all keys (empty prefix)
const allEntries = await agent.kv.list('');

​
Filesystem API

POSIX-like filesystem operations for managing agent data.

​
fs.writeFile(path: string, data: string | Buffer)

Write data to a file, creating parent directories as needed. 
// Write text
await agent.fs.writeFile('/reports/summary.md', '# Report\nContent...');

// Write binary data
const imageBuffer = await fetch(url).then(r => r.arrayBuffer());
await agent.fs.writeFile('/images/chart.png', Buffer.from(imageBuffer));

​
fs.readFile(path: string, options?: BufferEncoding): Promise<Buffer | string>

Read file contents. Returns a Buffer by default, or a string if encoding is specified. 
// Read as Buffer (default)
const data = await agent.fs.readFile('/reports/summary.md');
const text = data.toString('utf-8');

// Read as string with encoding
const content = await agent.fs.readFile('/reports/summary.md', 'utf-8');

// For JSON files
const jsonData = await agent.fs.readFile('/config.json');
const config = JSON.parse(jsonData.toString());

​
fs.readdir(path: string): Promise<string[]>

List directory contents. 
const files = await agent.fs.readdir('/reports');
// Returns: ['summary.md', '2024/', 'archive/']

// Check each entry type
for (const entry of files) {
  const stats = await agent.fs.stat(`/reports/${entry}`);
  if (stats.isDirectory()) {
    console.log(`Directory: ${entry}`);
  } else {
    console.log(`File: ${entry} (${stats.size} bytes)`);
  }
}

​
fs.stat(path: string): Promise<Stats>

Get file or directory metadata. 
interface Stats {
  size: number;        // File size in bytes
  mode: number;        // File mode/permissions
  mtime: number;       // Modified time (Unix timestamp)
  ctime: number;       // Created time (Unix timestamp)
  isFile(): boolean;
  isDirectory(): boolean;
}

const stats = await agent.fs.stat('/reports/summary.md');
console.log(`Size: ${stats.size} bytes`);
console.log(`Modified: ${new Date(stats.mtime * 1000)}`);

​
fs.exists(path: string): Promise<boolean>

Check if a file or directory exists. 
if (await agent.fs.exists('/reports/draft.md')) {
  console.log('Draft exists');
}

​
fs.deleteFile(path: string)

Delete a file. 
await agent.fs.deleteFile('/reports/old.md');

​
Tool Call Tracking API

Record and query agent tool invocations for debugging and compliance.

​
tools.record(name, started_at, completed_at, parameters?, result?, error?): Promise<number>

Record a tool invocation. 
await agent.tools.record(
  name: string,           // Tool identifier
  started_at: number,     // Unix timestamp (seconds)
  completed_at: number,   // Unix timestamp (seconds)
  parameters?: any,       // Tool parameters (JSON-serializable)
  result?: any,           // Tool result (JSON-serializable)
  error?: string          // Error message if failed
);

// Example: Track an API call
const start = Date.now() / 1000;
const response = await callOpenAI(prompt);

const id = await agent.tools.record(
  'openai_completion',
  start,
  Date.now() / 1000,
  { prompt, model: 'gpt-4', temperature: 0.7 },
  { response, tokensUsed: 150 }
);

​
tools.get(id: number): Promise<ToolCall | undefined>

Get details of a specific tool call. 
const toolCall = await agent.tools.get(42);
if (toolCall) {
  console.log('Duration:', toolCall.duration_ms, 'ms');
}

​
Browser Support

AgentFS works in browser environments using WebAssembly: 
<!DOCTYPE html>
<html>
<head>
  <script type="module">
    import { AgentFS } from 'https://unpkg.com/agentfs-sdk/dist/browser.js';

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

    // All APIs work the same in browser
    await agent.kv.set('browser:data', { platform: 'web' });
    await agent.fs.writeFile('/notes.txt', 'Hello from browser!');
  </script>
</head>
</html>

​
Support