@brain-core

Connectors

The four-tuple file coordinate, the URI vocabulary, and the host and brain connector kinds brain-core ships.

A connector is the driver behind a source kind; a source is one mounted data location of that kind (see Sources). Each source has a slug, and that slug is a URI scheme — every file in the platform is addressed as <source>://<path>. The runtime contract is described in the connector port; this page covers the vocabulary brain-core ships.

The coordinate four-tuple

Every file artifact lives at the coordinate (uri, connector, os_uri?, container_dir?):

  • uri — <source>://<path>, the stable identity used by tools, routes, the UI, and the vector index.
  • connector — the connector instance bound to that source slug at boot.
  • os_uri — optional full host-OS path. When the platform runs inside a container and no host mirror path is configured, the connector refuses with a structured error instead of fabricating a path — the UI and the vector index keep os_uri empty rather than a stale guess.
  • container_dir — optional container-side path counterpart, used when a shell or skill script needs to execute against the file.

The host-versus-container split is why a host source on this server has two fields: root (the path inside the container, required — or a path relative to the project, which each side joins onto its own project folder) and hostRoot (the same folder on the machine). A server running in Docker reads root; a server running natively on the machine reads the hostRoot beside an absolute root. The server fills in whichever half it can derive — under the Neuralis data home, or under a mount it knows the host folder of — so a source attached on one side opens on the other over the same data home, and a create request whose hostRoot contradicts that derivation is refused. The source listing shows these paths only to someone who could attach that source or can read its root, and the last sync's error text only to someone who may run syncs; everyone else sees the connector kind and a generic "the last sync reported errors".

URI vocabulary

SchemeConnector kindWhat it addresses
data://hostThe project's data zone — the default working area for agents and uploads
brain://brainVector-only memory backed by the index, agent-scoped by default
packages://hostThe project's package drop-zone (_packages/)
app://hostThe platform app zone — a privileged mount (sources.privileged); agent writes are denied
the machine source's slug, e.g. machine-ops://webtopA machine sandbox, contributed by machine-core
custom slugsanyEvery additional source you attach — the slug you choose becomes the scheme (repo://, notes-alex://)

Connector kinds shipped by brain-core

host is a folder as a source — on this server, or on a paired device through its broker — with ONE set of answers wherever the folder lives: list, read, rawRead, stat, write, delete, move, mkdir, rmdir, scanDelta, walk, count, peekCount, scanContent, subscribeEvents, resolveOsUri — every capability in the port except exec and its execDetached companion. stat answers "is this still there" without transferring the file. It blocks symlink traversal and .. escape and refuses explicit access to the platform app zone. Code execution is NOT a connector capability — shell/skill scripts run through the execute tool, gated per-path by the uri-policy exec permission, not by the connector.

brain is the Qdrant-backed internal memory, with the list and read capabilities. It is discoverable like any other kind, but reads and writes are serviced by the filesystem service against the vector index — there is no on-disk tree behind it, and no os_uri. Viewer roles are read-only on brain:// by default.

brain-core also declares an in-process Git MCP connector for git-backed sources; its human and agent faces are the Git Control panel and the git skill.

Other packages contribute further kinds through their manifests — for example the webtop kind from machine-core, whose source is addressed by its own slug (machine-ops:// for a user's desktop). The registry, capability checks, and the trust gate are the same for every kind. Connectors never enforce policy themselves: every gate sits one layer above them, which is why a route or tool is the safe way in.

On this page