Agentic File System (AFS)

• AFS is a unified file system abstraction that treats documents, memories, tools, and human inputs as nodes with structured metadata and access control.
• It enables consistent context assembly and verifiable GenAI prompt construction by leveraging cost-based file selection and dynamic mounting of resources.
• Its implementation within the AIGNE framework demonstrates composability, persistent storage, and rigorous governance to replace fragmented context practices.

The Agentic File System (AFS) is a formal abstraction for context engineering in generative AI (GenAI) systems. Designed to replace fragmented practices such as prompt injection, retrieval-augmented generation, and ad hoc tool integration, AFS unifies all context artefacts—documents, memories, tools, and human inputs—as nodes in a governed namespace with persistent storage, verifiable access control, and full context traceability and accountability. Its implementation within the AIGNE open-source framework demonstrates operational rigor and composability, supporting industry-grade, human-curated GenAI deployments (Xu et al., 5 Dec 2025).

1. Formal Specification

AFS formalizes the notion that “everything is a file,” treating heterogeneous context artefacts as file-system nodes. Its definition is as follows:

• $N = F \cup D$, the set of all nodes, where $F$ is a finite set of files and $D$ a finite set of directories.
• $E \subseteq D \times N$, the "contains" edge relation: $(d, n) \in E$ indicates directory $d$ contains node $n$.
• $M: D_\text{mnt} \rightarrow R$, maps mount points $D_\text{mnt} \subseteq D$ to external resources $R$ (e.g., vector-stores, memory DBs, MCP servers).
• $\mathrm{meta}: N \rightarrow \mathcal{K}$, associates each node $n$ with a metadata record in key–value space $\mathcal{K}$ (e.g., creationTime, owner, version, confidence).
• $\mathrm{ACL}: N \rightarrow 2^{U \times P}$, maps each node to an access-control list; $U$ is the universe of users/agents, $$P = \{\mathrm{read}, \mathrm{write}, \mathrm{exec}, \mathrm{admin}\}$$.

Thus, an AFS instance is the tuple:

$$\mathrm{AFS} = (N, E, M, \mathrm{meta}, \mathrm{ACL})$$

Operations conform to POSIX-like semantics (list, read, write, exec), but every mount point $M(d)$ is dynamically resolved. Each mount’s resolver provides a projection $\pi_R : \text{schema}(R) \rightarrow$ subtree under $d$, rendering disparate back-ends as regular subtrees.

For GenAI prompt assembly, $F$ is equipped with $\mathrm{cost}: F \rightarrow \mathbb{N}$ mapping file content to token cost, and $$\mathrm{sel}: F \times \mathrm{Context} \rightarrow \{0,1\}$$ for selection. The context-construction step selects $S \subseteq F$ such that:

$\sum_{f \in S} \mathrm{cost}(f) \leq W$

where $W$ is the model’s token window constraint.

2. AFS in the AIGNE Framework

Within AIGNE, AFS constitutes the backbone of a verifiable, closed-loop context-engineering pipeline:

• AFS Virtual File System (SystemFS): Provides a uniform namespace, exposes core APIs, and enforces fine-grained ACLs.
• Context Constructor: Pulls candidate context artefacts by querying AFS, applies relevance scoring (via metadata logic such as timestamps, provenance, owner trust, confidence) and automated compression (summaries, embeddings), producing a context manifest.
• Context Updater: Streams selected context fragments into the GenAI model’s buffer. It tracks context injection/replacement as AFS transactions for full auditability.
• Context Evaluator: Validates model outputs for factual consistency and provenance by comparison against AFS-recorded sources. Outputs passing confidence thresholds are stored as new memory; otherwise, they are sent for human review, all under strict lineage metadata.

This closed-loop is anchored by a persistent context repository, enabling reproducibility and accountability across multi-agent and human-in-the-loop settings.

3. Mounting, Metadata, and Governance

AFS realizes mounting of arbitrary back-ends—vector stores, external tools, memory databases, live MCP endpoints—at any point in the namespace. New mount points are added programmatically, e.g.,

const afs = new AFS() .mount(new AFSHistory({storage: ...})) // "/context/history" .mount(new UserProfileMemory({...})) // "/context/memory/user" .mount(mcpAgent); // "/modules/github-mcp"

Directories such as /context/history/, /context/memory/user/, and /modules/github-mcp/ integrate distinct resource types as regular subtrees.

Each file or directory carries structured metadata, typically in YAML or JSON, including identifiers, ownership, timestamps, source provenance, confidence, version, token count, and governance fields such as ACL, revision ID, status, and cost estimate. This schema enables fine-grained access controls and lineage tracking.

4. API Surface and Operations

AFS exposes asynchronous, access-controlled operations:

Method	Functionality	ACL Enforcement
afs_list	List child nodes (optionally with depth/filtering)	Yes
afs_read	Retrieve content and metadata of a file	Yes
afs_write	Create or update file/metadata	Yes
afs_search	Search files via full-text/regex/vector search plugins (e.g., ripgrep, Faiss)	Yes
afs_exec	Execute a function-file (e.g., tool endpoint) under policy sandbox	Yes

All agent and curator operations are mediated by the node’s ACL, ensuring enforceable read/update/exec/admin policies. Administrative operations include log inspection, policy modifications, and resolution of conflicting memory entries.

5. Verifiable Context Pipeline

AFS underpins a pipeline architecture with three principal stages, reflecting GenAI’s operational constraints:

1. Context Constructor:
   • Queries AFS for context files ($$f \in \{\text{history} \cup \text{memory} \cup \text{tools}\}$$).
   • Ranks by composite metrics: $$R(f) = \alpha \cdot \text{freshness} + \beta \cdot \text{similarity} + \gamma \cdot \text{ownerTrust}$$.
   • Selects subset within token-window: $\sum_{f \in S} \mathrm{cost}(f) \leq W$.
   • Summarizes via $Summ: S \rightarrow \text{Summaries}$.
   • Emits manifest with metadata, path, summaries, and cost.
2. Context Updater:
   • Reads manifest, streams context into model prompts.
   • Handles incremental insertion/removal for interactive/backtracking sessions.
   • Logs all context modifications in /context/logs/.
3. Context Evaluator:
   • Compares model output $O$ to sources (semantic distance, LLM fact-checking).
   • If confidence $\geq \tau$, stores $O$ as new fact in /context/memory/agent/fact/.
   • Otherwise, routes for human review and notifies curators.
   • All updates record lineage for complete chain-of-reasoning reconstruction.

Every step is persistent and replayable, providing a forensic basis for model decisions and human intervention.

6. Exemplar Applications

Two representative deployments illustrate AFS flexibility:

6.1 Agent with Persistent Memory

An agent instantiates AFS, mounting historical dialogue and user profile memory, e.g.,

const afs = new AFS() .mount(new AFSHistory({storage: "file:./memory.sqlite3"})) .mount(new UserProfileMemory({storage: "file:./memory.sqlite3"})); const agent = AIAgent.from({ instructions: "You are a friendly chatbot", inputKey: "message", afs });

Dialogue turns are appended under /context/history/, with summaries and session memories maintained in /context/memory/. On restart, recent summaries are reloaded to prime the agent's context window. This demonstrates verifiable, composable memory and recovery (Xu et al., 5 Dec 2025).

6.2 MCP-Based GitHub Assistant

An agent dynamically mounts a live MCP endpoint, exposing it as /modules/github-mcp/:

const mcpAgent = await MCPAgent.from({ command: "docker", args: [..., "ghcr.io/github/github-mcp"] }); const afs = new AFS().mount(mcpAgent); const agent = AIAgent.from({ instructions: "Help users interact with GitHub...", inputKey: "message", afs }); await afs_exec("/modules/github-mcp/search_repositories", {query: "aigne-framework"});

Search results are persisted as JSON artefacts in the namespace, illustrating first-class integration of procedural tools via the same abstractions as memory and documents.

7. Comparison to Existing Practices

AFS is distinguished from existing context-management techniques along several axes:

Method	Persistence	Governance/Traceability	Composability
Prompt Engineering	None	None	Limited, manual
RAG	Transient, per-call	Rarely versioned/audited	Retrieval only
Tool Integration	Ad hoc in prompt	No global trace	No mount abstraction
AFS	Full per-file/version	ACLs, lineage, audit logs	Arbitrary back-ends

AFS enables rigorous governance (via ACLs and metadata), persistent artefact versioning, unified audit trails over all context actions, and composability—any new memory or tool can be mounted into the namespace without global reconfiguration (Xu et al., 5 Dec 2025).

8. Implementation Challenges and Future Extensions

Notable technical challenges and solutions include:

• Resolver Latency: Each operation may incur external I/O. Mitigations include caching at mount resolvers, prefetching, and bulk-read interfaces.
• Token-Cost Estimation: Precise $cost(f)$ calculation is critical for prompt assembly. Reliance on lightweight tokenizers and dynamic re-estimation is adopted.
• Concurrency and Isolation: Multi-agent setups require strict namespace isolation, implemented via sandboxed processes and scoped ACLs.

Performance characteristics show O(depth + childCount) lookups, with directory indices held in memory. Search is delegated to external engines (e.g., ripgrep, Faiss), maintaining sub-100 ms latency for routine queries.

Planned extensions encompass agentic navigation (discovery and mounting of data sources via /modules/ traversal), self-organizing knowledge structures under human oversight, DevOps-style CI pipelines for context governance, projection of knowledge-graph views for multi-hop reasoning, and fine-grained policy controls such as temporal ACLs and multi-party consent.

AFS embodies software-engineering rigor for context engineering in GenAI, rendering context into a formally governed, versioned, and composable infrastructure. This supports traceable, auditable orchestration of memory, tools, human expertise, and model reasoning in a cohesive system (Xu et al., 5 Dec 2025).