TypeScript/JavaScript SDK

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

Installation

npm
bun
deno

npm install agentfs-sdk

bun add agentfs-sdk

import { AgentFS } from "npm: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

GitHub Issues - Bug reports and feature requests
Discord - Community support and discussions
Examples - Sample applications

AgentFS

Guides

SDKs

Reference

TypeScript/JavaScript SDK

Installation

Quick Start

Core APIs

AgentFS Class

`AgentFS.open(options?: AgentFSOptions)`

Properties

Key-Value Store API

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

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

`kv.delete(key: string)`

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

Filesystem API

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

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

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

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

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

`fs.deleteFile(path: string)`

Tool Call Tracking API

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

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

Browser Support

Support

​Installation

​Quick Start

​Core APIs

​AgentFS Class

​AgentFS.open(options?: AgentFSOptions)

​Properties

​Key-Value Store API

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

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

​kv.delete(key: string)

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

​Filesystem API

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

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

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

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

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

​fs.deleteFile(path: string)

​Tool Call Tracking API

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

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

​Browser Support

​Support

Installation

Quick Start

Core APIs

AgentFS Class

`AgentFS.open(options?: AgentFSOptions)`

Properties

Key-Value Store API

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

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

`kv.delete(key: string)`

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

Filesystem API

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

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

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

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

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

`fs.deleteFile(path: string)`

Tool Call Tracking API

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

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

Browser Support

Support