Skip to main content
A filesystem is the top-level organizational boundary in Moxn — and a shared primitive for both humans and agents. Everything you store — documents, databases, and tags — lives inside a filesystem. Filesystems give agents the same advantage a well-organized repo gives a developer: you can navigate to the right neighborhood before you read. The hierarchy lets the agent control retrieval instead of delegating relevance entirely to an embedding; tags and databases layer on cross-cutting dimensions. They’re also a strict isolation boundary. Users without access to a filesystem can’t see that it exists or what’s inside it. Every workspace gets a default filesystem with your whole team auto-added; many teams add more as they grow.

​
The Default Filesystem

Every Moxn workspace has exactly one default filesystem, created automatically when your workspace is set up. All workspace members are automatically added to it. For most teams, the default filesystem is all you need: one shared space where your agents and teammates collaborate on docs.

​
Multiple Filesystems

You can create additional filesystems when you need stricter boundaries — for example:
  • A private filesystem for sensitive playbooks that shouldn’t be visible to all agents
  • A product filesystem for a specific team or project
  • An engineering filesystem separate from marketing or sales docs
Each filesystem has its own:
  • Document namespace (paths like /guides/api-reference are unique per filesystem, not per workspace)
  • Tag pool
  • Databases
  • Member list and permission settings

​
Membership and Roles

Users belong to filesystems with a role (owner, edit, comment, or read). See Permissions for what each role can do. Each filesystem has exactly one owner. The default filesystem’s owner is the workspace creator. You can also set a tenant default role — a fallback role granted to all workspace members who aren’t explicitly added. Set it to read to make a filesystem visible-but-locked to everyone; set it to null to make the filesystem private (only explicit members can see it).

​
Scoping Agents to a Filesystem

By default, MCP tools (find, search, documents, databases) operate across all filesystems you have access to. Use the --filesystems flag to set a default filesystem for the session: 
{
  "mcpServers": {
    "context": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@moxn/mcp-kb",
        "--workspace=your-workspace-slug",
        "--filesystems=engineering"
      ]
    }
  }
}
Or set MOXN_FILESYSTEMS=engineering,product in your environment. When set, the filesystem slug is injected automatically into tool calls that accept a filesystem parameter — so the agent doesn’t need to specify it on every call. Actual access is still governed by the user’s filesystem membership and role.

​
Discovering Filesystems at Runtime

Agents can call the filesystems tool to list all accessible filesystems, then pass filesystem: "slug" to subsequent find, search, documents, or databases calls. 
"List my filesystems and find all documents in the engineering one"

​
Filesystem Structure

Workspace
├── default filesystem          ← all members auto-added
│   ├── /docs/api-guide         ← document (path-scoped to this filesystem)
│   ├── /runbooks/deploy        ← document
│   ├── Tags: /technology/ai    ← tag pool (global to filesystem)
│   └── Databases: Sprint Board ← databases
│
└── engineering filesystem      ← explicit membership
    ├── /architecture/overview
    ├── /rfcs/auth-v2
    └── Databases: RFC Tracker
Paths in different filesystems are independent — both can have /guides/quickstart without conflict.