Skip to content

Write notes in a knowledge base#

Every knowledge base has notes of its own, and Metis ▸ Notes turns them into a vault you write in, the way Obsidian works: plain Markdown files in folders, linked with [[wikilinks]], tagged with #tags, with pictures beside them. Use it to keep your own documentation — runbooks, decisions, meeting notes, a daily log — next to the documents the base reads, and searchable with them.

Your notes are written on the base's machine, in the base's own folder notes/, on the drive that keeps its index — the same place uploads and notes saved from conversations go (Add files). Nothing of their text is stored anywhere else on the way. Every note you save is found by its words within a second or so, and by meaning once it is embedded (a base with an embedding model).

The same folder opens in Obsidian

Notes are ordinary .md files: front matter, [[wikilinks]], ![[embeds]], callouts and tags as Obsidian writes them. Copy or sync the base's notes/ folder (download its files, or a drive you sync yourself) and open it in Obsidian as a vault; files you bring back with Add files are read the same way.

Before you begin#

  • A knowledge base (Build a knowledge base); a base with no source drive works — create it with no sources and write in it.
  • To read notes: knowledge-bases:read-content (the workspace role viewer and above; the Analyst preset). To write, move and delete: knowledge-bases:write-content (editor, admin; the Developer and Analyst presets). Without it, Notes opens read-only.
  • The base's machine must be on: notes live there (see When the machine does not answer).

Open Notes#

Open Metis ▸ Notes and choose the base at the top — or open the base in Metis ▸ Knowledge bases and choose its Notes tab. On a phone, the file tree and the side panels open as drawers: tap ☰ for the files, the link icon for backlinks.

Every note is a file of the base's notes. Read one with its version:

curl -s -H "Authorization: Bearer $ASTRALYX_TOKEN" \
  "$ASTRALYX_API/metis/knowledge-bases/handbook/vault/file?path=projects%2FPlan.md"

{"path": "projects/Plan.md", "text": "# Plan\n\nShip notes on Friday.\n", "version": "3f9a1c07b2e4d5a6", "size": 30}

The folder tree is GET …/files (items and folders). See API for every route.

The layout#

Part What it does
Files (left) The folders and notes. New note, New folder, Today's daily note; right-click (or ⋯ on a phone) a file to rename, move or delete it; drag a file onto a folder to move it; drop files from your computer onto a folder to upload them there.
Search, Tags (left) The base's search over your notes, and every tag with how many notes have it.
Tabs (middle) One per open note; Ctrl/Cmd+click a link opens it in a new tab. Back and forward per tab.
Links, Outline, Graph (right) The open note's backlinks, unlinked mentions and outgoing links; its headings; its local graph.

Three views#

A note opens in Live preview: the Markdown is shown formatted, and the line you are on shows its markup so you can edit it. Source shows the plain Markdown; Reading shows the note rendered, read-only. Edit beside reading splits the tab: Source on one side, Reading on the other. Ctrl/Cmd+E switches between editing and Reading.

What is rendered:

  • headings, bold, italic, ~~strikethrough~~, lists, - [ ] task boxes you tick with a click, tables, block quotes, horizontal rules;
  • fenced code with its language highlighted (```python);
  • callouts, as Obsidian writes them — > [!note] Title, tip, info, warning, danger, question, quote, … — folded with > [!note]- or open with > [!note]+;
  • front matter, shown as Properties above the note (edit a value, add or remove a property); tags and aliases count as the note's tags and other names;
  • pictures: ![[diagram.png]] or ![alt](attachments/diagram.png);
  • embeds: ![[Another note]] or ![[Another note#Heading]] shows that note (or section) inside this one, one level deep.

Math ($…$) is shown as written, not rendered.

What a note may show

Notes are rendered safely: no script, no event handler and no frame from a note ever runs; links to other sites open in a new tab without access to the console; pictures load only from the base's own notes or from https:// addresses.

Type [[ to link: the list completes note names, then # for a heading of that note, then | for the text to show instead — [[Leave policy#Vacation|our vacation rules]]. A link to a note that does not exist yet is shown dimmed; following it creates the note.

A link names a note by its file name (without .md), or by its path when two notes share a name ([[projects/Plan]]). A bare name reaches the note in the same folder first, then the one with the shortest path — as in Obsidian. Markdown links ([text](../ops/runbook.md)) work too.

The Links panel shows:

  • Backlinks — every line of another note that links here;
  • Unlinked mentions — lines that name this note (its name or one of its aliases, as a whole word) without linking it; Link turns one into a link;
  • Links from here — this note's own links, and where they lead.

#tag anywhere in the text (letters, digits, _, -, / for nested tags such as #project/atlas; not only digits, not inside code) and front matter tags tag a note. The Tags pane lists them; choose one to see its notes.

Renaming a note, or moving it or a whole folder, rewrites every link to it in the base's notes, as Obsidian's "update internal links" does: a link by name keeps the shortest name that still reaches it, a link by path gets the new path, and the relative links inside what moved still lead where they did. The console says how many links were updated.

Right-click the note (or ⋯) and choose Rename or Move, or drag it onto a folder.

curl -s -X POST -H "Authorization: Bearer $ASTRALYX_TOKEN" -H "content-type: application/json" \
  -d '{"from": "projects/Plan.md", "to": "archive/Plan 2026.md"}' \
  "$ASTRALYX_API/metis/knowledge-bases/handbook/vault/move"

{"moved": [{"from": "projects/Plan.md", "to": "archive/Plan 2026.md"}], "links_updated": [{"path": "Index.md", "links": 3}]}

"update_links": false moves without rewriting. A folder moves with everything in it. Something already at to is refused with 409 FILE_EXISTS.

Deleting a note leaves its folder in place; deleting a folder that holds notes asks first (the API refuses it with 409 FOLDER_NOT_EMPTY unless recursive=true).

Daily notes and templates#

  • Today's daily note opens daily/YYYY-MM-DD.md, creating it if needed — from templates/Daily.md when that note exists.
  • Any note in templates/ is a template: Insert a template (from the command palette) puts one where the cursor is, with {{date}}, {{time}} and {{title}} filled in.

Pictures and attachments#

Paste a picture, or drag one into a note: it is uploaded to attachments/ and ![[name.png]] is put where you dropped it. Pictures are .png, .jpg/.jpeg, .gif, .webp, .avif and .bmp, up to 64 MB; they are kept beside the notes and never indexed (search reads text). SVG is not accepted.

Graph#

Open the graph (Ctrl/Cmd+G) draws every note and the links between them; choose a node to open its note. Tags adds the tags as nodes, Orphans shows notes nothing links to, Not yet written shows links to notes that do not exist yet. The Graph tab of the right panel shows the open note's neighbourhood. The graph is drawn from the links you wrote — no model is involved.

Search your notes#

Search (Ctrl/Cmd+Shift+F) asks the base, keeping to its notes, and opens a result at the line it was found on. It is the base's own search by words — exact for names, error codes, tags — so it works on a base without an embedding model too. To search by meaning as well, use Metis ▸ Search on a base with an embedding model (Choose how a base searches).

Saving, and when someone else edits the same note#

Notes save themselves a moment after you stop typing (Ctrl/Cmd+S saves now). The status at the bottom says Saved, Saving…, Offline — kept in this browser or Conflict.

Every save names the version of the note you started from. If the note was saved meanwhile — by someone else, in another tab, or by a model — your save is refused and the console shows This note changed elsewhere with both texts side by side. Nothing is lost; choose:

  • Keep mine (overwrite) — your text replaces what is there;
  • Take theirs — your edit is dropped, the note as it is now opens;
  • Keep both (mine as a copy) — what is there stays, your text is saved as a new note beside it.

Through the API, a write sends the version it read; a stale one is refused with 409 VERSION_CONFLICT, the note's current version and text in detail:

curl -s -X PUT -H "Authorization: Bearer $ASTRALYX_TOKEN" -H "content-type: application/json" \
  -d '{"path": "projects/Plan.md", "text": "# Plan\n\nShip notes on Monday.\n", "version": "3f9a1c07b2e4d5a6"}' \
  "$ASTRALYX_API/metis/knowledge-bases/handbook/vault/file"

A new note is "create": true instead of a version (refused with 409 FILE_EXISTS when one of that path exists). A note holds at most 256 K characters.

When the machine does not answer#

Your notes live on the base's machine. When it is off or unreachable, Notes says so — the base is not serving (KNOWLEDGE_BASE_NOT_READY) or the machine cannot be reached — and what you type is kept in this browser until the machine answers; open the note again then and the console offers your unsaved text. Kept in this browser means this browser on this device only: another device does not see it, and clearing the site's data removes it.

Keyboard shortcuts#

Keys
Ctrl/Cmd+O Open a note (quick switcher)
Ctrl/Cmd+P Command palette
Ctrl/Cmd+N New note
Ctrl/Cmd+S Save now
Ctrl/Cmd+E Toggle Reading view
Ctrl/Cmd+G Open the graph
Ctrl/Cmd+Shift+F Search the notes
Ctrl/Cmd+W Close the tab
Alt+←, Alt+→ Back, forward
Ctrl/Cmd+click a link Open it in a new tab

A memory's facts#

In a memory base, memory/ holds the memory's facts. They are shown in Notes but changed in Metis ▸ Memory only: each fact keeps what it replaced, and a note edited by hand would lose that (Keep a memory of facts).

Next#