# Core concepts

Source: https://docs.elnora.ai/docs/get-started/concepts
Last modified: 2026-09-16T13:37:22-06:00

> The building blocks of the Elnora platform — organizations, tasks, files, the knowledge base, and more.

A quick tour of the objects you'll work with through the API, CLI, and MCP.

## Organizations

An **organization** is the top-level container for your team's data. It has
**members** (with roles) and **invitations**. Most resources belong to an org,
and requests act on your active organization unless you specify another.

## Files & the knowledge base

**Files** are your workspace documents (uploads and generated outputs), and
**folders** organize them into a tree. Files live in your **knowledge base**,
which is private to you by default. You choose what to share and with whom — with
specific members or your whole organization, as a **viewer**, **editor**, or
**admin** — and a folder passes its sharing down to everything inside it, so you
set access once. The **library** is your organization's shared collection of
reusable content.

You can read back the **effective access** on any file or folder
(`GET /files/{id}/access`, `GET /folders/{id}/access`): everyone who can reach
it, each entry marked as granted directly or inherited from a named ancestor
folder. A folder can also stop inheriting from its ancestors, and a file that is
shared more widely than the folder holding it keeps that wider audience until
you clear it explicitly — so narrowing a folder never silently changes who can
already read something inside it.

Every file also carries a short **description** and **tags**. Elnora fills these
in for the files it writes and derives them for files that arrive without any, so
similar-looking documents can be told apart without opening each one. You can set
your own at any time (`PUT /files/{id}`).

### Automatic curation

Elnora can also keep your organization's knowledge base tidy for you. With
**knowledge base auto-tidy** on, a file that lands in the organization's
knowledge base is classified, named, described, tagged, and filed by the agent as
it arrives, instead of waiting for someone to do it by hand. Everything it does
is an ordinary file operation, so each change is versioned and reversible like
any other.

Auto-tidy is **off by default** and is turned on per organization. Only an
organization **owner** or **admin** can change it — in the dashboard under
**Organization settings → Knowledge base**, or over the API:

```bash
curl -X PATCH https://platform.elnora.ai/api/v1/organizations/<org-uuid>/kb-autotidy \
  -H "X-API-Key: $ELNORA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
```

### What you can upload

Uploads are not limited to a fixed list of file types. A file is stored unless
its extension is one Elnora refuses outright — executables, installers, scripts
and similar runnable formats — and those fail with `400` and a message naming the
extension. A microscopy image, a sequencing read, a chromatogram or an instrument
export is accepted the same way a PDF is.

What varies by format is how much Elnora can do with a file, not whether you can
keep it. Documents, spreadsheets, delimited data and images are extracted and
searchable as described below, and many scientific formats can be opened and
measured by the agent. A format nothing on the platform can parse is still
stored, versioned, shared, and downloadable — it just has no text rendition
behind it, so file-content search has nothing to match on.

### Opening a file

In the dashboard, a file opens in a viewer of its own rather than only
downloading — the chat's attachments included: PDFs, Office and OpenDocument
documents, tables (CSV/TSV, Parquet, Arrow), notebooks,
Markdown, LaTeX and HTML, molecular structures, sequences, alignments and
phylogenies, genome tracks, HDF5 and Zarr containers, instrument traces,
declared archives such as plate exports, audio and video — as well as the
scientific images no browser displays on its own, including TIFF/OME-TIFF,
whole-slide scans, DICOM and NIfTI volumes. Where a format cannot be decoded in
the browser, the viewer says the file is stored and names what can read it
instead of showing a broken image; a format the platform doesn't recognise
offers a plain download rather than claiming support it doesn't have.

### Text extraction

When you upload a file, Elnora extracts its text in the background so the agent
can read it and search can find it. Documents (PDF, DOCX and PPTX including
their macro-enabled variants, ODT, ODP, HTML, XML, AsciiDoc, LaTeX, EPUB, `.eml`
email and `.vtt` transcripts) and spreadsheets (XLSX, XLS, ODS, CSV, TSV) are
converted to text; Markdown (including R Markdown and Quarto), plain text, JSON,
and YAML are taken as they are.
Text uploads are decoded using the file's own encoding, so a file saved as
UTF-16 or in a Windows code page such as
Windows-1252 extracts correctly instead of arriving empty. Images (PNG, JPEG,
GIF, WebP) are a supported input in their own right and are read with a vision
model, as are PDFs that turn out to be scans. Your original file is always kept
as uploaded — extraction only adds a text rendition alongside it.

Each file version reports how far extraction has got in `extractionStatus`:
`pending`, `running`, `done`, `failed`, or `deferred` (`null` when there was
nothing to extract, such as a file the agent wrote itself). File-content search
covers a version once it reaches `done`.

`deferred` is a success, not an error, and is worth handling separately from
`failed`: the file is stored, versioned, shareable, previewable and readable by
the agent, but its bytes hold no text worth extracting into the knowledge base —
a TIFF stack, an HDF5 container, a Parquet table, an instrument trace, or a
legacy binary Office file such as `.doc` or `.ppt`.

A document you attach to a task message is extracted the same way, and the agent
waits briefly for that extraction to finish before it starts work on your
message — so it reads the document's text rather than starting without it. If
extraction is still running when that wait ends, the agent tells you it can't
read that document yet rather than guessing at its contents; send the message
again once the file's `extractionStatus` reads `done`.

### Delimited data files

Delimited data files are read by their content, not their extension. When Elnora
previews or analyses a `.csv` or `.tsv`, it honours a leading `sep=` line, and
otherwise infers the separator (comma, semicolon, tab, or pipe) from the file
itself; it also recognises comma decimals. So a tab-delimited Excel export saved
as `.csv`, or a European-locale export with `;` separators and values like
`0,87`, keeps its real columns and numbers instead of collapsing into a single
column.

## Tasks & the agent

A **task** is a conversation with the Elnora agent. You create a task, send
**messages**, and the agent processes them asynchronously — generating and
optimizing **protocols**, designing experiments, analyzing data (including
measurements taken directly on scientific images — any image format the platform
can open, from a plain JPEG to a whole-slide scan, a DICOM series or a 3-D
volume) and plotting the results, searching your knowledge base as well as the
scientific literature, patents, public research databases and funding calls, and
producing deliverables
such as spreadsheets and slide decks. Poll the task's messages until the agent's
reply completes.

A task is private to whoever created it — another member of your organization
can't read it, and an API key sees exactly the tasks its creator can. You share
results by sharing the files, not the conversation.

Anything the agent produces is a first-class file in your knowledge base —
private to you by default — rather than a task-only artifact, so it can be
shared, versioned, and searched like any other file. Files you attach to the chat
stay scoped to the task.

### What the agent remembers

Each task is its own conversation, but the agent carries durable notes between
them, kept as ordinary Markdown files under a `memory/` folder in your workspace
and read back on every turn. What it learns about you and how you work stays
private to you, under `memory/user/`; conventions that belong to the whole team
live in `memory/AGENTS.md`, which every member of your organization — and the
agent — can read and edit, so those conventions stay current as they change.
Both are just files — browse,
read, edit, or clear them with the same [file](https://docs.elnora.ai/docs/api/reference/files) and
[folder](https://docs.elnora.ai/docs/api/reference/folders) endpoints as anything else.

## Search

**Search** runs across your own tasks' messages, plus the names and the extracted
full text of every file you have access to, so the agent — and you — can ground
work in your organization's data. Results never include a task or a file you
can't already open.

## Next steps

- [Authentication](https://docs.elnora.ai/docs/get-started/authentication) — get an API key and make your first call
- [CLI reference](https://docs.elnora.ai/docs/cli) — the same operations from your terminal
- [MCP & integrations](https://docs.elnora.ai/docs/mcp) — connect your AI tools