# Atomic

Self-hosted knowledge base that links markdown notes by meaning, with REST API and MCP server.

Atomic stores notes as atoms that are chunked, embedded, tagged and linked by similarity, then synthesized into cited wiki articles and scheduled reports. One Rust server exposes a REST API with OpenAPI docs and an MCP endpoint at /mcp, both with bearer tokens. It runs as a desktop app, Docker Compose or Fly.io; a hosted Atomic Cloud also exists.

- Capabilities: adaptable, operable
- Vertical: notes-knowledge
- Shape: product
- Form factor: web-app
- Execution model: hybrid
- Provenance: unknown (recorded, never ranked)
- Repo: https://github.com/kenforthewin/atomic (MIT), 2001 stars, last commit 2026-09-29
- Last activity: 2026-09-29
- Page: apps/kenforthewin--atomic.html
- JSON: apps/kenforthewin--atomic.json

## Use it when

- you want a private note graph your agent can search and write to over MCP
- you want cited wiki articles and recurring research reports built from your own notes

## Gotchas

- MCP tools cover read, search, create and edit; deleting notes, wiki generation, reports, feeds and chat need the REST API
- Needs an AI provider for embeddings, tagging, wiki and chat
- Desktop MCP uses a stdio bridge binary, remote MCP uses a bearer token
- Atomic Cloud Free stops at 250 atoms, 1 knowledge base and 100 MB; over the limit the account turns read-only

## Editions

- Self-hosted: Free, open source
  - source: https://github.com/kenforthewin/atomic
  - container: git clone https://github.com/kenforthewin/atomic.git && cd atomic && echo "ATOMIC_SETUP_TOKEN=$(openssl rand -base64 24)" > .env && docker compose up -d
  - binary: https://github.com/kenforthewin/atomic/releases
- Atomic Cloud Free: Free, closed source
  - hosted: https://atomicapp.ai/cloud
- Atomic Cloud Pro: $12 per month, closed source
  - hosted: https://atomicapp.ai/cloud

## Adaptable: make it yours

Effort: config-only (6 things to edit), surface kind admin-ui

Env vars only set up the deployment: ATOMIC_SETUP_TOKEN, PUBLIC_URL, ATOMIC_STORAGE, ATOMIC_DATABASE_URL and SQLite cache sizes. Behavior such as provider, models, auto-tagging and scheduled briefings is runtime settings stored in the database, edited in the Settings UI or through PUT /api/settings/{key}. Built-in prompts are Rust source in crates/atomic-core, so changing those is a code edit.

- Env vars: ATOMIC_SETUP_TOKEN, PUBLIC_URL, ATOMIC_STORAGE, ATOMIC_DATABASE_URL
- Config files: docker-compose.yml, fly.toml.example
- Prompt files: none
- Accounts you'll need: an AI provider (OpenRouter, OpenAI-compatible) or a local Ollama for embeddings, tagging, wiki and chat

## Operable: what an agent can drive

Operability: official. Interface: mcp at https://atomicapp.ai/guides/mcp-server/ (published by the builder, both).

### Reach (complete coverage)

- Create, update and edit notes (atoms): reachable. MCP tools create_atom, update_atom, edit_atom; REST /api/atoms
- Read and browse notes and tags: reachable. MCP tools read_atom, list_atoms, list_tags, list_databases
- Semantic search and find similar: reachable. MCP tools semantic_search, find_similar; REST /api/search
- Capture web pages: reachable. MCP tool ingest_url; REST /api/ingest/url
- Read synthesized wiki articles: reachable. MCP tools list_wikis, get_wiki
- Read scheduled report findings: reachable. MCP tools list_reports, get_report_findings
- Generate wiki articles and run reports: reachable. REST /api/wiki/{tag_id}/generate and /api/reports/{id}/run; not in the MCP tool list
- Subscribe to RSS feeds: reachable. REST /api/feeds and /api/feeds/{id}/poll; not in MCP
- Chat with the knowledge base: reachable. REST POST /api/conversations and POST /api/conversations/{id}/messages; not in MCP
- Delete notes: reachable. REST DELETE /api/atoms/{id}; no delete tool among the 16 MCP tools in crates/atomic-server/src/mcp/server.rs

## Code stack

- Languages: Rust, TypeScript, Swift
- Frameworks: Tauri, React
- Package manager: cargo, npm
- Database: SQLite, Postgres
- Hosting target: docker, fly.io, desktop

## Model stack

- Providers: OpenRouter, Ollama, OpenAI-compatible
- Models: none
- Keys you need (names only): none
- Prompts live in: crates/atomic-core/src/wiki/, crates/atomic-core/src/reports/, crates/atomic-core/src/chat.rs
- Tools: semantic_search, read_atom, find_similar, list_tags, list_atoms, list_databases, list_wikis, get_wiki, list_reports, get_report_findings, create_atom, ingest_url, update_atom, edit_atom, search, fetch

## Evidence and confidence

- formFactor: README: desktop app, Docker Compose, Fly.io, headless server with React web UI (confidence 0.9)
- executionModel: README: embeddings, tagging, wiki synthesis and chat call models; storage and search are deterministic (confidence 0.85)
- operability: crates/atomic-server/src/mcp/server.rs registers 16 tools, matching docs/manual/guides/mcp-server.md; docs/manual/api/overview.md and routes/mod.rs give bearer-token REST with /api/docs/openapi.json. Both ship in atomic-server. (confidence 0.95)
- effort: docs/manual/self-hosting/configuration.md: env vars are server flags; runtime settings live in the registry DB and are edited through the UI or API. No business behavior file found. (confidence 0.75)
- editions: README: MIT, self-host forever; atomicapp.ai/cloud page text and JSON-LD: Free $0 / month, Pro $12 / month; docs/manual/cloud/plans-and-billing.md matches. (confidence 0.95)
- active: latest commit 2026-09-29, release v1.45.0 on 2026-08-09
- reach:  (confidence 0.9)

## Sources

- https://atomicapp.ai (sourcing:notes-knowledge:community)
- https://github.com/kenforthewin/atomic (analysis:notes-knowledge)
- https://atomicapp.ai/cloud (analysis:notes-knowledge)
- https://atomicapp.ai/guides/mcp-server/ (verification)