Sign In

Surfaces

Filesystem view

Accessing Spectron's knowledge layer as a virtual filesystem.

The filesystem view is an experimental MCP feature that mounts Spectron's knowledge store as a virtual filesystem. Agents and tools that can read files – including coding assistants, file-browsing tools, and MCP-aware agents – can navigate the knowledge layer without needing to know document identifiers or query the API directly.

Experimental. The filesystem view is available in current Spectron releases but its structure and behaviour may change before stabilisation. Do not rely on the path conventions described here in production systems.

How it works

When an MCP client connects to Spectron's MCP server (/mcp), the server exposes a set of MCP resources alongside the standard tools. The filesystem view is one of those resources: it presents the knowledge store as a navigable directory tree.

  • Documents appear as files. Each ingested document is accessible as a file at a path derived from its title or original filename. The file content is the extracted text of the document, ready for the agent to read.

  • Knowledge nodes appear as directories. Entities extracted from the memory layer – people, projects, organisations, concepts – appear as directories. Each directory contains attribute files (key-value facts about that entity) and relation files (edges to other entities).

  • Scope is respected. The filesystem view only surfaces content visible to the authenticated API key. An agent key scoped to {org: "acme", agent: "planner"} sees only the knowledge reachable within that scope floor.

Directory structure

/
├── documents/
│   ├── architecture-spec.pdf.txt
│   ├── onboarding-guide.docx.txt
│   └── q3-roadmap.pdf.txt
├── entities/
│   ├── alice/
│   │   ├── name.txt
│   │   ├── role.txt
│   │   ├── location.txt
│   │   └── relations/
│   │       ├── works-at -> ../acme/
│   │       └── manages -> ../planner-agent/
│   └── acme/
│       ├── type.txt
│       ├── industry.txt
│       └── relations/
│           └── employs -> ../alice/
└── sessions/
    └── sess_01hx3.../
        ├── turns/
        │   ├── 001-user.txt
        │   └── 002-assistant.txt
        └── metadata.json

The exact path structure may evolve as the feature matures.

Use cases

The filesystem view is particularly useful when:

  • The agent uses file-reading tools – many agent frameworks expose read_file or list_directory as tool functions. The filesystem view makes Spectron's knowledge accessible through those tools without any Spectron-specific integration.

  • Document IDs are not available – when an agent needs to find a document by title or topic rather than by ID, browsing the documents/ directory is more natural than constructing a recall query.

  • Debugging and inspection – inspect the knowledge store structure through an MCP client without writing code.

  • Agent-to-agent knowledge transfer – an agent that builds up knowledge in one session can expose that knowledge as a filesystem resource for another agent to browse.

Accessing the filesystem view

The filesystem view is available through any MCP client connected to Spectron's MCP server. No additional configuration is required beyond the standard MCP connection.

In Claude Desktop, Cursor, or another MCP-aware tool, the filesystem view appears as a set of resources in the MCP resource list. The agent can use the resources/list and resources/read MCP methods to enumerate and read the virtual filesystem entries.

Example MCP resource URI pattern:

spectron://fs/documents/architecture-spec.pdf.txt
spectron://fs/entities/alice/role.txt

Manual access via MCP tools

If your MCP client exposes MCP resource access as tools:

{
  "method": "resources/list",
  "params": { "uri": "spectron://fs/entities/" }
}
{
  "method": "resources/read",
  "params": { "uri": "spectron://fs/entities/alice/role.txt" }
}

Enabling the filesystem view

The filesystem view is enabled by default when the MCP server is active. Set SPECTRON_FS_VIEW=false to disable it if you do not want to expose knowledge store contents as MCP resources.

Limitations

  • The filesystem view is read-only. You cannot create, modify, or delete knowledge nodes by writing to the virtual filesystem; use the standard memory operations API for that.

  • Very large knowledge stores may have slow initial enumeration. The view is not paginated at the filesystem level.

  • Symlinks in the relations/ directories are representational – they indicate graph edges but are not traversable as real filesystem symlinks in all MCP clients.

  • In-progress extraction (documents currently being processed) may not appear until extraction completes.

Next steps

Was this page helpful?

Previous

Embedded library