Claude Code has your repository, your folders and whatever it has learned about the work. What it doesn’t have is anywhere to leave the reasoning except a message. Give it a space and it writes that out as a structure beside the code, which the next person’s agent reads as readily as yours does. Free on every plan, with nothing of ours in the path.
Create .mcp.json at the root of the project:
{
"mcpServers": {
"filamental": {
"command": "node",
"args": [
"--no-warnings",
"/absolute/path/to/filamental-mcp/dist/index.js",
"--vault",
"/absolute/path/to/your/vault"
]
}
}
}Copy both absolute paths from Settings, then AI, then Other AI apps inside Filamental rather than typing them out, since the server ships with the application and lands somewhere platform-specific. Claude Code picks the file up automatically the next time it starts in that folder.
The --vault argument pins the connection to one space rather than whatever the app has open, so a repository is always joined to its own structure.
Committing that file won’t work, though. Both paths in it are specific to your own machine, so a teammate who clones the repository gets a config pointing at nothing. There’s a version that travels:
{
"mcpServers": {
"filamental": {
"command": "npx",
"args": ["-y", "filamental-mcp", "--vault", "./knowledge"]
}
}
}npx fetches the server from npm and a relative vault path resolves against the folder Claude Code started in, so this one is genuinely committable. It wants Node on the path and starts a shade slower, so the direct version is still better on your own machine.
A space is a folder of Markdown files with the relationships written into the YAML front matter, so Claude Code can read the folder and have the structure, with no server, no configuration and no restart. Two documents make it fluent, both published here in full: the skill file and the file format reference. With those it writes properly formed nodes straight back into the folder, and they appear in the app as they land. It’s the route we’d suggest first if you already keep an agent pointed at your project directory.
Over MCP, by contrast, asking about one thing pulls that thing and its neighbours as one document, which on our own help came to a fraction of the text.
Code records what was built and the tracker what was asked for. Neither holds why the boundary sits where it does, which constraint ruled out the obvious approach, or which of last year’s decisions are still load bearing.
A space holds it the way the team’s systems thinker holds it, as things and relationships, so supersedes, blocks and was rejected because are different connections, and asked which decisions a change touches, the model follows them rather than grepping for keywords and hoping.
An agent can already produce a summary or a commit message, all prose the next machine has to parse back into a structure. Writing to a space skips that round trip, since the typed connections are the artefact, in Markdown files beside the code.
Somebody who clones the repository in two years points their own agent at the same folder and it arrives briefed, and a client or an auditor handed the folder needs no account and no copy of this application.
Over MCP a short briefing arrives on connection, covering what nodes, categories and connectors are and the conventions that keep a structure readable, and the full skill guide and format specification are pulled on demand only when a task calls for them. Over the folder route you install the same two documents yourself.
Either way they’re the same two files, published here word for word as they’re sent. Filamental has no account and no telemetry, and the MCP server is a local process with no network access of its own.
One prerequisite catches people out. The server reads the index Filamental builds, so the space has to have been opened in the app at least once on that machine. To read a folder somebody sent you, point the AI at the files directly, since a space is plain Markdown and no index is involved.
You need Node.js 22 or later and Filamental v0.2.4 or later. The MCP server itself ships inside the application, so there’s nothing separate to install, and it’s also published on npm as filamental-mcp if you want it on a machine with no Filamental on it.
Unlike the one-click Claude Desktop route, this one is hand-configured and therefore works on Windows, macOS and Linux alike.
Free on the Personal plan, which is free permanently with no account and no card, and not reserved for a better tier. Professional is $120 a year, or $12 a month, and keeps a big space whole, sends a finished structure to somebody who doesn’t have Filamental as a link or a single HTML file, and presents it.
Create a file called .mcp.json at the root of your project with an mcpServers entry named filamental, running node against the bundled server and passing your space folder after a --vault argument. Copy both absolute paths for your own machine from Settings, then AI, then Other AI apps inside Filamental rather than typing them out. Claude Code picks the file up automatically the next time it starts in that folder.
Because that’s how Claude Code reads MCP configuration, and here it turns out to be the better arrangement, since the --vault argument pins the connection to one space instead of following whatever Filamental has open, so a repository is always joined to its own structure. Committing .mcp.json only helps if you use the portable form, because the ordinary one carries two absolute paths specific to your own machine. Set the command to npx with the arguments -y and filamental-mcp, give --vault a relative path, and the file works for everyone who clones it.
Yes, and for an agent with filesystem access it’s often the better route. A space is a folder of Markdown files with the relationships written into the YAML front matter, so you can point Claude Code at the folder and it reads the structure directly with no server, no configuration and no restart. Install the skill file and the file format reference alongside it and it can also write properly formed new nodes straight back into the folder.
The part of a codebase that has nowhere to live: why a boundary sits where it does, which constraint made the obvious approach wrong, what a migration was meant to unblock, and which decisions are still load bearing years later. Code records what was built and issue trackers record what was asked for, but the reasoning that joins them usually survives only in the heads of whoever was there, which is why onboarding costs what it does.
No. The MCP server is a separate local process that reads the same folder and the same index, so it works whether or not the application window is open, and the --vault argument means it doesn’t depend on which space you last had open either. In practice you’ll usually have Filamental open beside it, because watching the structure change as it is written is most of the point.
Nothing. It’s free on the Personal plan, which is free permanently with no account and no card, and it isn’t metered or credited, because there’s no server of ours in the path to meter it at. The paid tier, at $120 a year or $12 a month, adds shared links, updates to a link already sent, the HTML download and presenting.
Let it read the code, then ask for the constraints and dependencies as a Filamental space. What comes back is a first draft you can correct, which is a considerably better starting point than an empty canvas.