Agents Virtual Filesystem

Virtual file-system abstraction (AgentFS) providing safe read/write boundaries for AI agents.

AgentFS is the virtual filesystem layer for agents built into the @memofs/core runtime. It provides autonomous AI agents with an isolated workspace for task execution, scaffolding, file manipulation, and automated durable-memory extraction.

Canonical Memory Path Structure

AgentFS manages all canonical assets within the .memofs/ directory:

.memofs/
├── manifest.json              # Versioned manifest of all tracked memory assets
├── memory/
│   ├── core.md                # Core canonical memory
│   └── notes.md               # Archival memory notes
├── events/
│   ├── memory-events.jsonl    # Memory write/event log
│   └── conversations.jsonl    # Conversation history for recall
├── indexes/
│   ├── chunks.jsonl           # Chunked text index for recall
│   └── embeddings.jsonl       # Vector embeddings index
├── graph/
│   ├── nodes.jsonl            # Entity nodes
│   └── edges.jsonl            # Relationship edges
├── connectors.json            # Connector config (no secrets)
├── archive/                   # Cold storage for deprecated memories
│   └── <id>.json              # Full-fidelity archived memory records
└── snapshots/
    └── snapshots.jsonl        # Snapshot index

The Virtual Path Contract

AgentFS does not interact directly with POSIX filesystem APIs. Instead, it operates against the abstract MemoryStore interface, enabling execution in any JavaScript runtime (Cloudflare Workers, Deno, Bun, Browsers):

interface MemoryStore {
  read(path: MemoryPath): Promise<string>;
  write(path: MemoryPath, content: string): Promise<void>;
  append(path: MemoryPath, content: string): Promise<void>;
  exists(path: MemoryPath): Promise<boolean>;
  delete(path: MemoryPath): Promise<void>;
}

Agent Session Lifecycle

An agent session manages a dedicated workspace for a single task:

prepare(): Scaffolds the task directory (working/ and output/) and synchronizes baseline memory state.
Execution: The agent reads and writes scratchpad files during execution.
extract(): Extracts durable takeaways from the session artifacts.
complete(): Promotes durable memory, handles cleanup, and emits audit events.

import { MemoFS } from "@memofs/core";
import { createNodeFsMemoryStore } from "@memofs/core/node-fs";

const memofs = new MemoFS({
  store: createNodeFsMemoryStore({ rootDir: "." }),
  projectId: "my-project",
});

// 1. Start session
const session = await memofs.agentfs.startSession({
  task: "implement jwt token rotation",
  actorId: "agent-007",
});

// 2. Write working files in session
await memofs.agentfs.writeFile({
  sessionId: session.sessionId,
  path: "plan.md",
  content: "# Implementation Plan\n\n1. Generate RSA keypair\n2. Verify rotation",
});

// 3. Complete session with outcome
const result = await memofs.agentfs.complete({
  sessionId: session.sessionId,
  outcome: "success",
  extractDurableMemory: true,
  checkpointLabel: "jwt-rotation-done",
});

console.log(`Durable memory promoted: ${result.durableMemoryWritten}`);
console.log(`Working files cleaned: ${result.workingCleaned}`);

Session Outcomes Matrix

The complete() method accepts an outcome parameter ("success" | "failure" | "aborted"):

// Success: promotes memory, cleans working directory, preserves output
await memofs.agentfs.complete({
  sessionId: session.sessionId,
  outcome: "success",
  extractDurableMemory: true,
});

// Failure: blocks memory promotion, records session.failed audit event
await memofs.agentfs.complete({
  sessionId: session.sessionId,
  outcome: "failure",
  reason: "Compilation failed in test suite",
});

// Failure + Ephemeral: cleans all session artifacts
await memofs.agentfs.complete({
  sessionId: session.sessionId,
  outcome: "failure",
  ephemeral: true,
  reason: "Exploratory scratchpad discarded",
});

// Aborted: preserves workspace for future resumption
await memofs.agentfs.complete({
  sessionId: session.sessionId,
  outcome: "aborted",
  reason: "Task paused by user",
});

Outcome Behavior Reference

Outcome	`extractDurableMemory`	Promote to `notes.md`	Clean `working/`	Clean `output/`	Audit Event
`success`	`true`	✅	✅	—	`memory.created`
`success`	`false`	—	✅	—	—
`failure`	—	—	—	—	`session.failed`
`failure` + `ephemeral`	—	—	✅	✅	`session.failed`
`aborted`	—	—	—	—	—

Client API Reference

// Session management
memofs.agentfs.startSession(input: AgentSessionStartInput): Promise<AgentSessionResult>;
memofs.agentfs.readFile(input: AgentSessionFileInput): Promise<string>;
memofs.agentfs.writeFile(input: AgentSessionFileInput): Promise<void>;
memofs.agentfs.appendFile(input: AgentSessionFileInput): Promise<void>;
memofs.agentfs.extract(input: { sessionId: string }): Promise<AgentSessionExtractResult>;
memofs.agentfs.complete(input: AgentSessionCompleteInput): Promise<AgentSessionCompleteResult>;

// Adapter bridging
memofs.agentfs.createSession(options: CreateMemoFSAgentSessionOptions): MemoFSAgentSession;
memofs.agentfs.store(client: AgentfsLikeClient, config: AgentfsMemoryStoreConfig): AgentfsMemoryStore;

Secret Safety During Extraction

When extractDurableMemory: true is set, extracted content is validated against assertWriteAllowed. If a secret is detected:

The secret is blocked from entering notes.md.
durableMemoryWritten reports false.
A warning is emitted without leaking the secret token into logs or errors.

Advisory Leases

For multi-agent systems sharing a workspace, AgentFS provides advisory lease management to prevent concurrent write collisions:

import { InMemoryLeaseManager, withMemoryLease } from "@memofs/core";

const leaseManager = new InMemoryLeaseManager();

await withMemoryLease(
  {
    leaseManager,
    resource: "memory/notes.md",
    holder: "agent-1",
    ttlMs: 5000,
  },
  async () => {
    // Critical write section executed safely under lease
    await memofs.notes.record({ content: "Safe concurrent write." });
  },
);

Agents Virtual Filesystem

On this page