Knowledge base

Every workspace has one knowledge base: a folder of markdown files that Rookery reads, writes and searches, and that you can open in any editor.

It is a complete notes application in its own right. Plenty of people will use it as one and never build an agent — that is a perfectly good way to use Rookery. The agents are there when you want them, reading and writing the same notes.

It is deliberately not a database. If Rookery disappeared tomorrow, you would still have every note in a format that opens anywhere.

What lives in it

README.md              a home note, created for you
notes/                 anything you write — journals, plans, research
memory/
  USER.md              who you are: name, location, role, background
  SOUL.md              how you like to be spoken to
  GENERAL.md           quick notes added from chat
  <anything>.md        more context files you create
agents/<id>/           each agent's own area — its instructions, state and logs
skills/<name>/         skills you have created or imported
chats/                 conversations, saved as readable markdown

Memory files are injected everywhere

Everything in memory/ is added to the context of every agent run, design conversation and chat. This is how Rookery knows your timezone, your writing style and your preferences without being told each time.

Two are created for you — USER.md and SOUL.md — with placeholder content. While a file contains only placeholders it is skipped, so an unfilled template costs you nothing.

Agents read it and write to it

An agent can read the whole knowledge base and write back to it — both to its own area and to your notes. That is the point: an agent that watches something records what it saw, so the next run knows what has already been handled.

Agents are asked to leave the system-managed folders alone (chats/, other agents’ folders, and the internal .kb/). That is a rule in their instructions rather than a hard wall, so an agent you have written yourself can technically reach further.

Editing

The web interface has a full rich-text editor:

Formatting — headings, bold, italic, underline, quotes, code blocks, and text or highlight colour.
Lists — bulleted, numbered, and checkboxes you can tick.
Callouts — a note, tip or warning block that stands out from the prose.
Collapsible sections — a summary line that opens on click, for detail you do not want in the way.
Tables — with header rows, added and edited inline.
Images — dropped or pasted in, and resizable once placed.
Alignment — centre or right-align a paragraph, a heading, a list, a table or an image; select it and use the toolbar.
Columns — two, three or four blocks side by side; type /columns. Useful for a before-and-after pair of images.
Links — to the web, and [[wikilinks]] to your other notes.
A slash menu — type / for every block type without leaving the keyboard.
Emoji — a searchable picker, and icons for folders and notes.

There is a raw markdown mode too, if you would rather see the source.

Notes are stored as plain markdown, which has no notion of layout. Alignment is therefore written the way markdown has always expressed it — a <div align="center"> wrapper, the same form GitHub READMEs use — so a centred block you write here reads correctly anywhere else, and one pasted in from elsewhere is understood.

Columns carry two limits worth knowing for the same reason. Each block is one cell, so a cell holding a heading and a paragraph is not supported, and two bullet lists cannot sit side by side because markdown cannot express two adjacent lists as separate blocks at all. And columns are a Rookery layout: elsewhere — on GitHub, in an export — the cells appear stacked in order, with every image and every bit of formatting intact.

AI writing tools

Select any text and a toolbar appears with four actions:

Action	What it does
Improve	Rewrites the selection more clearly
Proofread	Fixes grammar and spelling, keeps your wording
Explain	Explains the selection in plainer terms
Reformat	Restructures it — into a list, a table, headings

Each returns a suggestion you accept or discard, so nothing changes until you say so. Explain is the exception: it answers a question about the passage and is never pasted over it.

Alongside them, Edit with AI opens a chat that already carries the passage and the request — no retyping. The assistant edits the note directly, and the open editor picks the change up as soon as the reply lands. If you had unsaved edits of your own they are not overwritten: you get a Reload option and decide.

Files that are not markdown open read-only: text and code in a monospace viewer, anything else as a download.

Bringing documents in

Drop in a PDF, Word document, spreadsheet, presentation, web page or CSV and it becomes a markdown note. Also available from the command line:

rookery kb convert report.pdf --dest notes/research

The result is a note you can edit, not just read: the converter writes the same markdown the editor itself writes, so an imported document opens in the rich text editor rather than read-only. Headings, lists — numbered ones included — tables, quotes, collapsible sections, alignment, underline and highlight colours all survive as things you can change afterwards.

Images inside a document come with it. A picture embedded in a Word file or on a slide is saved into uploads/ alongside the original and shown in the note, so it renders in the editor and travels into anything you export.

A scanned PDF is read with OCR. When a PDF has no text layer, Rookery rasterises the pages and recognises the text, and the note says in its own frontmatter that the words were read from images and may contain recognition errors. This needs tesseract and poppler-utils on the host; without them the note tells you which one to install. When a text layer is present but looks thin, the note says that too, so a scan that yielded almost nothing cannot pass as a clean one.

Conversion into markdown is the one-directional part — a note is never written back into the original file. Getting a note out in another format is a separate thing, and it is supported: see below.

Taking documents out

Any note can be exported as HTML, Word (.docx), PDF or its raw markdown, from the Export menu on the note.

PDF needs a renderer on the server. If you installed the browser (rookery browser install) you already have one and nothing further is needed; otherwise weasyprint, chromium, google-chrome, wkhtmltopdf or libreoffice will do. Without one, the PDF entry is shown as unavailable rather than failing when you press it.

Exports are self-contained: images in the note are embedded in the file, so an exported HTML page or PDF still shows them once it leaves the machine.

Searching

Search the whole knowledge base from the interface.
Agents have the same search as a tool, which is why “find the note where I mentioned the dentist” is one lookup rather than an agent reading every file.
It uses ripgrep when installed, and falls back to a slower built-in scan when it is not.

Big files

A knowledge base fills up with things that are too big to read in one go — an exported spreadsheet, a long research document, a year of meeting notes in one file. Rookery looks at the shape of a file before reading it, so a question about a large file does not turn into reading the whole thing.

Ask about a big file and it first works out what is in there: for a table, the columns and how many rows; for a document, its headings. It also notices when one part of a file is far larger than the rest — an exported CSV often carries a column of raw technical data that accounts for most of the file and answers none of your questions. Knowing that up front is the difference between an answer and a long silence.

From there it fetches only what it needs: one section of a document, or a search inside that single file rather than across everything you own.

Tables

A spreadsheet or CSV you import becomes a markdown table, and a match inside one comes back with the table’s column headers attached. Without them a row is just a line of values — nothing says which number is the amount and which is the date.

Totals, averages, counts and rankings are computed, not estimated. “How much did I spend per month”, “what are my five biggest transactions”, “how many were declined” — the numbers are worked out from the rows rather than added up by the model, which is the difference between an answer you can trust and one that looks plausible.

If a question needs something more unusual than filtering, grouping and ranking, it falls back to handing over the table with the bulky columns stripped out — small enough to read directly. For anything beyond that, an agent can run a script over the file.

Links between notes

Write [[Another note]] and Rookery resolves it, with backlinks shown on the target. This is the same convention Obsidian uses, so an existing vault carries over — and so does yours, if you ever leave.

Where it lives on disk

<data_dir>/vaults/<workspace-id>/

<data_dir> defaults to ~/.rookery and moves with ROOKERY_DATA_DIR. Back it up — see Backup and restore, which covers the database and every workspace’s knowledge base in one encrypted file.