@mounaji_npm/agentfs

A per-agent, portable filesystem home for AI agents. Each agent gets a yoagent-<id>/ directory under a configurable root, with a fixed set of layers plus room for custom nested folders, a manifest.json, and dependency-free .tar.gz export/import bundles — the foundation for portable Tier S agents.

Zero runtime dependencies (Node built-ins only).

Layers

learning · skills · memory · preferences · rules · soul · user · assets

Usage

import { createAgentFs, AgentFs } from '@mounaji_npm/agentfs';

// Create + ensure the layered home exists.
const fs = createAgentFs({ root: '/data/agents', agentId: 'abc123' });

fs.writeJson('memory/facts.json', { likes: ['dark mode'] });
fs.appendFile('learning/feedback_log.jsonl', JSON.stringify({ ok: true }) + '\n');
fs.writeFile('assets/logo.png', someBuffer);
fs.patchManifest({ custom: { tier: 'S' } });

fs.listFiles('memory');          // ['memory/facts.json']
fs.readJson('memory/facts.json');// { likes: ['dark mode'] }

// Portable export → import (round-trips every file, text or binary).
const bundle = fs.exportBundle();                 // Buffer (.tar.gz)
const clone  = AgentFs.fromBundle(bundle, { root: '/tmp', agentId: 'abc123' });

API

createAgentFs({ root?, agentId, layers? }) → AgentFs

Constructs and ensure()s the agent home. root defaults to ~/.yoagent/agents; the agent lives at <root>/yoagent-<agentId>.

AgentFs

• ensure() — create the agent dir, all layers, and manifest (idempotent).
• path(...segments) / layerPath(layer) — absolute paths (traversal-guarded).
• writeFile / readFile / appendFile / writeJson / readJson / exists / mkdir / remove — file ops on agent-relative paths (memory/facts.json).
• listFiles(relDir?) — recursive, sorted, forward-slashed relative paths.
• readManifest / writeManifest / patchManifest.
• exportBundle() → Buffer — gzipped tar of the whole agent tree.
• importBundle(bundle, { overwrite=true }) → { written, total }.
• AgentFs.fromBundle(bundle, { root, agentId?, overwrite? }) — rehydrate an agent (infers agentId from the bundle manifest if omitted).

Archive helpers

packTar · unpackTar · packTarGz · unpackTarGz — a minimal, standard-compatible tar (ustar) implementation for regular files. Produced archives open with tar -xzf.

Notes

• Paths are guarded: any attempt to escape the agent directory (../…) throws.
• Bundles are standard .tar.gz; inspect with tar -tzf agent.tar.gz.
• The learning/ layer is designed to hold @mounaji_npm/learning-core state.

Test

npm test   # node --test