# 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.