AgentFS

A virtual filesystem for AI agents, backed by SQLite. Implements the Agent Filesystem Specification v0.4 on Val Town.

AgentFS gives agents persistent, structured storage through three primitives:

Virtual Filesystem — POSIX-like file operations (read, write, mkdir, link, symlink, rename) using a Unix inode design with chunked content storage
Key-Value Store — Simple typed get/set for agent context, preferences, and structured state
Tool Call Audit Log — Insert-only trail of tool invocations with timing, parameters, results, and performance analytics

Quick Start


import { init, fs, kv, tools } from "https://esm.town/v/nbbaier/agentfs/mod.ts";

// Initialize tables (idempotent — safe to call on every run)
await init();

// Write and read files
await fs.writeFile("/notes/today.md", "# Meeting Notes\n- Ship v2");
const content = await fs.readFile("/notes/today.md", "utf-8");

// Key-value store (auto JSON serialization)
await kv.set("agent:config", { model: "gpt-4", temperature: 0.7 });
const config = await kv.get<{ model: string }>("agent:config");

// Tool call tracking
const result = await tools.trace("web_search", { query: "Val Town" }, async () => {
  // ... your tool implementation
  return { results: ["..."] };
});

Architecture

Rendering mermaid diagram...

All modules import from Val Town's scoped SQLite (std/sqlite/main.ts) so each val gets its own isolated database.

API Reference

`init()`

Creates all tables and seeds the root directory. Uses CREATE TABLE IF NOT EXISTS — safe to call on every startup.


await init();

Filesystem (`fs`)

Function	Description
`writeFile(path, content)`	Write a string or `Uint8Array`. Auto-creates parent dirs. Overwrites if exists.
`readFile(path, encoding?)`	Read a file. Pass `"utf-8"` for string, omit for `Uint8Array`.
`readFileAt(path, offset, length)`	Partial read at a byte offset.
`exists(path)`	Check if a path exists.
`stat(path)`	Get inode metadata (size, mode, timestamps, nlink).
`mkdir(path)`	Create a directory.
`mkdirp(path)`	Create a directory and all missing parents.
`readdir(path)`	List names in a directory.
`rmdir(path)`	Remove an empty directory.
`deleteFile(path)`	Unlink a file. Cleans up inode/data when last link is removed.
`link(src, dest)`	Create a hard link.
`symlink(target, linkPath)`	Create a symbolic link.
`readlink(path)`	Read a symlink's target.
`rename(oldPath, newPath)`	Move/rename a file or directory.
`resolve(path)`	Resolve a path to its inode number (or `undefined`).

Key-Value Store (`kv`)

Values are automatically JSON-serialized on write and deserialized on read.

Function	Description
`set(key, value)`	Upsert a key-value pair.
`get<T>(key)`	Get a value (or `undefined`).
`del(key)`	Delete a key.
`has(key)`	Check if a key exists.
`list(prefix?)`	List keys with optional prefix filter. Returns metadata without values.
`getEntry(key)`	Get the full entry including `created_at` and `updated_at` timestamps.

Tool Call Audit Log (`tools`)

An insert-only audit trail — records are never updated or deleted.

Function	Description
`record(opts)`	Record a completed tool call with name, parameters, result/error, and timestamps.
`trace(name, params, fn)`	Execute a function and auto-record timing, result, and errors.
`get(id)`	Get a tool call by ID.
`queryByName(name, limit?)`	Query calls by tool name, most recent first.
`queryRecent(since, limit?)`	Query calls after a Unix timestamp.
`analyzePerformance()`	Aggregate stats (call count, success/fail, avg duration) by tool name.

Types & Constants


import {
  // Types
  type Inode, type StatResult, type DirEntry,
  type KVEntry, type ToolCall, type ToolPerformance,

  // Mode helpers
  isFile, isDir, isSymlink,

  // Constants
  ROOT_INO,              // 1
  DEFAULT_CHUNK_SIZE,    // 4096
  DEFAULT_FILE_MODE,     // 0o100644
  DEFAULT_DIR_MODE,      // 0o040755
  S_IFREG, S_IFDIR, S_IFLNK, S_IFIFO, S_IFCHR, S_IFBLK, S_IFSOCK, S_IFMT,
} from "https://esm.town/v/nbbaier/agentfs/mod.ts";

Files

File	Purpose
`mod.ts`	Public entry point — re-exports all modules
`schema.ts`	DDL definitions and `init()`
`fs.ts`	Virtual filesystem operations
`kv.ts`	Key-value store operations
`tool-calls.ts`	Tool call audit log operations
`types.ts`	Type definitions and constants
`main.ts`	HTTP test handler — hit the endpoint to run the test suite
`test.ts`	Quick smoke test script
`docs/spec.md`	Full Agent Filesystem Specification v0.4

nbbaier

agentfs