Skip to content
Pilotoo
v0.1

0.1.0 Latest

ChangelogHow versions work

Brain

Introduction

Section titled “Introduction”

An agent that forgets everything between conversations, or that searches a pile of documents nobody curated, is hard to trust. Brain gives a workspace named memories that people and agents read and write, and decides on the server, before any ranking, what each caller may see.

A workspace holds as many memories as it needs, each of one kind. One memory does not replace another: a company can keep a graph, several collections and a personal memory side by side.

The three kinds

Section titled “The three kinds”
Kind What it holds Who sees it
graph A company’s second brain: sources from uploads and text, compiled pages with citations, labels, roles and a review queue. Members of the memory, and inside it only what their roles grant.
collection Retrieval over documents: passages with their locator. Members of the memory.
personal Facts agents learn about one person. Only that person. Always.

Every user has one personal memory, my-memory, created the first time they sign in.

How a graph memory compiles a source

Section titled “How a graph memory compiles a source”

Adding a source to a graph memory runs four steps, all inside one database transaction under a lock per memory:

  1. Extract. The model lists the companies, people and topics the source is about.
  2. Resolve. Each name is looked up among the pages that already exist, by alias, trigram similarity and full text. Only pages the source’s audience can already read are candidates, so a hidden page name never reaches the prompt.
  3. Judge. The model chooses an existing page from the candidates or declares a new one. When it is unsure, or a new page looks very close to an existing one, Brain files a Possible duplicate for an admin instead of guessing.
  4. Write. The facts are written, each with its citations, and the source is linked to its pages.

If the model fails at any step, nothing changed. A page keeps every name a source used for it as an alias, and is found by any of them regardless of case, accents or a legal suffix such as S.r.l..

Recompiling a source is a diff: only the facts that differ change, and re-adding identical content changes nothing.

Facts and faces

Section titled “Facts and faces”

A page is a list of facts, each with its citations.

  • One entry per fact. When several sources say the same thing about an entity, such as three invoices of one supplier, the page keeps one entry with every citation, and a new figure updates that entry.
  • Faces. Consolidation only happens between sources with the same labels. Sources with different labels stay in separate entries, so merging never shows anyone content from a source they cannot see.
  • Facts over time. A fact has a validAt date. When a newer source contradicts or replaces it, the old fact is retired, not deleted, and the new one points to it. Readers see current facts; an admin can show the retired ones with ?history=1.

Deleting a source

Section titled “Deleting a source”

Deleting a source retires the facts only it supported and rebuilds the facts other sources still support from those sources, so the page stays correct. A page left with no facts appears under Empty pages in review. An admin can instead erase a source, which removes it with everything derived from it, history and revisions included.

A source added with an externalId is versioned: the same id with new content becomes the next version of that source and only what differs changes; the same id with the same content does nothing.

Who sees what

Section titled “Who sees what”

A memory writes its pages in the language of their sources unless its language fixes one, such as it; answers always follow the language of the question.

A memory’s access is one of private (the owner only), members or workspace. People are added as members with the role admin or member.

Inside a graph memory, access goes further:

  • A label family groups labels, and a role grants each family one of none, some (a list of labels) or all. all includes labels added later.
  • A member sees a source only through a label that one of their roles grants. A source with no label is visible to memory admins only.
  • Pages, sections and graph nodes and edges are visible only when they derive from a source the viewer can see.
  • The filter runs in the database query before ranking, never in a model.
  • A workspace admin or memory admin can search, ask and read pages as another person (as); every such use is audited. Access checks let you write a question with the sources a person must and must not reach, and run them.

A memory the caller cannot see answers 404, the same as one that does not exist.

What runs without a model

Section titled “What runs without a model”

Brain works with nothing but PostgreSQL. A model and embeddings switch more on:

You configure You get
Nothing Sources, text extraction, full-text search, labels, roles, facts, tokens, the audit log.
An embedder Semantic search.
A chat model Page compilation, answers with citations on ask, and label suggestions. Without one, ask replies with modelOff: true.

The graph keeps its sources and search when the model is off; it only says that compilation is off.

Three ways to use it

Section titled “Three ways to use it”
You want Read
Claude, Cursor or another MCP client to use your memories Use it from an agent
Brain inside your own NestJS host, or as knowledge for the agents of the kit Embed it in a host
One service for a workspace, with a web app and sign-in Run the standalone service

Next steps

Section titled “Next steps”