Skip to content
NOEMATA

The file store

Noemata is based on files. Queries, dashboards, settings, documentation - everything is written to and read from files on disk. This shapes how Noemata works - with files being the main driver, everything is human-readable, searchable, versioned, and exactly how agents excel.

The power of a file system

Files are a natural way for agents to understand context and make changes. Code, AGENTS.md, skills - agents continuously read and write files, grepping through a code base, building up the right context to confidently make the change that matters. Files also enable version control: every file change from an agent is reviewable and reversible - a critical component of allowing agents to operate safely.

For humans, it means that they can not just review these changes - they can see everything in their editor, search through files, validate them offline and organize it in a way that fits their mental model.

The things you work with are all files in a single store:

  • Frames — Frame definitions, stored in a *.frame.json definitions
  • Queries — Queries stored in a frame definition or in *.template.json files
  • Markdown — notes, investigations, runbooks, post-mortems, technical documentation, and everything else that fits in a Markdown file

Because they’re all just files, the same operations apply across the board — list them, search them, open one, edit it, see its history. There’s no separate “dashboard database” to learn; the dashboard is the *.frame.json file.

Synchronization

When you start Noemata, it can either use the files on-disk (fs.local), sync between the local disk and a remote server (fs.sync), or fully depend on the remote server (fs.remote). fs.local is a good choice for individuals, or teams that are using git for version control. fs.sync is useful when you want to share changes immediately without version control, and fs.remote is the right choice if you have a remote Noemata instance and do not intend to make changes at all.

File layout

Noemata will create the following directories:

  • .data/ - local state such as logs, pids for process management and generated JSON schemas.
  • @frames/ - frame definitions, including those installed by integrations.
  • config/ - configuration for Noemata-owned services (such as ClickHouse, the OTel collector, and the Noemata app).
  • noemata.json - contains the Noemata project configuration.
  • noemata.projects.json - tracks all Noemata projects in the current git directory.

By default, frames from integrations are gitignored — they’re Noemata-managed and recreated on every noemata up, so committing them serves no purpose. Any frames you’ve added yourself are not gitignored. If you’d rather own an integration’s dashboards — edit them in place and keep them under version control — configure the project as user-owned (collect.integrations.managed: false, offered as a prompt in noemata config). Noemata then seeds the packs once and leaves them alone, and they’re committed like any hand-authored frame; noemata up --managed re-syncs them from source when you want to pull upstream changes. See Integrations and packs.