# Atomic self-hosted semantic knowledge base review

> Atomic is a self-hosted personal knowledge base that converts Markdown notes into embedded, tagged, and semantically linked atoms. Its Rust workspace supports desktop, server, web, mobile, browser capture, and MCP integrations, but adopting it requires operating both persistent storage and one or more AI providers.

**kenforthewin/atomic** — Self-hosted, semantically-connected personal knowledge base

- Repository: https://github.com/kenforthewin/atomic
- Website: https://atomicapp.ai
- Stars: 1,993 · Forks: 142
- Language: Rust
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/kenforthewin-atomic

## Why Atomic treats notes as connected data

Atomic addresses personal and research knowledge that is easy to collect as isolated Markdown files but difficult to retrieve by meaning. It is aimed at users who want to search notes, inspect relationships, generate cited articles, combine sources, and expose a personal corpus to AI tools without surrendering server ownership.

The basic unit is an atom: a Markdown note that Atomic automatically chunks, embeds, tags, and links according to semantic similarity. This differs from treating a folder of Markdown files as an undifferentiated collection. The resulting structures support vector search through `sqlite-vec`, a force-directed canvas whose layout reflects similarity, and wiki synthesis that cites the underlying notes. Chat can search the knowledge base during a conversation, while scheduled reports can turn stored atoms into recurring findings such as daily briefings, contradiction scans, and open-question tracking.

Several entry points feed this model. RSS subscriptions can synchronize new articles as atoms, the browser extension captures pages and queues them offline until the server is reachable, and the native SwiftUI iOS app supports mobile reading and writing. This makes Atomic relevant to researchers and developers with several capture paths, although it also means adoption involves choosing which interfaces and data sources to connect.

## How atoms move through Atomic's architecture

The repository layout shows a Rust Cargo workspace rather than a single server binary. Members include `atomic-core`, `atomic-server`, `mcp-bridge`, `atomic-cloud`, `atomic-bench`, `atomic-test-support`, and the Tauri application in `src-tauri`. The frontend is built with Vite and TypeScript, while Capacitor scripts handle iOS and Android packaging. This separation supports the desktop, browser, headless server, and mobile clients described in the README.

For self-hosted operation, `docker-compose.yml` defines three default services. `server` runs the Rust API and persists `/data` in the `atomic-data` volume. `web` serves the frontend on the internal Docker network. `proxy` runs nginx, maps host port `8080` to port `80`, and routes traffic to the two application containers. Operators who already use Caddy, Traefik, or another reverse proxy can omit the supplied proxy and route traffic directly.

The content pipeline depends on AI services. Atomic supports OpenRouter, locally available Ollama models, and providers exposing an OpenAI-compatible API. Embeddings feed semantic retrieval and similarity relationships. Separate model choices can be configured for embedding, tagging, wiki, and chat through OpenRouter, while Ollama setup relies on model auto-discovery. The documentation does not explain the internal chunk-size defaults, embedding migration procedure, or recovery behavior after changing embedding models, so those details need checking before production data is imported.

## Docker Compose setup and initial instance claim

The quickest documented self-hosted path uses the repository's Docker Compose configuration. The setup token is generated into `.env`, and the default stack starts the API, web interface, and nginx proxy. The reader should see the three containers associated with those services become available.

```bash
git clone https://github.com/kenforthewin/atomic.git
cd atomic
echo "ATOMIC_SETUP_TOKEN=$(openssl rand -base64 24)" > .env
docker compose up -d
```

After startup, open `http://localhost:8080`. The setup wizard asks for the `ATOMIC_SETUP_TOKEN` value written to `.env`; this token claims the new instance. The first-use sequence then requires AI provider configuration because embeddings, automatic tagging, wiki generation, and chat depend on a provider.

OpenRouter requires an API key and permits separate model selection for the AI roles. Ollama requires locally installed and pulled models, with model discovery handled by Atomic. An OpenAI-compatible provider requires its base URL and API key. The README does not provide a noninteractive configuration file for these settings, so the documented first-run path is the setup wizard. It also does not identify a port other than `8080` for the convenience Compose stack.

## Standalone server operations and durable data

A source checkout and Rust toolchain provide a standalone server path outside Docker Compose. The following command stores data under `./data` and listens on port `8080`. On the first run, the setup wizard expects the same environment variable used by the container deployment.

```bash
ATOMIC_SETUP_TOKEN="$(openssl rand -base64 24)" \
cargo run -p atomic-server -- --data-dir ./data serve --port 8080
```

Atomic also documents direct token creation for automation or an initial setup flow that does not go through the wizard:

```bash
cargo run -p atomic-server -- --data-dir ./data token create --name default
```

The Compose file makes the persistence boundary visible: the server mounts `/data`, and Docker stores it in the named `atomic-data` volume. That boundary is operationally important. Removing the container does not by itself remove the named volume, but replacing the volume does remove the mounted Atomic data. The repository includes an optional Litestream service under the `backup` profile, configured through `docker/litestream.yml` and environment variables for credentials, bucket, endpoint, and replication path. The README excerpt does not document a restore procedure or backup verification, so the presence of replication support should not be treated as a confirmed recovery plan.

## SQLite concurrency creates a measurable memory trade-off

Atomic's default Compose deployment uses SQLite rather than requiring PostgreSQL. The server container explicitly documents one writer connection plus a configurable read pool, with a separate page cache on each connection. Its default settings are a read pool of 16, a 64,000 KiB write cache, and an 8,000 KiB read cache.

That design is simple for a personal deployment, but the repository's own configuration comment warns that steady-state memory scales with the number of databases, read connections, and cache size. The Compose file exposes three tuning variables:

```yaml
- ATOMIC_SERVER_READ_POOL_SIZE=${ATOMIC_SERVER_READ_POOL_SIZE:-}
- ATOMIC_SQLITE_CACHE_KB=${ATOMIC_SQLITE_CACHE_KB:-}
- ATOMIC_SQLITE_READ_CACHE_KB=${ATOMIC_SQLITE_READ_CACHE_KB:-}
```

The file specifically points to an 8 GB host running several databases as a case where operators should lower the pool and cache budgets. No measured memory result is supplied, so adoption planning should use the documented formula rather than an invented capacity estimate. Also note that `dev:server:pg` exists in `package.json`, but the visible self-hosting documentation centers on SQLite. It does not explain when PostgreSQL should be selected or document its production configuration.

## MCP and browser capture widen the trust boundary

Atomic exposes its knowledge base through an MCP endpoint. The documented capabilities are search, reading, creation, updating, and ingestion of atoms. A remote client connects to `/mcp` using a Bearer token:

```json
{
  "mcpServers": {
    "atomic": {
      "type": "url",
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

That endpoint can modify knowledge as well as retrieve it, so access control matters even when the server is self-hosted. The README does not document per-operation scopes, token expiration, audit logs, or a rollback mechanism for MCP changes. Desktop local mode instead uses `atomic-mcp-bridge`, a stdio-to-HTTP bridge that reads the local authentication token automatically.

The Chrome extension is a separate capture path. It stores the server URL and API token, queues captures while offline, and synchronizes them when the server becomes available. This is convenient for intermittent connectivity, but it also extends the trust boundary beyond the deployment host. Operators should decide whether the browser extension and MCP endpoint are needed before exposing the service beyond a trusted network.

## Maintenance, licensing, and deployment choices

The repository is not archived, and its last push was on 2026-09-29. Recent tagged releases include `v1.45.0` on 2026-08-09, `v1.44.0` on 2026-08-08, and `v1.43.0` on 2026-08-04. Those dates indicate recent project activity, but the README does not provide a published upgrade-compatibility policy, migration guide, or support commitment.

Atomic is distributed under the MIT license. That permits use, modification, distribution, and sublicensing subject to the license terms, while the documentation does not present warranty or liability protections for AI-generated output. Self-hosting still creates direct costs for storage, backups, provider usage, upgrades, and monitoring. Ollama can keep inference local, whereas OpenRouter and remote OpenAI-compatible providers introduce an external service dependency that the MIT license does not remove.

The documented alternative to self-hosting is Atomic Cloud, described as a hosted deployment at a user subdomain. The distinction is operational: Atomic Cloud removes the operator's need to run the documented Compose or Fly.io stack, while self-hosting places `atomic-data`, AI provider configuration, networking, backups, and upgrades under the operator's control. The README also documents a desktop build, but it does not claim that every server feature is available without the web or server components.

## Conclusion

Atomic is appropriate for a technically capable user or team that wants self-hosted Markdown notes with semantic search, graph visualization, generated articles, agentic chat, and MCP access. It is a poor fit for someone seeking a zero-configuration local notes editor or a fully private deployment that requires no external inference service. Before adoption, verify provider availability, model compatibility, the memory needed for SQLite read pooling, backup arrangements for the `atomic-data` volume, and whether features exposed through `/mcp` meet the intended access-control policy. For this repository, the first concrete adoption check is a Docker Compose deployment using the documented `ATOMIC_SETUP_TOKEN` flow and the provider you expect to operate.

## FAQ

### How do I self-host Atomic with Docker Compose?

Clone the repository, generate `ATOMIC_SETUP_TOKEN` into `.env`, and run `docker compose up -d`. Open `http://localhost:8080` and enter that token in the setup wizard.

### Which AI providers can Atomic use?

Atomic supports OpenRouter, Ollama, and providers with an OpenAI-compatible API. The selected services supply embeddings and language-model features used by search, tagging, wiki synthesis, and chat.

### Does Atomic need an internet connection or external AI service?

The core server and web application run through the documented self-hosted deployment. AI functionality still requires either a remote configured provider or locally available Ollama models; the README does not promise that every AI feature works fully offline.

## Sources

- [kenforthewin/atomic on GitHub](https://github.com/kenforthewin/atomic)
- [License: MIT](https://github.com/kenforthewin/atomic/blob/main/LICENSE)
- [Project website](https://atomicapp.ai)
- [README](https://github.com/kenforthewin/atomic/blob/main/README.md)
- [Releases](https://github.com/kenforthewin/atomic/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kenforthewin-atomic