New to this? Start with AI Basics: Side-by-Side, a six-step walkthrough for going from a blank project to a populated graph using nothing but copy and paste. Come back here once you want to go deeper: live connections, persistent skills, and the full prompt library.
There are five ways to work with AI in Filamental, and they divide cleanly in two before anything else about them matters.
Three are live connections. The AI works inside your space continuously: it reads what is there, writes new nodes, draws connections, and you watch it happen. Use one of these for real work.
Two are one-shot transfers. You move something across once and the link ends there. Use one of these when the AI cannot reach your machine at all, which includes most locked-down work accounts.
| Where you type | Setup | Live or one-shot | Needs the app | |
|---|---|---|---|---|
| Filamental AI | In Filamental | Paste your own API key | Live, reads and writes | Yes |
| MCP | In your AI | One JSON entry, or one click for Claude Desktop | Live, reads and writes | Yes, and the space opened once |
| Folder access | In your AI | Nothing, plus the skill files | Live, reads and writes the files | No, the folder is enough |
| Export for AI | Any chat box | Nothing | One-shot, read only | Yes |
| Mermaid import | In your AI, then Filamental | Nothing | One-shot, into the app only | Yes |
What each one cannot do, which is usually the faster way to choose. Filamental AI knows only the space in front of it, since an API key arrives with no memory and no access to your other files. MCP needs the application, because it reads the index Filamental builds. Folder access has no index, so the AI reads files rather than searching them, which is slower on a large space. Export for AI is a snapshot and goes out of date the moment either side changes anything. Mermaid import carries the shape and not the substance, so the notes are a second step.
Skills are not a sixth method, they're the briefing. Every route needs the AI to understand what Filamental is and how a node file is put together. Filamental AI and MCP hand that over for you automatically, with nothing to install. The other three need you to supply it, which is what the skill files are for. What We Tell Your AI shows you the exact text either way.
A rough rule. If your AI runs on your machine, use MCP or folder access. If it cannot see your machine, use Export for AI or Mermaid import with a skill loaded. Filamental AI works regardless, because the app does the reaching for you.
Click the AI button in the top bar. Choose your provider from the list, paste an API key from it, and you're connected. Nothing else to install, no separate app, no Node.js.
It gets the same live read/write access to your open project that MCP gives Claude: search nodes, follow connections, create and edit content, define whole category and connector vocabularies, all from the chat window. Attach a PDF, image, or Word file straight to a message.
When a reply changes your project, an Undo these changes button appears under it and reverses everything that reply did. Changes made through MCP from another app can't be undone this way. More in Undo and Redo.
Filamental never sees or stores your key or your conversation, both stay strictly between you and your chosen provider. And to be clear about what this is: Filamental doesn't have its own AI, this is a plain wrapper around whichever model you connect. The header always says exactly which one, "Connected to: Claude" or whichever you picked, nothing blended or implied.
Multiple models: connect more than one and switch between them from the dropdown at the top of the chat, handy for a second opinion or a cheaper model for quick questions.
The providers we connect to
That's the full list of hosted providers rather than a sample, and the two on your own computer follow below. Kimi, Qwen and MiniMax each run an international and a China address, and each has its own entry in the list, so pick the one your key came from.
If the provider you use isn't there, email us at support@filamental.space and we're happy to add it. It's usually a small job, so do ask.
If you're on GPT or Gemini and want a live, no-copy-paste connection with the same reach MCP gives Claude, this is it.
On your own computer. Ollama (on this computer) and LM Studio (on this computer) are in the same list. Pick one and the box where the key would go becomes the address of the server, which we fill in with the usual one. Click Connect and Filamental lists the models you have loaded. There's no key, and nothing leaves your machine. The server has to be running first, otherwise you'll be told it couldn't be reached. Many local models can't call tools, which is how the AI edits your project, and one that can't will say so in its own words. Step by step in AI on Your Own Computer.
Reading documents. Filamental AI can also read a folder of documents, or a single document, and build a project from it. See Explore a Folder or Document with AI.
If you specifically live in another AI window rather than Filamental's own, connect over MCP instead. Same live read/write access, just from your AI's window rather than ours.
One prerequisite, and it is the only one that catches people out. The MCP server reads the index Filamental builds, so the space has to have been opened in Filamental at least once on that machine before any client can reach it. If it hasn't, the server stops with "Filamental database not found" and tells you exactly that. There is no way round it, and it means MCP is for people who have the app, not a way to browse somebody else's folder without it. (For that, see Folder Access below, which needs no index at all.)
What the AI is given. The briefing arrives in three layers and none of them need installing. The essentials land the moment you connect: what nodes, types and connectors are, how relationships work, and the conventions that keep a structure readable. Beyond that the AI can pull the full skill guide and the complete file format spec on demand, but only when a task actually calls for them. It's a better arrangement than pasting a skill in by hand, because nothing is spent on detail the job doesn't need.
Which world does Claude see? Whichever one is open/you last opened in Filamental, that's the reference point. (Filamental doesn't technically need to be running but in practice you'll have it open anyway.) The exception is a client configured with --vault, which is pinned to that one folder and doesn't follow.
How it differs from Filamental AI: functionally near-identical, the real difference is just which window you're typing in.
What the AI can do: You can have a full conversation about a topic and then say "turn this into a Filamental project folder" and it will do exactly that. It's exactly how we created the demos on the website. Come back later, ask it to read the folder again, and it's fully briefed in seconds, with a full relational understanding.
Two questions it answers without being walked through them. Ask how two nodes are connected and it finds the shortest chain of connectors between them and reads it back hop by hop (find_path), the same route the Pathfinder lights up in the app (see Pathfinder). And on a space it hasn't seen, it can ask for a short orientation (get_structure_report): which classifications and connectors are in use, the most connected nodes, the load-bearing ones that would split the structure if they went, how many separate groups there are, and what's unconnected or has no notes. Filamental AI has both as well.
Filamental handles the path resolution. The connection follows whichever world you have open, no restart needed if you switch worlds later. This is the only one-click route, and it's offered on Windows and macOS.
Every other client is hand-configured, and they nearly all take the same shape. Copy the exact paths for your machine from Settings > AI > Other AI apps:
{
"mcpServers": {
"filamental": {
"command": "node",
"args": [
"--no-warnings",
"/absolute/path/to/filamental-mcp/dist/index.js",
"--vault",
"/absolute/path/to/your/vault"
]
}
}
}Where it goes:
| Client | File |
|---|---|
| Claude Code | .mcp.json in your project root |
| Cursor | .cursor/mcp.json in a project, or mcp.json in ~/.cursor for all of them |
| LM Studio | its own mcp.json (0.3.17 and later, which is when it became an MCP host) |
| Claude Desktop, by hand | %APPDATA%\Claude\claude_desktop_config.json |
| Gemini CLI | settings.json in ~/.gemini for all projects, or .gemini/settings.json in one |
Codex reads a TOML file, config.toml in ~/.codex (or .codex/config.toml in a project you've marked as trusted), and the Codex CLI, its IDE extension and the ChatGPT desktop app all share it. Add a table with the same command and arguments:
[mcp_servers.filamental]
command = "node"
args = ["--no-warnings", "/absolute/path/to/filamental-mcp/dist/index.js", "--vault", "/absolute/path/to/your/vault"]On Windows, write those paths with forward slashes or in single quotes, because TOML reads a backslash inside double quotes as an escape.
Zed keeps them in its settings file under context_servers rather than mcpServers, with the same command and args. You can also add one from Zed's Settings > AI > MCP Servers > Add Server > Add Local Server, and a green dot there means it's running.
VS Code reads the same server but wants a different structure: the top-level key is servers rather than mcpServers, and each entry declares its type. Put this in .mcp.json or .vscode/mcp.json at the root of your project:
{
"servers": {
"filamental": {
"type": "stdio",
"command": "node",
"args": [
"--no-warnings",
"/absolute/path/to/filamental-mcp/dist/index.js",
"--vault",
"/absolute/path/to/your/vault"
]
}
}
}Paste the mcpServers version into VS Code and it will simply ignore it, with no error, which is a frustrating twenty minutes if you don't know to look for it.
The snippets above carry two absolute paths, and both are specific to your machine, so a file containing them is not much use to anybody else on the team. There is a version that travels:
{
"mcpServers": {
"filamental": {
"command": "npx",
"args": ["-y", "filamental-mcp", "--vault", "./knowledge"]
}
}
}npx fetches the server from npm rather than pointing at your install, and a relative vault path is resolved against the folder the client starts in, so ./knowledge means the same thing on every machine. That makes .mcp.json genuinely committable.
Each person still has to have opened that folder in Filamental once, because of the index. What the portable form removes is the path editing, not the prerequisite. It also needs Node on the path and is a little slower to start, so for your own machine the direct version above is still the better one.
There is nothing Claude-specific about the server. It speaks stdio, which is the most widely supported MCP transport, so any client that can start a local process and talk to it will work: Cherry Studio and Hermes among others, alongside the ones named above. If your client asks for a command and arguments, it can run this.
Open WebUI is the exception, and it's a real one. Its MCP support is HTTP-only by design, since it runs as a web application rather than a local process, and our server talks over stdio. It can be bridged with a proxy such as mcpo, but that's a self-assembly job and we don't support it.
Requirements: Node.js 22 or later; Filamental v0.2.4 or later; the space opened in Filamental at least once. Filamental AI above has none of these, so reach for that first unless you specifically live in one of these tools already.
For AI tools that read files on your machine directly: Claude Code, Cowork, or any agent with filesystem access.
Rather than connecting to Filamental at all, you point the AI at the project folder and let it read your notes as what they are, plain markdown files on disk. Install the two skill files below so it knows the format, and it can read your whole structure, reason across it, and write properly formed new nodes straight back into the folder. Hit refresh and they appear.
This is the method that turns Filamental into a genuine second brain rather than a graph you consult. The AI isn't visiting your structure through a window, it's working inside the folder alongside everything else you keep there.
Why you'd choose this over MCP:
Why you'd choose MCP over this:
Requirements: an AI with file access to your machine, and both skill files installed.
Skills are how you brief an AI that can't be briefed automatically. If you're on Filamental AI or MCP, the briefing is already handed over and there's nothing to install. If you're using folder access, Export for AI or Mermaid import, this is the piece that teaches your AI what it's looking at.
Reach for a skill if you're using ChatGPT, Gemini, or Claude.ai (the web version), none of which support MCP. A skill is a prewritten briefing you install once in your AI. It teaches the AI how Filamental works: the structure, node format, and type system. Once installed, pair it with a Export for AI snapshot (below) and almost any AI can work with your vault nearly as well as Claude does via MCP.
The skill files are also just readable documents. If you want to see how Filamental describes itself to an AI, or you'd rather write your own briefing, download them and read them. What We Tell Your AI shows the exact text sent to connected assistants.
Recently, the major AI platforms agreed to Claude's skill standard, so installation is fairly painless everywhere now. A "plugin" in an AI platform's own discovery menu is just a formal listing of skills, ours are already there to download that way if your platform supports it, as an alternative to manual install.
Install: Go to Customise > Skills > New Skill, then copy-paste the text from the two skill files.
The Filamental skill is two parts:
filamental_SKILL.md, the main briefing: working modes, scaffolding, session building, format compliance rules.filamental-format-reference, a companion covering the complete node file format spec, UUID rules, filename conventions, and the integrity checklist.In Cowork both install as separate skills and work together automatically. Elsewhere, both are distributed as files, install both for full capability. The main skill alone is enough for reading and analysis; the format reference is required whenever the AI is writing or generating node files.
What happens when the skill is active: the AI reads your .filamental/ config to learn your type vocabulary, reads whatever you've given it access to, then gives you a brief orientation and asks what you want to do. From there: gap analysis, new nodes, a briefing, a whole new project from scratch, or any question about the structure.
With Cowork or Claude Code: install both skills, then point the AI at your folder. See Folder Access above, that's the route this combination unlocks and it's the most capable one on this page.
With Claude.ai: paste SKILL.md into Project Instructions. At the start of each conversation, use the broadcast button (below) to export your snapshot and paste it in.
With any other AI: paste SKILL.md as a system prompt at the start of your conversation, then share your project snapshot.
Click the broadcast icon in the bottom bar and Filamental saves your entire world, every node, connection, and type definition, as a single Markdown file. It opens with a short Structure section that tells the AI what your world is made of and where the weight sits, before it reads a single note. Attach the file to any AI chat and start talking, or press Copy to clipboard in the confirmation to paste it instead. Quick and easy, and a good way to "one-shot" a conversation without any install step. What the Structure section holds is in Export for AI.
Paste it in with an opener like:
Here is my Filamental knowledge graph. I will follow up with specific questions.
[paste your world snapshot here]Tip for ongoing work: if you're coming back to the same world across sessions, create a Claude Project and paste your snapshot into the project instructions. Claude keeps that context persistently, just re-export and update the instructions when your world changes significantly.
A complete route in its own right, and the one that needs least from your AI. Talk a subject through in any chat tool, ask for the result as a Mermaid diagram, then import that diagram as a structure. No connection, no skill, no file access. Every AI worth using can produce Mermaid.
It's the fastest way from a conversation you've already had to something you can navigate, and it pairs well with the others: import the skeleton this way, then use one of the live routes to fill in the notes.
Conversation to Graph: append this to the end of any AI conversation to turn the discussion itself into a structure, no need to re-describe it.
Convert this conversation into a Mermaid flowchart I can import into a knowledge graph tool.
Rules:
- Opening line must be: flowchart TD
- Node IDs must use alphanumeric characters and hyphens only (e.g. payment-api not "Payment API")
- Node labels go inside brackets: nodeID[Label Here]
- Use [square brackets] for most nodes
- Use (round brackets) for processes or steps
- Use {curly brackets} for decisions or branch points
- Use ((double brackets)) for key goals or outcomes
- Connect nodes with --> for directed flow, --- for undirected, <--> for bidirectional
- Label edges where the relationship has a clear name: A -->|feeds into| B
- Aim for 10 to 20 nodes. Collapse minor details and keep the concepts that matter most
- Do not include subgraph, style, classDef, or click lines
Output only the Mermaid code block. No explanation before or after it.Create a structure from scratch: for a topic you haven't discussed yet. Nine times out of ten, just saying "turn this conversation into a mermaid chart code" is enough. For more control:
Generate a Mermaid flowchart of [describe your topic here].
Rules:
- Opening line must be: flowchart TD
- Node IDs must use alphanumeric characters and hyphens only (e.g. market-research not "Market Research")
- Node labels go inside brackets: nodeID[Label Here]
- Use [square brackets] for most nodes
- Use (round brackets) for processes or steps
- Use {curly brackets} for decisions or branch points
- Use ((double brackets)) for key goals or outcomes
- Connect nodes with --> for directed flow, --- for undirected, <--> for bidirectional
- Label edges where the relationship has a name: A -->|depends on| B
- Aim for 12 to 20 nodes. Focus on key concepts, not exhaustive detail
- Do not include subgraph, style, classDef, or click lines
Output only the Mermaid code block. No explanation before or after it.Replace the bracketed description with something specific, for example "the components of a SaaS startup's go-to-market strategy," or "how a payment transaction flows from customer to bank."
To import either result: Bottom toolbar > + button > Insert Mermaid diagram > paste > Build. The wizard asks you to map each shape to a node type, create new ones on the spot or assign to existing ones. Node titles are capped at 200 characters, if a Mermaid label is longer, that node will fail to import, shorten it first.
Do this after a Export for AI export (above).
Gap Analysis: ask Claude what's missing.
Looking at the knowledge graph I have shared with you, please identify:
1. Important concepts that appear to be missing from the graph entirely
2. Nodes that seem underdeveloped: isolated with few connections, or lacking in related ideas
3. Connections that are implied by the existing structure but not explicitly drawn
4. Any areas where the graph feels unbalanced: too much detail in one area, too little in another
For each finding, suggest a concrete action: a node to add, a connection to draw, or a note to write.
Keep your response structured and specific to the nodes and connections in this graph. Do not make generic suggestions that could apply to any knowledge graph.Expand a Node: ask Claude to develop one node further.
Looking at the node "[node name]" in the knowledge graph I have shared:
1. Suggest 5 new nodes that would meaningfully extend or connect to this one
2. For each suggestion provide:
- A short node name suitable as a file name
- Which entity type it should be, using the types defined in my graph
- One sentence describing what it represents
- How it should connect to "[node name]": the connection type and direction
Focus on genuine gaps in the current graph. Do not suggest nodes that are already there or that are close variations of what exists.id: on one of the other generated nodes.No direct integration yet. Workaround: download the doc as a file, then drop it into the folder or use the Insert menu (see Graph). Google doesn't play well with local files and wants your data in their cloud, we'll figure it out eventually.
A useful external resource for open-source intelligence work: osintframework.com. We've been told Filamental pairs well with Spiderfoot (OSINT automation), similar-looking tools, different jobs.
Still stuck? Email support@filamental.space.