@cogineai/mafs-core

Runtime-agnostic primitives for MAFS — A Unified Virtual File System for AI Agents.

This is the engine: the Workspace class, the Resource interface, the ops/commands registry, the shell parser and executor, the cache abstractions, and reusable resource implementations that don't need Node-specific I/O (RAM, S3 over fetch, Slack/Discord/GitHub HTTP transports, …). It runs anywhere modern JavaScript runs — Node ≥ 20, browsers, edge runtimes, Bun, Deno, Pyodide.

Most consumers should depend on @cogineai/mafs-node or @cogineai/mafs-browser — both re-export everything here and add runtime-specific pieces. Reach for mafs-core only when:

• You're authoring a new resource or runtime adapter,
• You're embedding MAFS into a non-standard environment (Pyodide, a custom edge worker), or
• You want the smallest possible bundle and only need RAM-level functionality.

Install

npm install @cogineai/mafs-core

Optional peer:

npm install pyodide   # only if you'll execute Python inside the workspace

Quick start

import { MountMode, RAMResource, Workspace } from '@cogineai/mafs-core'

const ws = new Workspace({ '/data': new RAMResource() }, { mode: MountMode.WRITE })

await ws.fs.writeFile('/data/hello.txt', 'hello mafs\n')
const result = await ws.execute('cat /data/hello.txt | wc -l')
console.log(result.stdoutText) //=> "       1\n"

await ws.close()

What lives here

• Workspace — the unified VFS façade: ws.fs.* for direct file ops, ws.execute(cmd) to run a shell pipeline across mounts, ws.snapshot() for portability.
• Resource — the abstract contract every backend implements (readdir, read, write, stat, unlink, glob, …). RAMResource, DevResource, and HTTP-only resources (Slack, GitHub, GCS via fetch, …) live here; native-binding resources (FUSE, postgres-driver, sherpa-onnx) live in @cogineai/mafs-node.
• OpsRegistry — the registry that maps shell commands (cat, grep, sort, find, jq, …) to per-resource implementations. ~80 builtin RAM ops plus per-resource overrides (S3, Slack, GitHub, …).
• Shell layer — createShellParser, executeNode, expansion, jobs, redirects, control flow. The full POSIX-ish shell that powers ws.execute().
• Cache layer — IndexCacheStore + FileCache mixin, with RAM-backed implementations. Redis-backed implementations live in mafs-node; consumers can plug their own.
• Session, SessionManager, ExecutionHistory — multi-turn agent state.
• Snapshot / clone — tar-based portable workspace export/import.

Extending MAFS

Adding a new backend means implementing Resource. Once registered, every shell command, agent adapter, and CLI inherits filesystem semantics for free:

import { type Resource, throwUnsupported } from '@cogineai/mafs-core'

export class MyResource implements Resource {
  async readdir(path: string): Promise<string[]> {
    /* … */
  }
  async read(path: string): Promise<Uint8Array> {
    /* … */
  }
  async stat(path: string) {
    /* … */
  }
  // The base interface marks unimplemented methods with throwUnsupported()
  // until you fill them in — useful for read-only or partial backends.
}

The same applies to ops (OpsRegistry.register({ kind: 'cat', resource: 'my', impl })) and shell builtins.

API surface

@cogineai/mafs-core exports ~1000 named symbols — far too many to list here. Browse the full surface in packages/mafs/typescript/packages/core/src/index.ts or rely on your IDE's import suggestions; everything is typed.

The most-used groupings:

• Top-level types — Workspace, Resource, MountMode, FileStat, FileType, PathSpec, ResourceName.
• Resources — RAMResource, DevResource, S3Resource, SlackResource, GitHubResource, LinearResource, NotionResource, GDocsResource, GSheetsResource, GmailResource, … (40+ resources).
• Ops — RAM_OPS, S3_OPS, GITHUB_VFS_OPS, … (one per resource).
• Cache — RAMFileCacheStore, RAMIndexCacheStore, IndexCacheStore, IndexEntry.
• Cache parts of resources — most resource modules export *_PROMPT and per-tool helpers (featherCat, parquetGrep, …) you can compose into your own backends.

Companion packages

• @cogineai/mafs-cli — coginex + mafs binaries.
• @cogineai/mafs-node — Node resources, FUSE, Redis cache.
• @cogineai/mafs-browser — browser bundle.
• @cogineai/mafs-server — mafs-daemon HTTP server.
• @cogineai/mafs-agents — agent framework adapters.

License & attribution

Apache-2.0. MAFS is a fork of Mirage; see the project-level NOTICE for attribution and the relationship to upstream.