@cogineai/mafs-node

Node.js bundle for MAFS — A Unified Virtual File System for AI Agents.

This is the package most server-side and CLI consumers want. It re-exports everything from @cogineai/mafs-core and layers on Node-specific pieces:

• Disk-backed resources: DiskResource, FUSE mounts via MafsFS, native nativeExec shell helpers.
• Cloud storage with native SDKs: S3Resource, R2Resource, GCSResource, OCIResource, SupabaseResource.
• Database resources: PostgresResource (with node-postgres driver), MongoDBResource.
• HTTP-only resources (re-exported, identical to browser): Slack, Discord, Linear, Trello, Langfuse, GitHub, GitHub CI, GDocs/GSheets/GSlides/GDrive, Dropbox, Box, Gmail, Email (IMAP/SMTP).
• Redis-backed cache: RedisFileCacheStore, RedisIndexCacheStore, RedisStore.
• Local audio: LOCAL_AUDIO_COMMANDS powered by an optional sherpa-onnx-node peer.

Install

npm install @cogineai/mafs-node

Optional peers — only required if you use the matching feature:

| Peer | Used by | | ---------------------- | -------------------------------------------------- | | @zkochan/fuse-native | FUSE mounts (MafsFS, fuseMount, FuseManager) | | sherpa-onnx-node | Local audio transcription (localAudioTranscribe) |

The Workspace itself works fine without these peers; importing the corresponding modules without the peer installed surfaces a clear loadOptionalPeer error at first use.

Requires Node.js ≥ 20. macOS or Linux for FUSE; Windows is supported for the rest.

Quick start — S3 + RAM, with cache

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

const ws = new Workspace(
  {
    '/data': new RAMResource(),
    '/s3': new S3Resource({
      bucket: 'logs',
      region: 'us-west-2',
      credentials: { accessKeyId: '…', secretAccessKey: '…' },
    }),
  },
  { mode: MountMode.WRITE },
)

// First call streams from S3 and populates the file cache.
await ws.execute('cp /s3/2026/05/22/error.log /data/error.log')

// Subsequent reads of the same key serve from the cache.
const lines = await ws.execute('grep "504 Gateway" /s3/2026/05/22/error.log | wc -l')
console.log(lines.stdoutText)

await ws.close()

Quick start — FUSE-mount a workspace as a real filesystem

import { fuseMount, RAMResource, Workspace } from '@cogineai/mafs-node'

const ws = new Workspace({ '/': new RAMResource() })
await ws.fs.writeFile('/hello.txt', 'mounted via FUSE!\n')

const handle = await fuseMount(ws, '/tmp/my-mafs-mnt')
// `cat /tmp/my-mafs-mnt/hello.txt` from another shell now works.

// Later:
await handle.unmount()
await ws.close()

Quick start — Redis cache for shared workers

import {
  RedisFileCacheStore,
  RedisIndexCacheStore,
  S3Resource,
  Workspace,
} from '@cogineai/mafs-node'

const ws = new Workspace(
  { '/s3': new S3Resource({ bucket: 'my-bucket' }) },
  {
    cache: new RedisFileCacheStore({ url: 'redis://localhost:6379/0', limit: '8GB' }),
    index: new RedisIndexCacheStore({ url: 'redis://localhost:6379/0', ttl: 600 }),
  },
)

What's exported beyond mafs-core

The full list lives in packages/mafs/typescript/packages/node/src/index.ts. Highlights:

• DiskResource, DiskStore, DISK_OPS
• RedisResource, RedisStore, RedisAccessor, REDIS_OPS
• RedisFileCacheStore, RedisIndexCacheStore
• MafsFS, FuseManager, fuseMount, fuseMountBackground
• nativeExec, nativeExecStream, NativeProcess
• S3Resource, R2Resource, GCSResource, OCIResource, SupabaseResource
• PostgresResource, PostgresStore
• MongoDBResource, MongoDBStore
• SSCholarPaperResource, SSCholarAuthorResource, VercelResource, PostHogResource
• SlackResource, DiscordResource, TrelloResource, LinearResource, LangfuseResource, GitHubResource, GitHubCIResource
• GDocsResource, GSheetsResource, GSlidesResource, GDriveResource, DropboxResource, BoxResource
• GmailResource, EmailResource
• patchNodeFs for transparently routing Node fs.* reads through a Workspace
• LOCAL_AUDIO_COMMANDS (optional sherpa-onnx-node)

Every Workspace primitive (Workspace, MountMode, FileStat, …) is also re-exported from @cogineai/mafs-core.

Companion packages

• @cogineai/mafs-cli — coginex + mafs binaries.
• @cogineai/mafs-core — runtime-agnostic primitives.
• @cogineai/mafs-browser — browser/edge 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.