Troubleshooting and FAQ#
Short answers, with a link to the page that explains each in full. For a base that waits or fails, or a document that was not indexed, start with Troubleshoot a knowledge base.
Privacy#
Do my documents or questions leave my machines?#
No. A knowledge base runs on one of your workspace's machines: it reads the documents where they are, keeps its index on a drive of its own on that machine, and calls its models — Eos deployments of the workspace — on the workspace's network. Files you upload and notes you save go from your browser, phone or terminal to the base's machine, which writes them; they are not kept anywhere on the way. Astralyx keeps a base's settings and totals — documents, chunks, how many searches per day, an evaluation's numbers — never a document's name or text, a question, or a fact.
What does Astralyx see of a search?#
That it happened, as a count per day. The question goes to the base's machine, and the passages come back to you. Through an AI assistant over MCP, the assistant's provider sees what it sends and receives, as for anything you ask it.
Does a memory read my chats?#
Only the conversation you choose, when you choose Remember this conversation, once. The app keeps its chats on your phone and the Playground in your browser; nothing is remembered on its own. See Memory.
Can a model save something to a base by itself?#
No. A model proposes a note (save_to_knowledge,
save_to_knowledge_base); it is kept as a draft until a person saves it,
and dropped after a day otherwise. See
Let a model save when asked.
Files#
Which files does a base read?#
Markdown (.md, .markdown, .mdx), text (.txt, .text, .rst,
.adoc, .org, .csv, .tsv, .json, .jsonl, .log, .tex), HTML
(.html, .htm, .xhtml), PDF and Word (.docx). Other files are
counted by extension and left out; hidden files and folders are not read.
See Files read.
My .doc, .pptx or .xlsx files are not indexed.#
They are not kinds a base reads. Save Word documents as .docx and
slides or sheets as PDF.
Are scanned PDFs read?#
Not yet: there is no OCR. A PDF is read from its text layer, page by page; a PDF that is only images of pages is listed with the PDF has no text layer (a scanned document?). Export it with text from where it came from, or run OCR on it yourself (a tool such as OCRmyPDF) and replace the file.
Are images, tables and diagrams read?#
Text only. A PDF's or a Word file's text is read, tables as their text; images and the text inside them are not.
What does a citation hold?#
The drive, the document's path, its title, its kind, the page (PDF) or the line (text, Markdown), the headings above the passage, and a snippet. See Citations.
Limits#
How large can a file be?#
64 MB, whether a base reads it from a drive or you upload it. A PDF is given 120 s to read. A note saved from a conversation holds up to 256 KB of text.
How large can a base be?#
A base compares each question with every chunk it holds — an exact search
that misses nothing — and is built for up to about 100,000 chunks. Its
index is held in memory, about 5 KB per chunk at 1024 dimensions: raise
placement.memory_gb (2 GiB by default) for a large base. A base reads
up to 16 source drives or folders.
Can a base run more than one replica?#
Not yet: one index service per base. While it is replaced after a change, searches are answered by the old one until the new one takes over.
Other limits?#
A question up to 4,000 characters; 1 to 50 results per search; an evaluation of up to 500 questions that finishes within 60 s; 100 facts kept at once. All of them: Limits.
Languages#
Which languages does it work in?#
Searching by meaning works in the languages of the embedding model: BGE-M3 reads more than 100, and finds a passage in one language from a question in another. Searching by words works on any language written with spaces between words, with accents ignored (configuracao finds Configuração) and no stemming; for languages written without spaces (Chinese, Japanese, Thai), it is meaning that finds passages. Word headings are read in any language. A memory's extractor writes facts in the conversation's language.
Files not in UTF-8?#
Text that is not UTF-8 is read as Latin-1 (older Windows files), UTF-16 by its byte-order mark.
Running it#
Does Metis need a GPU?#
No. The index service runs on CPUs, and the default models — BGE-M3 for embeddings, BGE Reranker v2 M3, Qwen3 4B for a memory's extractor — are served by Eos on CPUs. A whole base fits a small machine with 5 free cores and about 6 GB of memory (A personal notes base on a CPU-only machine). An embedding model on a GPU indexes a large corpus faster; searching needs none.
Which embedding model should I choose?#
BGE-M3 (multilingual, 1024 dimensions) on a CPU is the default the console suggests; Qwen3 Embedding 0.6B runs on a CPU too. Any embedding model of the Eos library works, and the base sets its query and document prefixes from the model. Changing a base's model reads every document again. Measure the choice on your own questions: Measure and improve search quality.
Do I need a reranker?#
No, but it orders the best candidates more precisely: without one, results come in the fused order. Evaluate with and without it (Metis → Evaluations → Run with and without the reranker) to see what it does for your documents.
Why is my base Waiting?#
Its index cannot go on, almost always because its embedding model is not serving. Searches still answer from what is indexed (by words, if the model is down). Keep every model of a base at one replica at least: a deployment that scales to zero is not woken by the base. See Troubleshoot a knowledge base.
How quickly are changes picked up?#
Files you add: at once. Files changed on a plain drive: within
rescan_seconds (60 s by default). A drive from a data source: at each
new revision. Only what changed is read again.
Sharing and permissions#
Who can use a base?#
A base belongs to its workspace. Everyone with a role in the workspace
that allows it may search it — in the console, with astra, through the
API, from an AI assistant or Claude Code — and the workspace's own work
(runs, functions) may call it at http://metis-<base>:7700 inside the
workspace. A base cannot be shared with another workspace, or with a guest,
and cannot be given to one person as a single resource: to let someone
search it, give them a role in the workspace.
Who may search a base, and who may add to it?#
| Role | See bases (names, states, totals) | Search | Read documents, added files, facts | Add files, notes, facts | Create, change, delete | Reindex | Evaluate |
|---|---|---|---|---|---|---|---|
| Workspace admin, editor; Workspace admin, Developer presets | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Analyst preset | ✓ | ✓ | ✓ | ✓ | |||
| Workspace viewer (Viewer, as before) | ✓ | ✓ | ✓ | ||||
| Viewer, Auditor presets | ✓ |
The permissions behind them are knowledge-bases:read, search,
read-content, write-content, create, update, delete, reindex
and evaluate; a custom role may hold any of them
(Permission catalog). Saving a note a model
proposed takes write-content from the person who confirms.
Is a memory private to me?#
No: a memory is a base of the workspace, read by whoever may read its bases. For a memory of your own, make it in a workspace of your own.
Cost#
What does Metis cost?#
Metis has no price of its own. A base's index service and its models are work of the workspace like any other: they are metered by the CPU cores and memory they hold (1 core and 2 GiB for a base by default; 2 cores per small CPU model replica), and priced by the cluster's price table. The base calls its models on the workspace's network, not through a gateway, so indexing and searching count no tokens. See Usage, cost and budgets.
What does a base take on disk?#
Its index, on its own drive on its machine's data location; files and notes added to it; and, for a drive from a data source, the copy of the revision it reads. The documents of a plain drive are read where they are, not copied.
Not yet#
- Chat that searches a base by itself: a deployment or a chat request cannot name a base to search. Give the model a search tool — Chat with your documents in Eos.
- OCR of scanned PDFs.
- Connectors (Obsidian, Google Drive, Gmail): until then, export them to a drive or add the files to a base.
- A graph of the people, projects and decisions documents name, for questions that span several documents.
- Remembering conversations automatically, and a memory placed in front of every chat.
- Keeping what was added when a base is deleted, and more than one replica per base.