Importing Data

Atomic supports several capture and import paths. Choose the path that matches where your data currently lives.

Markdown Folders and Obsidian Vaults

The desktop app includes a folder importer for markdown files. It is commonly used with Obsidian vaults.

The importer:

  • Imports markdown files as atoms
  • Preserves Obsidian-style [[wikilinks]]
  • Can turn folders/frontmatter tags into Atomic tags
  • Excludes common non-note directories such as .obsidian, .trash, .git, and node_modules
  • Uses source URLs such as obsidian://VaultName/path/to/note for deduplication

From the UI, use the import/capture options and choose a folder.

From scripts in a local checkout:

npm run import:obsidian /path/to/vault

npm run import:obsidian /path/to/vault -- --max 100

npm run import:obsidian /path/to/vault -- --dry-run

npm run import:obsidian /path/to/vault -- --exclude "Templates/**"

The server API also exposes:

curl -X POST http://localhost:8080/api/import/obsidian \

-H "Authorization: Bearer <token>" \

-H "Content-Type: application/json" \

-d '{"vault_path": "/path/to/vault", "max_notes": 100}'

Server-side import paths must exist on the server machine.

Apple Notes

The desktop app includes an Apple Notes importer on macOS. It reads the local Apple Notes database, converts notes to markdown, and can turn Apple Notes folders into tags.

Apple Notes import requires Full Disk Access so Atomic can read the Notes database. This is desktop-only and does not apply to a remote headless server.

URL Ingestion

Use URL ingestion when you want Atomic to fetch and extract an article:

curl -X POST http://localhost:8080/api/ingest/url \

-H "Authorization: Bearer <token>" \

-H "Content-Type: application/json" \

-d '{

"url": "https://example.com/article",

"tag_ids": [],

"title_hint": null,

"published_at": null

}'

Batch ingestion:

curl -X POST http://localhost:8080/api/ingest/urls \

-H "Authorization: Bearer <token>" \

-H "Content-Type: application/json" \

-d '{

"urls": [\
\
      { "url": "https://example.com/one", "tag_ids": [] },\
\
      { "url": "https://example.com/two", "tag_ids": [] }\
\
    ]

}'

URL ingestion emits WebSocket events such as ingestion-fetch-started, ingestion-complete, and ingestion-failed.

RSS and Atom Feeds

Use feeds when you want Atomic to poll a source repeatedly and create atoms for new entries. See URL Ingestion and Feeds for details.

Wikipedia Import Script

The repository includes a Wikipedia import script for stress testing and demo data:

npm run import:wikipedia -- "Machine Learning" "Rust (programming language)"

Treat this as a developer utility rather than the main user import flow.

After Import

Imports create atoms immediately and then the background pipeline handles embeddings, tagging, and graph updates. Check progress with:

curl http://localhost:8080/api/embeddings/status \

-H "Authorization: Bearer <token>"