# Introduction > What Filement is, how it is put together, and where to start reading. Filement is a workspace for project files that also keeps track of what those files mean. It looks and behaves like a file manager: projects, folders, documents, click to open. Underneath, it records the context that usually lives only in people's heads: what a document is, what it answers, what replaced it, and what else matters around it. That context then goes wherever the work goes. A teammate opening a folder sees it. The built-in assistant uses it when it answers. AI tools such as Claude Code, Codex and Cursor can read it over MCP, under the same access rules as the people in the workspace. ## Two layers, kept apart - **The files you organise.** Your projects and folders stay exactly as you arranged them. The AI suggests; only you, or a tool you connected, move anything, and every such change can be undone. - **The context around them.** Notes people write, relationships between documents and folders, summaries, and connections the AI suggests. All of it sits one click deeper than the file browser, so the first thing you see is always a plain file manager. Where a person and a model both say something about a document, you can always tell which is which. ## Where to go next - New here: [Getting started](https://filement.app/docs/getting-started.md). - How the pieces fit: [How Filement works](https://filement.app/docs/concepts/how-it-works.md), then [Notes](https://filement.app/docs/concepts/notes.md) and [Relationships](https://filement.app/docs/concepts/relationships.md). - Day-to-day use: the **Guide** pages, starting with [Projects, folders and documents](https://filement.app/docs/guide/files-and-folders.md). - Connecting an AI tool: [Connect an agent](https://filement.app/docs/agents/connect.md). ## Reading these docs as an agent Every page is plain markdown, available three ways: - add `.md` to any docs URL, for example `/docs/getting-started.md`; - request any docs URL with the header `Accept: text/markdown`; - read [`/llms.txt`](https://filement.app/llms.txt) for an index of every page, or [`/llms-full.txt`](https://filement.app/llms-full.txt) for all of them in one file. The same files live in the `docs/` folder of the repository, so what you read here and what is in the source are always identical. Source: https://filement.app/docs --- # Getting started > Create an account, make your first project, add documents, and give them context. This takes about five minutes and covers the whole loop: files, notes, a relationship, and a question answered from your own documents. ## 1. Create your account Open the app and choose **Create one** on the sign-in screen. Enter your email and a password, then type the six-digit code sent to your email. It submits itself on the sixth digit. It expires in 15 minutes; if it doesn't arrive, check your spam folder, then ask for a new one (offered again 30 seconds after the last). Your account comes with a workspace of its own; you can invite people to it later, or create more workspaces. ## 2. Make a project A project is the top-level container for one piece of work: a client engagement, a product, a research effort. Choose **New project** and give it a name. ## 3. Add documents Inside the project you can: - **Upload files** by dragging them in. Any file type uploads and previews. Text and markdown files are also read, so they can be searched and summarised. - **Write a document** with **New document**. Documents are markdown and open in an editor several people can use at once. - **Make folders** with **New folder**, and nest them however you like. If you upload a file that is already in the workspace, Filement tells you instead of storing a copy. If you upload a different file with the same name, it asks whether this is **A newer version of it** or **A separate document**. ## 4. Say what things are Open a document and add a note: one short line saying what it is. "Signed-off requirements from the March call" or "Draft, not agreed yet" is exactly right. Notes on a folder apply to everything inside it. See [Notes](https://filement.app/docs/concepts/notes.md). ## 5. Connect related documents Drag one document onto another, or use **Connect to…**, to record a relationship: this one _references_, _responds to_, _supersedes_ or is _related to_ that one, with a short reason. Filement will also suggest connections it finds, marked as AI-suggested. See [Relationships](https://filement.app/docs/concepts/relationships.md). ## 6. Ask a question Choose **Ask Filement** and ask something only your documents can answer, such as "what did the client change in the second version of the requirements?". The answer names the documents it read. ## 7. Bring your AI tools Open **Settings → Agents** and connect Claude Code, Codex, Cursor or another MCP client. It gets the same files, notes and relationships, limited to what you can see. See [Connect an agent](https://filement.app/docs/agents/connect.md). Source: https://filement.app/docs/getting-started --- # How Filement works > The two layers, the files people organise and the context around them, and why they stay separate. A file system answers "where did I put this?". Search answers "which files contain these words?". Neither answers the questions people actually get stuck on: - What is this document, and is it still current? - What replaced it, and what responds to it? - What else do I need to read to understand this piece of work? - Can someone else, or an AI tool, pick this project up without me explaining it? Filement answers them with two layers that complement each other. ## The file layer Projects contain folders, folders contain documents and more folders. It works the way a file manager does, because that is how people remember where their work is. You decide the structure. The AI layer reads it and never changes it on its own. A model can suggest where a file belongs, but a file only moves when a person presses the button, or when an AI tool you connected does it for you, and then Activity lists the change so you can undo it. Folder location is itself context. A document inside `Client A / Authentication` is about authentication for client A, and Filement uses that when it searches and answers. ## The context layer Around the files sits everything that explains them: | Piece | Who writes it | What it does | | ----------------- | -------------------------- | ------------------------------------------------------------- | | **Notes** | People | One line saying what a folder or document is, or its status | | **Relationships** | People, or suggested by AI | Typed, directional links with a reason | | **Summaries** | AI | A short gist and topics for each readable document | | **Search index** | AI | Lets search find passages by meaning, not only by exact words | | **History** | Automatic | Every version of every document | ## One click deeper The file browser is the only thing you see at first glance, and it contains nothing but file-manager behaviour. Relationships, summaries, the knowledge graph, AI suggestions and version history are all one interaction away: open a document's insights, open the graph, ask the assistant. Someone who only wants a tidy shared drive never has to deal with the rest. ## People and AI stay distinguishable A note is always written by a person. A relationship always records whether a person drew it or a model suggested it, and suggested ones look different everywhere they appear: in a document's insights, in the graph, and in what agents read over MCP. When the two disagree, a person's word counts for more. ## The same context, everywhere Everything above is available in three places, with the same permissions: - **In the app**, for you and your teammates. - **In the assistant**, which searches the workspace, reads what it finds, and cites it. - **In external AI tools**, over [MCP](https://filement.app/docs/agents/connect.md). - **In chat apps**, starting with [Zoho Cliq](https://filement.app/docs/guide/zoho-cliq.md): save a file from a chat, or ask the assistant without leaving it. A folder someone cannot open in the app does not exist for their assistant or their agents either. Source: https://filement.app/docs/concepts/how-it-works --- # Notes > One human-written line on a folder or document that tells people and AI what it is. A note is a short line on a folder or a document that says what it is. It is the single most useful piece of context you can add. > Signed-off requirements from the 12 March client call. Supersedes the January draft. ## One line, two readers The same note does two jobs: - **People** see it in the file browser and on the document, so a teammate knows what they are looking at before opening it. - **AI** receives it alongside the document whenever the document is read: by the assistant, and by agents over MCP. It is treated as more reliable than the model's own reading of the text. There is no separate "instructions for the AI" field. What you would tell a colleague is what steers a model well. ## Folder notes cascade A note on a folder applies to everything inside it, at any depth. Frame a whole area once: > Everything in here is from the 2025 engagement and is historical. Every document below then carries that framing, together with its own note. ## Good notes - **Say what it is and its status.** "Draft", "agreed", "superseded by V2", "meeting notes, unreviewed". - **Keep it short.** Notes are capped at one line's worth of text on purpose. - **Update it when the status changes.** Editing a note does not create a new version of the document; it describes the document rather than being part of it. ## Suggested notes When Filement reads a document that has no note, it drafts one. The suggestion is offered for you to accept or change, and Filement never writes it on its own. An unaccepted draft isn't a note, and nothing treats it as one. You will meet it in three places: - **On the document**, under the title, with **Use as note** and **Edit first**. - **On the board**, as a small ochre halo at the card's top-right corner. Right-click the card (or use its **⋯** menu) and choose **Add a note** to read the draft and accept it. A stack shows the same mark when any document in it is waiting on a note; open the stack and the row wearing it is the one it meant. - **Over MCP**, as `suggestedNote` on a document in `list_folder`. It's a separate field from `note`, so an agent can always tell a draft from what a person wrote. An agent that agrees with one passes it to `set_note`. The dot and the field both disappear the moment the item has a note of its own. ## What a note is not A note steers; it does not enforce. "Ignore this file" makes a model far less likely to rely on a document, but it does not hide it. Anything that must not be read belongs behind [folder access](https://filement.app/docs/guide/workspaces-and-access.md). Source: https://filement.app/docs/concepts/notes --- # Relationships > Typed, directional links between documents and folders, drawn by people or suggested by AI. Folders say where something lives. Relationships say how it connects to things that live elsewhere: the implementation that answers a requirement, the version that replaced a draft, the feedback on a release. ## Four types Every relationship has one of four types and a required reason. | Type | Read as | Use it when | | --------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------ | | **references** | references / referenced by | It mentions or points at the other, without depending on it | | **responds to** | responds to / answered by | It addresses, implements or answers the other | | **supersedes** | supersedes / superseded by | It replaces the other; this is the version that counts now | | **related to** | related to | They are connected, but not in one of the specific ways above (drawn by people; the AI uses threads instead) | Relationships have a direction. "Requirements V2 _supersedes_ Requirements" shows on V2 as _supersedes_ and on the original as _superseded by_. Either end can be a document or a folder, so "Client feedback _responds to_ the Release 1 folder" works too. ## Drawing one - **Drag** a document or folder onto another document. - Or use **Connect to…** on either item. Pick the type, write the reason, save. Dropping onto a _folder_ moves the item instead; dropping onto a _document_ relates them. ## AI-suggested relationships When you add or change a document, Filement compares it with the rest of the workspace and suggests the specific connections it finds: a newer version, a reply, a citation. Suggestions are marked as AI-suggested, sit in their own section of a document's insights, show dashed in the knowledge graph, and carry a confidence score. Hover a suggestion to see the score, or read it under the suggestion on a touch screen. Filement learns the score from what people in your workspace kept and turned down before, not only from the model's own guess. The AI doesn't suggest plain **related to** links. Documents from the same piece of work go into the same **thread** instead (below), which says it once for all of them. For each suggestion you can: - **Keep this connection**, which makes it your relationship. It remembers it began as a suggestion. - **Dismiss** it, which removes it and stops the same pair being suggested again. - **Leave it.** It stays a suggestion until later reading contradicts it. Relationships that AI tools create over MCP count as AI-suggested too, even though they arrive under your account, because a model decided them. ## Threads, versions and Activity Filement keeps three things up to date on its own, so a workspace gets easier to read as it grows. **Versions.** Copies, re-downloads such as `plan(1).md`, drafts, and v1/v2 of one document form a family with one current version. When the text proves it, the family shows as one card on the board ("3 versions") with the older ones tucked behind it. When it's only the AI's reading, older versions stay visible, greyed, with "Newer: …". **Versions…** in an item's menu lists them, and **Not the same document** separates one for good. **Threads.** A thread is one piece of work across documents and folders: the request, the spec, the status reports, the reply, the decisions, the plan. It has its own page with a dated timeline, where the work stands, what was decided and what is still open. On that page, hover a document to see what it's connected to, and click "answers …" to jump to the document it names. Click a decision or an open question to go to the document it came from. Hovering a card anywhere outlines everything in its thread and family. A folder's **Brief** lists the threads in it. A thread never mixes documents from areas with different access. **Activity.** Activity lists every change the AI makes, and every change something makes on your behalf, in plain words and in groups. A group is one connected agent's working session (its changes until it has been idle for half an hour), one conversation with the assistant, one upload or file saved from chat, or one reading of a document. **Undo all** (just **Undo** on a group of one) takes a whole group back, newest change first, so a chain unwinds in order. Say an agent made a folder, moved files into it and edited one: the edit is reverted, the files move back, and the folder goes to Trash. You can undo any single change on its own too. A change someone has touched since stays as it is, and the list says so. Undoing never loses anything: created items go to Trash, and edits come back as a new version. ## Connected items stack together When you connect two things that sit in the same folder, they collapse onto one card there: a small pile with a count, so you can see the connection while you're just browsing. **Click the pile** to open its route view. The pile lifts into a panel where it stands and reads top to bottom. Each connection gets its own line with the type in its colour, the reason whoever drew it wrote, and the item it leads to. It reads oldest first: the original document, then what superseded or answered it, then whatever came from _that_. So each line is labelled the way you read it. The spec is "answered by" the implementation, even if you drew the connection as "responds to" from the other end. Connections chain, and they branch. A line runs from each item to the one it leads to, in the relationship's colour, with the label hanging off it. A chain runs straight down one column; where two things came out of the same item, each branch is indented under it. The route view is the only way a stack is shown, because it's the only view that shows both the shape and the reasons. The page behind dims while the panel is open. A press anywhere outside closes it, and so does Escape. From the panel you can open any item or use its menu as anywhere else, and **Open in the graph** hands a tangled one to the knowledge graph, which has pan, zoom and filters. Drag a member out onto an empty slot on the board to separate it again; the connection stays. ### Connecting to something inside a stack Drag a file onto a stack and **hold for a moment**. The route view opens while you're still dragging, and dropping on any row connects to that item. That's how you link to something in the middle of a chain, not just to the card on top. ## Where you see them - **In the folder itself.** Connected items stack onto one card that opens to the route view. - **In a document's insights.** Relationships people added come first, with AI suggestions in a separate section below. - **In the knowledge graph.** Every connection in the workspace or one project, solid for people and dashed for AI. See below. - **For agents.** MCP tools return the two groups separately. See [Tools](https://filement.app/docs/agents/tools.md). ## The knowledge graph Open it from the sidebar. It draws the connections in the workspace, solid for connections people added and dashed for ones Filement suggested, with an arrowhead for the directional ones. Lines are grey until you point at or select an item. Then that item's lines show in the colour of their relationship type. Filement groups what it already knows belongs together, so the graph stays readable as it adds connections: - **Versions of one document are one card.** Drafts, copies and earlier versions stack behind the newest one, and the card says how many there are ("3 versions"). Connections to any of them are drawn to that card. Select it to see the versions and how each connection reached it. To see every version as its own card, switch **Current** to **All versions**. - **A thread is a shaded area.** The documents in one thread sit together inside an area labelled with the thread's name. Click the name to see where the thread stands, what's open and what was decided. Double-click it to open the thread. Drag the name to move the whole thread. - **Zoom out and the threads take over.** When cards get too small to read, each thread shows its name in large type and a single line joins two threads, labelled with how many connections run between them. - **Lines that repeat something are hidden until you look.** A "related to" link between two documents in the same thread says the same thing as the thread. A chain of "supersedes" links already says the oldest version was replaced. Those lines appear when you point at or select one of their items. Filement works the layout out from the connections themselves, and it's the same every time you open the same workspace, so you can find things where they were last time. **Re-arrange** moves everything, and so does switching between **Current** and **All versions**. Dragging a card moves just that card. Filtering never moves anything. To narrow it down: - **Find in graph** (or press `/`) lights up items whose name matches and fades the rest. - **Types** and **People / Suggested** take whole classes of connection off the canvas. - **Projects** appears when the workspace has more than one. A connection stays on screen if either end is in the project you picked, so links that leave the project stay visible. **Click an item to focus it.** Everything more than one hop away fades, and the canvas frames the neighbourhood. The panel on the right lists that item's connections with the reason someone gave for each, who added it, and, for suggestions, how confident Filement is. Accept or dismiss a suggestion right there. Use the **1 / 2 / 3** control to widen the focus to two or three hops. Double-click an item, press `Enter`, or use **Open** to go to it. `Esc` clears the focus. Right-click any item for the usual Rename, Move, Connect and Trash. Source: https://filement.app/docs/concepts/relationships --- # Projects, folders and documents > Organising work in Filement. Creating, uploading, moving, renaming, versions and duplicates. The file browser is the first thing you see, and it behaves like the file managers you already know. Click a folder to open it, click a document to read it, and use the breadcrumb or Back to go up. ## Projects A project is the top level of your workspace: one client, product, or body of work. Create one with **New project**. Projects appear in the sidebar, and the home screen shows them next to your recent documents. ## Folders Use **New folder** inside a project or another folder, and nest as deep as the work needs. Two folders side by side can't share a name. A folder can carry a [note](https://filement.app/docs/concepts/notes.md) that applies to everything inside it, and you can [restrict it to specific people](https://filement.app/docs/guide/workspaces-and-access.md). ## The sidebar The button at the top of the sidebar, beside the Filement name, hides the sidebar and gives the page the whole window. The button then moves to the left of the top bar, where it shows the sidebar again. ⌘+\\ does the same. Filement remembers the choice in this browser. On a phone the same button opens the sidebar as a drawer. ## Documents There are two kinds: - **Markdown documents**, made with **New document** or by uploading a `.md` or `.txt` file. They open in the [editor](https://filement.app/docs/guide/writing-and-editing.md). - **Uploaded files** of any other type: PDFs, images, spreadsheets, anything. You can preview and download them, and Filement reads what is inside so search and the assistant can find them by their contents. See [What gets read out of a file](#what-gets-read-out-of-a-file). ## Arranging a folder A folder, and a project's top level, is a board you arrange yourself, the way you arrange apps on a phone. Drag a card between two others and a slot opens for it; everything after it shifts along. Everyone in the workspace sees the same arrangement. There is no sort order to pick. Where you put something is the order, and it reads the same on a wide screen or a narrow one, because Filement stores the order and not a spot on a grid. While you drag, the grid shows faintly underneath so you can see where the card will land. On a touch screen, press and hold a card to pick it up, and tap it to open it. Press and hold only ever starts a drag. The card's **…** button is its menu. Tapping the empty space around the cards does nothing, so scrolling the board can't open something by accident. Press and hold that empty space for the New menu. Drop a card **on the middle of another one** to combine them instead. Onto a folder moves it inside; onto a document [connects the two](https://filement.app/docs/concepts/relationships.md). Once the card you hold is over the middle of another, it locks onto it: the target lights up and says what dropping there would do (_Move into_ or _Connect_), and the rest of the board holds still until you move away, so your target can't shift under you. Connected items sit together in one slot as a small fan of cards. Click it to see how they are connected and why. Right-click the fan, or use **…** at the top of an open one, for what you can do to all of its cards at once: re-check them with AI, move them, lock or unlock them, or move them to Trash. To connect to one particular card inside a fan, hold your card over the fan for a moment. It opens mid-drag and you can drop onto the one you mean. ### Selecting several cards With a mouse, **drag across the empty space** around the cards to draw a box: every card it touches is selected. Hold **Shift**, **Cmd** or **Ctrl** while dragging to add to what's already selected, or while clicking a card to add or remove just that one. A fan of cards is selected as a whole. **Cmd+A** (Ctrl+A) selects everything on the board, and **Esc** or a click on empty space lets go. A bar at the bottom says how many are selected and what you can do with them: download them as one zip, move them, re-check them with AI or move them to Trash (**Cmd+Backspace** or **Delete** does the same), with anything else under **…**. Right-click any selected card for the same actions. The menus only offer what works for every selected item: Lock or Unlock appears when they are all locked or all unlocked, and with exactly two selected you can connect them, or open two documents side by side. Right-clicking a card outside the selection lets go of it and opens that card's own menu. Selecting is for mouse and trackpad; on a touch screen, press and hold still picks a card up. ## Uploading Drag files into any folder, or use the upload button. A panel opens as soon as you drop, grown out of the drop target, with one row per file and its progress. You can fold it down to a small pill and keep working. It follows you to other folders, and after a refresh or on another device it comes back folded until you've answered everything in it. The expand button, or a double-click on its title, grows it to the full height of the window. - **Exact duplicates** never upload. If the same file already exists in the workspace, its row tells you where, and Filement doesn't store it twice. - **Same name, different content** gets a question in the file's row: - **A newer version of it** keeps one document and adds a version you can roll back to. - **A separate document** keeps both and renames the new one, so nothing is overwritten. - **Your browser compresses photos and video before sending them.** A camera photo carries megabytes of detail no screen will show, so the browser resizes it to 2048px on its long edge and saves it as WebP. Video becomes a 1280px MP4. This happens on your machine before anything uploads, so nothing is sent twice, and the location data cameras write into photos doesn't survive it. Two things follow. A compressed file is **renamed to match** what it now is, so `photo.jpg` is listed and downloaded as `photo.webp`, and the name always tells you what the file is. And anything that wouldn't gain is **left exactly as it is**: an image that is already small, an animated GIF, an SVG, a clip that comes out no smaller, or a file this browser can't read. PDFs, documents, spreadsheets, archives and everything else that isn't a photo or a video are stored byte for byte as uploaded. ## Connections suggested as you upload While the panel is open, Filement reads each file you upload against the rest of the workspace and suggests what it belongs with: - **Newer version of, Earlier version of, Copy of.** The file is a revision of a document already here, the original of one, or the same document again (a re-export to PDF, say). Filement compares the text itself, the names (`v2`, `final`, dates) and the file's own modified date, so it still recognises an old original uploaded today as the older one. - **References, Responds to**, and their reverse, _Referenced by_ and _Answered by_. One document cites, answers or implements the other. - **Belongs in…** The folder you dropped into has subfolders, and one of them is clearly a better home, judging by the folder's note, what is already in it and where the file's related documents live. **Move there** moves it; **Keep here** leaves it. By default Filement files a new file for you when it's sure: it moves the file to where it belongs, and keeps a copy, version or reply connection as your own. Those rows say **Automatic**, and **Undo** on the row puts it back as a suggestion. What it isn't sure of, and every citation, waits for you. To confirm everything yourself instead, set **Organizing new files** to **Ask me first** in **Settings → Preferences**. Every suggestion comes with a one-sentence reason. **Keep** makes it your own connection, **Not related** dismisses it for good, and **Change** keeps it as a different type or pointing the other way. You can undo any of it from the same row. Suggestions stay dashed until you keep them, the same way AI-suggested connections look everywhere else. Filement doesn't link files from the same piece of work to each other one by one. Each file joins a **thread** instead, the whole piece of work in date order, and its row says which ("In thread _Mobile launch_"). Copies and older drafts join a **family** with one current version, and the board shows the family as one card ("3 versions"). The panel sums it up at the top ("11 files → joined _Mobile launch_ · 2 families · 3 to confirm"), and **Undo all** takes back everything the review did. You don't have to answer. Close the panel and unanswered suggestions stay in the document's **Insights**, like any other suggestion. Filement only ever suggests documents you can open and folders you can add to. A review you haven't finished shows up on the **Reviews** page: one you closed the tab on mid-upload, or one for a file you [saved from Zoho Cliq](https://filement.app/docs/guide/zoho-cliq.md). The page appears in the sidebar only while something is waiting. Each entry says what is left (links to answer, files to place, files still being read). **Open** brings the review back in the panel, **Accept all** keeps every suggested connection and moves every file to where it belongs, and **Done** clears it from the list. Unanswered suggestions stay in each file's Insights. ### Re-checking files already filed Filement can read files it has already filed again: where each one belongs, and what it's a version, copy, reply or citation of. Use **Re-check with AI** on a file or folder's menu (a folder re-checks every file inside it), **Re-check project with AI** on a project's menu, the re-check button in a fan's header, or the bar at the bottom when several cards are [selected](#selecting-several-cards). It doesn't re-read the file's text or rebuild its search index. It only asks the placement and connection questions again, and opens the answer in the same panel an upload uses. Up to 100 files are re-checked at once. A re-check is a fresh look. It ignores what was decided before: a pair you marked **Not related**, or undid, is judged again on what the files say now, and so is anything you undid after it was filed automatically. Refuse it again and it stays refused for ordinary uploads. A re-check can question connections you made yourself. If it reads two files differently (a newer version where you said one references the other), it asks **Change it** or **Leave it**; if it reads them as not connected at all, **Remove it** or **Leave it**. It never changes your own connections by itself, even with automatic filing on, and **Undo** puts yours back exactly as it was. ## What gets read out of a file Uploading does more than store bytes. Filement reads the text out of the file so you can search it and the assistant can quote it: - **PDFs, Word documents, spreadsheets and slide decks** (`.pdf`, `.docx`, `.xlsx`, `.pptx`) have their text extracted. A spreadsheet is read sheet by sheet with each row on a line, and a deck slide by slide with its speaker notes. - **A Word document opens as a document.** Its headings, lists, tables, links and footnotes are kept, so it reads like any other document here, with an outline you can jump around. The assistant can also go straight to a section by its heading. A line at the top says who wrote the file and when it was last saved, from the file itself, and how many pictures aren't shown. Press **Original** at the end of that line to see the file as it looks in Word, with its fonts, page layout and pictures, and **Text** to go back. Word documents can't be edited in Filement: the text shown is read out of the file you uploaded. - **Plain text** is read whatever it's called: `.csv`, `.json`, `.yaml`, source files, logs, and anything else whose contents are text, such as a code snippet saved from a chat as `Untitled.coffee`. Text saved as UTF-8, UTF-16 or in an older Windows encoding all reads correctly. - **Images** get a description instead. A model writes down what the image shows and any text legible in it, so you can find a screenshot of an error message by searching for the error. - **A scanned PDF**, where the pages are pictures of text, has nothing to extract. The document says so, instead of leaving you to find out through a search that returns nothing. - **Very long files** are read up to a limit. When the text stops short, the document says so. This runs in the background, usually within seconds of the upload. Wherever it can, extraction runs in your own browser, and nothing is sent anywhere until it has. Filement works through a large upload a few files at a time, so it can take a while for every file to be searchable and summarised. Anything that fails is retried on its own. If you run the workspace, **Settings → General** lists, under **Background work**, what is still being read or indexed and what failed, with a **Retry** for the failures. ## The item menu **Right-click anything** (a card on the board, a folder in the sidebar, a line in the recently edited list, a node in the knowledge graph) for Open, Download, Rename, Add a note, Move to…, Lock and Move to Trash, plus two groups. **Share ▸** holds Copy link, Public link… and Who can see this…; **Connections ▸** holds Connect to…, Versions…, Show related and Re-check with AI. Point at or click a group to open it beside the menu (the menu steps back while it's open); point at another row, press Esc or the left arrow key to close it again. Cards also have a **…** button that opens the same menu. On a touch screen that button is the way in, because press and hold on a card starts a drag. The menu is the same wherever the item appears, including on the item's own page. Open a folder or a document and the **…** in its header offers exactly what right-clicking it did, minus the Open you no longer need. Anything you can't do is left out, with two exceptions. Share and Who can see this always show, and answer honestly, because whether you may hand out a link deserves a real answer and not a missing line. Right-clicking a project offers Rename, Re-check project with AI, and Delete once the project is empty. The **…** in a project's own header offers the same. ## Downloading Anyone who can open an item can download it, from **Download** in its menu: - An uploaded file downloads as the original file. - A markdown document downloads as a `.md` file with its current text. If it has images or videos in it, you get a zip instead: the `.md` plus an `_assets` folder it links to. - A folder downloads as a zip of everything inside it that you can see, subfolders kept as folders. - [Several selected items](#selecting-several-cards) download together as one zip. In Chrome and Edge a zip is written straight to the place you pick, so a big folder never has to fit in memory; other browsers build it in the tab and save it when it's done. Keep the tab open until it finishes. A file that couldn't be fetched is listed in `MISSING.txt` inside the zip. A zip holds at most about 65,000 items and 3.5 GB, so anything bigger comes as several: `Name.zip`, `Name (part 2).zip` and so on. Unzip them into the same folder and they make one tree again. A single file too big for any zip downloads on its own beside them. ## Moving and renaming - **Drag onto a folder** to move an item there. Folders move with everything inside them, across projects too. - **Drag onto a document** to [relate](https://filement.app/docs/concepts/relationships.md) the two instead. - Or use **Move to…** and **Rename** from an item's menu. ## Search Press **⌘K** (or **Ctrl+K**) anywhere to open search. It matches file names and document text across the workspace, finds folders and projects by name, and jumps to All files, the knowledge graph, Activity, Trash or Settings. To search by meaning, pick **Ask about "…"** at the bottom of the results. What you typed goes to the [assistant](https://filement.app/docs/guide/search-and-assistant.md) as a question, ready to send. ## Deleting Deleting moves an item to [Trash](https://filement.app/docs/guide/trash.md), where you can restore it for 30 days. Source: https://filement.app/docs/guide/files-and-folders --- # Writing and editing > The collaborative markdown editor, presence, version history, and locking a document. You write markdown documents in Filement itself. Open one and choose **Edit**; choose **Done** to go back to reading. Shift+⌘+E toggles between the two from the keyboard. Esc always returns to reading. Reading and writing share one layout on purpose. The text stays exactly where it was when you switch, so you never lose the line you were on. ## Finding your way around a document A document with headings gets an **Outline** in the panel beside it. It lists every heading down to three levels and follows you as you scroll. Clicking an entry jumps to that section, while writing as well as while reading. The bar above the document shows the word count and how long the document takes to read. The copy button in the corner of a code block copies the whole block. It appears when you hover the block, and always shows on a touch screen. ## Two documents side by side To read or write with another document in view, choose **Open beside…** from a document's **…** menu (or its right-click menu on the board) and pick the second one. The two sit side by side, and each scrolls and edits on its own. The outline and Insights move into the bar above each document to leave room for the text. The keyboard shortcuts act on whichever side you last clicked. **Close**, at the top of the right-hand document, goes back to one. The pair is part of the address, so a reload or a copied link opens both. On a narrow window the second document sits under the first, and on a phone the option is not offered. ## Writing together Several people can edit the same document at once. Changes merge as you type, and you see who else is in the document: their avatars at the top and their cursors in the text. Each person gets a colour of their own, and the ring round their avatar matches it. People who are only reading show as viewing, not editing. ### Pointing something out You don't have to be editing to show someone what you mean. Press the **share** button (the arrow) in the bar above the document. It appears once someone else has the document open. While it is on, everyone else on the document sees what you select, highlighted in your colour with your name beside it, and sees your mouse move over the text. That works whether they are reading or editing. When two people select the same words, both colours show. Click anywhere to clear a selection. Sharing stays on until you press the button again or everyone else leaves. Other people's selections and pointers show up without you turning anything on. On a touch screen you can share selections; there is no pointer to share. While you are editing, your cursor is always visible to the others, shared or not. Sharing connects your browser directly to the browsers of the other people on the document, so what you point at moves without delay. Like a video call, that lets each side see the other's network address. On networks that block direct connections everything still shows, a little behind. On an older browser you may see the name and the cursor of the person selecting, without the coloured highlight. The editor handles headings, lists, checklists, quotes, code, links, tables, images and video. Filement stores everything as markdown, so what you write is also what search, the assistant and agents read. There is no Save button and nothing to lose. Your writing goes to the server as you type. The bar above the document says **Saving…** while a change is on its way and **Saved** once it has arrived. If the document changes while you have the editor open but aren't typing, for example when an agent edits it or someone restores a version, the editor reloads with the latest text and tells you so. Everything you had written was already saved, and it's part of what reloads. A tab left open in the background can never save its old copy over newer changes. ## Adding a block Type / on an empty line to see everything a document can hold: headings, lists, a checklist, a quote, a code block, a table, a divider, an image, a clip. Keep typing to narrow it (`/tab`, `/todo`), use ↑ and ↓ to move, Enter to choose and Esc to leave it. Each entry shows its markdown shortcut beside it, which is faster once you know it: `#` for a heading, `-` for a bullet, `1.` for a numbered list, `[]` for a checklist, `>` for a quote, ` ``` ` for code, `---` for a divider. They work as you type. The **+** in the margin beside a block does the same thing. It opens a new block below that one with the menu already up. ## Formatting what you selected Select some text and a small bar appears above it with bold, italic, underline, strikethrough, inline code and links, plus a menu on its left for turning the whole block into something else. The toolbar above the document has the same controls if you'd rather go there. ## Links Put the cursor in a link and a card appears showing where it goes, with three actions: open it in a new tab, change the address, or remove the link and keep the words. Clicking a link while editing puts the cursor in it instead of following it. That's what the card is for. ## Code A code block can say what language it is. Choose one from the picker in its top-left corner, or write the language on the fence (` ```ts `). The block is then coloured as you write, and coloured the same way when you go back to reading. The **copy button** in its corner takes the whole block. ## Tables Put the cursor in a table and a bar appears above it. You can add a row above or below, add a column left or right, delete either one, turn the header row on or off, or delete the table. A wide table scrolls sideways instead of squeezing into the page. Markdown has no way to write down a column width, so Filement doesn't store one, and a table is as wide as its contents. ## Pasting Paste markdown and it arrives as a document, not a wall of hashes and asterisks. Headings, lists, quotes, code fences, tables and links all come through as you'd expect. Text with no markdown structure stays exactly as you pasted it. ## Find and replace Press ⌘+F while editing. It searches the whole document, not only the part on screen (which is all the browser's own find can reach), and it can replace one match at a time or all at once. Enter moves to the next match, ⇧+Enter to the previous one, and Esc closes it and hands ⌘+F back to the browser. Match case and whole words are the two toggles at the bottom. Whatever you had selected when you opened it becomes the search term. ## Moving blocks around Hover over any block while editing and two controls appear in the margin to its left: **+** to add a block below, and a **grip**. - **Drag the grip** to move that block. A line shows where it will land. - **Click the grip** for the block's own menu: turn it into something else, move it up or down, duplicate it, or delete it. From the keyboard, ⌘+D duplicates the block the cursor is in and ⌘+⇧+↑/↓ moves it past its neighbour. All of this works on a single checklist item or list row too, so you can reorder a list of tasks one at a time. ### On a phone or tablet The margin controls need a pointer and dragging needs a mouse, so on a touch screen the same menu lives on the **toolbar**. The grip button at its left end acts on the block the cursor is in. **Move up** and **Move down** there do what dragging does elsewhere, and the rest of the list is the same: turn into, insert below, duplicate, delete. The toolbar also has **Image** and **Video** buttons, so you can add a picture without a right-click. ## Checklists Type `[]` at the start of a line, or use `/todo`, to start a checklist. Ticking an item draws a line through it and dims it. Anything nested underneath stays as it is, because an unfinished task holding a finished one isn't finished itself. Ticks are read-only while you read. You change them in the editor. ## Images and video Paste an image or a video clip, or drag one from your desktop, and it lands at the cursor. It shows straight away and uploads in the background. You can also **right-click anywhere in the editor** and choose **Add image** or **Add video** to pick a file. It goes in after the line you clicked. The toolbar's Image and Video buttons and the `/image` and `/video` entries open the same picker and put the file at the cursor. Both show small in the document, about a third of the page, and open full size when you click one. A picture opens fitted to the screen, however tall it is. **Scroll to zoom in**, drag or scroll to move around it, scroll back out to fit it again, and press Esc to close. Double-clicking zooms in and out too. While editing, the **play button on a clip** still opens it on a single click. A single click anywhere else selects the image or clip so you can move or delete it, and a double click opens it. - **Every image is shrunk before Filement stores it**, to at most 2048 pixels on its long side, and converted to WebP. A photo straight off a phone usually ends up around a tenth of its original size and looks the same on screen. - **Camera metadata goes** in the same step, including the GPS coordinates most phones write into a photo. - **Animated GIFs and SVGs stay exactly as they are.** Re-encoding either one would damage it. - **The same image used twice is stored once**, however many documents it appears in. - **A model describes each image**: what it shows and any text legible in it. You can then find a diagram or screenshot by searching for what's in it, and the assistant can talk about it. If the deployment has no model configured, images still work; they just don't get a description. ### Video Your browser **compresses a clip before uploading it**, to at most 1280 pixels on its long side, as MP4. A phone or screen recording usually ends up a fraction of its original size, which decides whether a clip is something you can keep in a document or something that eats a workspace. Nothing uploads until that finishes, so a long clip shows a progress bar where it will appear. - **Up to 10 minutes and 500 MB** as it comes off your disk. Anything longer belongs in a folder as a file. - **Sound stays.** Only the picture is re-encoded. - **A clip that is already small and efficient is left alone**, not re-compressed into something larger. - **No model watches video.** You find a clip by the text around it and by its name. An image, by contrast, gets a description and is searchable by what it shows. - It needs a recent browser (Chrome, Edge or Safari 17+). If yours can't compress video, the paste is refused with a note saying why, and the original isn't uploaded. Images and clips live inside the document that holds them. They don't appear as separate files on the board or in All files, and deleting the document deletes them. If you remove one from a document, Filement keeps it for a week before clearing it, so an undo always finds it. ## Discarding what you wrote While you edit, **Discard** appears in the bar above the document as soon as there is something to discard. It puts the document back exactly as it was when you opened the editor and takes you back to reading. Nothing is kept, so it asks first. Discard covers the session you are in, not your last one. Once you leave the editor, that writing is a version, and the way back to an earlier one is **Restore**. Discard is refused while someone else is typing in the same document. Their paragraph isn't yours to throw away. ## Version history Every document keeps its history, uploaded files included. Open a document's insights to see **Version history**: each version, who made it, and when. - **One editing session is one version.** Filement writes it when the last person leaves the editor, not while you type, so a morning of writing is one entry, not a hundred. - **The same goes for an agent or the assistant.** An agent connected over MCP that makes a dozen small edits to a document in one sitting leaves one version, and so do several of the assistant's changes applied from one conversation. The entry says it came via an agent or the assistant and how many edits went into it. Anyone else saving in between, or a pause of half an hour, starts a new version. Undoing it (from Activity, or the assistant's card) puts the document back to how it was before the session. - **Opening the editor isn't an edit.** Look at a document, change nothing, close it again, and history stays as it was, and so does the file, down to how its markdown is written. The same goes for typing something and deleting it before you finish. - Your writing still saves continuously while you work. Saving and versioning are different things: the bar says _Saved_ long before there is a version. - **Open a version to read it.** Click any entry and the version opens as the document it was. Switch to **What changed** to compare it with the current text, with added and removed lines marked. Reading a version changes nothing, so you don't have to restore one to see what it said. - **Restore** brings an old version back as a new version. History is never rewritten. - **Versions are kept indefinitely.** Nothing removes one, so a document you have worked on for months still has every state it passed through. - **History costs almost nothing.** A version isn't a second copy of the document. Text that hasn't changed since the last version is stored once and shared, so saving a long document again after fixing a paragraph stores just the paragraph. History doesn't count towards your [storage](https://filement.app/docs/guide/limits.md) at all. Deleting the document is what clears it. ## Locking **Lock editing** on a document, or **Lock folder** on a folder, freezes it. While it's locked, only the person who locked it and workspace owners and admins can change it. Everyone else can still read it. A folder lock covers everything inside. Use **Unlock** to lift it. A lock means "please leave this alone". It doesn't hide anything. To hide a folder, use [access](https://filement.app/docs/guide/workspaces-and-access.md). ## Edits from AI tools An AI tool with write access can edit markdown documents over MCP. Each of its edits is a normal version you can restore. If someone has the document open in the editor at that moment, Filement refuses the edit and tells the tool who has it open, so the two never race. Everything a tool changes is also listed in **Activity**, grouped into one entry per working session. **Undo all** there takes the whole session back, newest change first, and an undone edit comes back as a new version. Source: https://filement.app/docs/guide/writing-and-editing --- # Search and the assistant > Finding documents, asking questions answered from your workspace, and saving pasted text. ## Search **⌘K** / **Ctrl+K** opens search from anywhere. It finds documents by name and by the words in their text, within the workspace you are in, and only among documents you can open. Folders and projects whose names match appear under the documents, and the last row, **Ask about "…"**, hands what you typed to the assistant. That includes the text inside uploaded files (PDFs, Word documents, spreadsheets, source files) and what images show, which is why searching for the words on a whiteboard photo finds the photo. See [What gets read out of a file](https://filement.app/docs/guide/files-and-folders.md#what-gets-read-out-of-a-file). ## Ask Filement **Ask Filement** opens the assistant. It answers questions about the documents in your current workspace, and nothing else. - It **works in steps, the way a person researches.** It breaks your question into the parts it depends on and searches for each, several at once, by meaning and by the words themselves. It tries more than one wording when your files might put it differently from your question. When several documents could answer, it skims their notes and summaries first. When a passage is cut short, or the answer needs exact figures, dates or a list, it opens the document and reads the section that matters. It can also look inside a folder you name ("what's in the Q3 folder"). - It **knows which version is current.** When several documents are versions or copies of one another, it answers from the current one. An older draft it read gets a **Newer version** chip under the answer that opens the current one. The chip says **Likely newer version** when only Filement's own reading says so and nobody has confirmed it. Ask about history ("what did the first draft say") and it reads the older versions too. - It **checks the workspace's own map first** for questions like "where does the pricing work stand", "what changed this week", "what is still undecided" or "what do we have on Acme". Filement tracks which documents are one piece of work over time, what was decided along the way and what is still open, and the assistant reads that before searching. A thread it used shows under the answer with what was decided and what is open. If you can't open every document in a piece of work, the assistant leaves its summary out. - It **stops when it can answer.** Each answer has a fixed allowance of steps and reading, so a hard question takes a few more seconds instead of running on. When the allowance runs out, it answers with what it found and says what it didn't get to. - It **follows your connections.** For whatever a search turns up, the assistant also sees what you connected to it and the reason you gave. So a document that uses different words still reaches the answer: a later request hanging off a status report, or a decision that supersedes a plan. Your connections and Filement's suggestions stay separate; see [Relationships](https://filement.app/docs/concepts/relationships.md). - It **names the documents it used**, the ones it found by searching and the ones it opened to read, so you can open the source. Under each answer one line counts them ("2 connected by a person · also read 5"); open it to see the list. The documents you connected by hand come first, in their own group, each with the relationship and the reason you wrote. Everything the search only matched comes under them. A note written on a document shows beneath it. A connection you drew therefore appears under the answer whether or not the answer mentions it, so you see what somebody said belongs with what was read. - It **shows its work.** While it works you see each step as it happens: every search in its own words, "Read Pricing § Enterprise tier", "Checked connections of Q3 plan". Afterwards that folds into one line ("Searched 3 ways · read 2 documents") you can reopen. If an answer misses something, this tells you whether it searched badly or read badly. - It **trusts notes over its own reading.** If a note says a document is a draft or superseded, the answer says so. - It **lists and counts from the whole set.** It answers "every decision this quarter", "how many documents mention Acme" or "what did we change last week in Research" from the workspace's index of what each document is and names, not from the few documents a search ranked highest. A count it couldn't finish says "at least". - It **reads long documents whole** when it needs to, such as summarising an eighty-page PDF or comparing the same clause across twenty contracts, and gives you each document's answer with the passages it rests on. - If it finds nothing relevant, it says so plainly instead of guessing. ## Asking it to change something Ask the assistant to change anything you could change yourself and it **proposes** the change instead of making it: write, edit or rewrite a document, create a folder or a project, add a note, connect two documents or remove a connection, move or rename something, move something to Trash or bring it back, or put a document back to an earlier version. Each proposal appears under the answer as a card saying exactly what will happen (for an edit, the text before and after), with **Apply** and **Discard**. - **Nothing changes until you press Apply**, and only you can apply what the assistant proposed to you. - **Bigger jobs come as a set.** "Make a Q3 folder and move these eight files into it" is one card for the folder and one for each move, and the moves say they go into the new folder. **Apply all** above the cards applies the set in order; applying any one card makes whatever it goes into first. Discarding the folder discards what was going into it. With more than three cards, each is one line until you open it. - For a new document, an edit or a version restore, **Review** opens the whole document as Apply would leave it, with every changed line marked, so you can read all of it first. - Apply makes the change as you, under the same rules as doing it yourself. A locked document, a folder you can't write to, or a document someone is typing in right now refuses it, and the card says why. - If the document has changed since the proposal and the passage it would change is gone, the card says it's out of date instead of guessing. A whole rewrite or a version restore applies only to the version it was proposed against. - **Undo** on an applied card takes back exactly what that card did. Undoing a folder first undoes what was moved or created in it. Something that has changed since is left alone, and the card says so. - Everything you applied from one conversation is also listed together in **Activity**, where **Undo all** takes it back in one go. - Deleting means Trash, where things stay restorable for 30 days. The assistant can look in Trash to find what to bring back, but it can't delete anything for good. - In Zoho Cliq the same proposals come as buttons, led by **Apply all** when there are several. Closing the assistant keeps your conversation, and reopening it picks up where you left off; **New conversation** starts over. The expand button opens the same conversation as a full page, with your past conversations beside it, and the collapse button there takes it back to the panel. Earlier conversations are under **Past conversations**, where you can delete one or clear them all. Deleting removes the questions, the answers and what they were asked against. Anything you saved as a document stays where it is. History is your own: clearing yours never touches a colleague's. On deployments with voice enabled, you can dictate a question instead of typing it. ## Asking about something in particular The **@** button next to the composer attaches things to one question, so the answer is about what you picked and not whatever the search turned up. - **The page you are on** comes first: the document, folder, project or thread you were looking at when you opened the assistant. - **Search** finds any document you can open. - To attach a folder or a project, open it and use **The page you are on**. The assistant reads an attached document in full. An attached folder or project arrives as a list of names, and the assistant's searches and listings **stay inside it** unless your question clearly reaches further. An attached thread arrives as where it stands, what was decided and what is still open, its documents in date order, and the reasons they are connected; the assistant opens the document your question turns on. It still searches the rest of the workspace when your question needs something the attachments don't cover. Attachments belong to one question, not the whole conversation. They clear when you send, and the chips above a question show what it was asked against. You can attach up to eight at a time. If someone's access to a document changes before the answer is written, that document drops out of the answer. ## Saving text as a document The box that takes questions also takes content. Paste meeting notes, an email or a chat thread and choose **Save as document**. Filement saves it as a markdown document in the folder you started the conversation from, unless you pick another. If what you pasted looks like something to keep and not a question, Filement offers to save it, but it never saves unless you choose to. ## How many questions you get Ten a day, per person, resetting at midnight UTC. Search doesn't count, and neither does saving text as a document. See [storage and limits](https://filement.app/docs/guide/limits.md). ## What is used for AI When summaries and semantic search are on, Filement sends document text to the configured AI provider in pieces, for summaries, search indexing and answers. It sends each image once, when you first add it, so a model can write down what it shows for search. It never sends a whole workspace at once. When a document leaves Trash for good, Filement deletes its text, summaries and search index entries with it. Source: https://filement.app/docs/guide/search-and-assistant --- # Workspaces and access > Workspaces, roles, inviting people, restricting folders and documents, and switching workspaces. ## Workspaces A workspace holds projects and the people who work on them. Your account starts with one. A personal workspace is simply a workspace with one member; it works the same as a team's. You can belong to several. Switch between them, or create a new one with **New workspace**, from the account menu. Search, the assistant and agents only ever look inside one workspace at a time. ## Roles Every member has one role across the workspace. | Role | Can | | ---------- | ------------------------------------------------------------- | | **Owner** | Everything, including deleting the workspace | | **Admin** | Manage members and settings, plus everything an editor can do | | **Editor** | Create, edit, organise and connect files | | **Viewer** | Read, search and ask questions; cannot change anything | Owners and admins invite people by email from **Settings → Members**, choosing their role. The invited person sees it under **Invitations** in the account menu, once they have an account with that email, and chooses **Join** or **Decline**. Until they join, Members lists them as invited. ## Handing over or deleting a workspace The owner can hand the workspace to another member. In **Settings → Members**, open that member's menu and choose **Make owner**. They become the owner and you stay on as an admin. The workspace's storage then counts against their plan, so the handover fails if their plan doesn't have room for it. The owner can also delete the workspace. At the bottom of **Settings → General**, choose **Delete workspace** and type its name to confirm. You can't delete your only workspace, so delete your account instead. > [!WARNING] > Everyone loses access at once and share links stop working. Within a few minutes Filement > permanently deletes every project, file, version, link and conversation in it. Nothing goes > to Trash, and you can't undo it. ## Restricting a folder or document A role applies everywhere by default. To narrow it for one folder or document, open its access settings and switch from **Everyone in the workspace** to **Only specific people**. Then pick who, and at what level: - **Their usual role**: they keep whatever their workspace role allows. - **Can view**: read-only here, even if they are an editor elsewhere. - **Can edit**: can change things here. - **Can manage access**: can also change who has access here, and lock or unlock it. Everyone not listed stops seeing that folder or document anywhere in the app: in the browser, in search, in the assistant's answers, and as the far end of a relationship. The restriction applies to everything inside a folder. Access narrows a role; it never raises one. A viewer given **Can edit** on a folder is still a viewer. Workspace owners and admins always keep access, so a restriction can never lock out the people responsible for the workspace. ## Sharing outside the workspace [Share links](https://filement.app/docs/guide/sharing.md) are the one way content leaves all of this. By default an editor can share what they can edit; an admin can restrict that to admins and folder managers from **Settings → Sharing and privacy**. ## AI tools follow the same rules A connection from Claude Code, Codex or another agent acts as the person who connected it, in one workspace. It sees exactly what that person sees, and loses access the moment that person is removed from the workspace. See [Access and authentication](https://filement.app/docs/agents/security.md). Source: https://filement.app/docs/guide/workspaces-and-access --- # Your account > Signing in, resetting your password, and what Filement keeps about you. ## Signing in You sign in with your email and a password of at least 8 characters. A new account only works after you type the six-digit code sent to your email. ## Forgot your password On the sign-in screen, choose **Forgot password?** and enter your email. Capitals don't matter in the address. If an account uses that address, we email it a six-digit code. Type the code and a new password, and you're signed in. - The code expires in 15 minutes. - Setting a new password signs you out on every other device and disconnects every agent token and connected agent, so whoever knew the old password loses every way in. Reconnect your own agents afterwards under **Settings → Agents**. - The screen looks the same whether or not the address has an account, so it can't be used to find out who has signed up. - We send at most 6 codes an hour to one address. ## Security log **Settings → Security log** lists every change to who can reach what, newest first, with who made it and when: - members invited, joining, removed, or given a new role, and the workspace renamed; - folders and files restricted to certain people, locked or unlocked; - share links created or revoked, and who may create them; - agent tokens created or revoked, and agents connected or disconnected; - chat apps connected or disconnected, and accounts linked to them; - your own sign-up, password resets and exports. Everyone sees what they did themselves under **Your activity**. Owners and admins also see **This workspace**, which includes everyone's changes. An entry keeps the names as they were at the time, so it still reads correctly after a file is renamed or deleted. Entries are kept for a year. ## Exporting your data Open **Settings → Your account** (or click your name at the top of the account menu), then **Export**. You get a zip of everything you can see in the current workspace; switch workspace to export another. - Each project is a folder, with your folders inside it. - Documents are markdown (`.md`). Uploaded files are their original bytes. - Images and videos inside documents are in `_assets/`, and the markdown links to them. - `filement.json` has each item's note and dates, and every relationship with its type and reason. `"drawnBy": "person"` is a connection someone made; `"filement"` is one Filement found. The export leaves out folders restricted from you, and any relationship that touches one. Your browser builds the zip. In Chrome and Edge you choose where to save it first, and it writes straight to that file. Other browsers hold it in memory and download it at the end, so a very large workspace exports best from Chrome or Edge. Keep the tab open until it finishes, or press **Cancel**. Each export you start shows in the [security log](#security-log). ## Deleting your account Open **Settings → Your account**, choose **Delete my account**, and type your email to confirm. - You're signed out everywhere, and your sign-in, agent tokens, linked chat accounts, conversations and settings are deleted. - Workspaces only you use are deleted with everything in them, the same way as [deleting a workspace](https://filement.app/docs/guide/workspaces-and-access.md#handing-over-or-deleting-a-workspace). - In a workspace you share with others, you leave and what you wrote stays, because it belongs to that workspace. Its security log keeps your email next to the changes you made there. - If you own a workspace that other people use, hand it over (**Make owner**) or delete it first. Source: https://filement.app/docs/guide/account --- # Share links > Hand a file or folder to someone with no account, on your terms. Expiry, passphrase, view limit, and revocation that works immediately. Everything else in Filement belongs to a workspace. To read something you have to be a member, and [access rules](https://filement.app/docs/guide/workspaces-and-access.md) narrow it from there. A share link is the one exception. It hands one file or folder to someone who has no account at all. Because it's the exception, it's deliberately narrow. ## Who can make one By default, anyone who can edit something can share it. If you can change a document, you can hand it out. Sharing is part of ordinary work, not a request you file. A workspace admin can tighten that. **Settings → Sharing and privacy** has two choices under **Who can share publicly**: | Setting | What it means | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | **Anyone who can edit it** (default) | Editors and above share the files and folders they can already change. | | **Admins and folder managers only** | Only workspace owners and admins, plus anyone given **Can manage access** on a specific folder or file, can create a link. | Either way, the rule is per item. Someone held to read-only on one folder by its [access settings](https://filement.app/docs/guide/workspaces-and-access.md) can't share out of it, whatever their workspace role. Tightening the setting doesn't revoke links already handed out. Those are already outside, and you take one back by revoking it. ## Making one Open the "…" menu on any file or folder and choose **Share…**. You get four decisions: | Setting | Default | What it does | | --------------------- | ------- | ------------------------------------------------------------------------------------------------- | | **Expires** | 7 days | After this, the link stops working. "No expiry" is available and is the one to think twice about. | | **Passphrase** | none | The visitor has to type it before they see anything. Send it separately from the link. | | **View limit** | none | The link dies after this many opens. A limit of 1 makes it single-use. | | **Allow downloading** | off | With it off, the page shows the contents but never hands over a URL to the original file. | The link appears once, when you create it, and goes to your clipboard. Filement never shows it again. It stores only a fingerprint of the link, which is why the record can stay around safely after the link dies. Lost the link? Revoke it and make a new one. ## What the other person sees One page: the file, or the folder and what's inside it. No workspace, no navigation into the app, no sign-in prompt. They can browse a shared folder downward, so everything beneath it is included, **except** anything you've separately restricted to specific people. Restricting something and then sharing a folder above it doesn't quietly undo the restriction. Share pages ask search engines not to index them. That's a courtesy, not a protection. The real protection is that the link is unguessable, expires, and can be revoked. ## Seeing what is shared A globe icon marks anything with a live link: on its card, in lists, and in the document header. [All files](https://filement.app/docs/guide/files-and-folders.md) has a **Shared** filter, the fastest way to answer "what can people outside see right now". An icon only appears when something is unusual about an item: shared, restricted to specific people, or locked. No icon means no surprises. ## Turning one off Open **Share…** on the item again and press **Revoke** next to the link. Whoever may create a link may also revoke one. It stops working immediately, for everyone holding it. There's no undo and no way to bring the same link back, which is the point. Links also die on their own when they expire or reach their view limit, and any link pointing at something you move to [Trash](https://filement.app/docs/guide/trash.md) stops working straight away. Source: https://filement.app/docs/guide/sharing --- # Zoho Cliq > Save files from any Cliq chat into Filement, and ask the assistant questions without leaving Cliq. If your team works in Zoho Cliq, the Filement bot lets you use the workspace from the chat: - **Save a file.** Right-click any file in any chat (tap and hold on a phone) and choose **Save to Filement**. It works on files other people sent too. You can also send files to the bot with no message. Add a message and it becomes a question about the files instead. - **Ask a question.** Message the bot, or mention it in a chat. It answers from your workspace and links the documents it used. - **Ask about a file.** Reply to a file and mention the bot. The bot reads the file along with your question, and doesn't save it unless you tell it to. ## What happens after a save Filement reads a file saved from Cliq against your workspace, the same way it reads a file dropped into the app, and files it: - if it clearly belongs in another folder, it moves it there - if it's clearly a copy, or a newer or earlier version of something already there, or a reply to another document, it connects them - it adds the file to the piece of work it's part of The bot then sends you one card: **Done for you** lists what it did, and **Needs you** lists anything it wasn't sure of, with the reason. Press **Undo** to put back everything it did on its own; **Accept all** takes what it wasn't sure of too; **Review** opens the full review in the app, where you can answer each one separately, change how two files are connected, or undo one change. Mentioning the bot with just "save this" on a file does the same as right-click → Save to Filement, straight away. Prefer to confirm everything first? In the app, open **Settings → Preferences** and set **Organizing new files** to **Ask me first**. Nothing moves then until you press Accept all or move a file in Review. ## Asking about a file Reply to any file in Cliq and mention the bot with what you want: ``` @Filement does this quote match our current price list? @Filement save this in a new folder called Quotes @Filement summarise this and save it next to the Acme contract ``` The bot reads the file, checks it against your workspace if you asked, and answers you privately. When your request would change the workspace (saving the file, making a folder, adding a note), the answer ends with a **Save** or **Apply** button and a line saying exactly what it will do. Nothing happens until you press it. If you only asked a question, there's no button. To keep the file afterwards, just say so in the same conversation, like "save it" or "file that in Quotes". Filement remembers the files you asked about in a conversation for a day, so follow-ups like "what did that file say about pricing?" work too. Send `new` to start fresh. Only you can press your own buttons, even on an answer posted in a channel. ## Connecting The first time you use the bot, it sends you a **Connect** link. Open it, sign in to Filement if you need to, check the page names the right Cliq account and the right person, and press Connect. Then go back to Cliq and try again. The first person to connect has to be a workspace owner or admin. They choose which workspace the Cliq organization belongs to and which project saved files go into. After that, anyone in the workspace can link their own account. The bot never links accounts by matching email addresses. The only way an account gets linked is its owner pressing Connect while signed in. If your Cliq email differs from your Filement one, the page asks you to confirm the Cliq account is yours first. **If someone else sent you a Connect link, don't use it.** Whoever holds that Cliq account would be able to read everything you can. ## Whose access is used The bot does everything as you: - It saves a file **as you**, into the chosen project, and only if you can add files there. The file counts toward your workspace's storage like any upload. Filement keeps who originally sent it, and in which chat, as where it came from. - It builds an answer only from what **you** can open, and the question counts toward your daily allowance. So answers arrive **privately**, in your own chat with the bot, even when you mention it in a channel. An answer posted into a group would show everyone there documents that some of them may not be allowed to open. The channel only sees a short "looking into it". ## Answering in the channel If you want everyone in a channel to see the answer, start the question with **here:** ``` @Filement here: what's the latest quote for Acme? ``` The bot posts the answer in the channel, with a line saying it answered from your access. Only do this when the answer is fine for everyone in the channel to read. The bot can see whatever you can, and the people in the channel may not be allowed to open the same documents. The bot has to be a member of the channel, so add it like any other member. If it isn't one, or you use **here:** in a direct message or group chat, you get the answer privately with a note saying why. ## Good to know - You can save files up to 20 MB from Cliq. - The first time you ask about a file, Cliq asks you to let Filement read the file you replied to. That permission is yours, so the bot can only fetch files you can see in Cliq. - Filement keeps a file you asked about but didn't save for a day, so a Save button on an answer still works, then deletes it. It doesn't count toward your storage unless you save it. - Saving the same file twice doesn't make a copy. The bot tells you it's already there and links to it. - Text in PDFs, Word files and other documents becomes searchable after saving, like an upload. - Type **new** to start a fresh conversation with the bot. A question within a few hours of the last one continues the same conversation, so you can ask follow-ups. - Conversations with the bot also show up in the assistant's history in the app, marked with where you asked. You can carry on a private one there; answers to questions you type in the app stay in the app. A conversation answered in a channel (`here:`) can only be continued in Cliq. - Everything the bot changes for you is listed in **Activity**, grouped by save and by conversation, and you can undo any of it. ## Managing it **Settings → Integrations** shows what is connected and where saves go. You can unlink your own account there. Admins can change the project saves go to, or disconnect Cliq altogether. Disconnecting unlinks everyone. Files already saved stay where they are. Source: https://filement.app/docs/guide/zoho-cliq --- # Trash > Deleting, restoring, and what permanent deletion removes. Deleting a document or folder moves it to **Trash**. Nothing is removed straight away. - A deleted folder goes to Trash as one item with everything inside it, and comes back the same way. - While an item is in Trash it is hidden everywhere: the browser, search, the assistant, relationships and agents. - **Restore** puts it back where it was. **Undo** right after deleting does the same. ## After 30 days Items are permanently deleted 30 days after they were moved to Trash. You can also **Delete permanently** one item, or **Empty trash** for everything. On a touch screen both row actions, and the days left before the item goes, are in the menu at the end of the row. Permanent deletion removes the stored file and every version of it, its summary, its search index entries, its relationships and its access settings. There is no copy left to recover. Items in Trash still use storage until they're permanently deleted. See [storage and limits](https://filement.app/docs/guide/limits.md). Source: https://filement.app/docs/guide/trash --- # Storage and limits > How much space a workspace has, what counts towards it, and the daily limit on questions. Every account is on the **Free** plan, which includes **500 MB of file storage** and **10 questions to the assistant per day**. **Settings → Storage and usage** shows where you stand on both. ## Storage The 500 MB belongs to **you**, not to one workspace. If you own several workspaces ([workspaces and access](https://filement.app/docs/guide/workspaces-and-access.md)), they share the same 500 MB. Uploading into a workspace someone else owns uses **their** space, not yours. The owner is the one who can free space in a workspace, so the space comes out of their allowance. ### What counts **The 500 MB is for files, images and video.** That page splits it five ways, so you can see what takes up the room: - **Files you uploaded.** PDFs, images, spreadsheets and anything else added to a folder. These count. - **Images inside documents.** Pictures pasted or dropped into something you wrote. These count too, and the same picture used in several documents is stored once. - **Video inside documents.** Clips pasted or dropped into something you wrote. These count at their compressed size. Your browser shrinks a clip before uploading it, so you're charged a fraction of the file you dropped ([writing and editing](https://filement.app/docs/guide/writing-and-editing.md)). - **Documents you wrote.** The current text of everything written in Filement. Shown so you can see it; it doesn't come out of your 500 MB. - **Earlier versions.** The text a document _used_ to have, so you can go back to it ([version history](https://filement.app/docs/guide/writing-and-editing.md)). Also shown, also not counted. Writing isn't what fills an account. A busy workspace of documents and their whole history usually comes to less than a single photo off a phone, so Filement doesn't charge for it. Write and edit as much as you like; the bar in Settings keeps measuring the things that are actually large. Written text still has an upper bound, a much larger one, separate from the 500 MB. It's there so a workspace used to park an entire library of text hits a limit somewhere. You won't reach it by writing. If a bulk import or an AI tool ever does, it's refused the same way an upload is, with the numbers in the message. Anything in **Trash** still counts until it's deleted for good. These don't count either: search indexes, the summaries Filement builds, and the text it reads out of a PDF or spreadsheet so you can search inside it. Filement makes all of that _from_ what you added, and you can't delete it without deleting the file it came from, so an uploaded PDF costs the size of the PDF and nothing more. Markdown and plain text you upload (`.md`, `.txt`) become documents, exactly like ones written here. Filement stores them as text, not files, so they don't count against the 500 MB either. ### Getting space back [Emptying the Trash](https://filement.app/docs/guide/trash.md) is the fastest way. Items there are still stored until they're permanently deleted, which otherwise happens 30 days after deletion. When a workspace is full, Filement refuses uploads before the file is sent, with the numbers in the message. Nothing already stored is affected. ## Questions to the assistant Ten questions a day, per person. The allowance is your own. The workspace doesn't share it, and asking in someone else's workspace still counts against yours. - Each question you send counts as one. Replies, retries within an answer and searching don't. - A question that gets no answer doesn't count. If the model provider fails or takes too long, the assistant says so in the conversation and gives the question back, so you can ask again for free. - The count resets at midnight UTC. - The composer tells you when you have three or fewer left. When you run out, you can still use the panel to **save text as a document**, which costs nothing. [Search](https://filement.app/docs/guide/search-and-assistant.md) keeps working too, including filtering and opening what it finds. Connected AI tools ([agents over MCP](https://filement.app/docs/agents/connect.md)) read and write through their own tools, not the assistant panel, so they don't count against this limit. Source: https://filement.app/docs/guide/limits --- # Connect an agent > Connect Claude Code, Codex, Cursor, VS Code, Claude, ChatGPT, Gemini CLI or Windsurf to a Filement workspace over MCP. Filement runs an [MCP](https://modelcontextprotocol.io) server for every workspace. An agent connected to it can search, read, follow relationships and, if you allow it, create and edit documents. It only ever sees what you can see in the app. - **Server URL:** shown in **Settings → Agents**. On the hosted service it is the deployment's `…convex.site/mcp` address. - **Transport:** Streamable HTTP. - **One connection = one person + one workspace**, either read-only or read & write. The server also ships **prompts**, saved workflows like "gather context on X" or "is this document still current". Clients surface them as slash commands (Claude Code: `/mcp__filement__research`) or in a prompt picker. See [Tools and resources](https://filement.app/docs/agents/tools.md#prompts). Settings → Agents in the web app has copy-ready snippets for every client below. Once you create a token there, it fills the token into the snippets. Replace `` with your server URL. Two ways to authenticate: - **Sign in with your browser (OAuth).** Nothing to paste. The client opens Filement, and on the consent screen you pick the workspace and the access level. Use this wherever the client supports it. - **Personal access token.** Create one in Settings → Agents and send it as `Authorization: Bearer `. It is shown once. Use it for clients that only take headers, and for scripts and CI. ## Claude Code ```sh claude mcp add --transport http filement # then inside Claude Code: /mcp → filement → Authenticate ``` With a token: ```sh claude mcp add --transport http filement \ --header "Authorization: Bearer " ``` ## Codex CLI ```sh codex mcp add filement --url codex mcp login filement ``` With a token: ```sh export FILEMENT_TOKEN= codex mcp add filement --url --bearer-token-env-var FILEMENT_TOKEN ``` or in `~/.codex/config.toml`: ```toml [mcp_servers.filement] url = "" bearer_token_env_var = "FILEMENT_TOKEN" ``` ## Claude (web and desktop) Settings → Connectors → Add custom connector. Paste the URL, press Connect, and approve. ## ChatGPT Settings → Apps & Connectors → Advanced settings → turn on Developer mode. Create a connector with the URL and OAuth authentication, then approve. ## Cursor `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global): ```json { "mcpServers": { "filement": { "url": "" } } } ``` With a token, add `"headers": { "Authorization": "Bearer " }`. ## VS Code `.vscode/mcp.json`. With this form VS Code asks for the token once and stores it securely: ```json { "inputs": [ { "type": "promptString", "id": "filement-token", "description": "Filement token", "password": true } ], "servers": { "filement": { "type": "http", "url": "", "headers": { "Authorization": "Bearer ${input:filement-token}" } } } } ``` Leave out `inputs` and `headers` to sign in with OAuth instead. ## Gemini CLI `~/.gemini/settings.json`, then `/mcp auth filement`: ```json { "mcpServers": { "filement": { "httpUrl": "" } } } ``` ## Windsurf `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "filement": { "serverUrl": "", "headers": { "Authorization": "Bearer " } } } } ``` The server was tested end to end with scripted clients over both protocol versions, and Claude Code and Codex were checked for which protocol they send (see [Protocol versions](https://filement.app/docs/agents/developers.md#protocol-versions)). No snippet here has yet been run inside its client against a deployment; they follow each client's documented config format. Source: https://filement.app/docs/agents/connect --- # Tools and resources > Every MCP tool Filement exposes, what it returns, and the resources clients can attach. Tool names carry no `filement_` prefix. Clients already namespace tools by server (Claude Code shows `mcp__filement__search`), and a shorter name costs fewer tokens on every turn. ## Read | Tool | What it does | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace_overview` | The bound workspace, your role, whether this connection can write, every project, and recently changed documents. Call it first. | | `search` | Meaning and literal words at once, then one hop along the relationships people drew: a result carries the `connections` somebody stated about it, and a connected document that matched nothing itself is appended with `matchedBy: "connected"`. `mode`: `auto`, `semantic`, `keyword`. Optional `alternates` (up to two more wordings, searched together), `projectId` or `folderId` (any depth), `limit`, `includeSuperseded`. See [Current versions in search](#current-versions-in-search). | | `read_document` | Path, version, notes, AI summary, lock state, and text (a Word file's text is markdown, with its headings and tables). An uploaded Office file also carries `fromFile`: its author and when it was created and last saved, from inside the file. Read part of it with `find` (where a phrase occurs, no body returned; a phrase that is not there returns the text with `findMiss`), `section` (one heading, or a trail like `Plan › Pricing` to pick the one under another; with `find`, searches only under it), or `offset` / `maxChars` (default 20 000, max 100 000). A long document also returns its `headings`. | | `read_documents` | `read_document` for up to 8 documents in one call, sharing one `maxChars` budget (default and max 60 000). `section` and `find` apply to each. | | `list_documents` | Documents by what they are, newest first, with a `total` (`"N+"` when there are more than were scanned) and a `cursor`: `kind` (as the pipeline classified it), `mentions` (a name it contains), `since` / `until`, `nameContains`, `projectId`, `folderId`. For list and count questions; `search` only ranks a sample. | | `document_summaries` | Notes and AI summaries for up to 25 documents, without their text. For triage before reading in full. | | `list_folder` | Direct children of a project root or folder, with ids, notes, sizes, and lock state, 200 at a time: pass `nextCursor` back as `cursor` for the rest. A document with no note carries `suggestedNote`, an unaccepted draft. Pass a good one to `set_note`. | | `project_tree` | The project (or a subtree) as an indented text outline. `maxDepth` defaults to 4. | | `get_relationships` | Direct edges of a document or folder, split into `userAsserted` and `aiSuggested`. | | `related_context` | Follows relationships 1–3 hops out and returns every reachable item with its notes and summary, plus the edges. | | `recent_documents` | Most recently changed documents, optionally within one project. | | `document_history` | Version list, or the text of one `version`, paged. | | `resolve_path` | Turns a path a person would say (`Roadmap / Q3 / Spec`) into ids. A segment that misses returns the candidates at that level rather than failing. | ## Threads, versions and names Filement works out which documents are versions of one another (a **family**, with one current version) and which documents are one piece of work told over time (a **thread**, with a summary, what was decided and what is still open). These tools read that directly, so a question like "where does the pricing work stand" does not have to be pieced together from search results. | Tool | What it does | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `current_state` | Where a piece of work stands. Pass `nodeId`, or `topic` to find it by meaning. Returns its thread(s): `summary`, `decided`, `open`, the `current` documents, and the `timeline` with each document's date, role and whether it is an earlier version or a copy. | | `what_changed` | Documents changed since `since` (an ISO date or date-time), newest first, at most 25, each with who changed it, its summary and thread; plus the threads with activity since then. Optional `projectId` or `folderId` (everything under the folder). | | `open_questions` | What is still undecided, deduplicated: the `open` items of recently active threads and the open questions their current documents raise, each with where it comes from. Optional `threadId`, `projectId` or `folderId`. | | `entity` | Every document that names a person, organisation, system or identifier. An exact, case-insensitive match on the name, then by prefix. Not a search by meaning. Newest and current versions first, each with its thread, with a `total` and a `cursor`. | | `list_threads` | The pieces of work in the workspace, a project or a folder, most recently active first, each with its summary, `decided`, `open` and current documents. Optional `projectId`, `folderId`, `cursor`. | | `get_thread` | One thread whole: its summary, `decided`, `open`, and every document in time order with its date, role, version and a one-line summary. | | `document_versions` | A document's family, newest first: which one `isCurrent`, and `howSure`: a person said so, the files show it, or a model's reading. Not the edit history of one document; that is `document_history`. | A thread whose documents you cannot all open comes back without its summary, decisions and open questions, since those were written from every document in it. A current version you cannot open is never named. ### Current versions in search When a search result is an older version or a copy of a document, it carries `supersededBy` with the current one. Nothing is hidden, but older versions are demoted: - With the current version also in the results, the older one keeps its row and loses its excerpt (`demoted: true`). - Without it, the current version is appended as a result with `matchedBy: "newer_version"` and its summary. These rows do not count against `limit`. - Five copies of one file share one document's allowance of passages, so they cannot crowd out everything else. Pass `includeSuperseded: true` for a question about history ("what did the first draft say"): every excerpt is kept, and results are still labelled. ## Write These tools are hidden from `tools/list` for read-only connections and for workspace viewers, so they take up no context there. Everything they change is listed in the workspace's **Activity**, grouped into one session per connection (a session ends after half an hour without a change), under the name the connection was given. People can undo the whole session or any change in it. | Tool | What it does | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `create_document` | Creates a markdown document. A name clash gets a numbered suffix. | | `edit_document` | `mode`: `str_replace` (preferred; `oldText` must match exactly once unless `replaceAll`), `append`, `prepend`, `append_to_section` / `replace_section` (what is under the heading named in `section`), or `replace` (whole text; requires `expectedVersion`). Pass `expectedVersion` to catch conflicts. | | `create_folder` | Creates a folder at a project root or inside `parentNodeId`, with an optional note. | | `create_project` | Creates a top-level project. | | `set_note` | Sets or clears (`""`) the note on a document or folder. | | `rename_item` | Renames a document or folder. | | `move_item` | Moves into `targetNodeId`, or to a project root by omitting it: its own, or with `targetProjectId`, another project's (everything inside moves along). | | `link_items` | Creates a directional relationship with a type, a reason, and a confidence from 0 to 1. Stored as AI-suggested and listed in Activity, where people can undo it. Refused on a pair a person already connected. | | `unlink_items` | Withdraws one relationship by `relationshipId`. An AI-suggested link is dismissed, so it is not suggested again; a link a person drew needs `force: true`. | | `trash_item` | Moves to Trash, recoverable for 30 days. Nothing here deletes permanently. | | `restore_item` | Puts an item back from Trash. The undo for `trash_item`. | | `restore_version` | Puts a document's text back to an earlier version. The restore is itself a new version, so nothing is lost. | Every tool declares MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so clients can decide which calls need approval. Tools return JSON text. They deliberately declare no `outputSchema`: with one, the gateway also sends `structuredContent`, and every result would go over the wire twice. ## Prompts Prompts are workflows rather than calls: a client shows them as slash commands (`/mcp__filement__research` in Claude Code, the prompt picker in Claude Desktop), and picking one sends the agent a sequence to follow with the tools above. | Prompt | Arguments | What it does | | ----------------- | --------------- | -------------------------------------------------------------------------------------------------- | | `orient` | none | Surveys the workspace: projects, shape, what is in flight. Reads nothing in full, changes nothing. | | `research` | `topic` | Search, triage, read, follow relationships, and report with citations by path. | | `check_current` | `subject` | Whether a document is still the one that counts: its note, its versions, its thread, its edges. | | `capture` | `what`, `where` | Files new material in the right place, with a note and links back to what it came from. | | `review_document` | `subject` | Reads a document with everything around it and says what is stale, contradicted or missing. | | `map_connections` | `subject` | Proposes the relationships an item should have, for approval before anything is written. | `subject` takes a path, a name or a `nodeId`. The prompt resolves it first. ## Resources and instructions - **`filement://document/{documentId}`**: a resource template. Reading it returns the document as markdown, headed by its path, version, note, and AI summary. - **`resources/list`**: your 50 most recently changed documents, so clients with an attach or @-mention picker can pull one into context. - **Server instructions**: sent in `initialize` and `server/discover`. A short guide to finding things, reading without spending the whole context window, judging what you read (notes outrank AI summaries; `user` and `ai` relationships are not the same claim), and writing: `str_replace` with `expectedVersion`, a note on anything you create, and which tool undoes which. Source: https://filement.app/docs/agents/tools --- # Access and authentication > What an agent can and cannot see, how tokens and OAuth sign-in work, and how to revoke access. ## Rules agents inherit An agent follows the same rules as a person in the web app, and a few of its own. - **Access is identical.** Every tool resolves the workspace role, per-folder and per-document grants, and locks through `lib/access.ts` (CONCEPT.md §23b). A document you cannot open does not exist to the agent: not in search, not in listings, and not as the far end of a relationship. - **Denied reads as not found.** The agent never learns that a restricted item exists. - **One workspace per connection.** IDs from another workspace, even one you belong to, come back as not found. - **Notes outrank summaries.** A note is written by a person. Tools return notes separately from AI summaries, and a folder's note is included with everything inside it. - **Agent-drawn links are `origin: "ai"`.** A model decided the edge, even though your credentials carried the request (§9). They show up as AI suggestions in the web app, and a pair someone dismissed cannot be proposed again through MCP. - **Edits are versioned.** Each change creates a document version that people can restore, and it re-runs the AI pipeline. - **The live editor wins.** If someone has the document open in the collaborative editor, `edit_document` refuses and tells the agent who. Otherwise it clears the editor's CRDT state, and the next editor to open loads the new markdown. ## Authentication Both ways of connecting produce the same thing: a row in the `agentTokens` table. | Field | Meaning | | -------------------------- | ---------------------------------------------- | | `userId` | Who the agent acts as | | `workspaceId` | The one workspace it can reach | | `scope` | `read` or `write` | | `kind` | `personal` (token) or `oauth` (sign-in) | | `tokenHash`, `refreshHash` | SHA-256 of the tokens. No plaintext is stored. | On every request the gateway hashes the bearer token, looks up the row, checks expiry, and **re-checks workspace membership**. Removing someone from a workspace cuts off their agents without anyone revoking tokens. Revoking in Settings → Agents deletes the row, and the next request is refused. Resetting your password deletes every token and connection you hold, in every workspace. Each tool call is recorded with its tool name, ids, outcome and time, kept for 30 days. What an agent writes or asks (search queries, document text, notes, reasons, names) is not kept. Anonymous requests get `401` with `WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp"`, which starts OAuth discovery in clients that support it. ### Personal access tokens - Format `ctx_pat_…`, 256 bits of randomness, minted in an action (not a mutation, which replays deterministically). - Expiry: 30 days, 90 days, 1 year, or never. - A viewer cannot create a write-scoped token. ### OAuth 2.1 Implemented in `convex/oauth.ts` as Convex HTTP actions. It is not a separate auth service. | Endpoint | Standard | | ------------------------------------------------------ | --------- | | `/.well-known/oauth-protected-resource[/mcp]` | RFC 9728 | | `/.well-known/oauth-authorization-server[/mcp]` | RFC 8414 | | `/oauth/register` | RFC 7591 | | `/oauth/authorize` → web app `/oauth/consent` | OAuth 2.1 | | `/oauth/token` (`authorization_code`, `refresh_token`) | OAuth 2.1 | | `/oauth/revoke` | RFC 7009 | - **Public clients only.** PKCE with `S256` is required. No client secrets, and no implicit or password grant. - **Client identity:** - A Client ID Metadata Document URL (the method the 2026-07-28 spec prefers; Claude Code uses `https://claude.ai/oauth/claude-code-client-metadata`). The server fetches it, and the document must name itself as the `client_id`. - Or Dynamic Client Registration, which the spec deprecates but most clients still use. - **Redirect URIs:** matched exactly, except that loopback addresses may use any port (RFC 8252 §7.3). Native clients bind whatever port is free, and their metadata cannot know it in advance. - **Authorization responses include `iss`** (RFC 9207). A `resource` parameter (RFC 8707) must name this server. - **Consent** happens in the web app, where your session already exists. Everything shown about the client is re-derived on the server from its id, never read from the URL. The page sends `frame-ancestors 'none'`, so it cannot be framed to steal a click. - **Lifetimes:** code 5 minutes, single use. Access token 1 hour. Refresh token 90 days, rotated on every use (the old refresh and access tokens stop working). - Requires the `SITE_URL` env var on the Convex deployment, pointing at the web app. Convex Auth already needs it. Source: https://filement.app/docs/agents/security --- # For developers > Protocol versions, how the MCP server is built, how to add a tool, operations and known limits. ## Protocol versions The gateway serves both protocol eras on the same endpoint. - **2026-07-28 (stateless).** No handshake and no sessions: each request carries its protocol version and client capabilities in `_meta`, plus `Mcp-Method` / `Mcp-Name` headers. Nothing is stored between requests. - **2025-03-26 / 06-18 / 11-25 (sessions).** `initialize` creates a session row. Each later request costs one session read and one small write. Captured from real traffic on 2026-09-13: | Client | First request | Version | | ------------------- | ----------------- | ---------- | | Claude Code 2.1.270 | `server/discover` | 2026-07-28 | | Codex CLI 0.154.0 | `initialize` | 2025-06-18 | Dropping the session path would disconnect Codex, so it stays. Idle sessions are pruned after 24 hours. Once Codex sends 2026-07-28, the session path can be retired by refusing `initialize` in `convex/mcp.ts`. ## Implementation All code lives in `packages/backend/convex` except the two web pages. | File | Role | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `mcp.ts` | Tool and resource registration, server instructions, token resolution, the `authorize` callback, request handling | | `mcpPrompts.ts` | The prompt catalog, and the `prompts/list` / `prompts/get` handling the gateway does not provide | | `agentApi.ts` | Read tools (internal queries and the search action) | | `agentWrite.ts` | Write tools (internal mutations) | | `lib/agentCaller.ts` | `agentAccess` (caller → access, scope check) and `agentGuard` (access errors → `ConvexError`) | | `agentTokens.ts` | Personal tokens, token resolution, expiry purge, audit and session pruning | | `oauth.ts` | The authorization server | | `lib/tokens.ts` | Token minting, hashing, PKCE | | `http.ts` | Routes for `/mcp`, `/.well-known/*`, `/oauth/*` | | `apps/web/app/app/settings/agents/page.tsx` | Settings → Agents: setup snippets, token creation, connection list | | `apps/web/app/oauth/consent/page.tsx` | The consent screen | ### Request flow ```text client ──POST /mcp──▶ http.ts ─▶ mcp.handleMcp │ resolveIdentity: sha256(token) → agentTokens.resolve │ authorize: hide/deny write tools for read scope or viewers ▼ convex-mcp-gateway (component) │ injects { subject, claims } as the tool's `caller` arg ▼ internal.agentApi.* / internal.agentWrite.* │ agentAccess(caller) → documentFor / folderFor ▼ the same *As helpers the web app's mutations call ``` ### Prompts `convex-mcp-gateway` 2.0 doesn't handle prompts. It answers `tools/*` and `resources/*` and advertises only those. So `mcpPrompts.ts` serves `prompts/list` and `prompts/get` ahead of the gateway and patches `prompts: {}` into the capabilities of the `initialize` and `server/discover` responses on the way back out. Everything else is delegated untouched. Three things it has to keep doing, because a prompt response that differs from every other response on the endpoint is a bug that shows up on one client only: - **Resolve the bearer token itself**, through the same resolver `handleMcp` gives the gateway. No token gets the same 401 with a `WWW-Authenticate` challenge, so OAuth discovery still works when a prompt call is a client's first request. - **Mirror the framing**: SSE when the client asked for it, JSON otherwise, and the stateless era's `resultType` / `_meta` / `ttlMs` envelope fields when the request declares 2026-07-28. - **Buffer the gateway's response to patch it.** That is safe because the gateway's SSE body is a single frame, already closed. It's never a live stream. Adding a prompt is an entry in the `PROMPTS` array: a name, a title, a description, its arguments, and a `build` that returns the user-role text. Write it as a sequence of tool calls with a stopping condition, not as a description of the feature. ### Writing a new tool 1. **Write an internal function** in `agentApi.ts` (read) or `agentWrite.ts` (write). Give it a `caller: mcpCallerValidator` argument. Do not use `getAuthUserId`, `requireAccess` or `requireDocument` there: the gateway strips `ctx.auth`, so they always fail. Call `agentAccess(ctx, caller, capability)`, then `documentFor`/`folderFor` for entity-level checks. 2. **Reuse the shared helpers.** For writes, call the `*As` helper the web mutation uses (`createMarkdownAs`, `saveContentAs`, `moveFolderAs`, …) rather than copying the mutation body. If none exists, extract one from the mutation first. 3. **Enforce the token's workspace.** Before touching any id argument, check that it belongs to `access.workspaceId`. The helpers check the entity's own workspace, which is not the same thing when a person belongs to several. 4. **Throw `ConvexError` for messages the agent should read.** The gateway replaces any other error with "Tool execution failed". Wrap the body in `agentGuard` so access errors come through. 5. **Register it in `mcp.ts`** with `identityArg: "caller"`, annotations, and a short description written for a model. Add `metadata: WRITES` if it changes anything. 6. **Shape the output for a context window.** Put ids next to names, use paths instead of parent-id chains, page long text, and leave optional fields undefined rather than `null`. ## Operations Crons in `convex/crons.ts`: | Job | Interval | What | | -------------------------- | -------- | ----------------------------------------------------------------------- | | purge expired agent tokens | 1 h | Expired personal tokens, OAuth grants past refresh expiry, unused codes | | prune MCP audit log | 6 h | Gateway audit rows older than 30 days | | prune idle MCP sessions | 6 h | Legacy sessions idle for 24 hours | - **Audit:** the gateway writes one row per tool call (`mcpGateway` component, `audit` table), recording tool, caller, outcome, and duration. Browse it in the Convex dashboard under the component's data. - **OAuth discovery config** is written to the gateway's tables on the first request each process serves, from `CONVEX_SITE_URL`. Dev, preview, and prod need no setup step. - **Env:** `SITE_URL` (web app origin) is required for OAuth. Semantic search needs an embedding provider key (see README → Configuration); without one, `search` falls back to keyword and reports `mode: "keyword"`. ## Testing by hand Stateless call with a personal token: ```sh URL=https://.convex.site/mcp TOKEN=ctx_pat_... META='"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1"}}' curl -s -X POST $URL \ -H 'content-type: application/json' \ -H 'accept: application/json, text/event-stream' \ -H 'mcp-protocol-version: 2026-07-28' \ -H 'mcp-method: tools/call' -H 'mcp-name: workspace_overview' \ -H "authorization: Bearer $TOKEN" \ -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"workspace_overview\",\"arguments\":{},$META}}" ``` Check discovery: ```sh curl -s -i -X POST $URL -H 'content-type: application/json' -d '{}' | grep -i www-authenticate curl -s https://.convex.site/.well-known/oauth-authorization-server ``` The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) also works: point it at the URL and choose OAuth or a bearer header. ## Rate limits Requests over a limit get HTTP `429` with a `Retry-After` header in seconds. The limits sit well above what a person or a well-behaved agent does: | Endpoint | Limit | Counted per | | ------------------------------------------- | -------------------------- | ------------------------------------------- | | `/mcp` (every request, tool calls included) | 120 a minute, bursts of 60 | bearer token, or address before one is sent | | `/oauth/token` | 60 a minute, bursts of 20 | client | | `/oauth/register` | 20 an hour, bursts of 10 | address | Semantic search (in the web app, in the assistant, and through the `search` tool here) and voice transcription share a separate limit of 60 a minute per person, because each call is a paid model request. It is per person rather than per token, so a second token does not buy a second budget; a search past it still runs on literal matches and says `mode: "keyword"`. The limits are defined in `convex/lib/rateLimits.ts`. If the limiter itself is overloaded, requests are let through rather than refused. ## Known limits - **Client metadata fetches** need a signed-in person and reject IP literals and `localhost`, but a hostname that resolves to a private address is not checked. - **Tool results are pretty-printed JSON.** The gateway formats them with two-space indentation, which costs some tokens. - **Error text includes a stack trace on dev deployments.** Expected to be absent on prod, not yet confirmed. - **No Tasks.** No current tool runs long enough to need them. Prompts are served by `convex/mcpPrompts.ts`, since the gateway has no prompts primitive. Source: https://filement.app/docs/agents/developers