{"id":47620530,"url":"https://github.com/kenforthewin/atomic","last_synced_at":"2026-04-24T05:01:33.086Z","repository":{"id":345990551,"uuid":"1103927253","full_name":"kenforthewin/atomic","owner":"kenforthewin","description":"Self-hosted, semantically-connected personal knowledge base","archived":false,"fork":false,"pushed_at":"2026-04-20T23:39:39.000Z","size":43651,"stargazers_count":1110,"open_issues_count":23,"forks_count":79,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-04-21T00:40:10.440Z","etag":null,"topics":["knowledge-base"],"latest_commit_sha":null,"homepage":"https://atomicapp.ai","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kenforthewin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-25T14:18:06.000Z","updated_at":"2026-04-21T00:39:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"49b83fe4-f009-4c2e-a110-f26e577984b9","html_url":"https://github.com/kenforthewin/atomic","commit_stats":null,"previous_names":["kenforthewin/atomic"],"tags_count":111,"template":false,"template_full_name":null,"purl":"pkg:github/kenforthewin/atomic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenforthewin%2Fatomic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenforthewin%2Fatomic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenforthewin%2Fatomic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenforthewin%2Fatomic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kenforthewin","download_url":"https://codeload.github.com/kenforthewin/atomic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenforthewin%2Fatomic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32209895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T03:15:14.334Z","status":"ssl_error","status_checked_at":"2026-04-24T03:15:11.608Z","response_time":64,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["knowledge-base"],"created_at":"2026-04-01T22:01:36.473Z","updated_at":"2026-04-24T05:01:33.055Z","avatar_url":"https://github.com/kenforthewin.png","language":"Rust","readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./docs/images/logo-dark.svg\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"./docs/images/logo.svg\"\u003e\n  \u003cimg alt=\"Atomic\" src=\"./docs/images/logo.svg\" width=\"300\"\u003e\n\u003c/picture\u003e\n\n[![Discord](https://img.shields.io/discord/1489017497200885800?label=discord\u0026logo=discord\u0026logoColor=white\u0026color=5865F2)](https://discord.gg/fT4vTERhz3)\n[![Desktop App](https://img.shields.io/github/v/release/kenforthewin/atomic?label=desktop\u0026logo=github)](https://github.com/kenforthewin/atomic/releases/latest)\n[![Server Image](https://img.shields.io/github/v/tag/kenforthewin/atomic?label=server\u0026logo=docker)](https://github.com/kenforthewin/atomic/pkgs/container/atomic-server)\n[![Web Image](https://img.shields.io/github/v/tag/kenforthewin/atomic?label=web\u0026logo=docker)](https://github.com/kenforthewin/atomic/pkgs/container/atomic-web)\n\nA personal knowledge base that turns markdown notes into a semantically-connected, AI-augmented knowledge graph.\n\nAtomic stores knowledge as **atoms** — markdown notes that are automatically chunked, embedded, tagged, and linked by semantic similarity. Your atoms can be synthesized into wiki articles, explored on a spatial canvas, and queried through an agentic chat interface.\n\nhttps://github.com/user-attachments/assets/e8cd771f-6e23-46cf-86d1-3c70cb8d1954\n\n*Daily briefing — AI summary of recent atoms with inline citations that highlight the source on a mini-canvas*\n\nhttps://github.com/user-attachments/assets/282da0e3-4969-42dd-b591-7da974078e87\n\n*Atoms — markdown notes with tags, sources, and neighborhood graph*\n\n![Atom Viewer](./docs/images/atom.png)\n\n*Wiki synthesis — LLM-generated articles with inline citations*\n\n![Wiki Synthesis](./docs/images/wiki.png)\n\n*Canvas — view your knowledge on an interactive graph*\n\n![Canvas](./docs/images/canvas.png)\n\n*Semantic search — find by meaning, not keywords*\n\n![Semantic Search](./docs/images/search.png)\n\n## Features\n\n- **Atoms** — Markdown notes with hierarchical tagging, source URLs, and automatic chunking\n- **Semantic Search** — Vector search over your knowledge base using sqlite-vec\n- **Canvas** — Force-directed spatial visualization where semantic similarity determines layout\n- **Wiki Synthesis** — LLM-generated articles with inline citations, built from your notes\n- **Chat** — Agentic RAG interface that searches your knowledge base during conversation\n- **Auto-Tagging** — LLM-powered tag extraction organized into hierarchical categories\n- **Multiple AI Providers** — OpenRouter, Ollama, or any OpenAI-compatible provider for embeddings and LLMs\n- **RSS Feeds** — Subscribe to feeds and automatically sync new articles as atoms\n- **Browser Extension** — Capture web content directly into Atomic ([Chrome Web Store](https://chromewebstore.google.com/detail/bknijbafnefbaklndpglcmlhaglikccf))\n- **MCP Server** — Expose your knowledge base to Claude and other AI tools\n- **Multi-Database** — Multiple knowledge bases with a shared registry\n- **iOS App** — Native SwiftUI client for reading and writing atoms on mobile ([App Store](https://apps.apple.com/us/app/atomic-kb/id6759266634))\n\n## Getting Started\n\nAtomic runs as a **desktop app** (Tauri), a **headless server** (Docker/Fly.io), or both.\n\n### Desktop App\n\nDownload the latest release for your platform from [GitHub Releases](https://github.com/kenforthewin/atomic/releases) (macOS, Linux, Windows).\n\nOn first launch, the setup wizard walks you through AI provider configuration.\n\n### Self-Host with Docker Compose\n\n```bash\ngit clone https://github.com/kenforthewin/atomic.git\ncd atomic\ndocker compose up -d\n```\n\nThis starts three services: the API server, the web frontend, and an nginx reverse proxy. Open `http://localhost:8080` and claim your instance through the setup wizard.\n\nThe proxy service is provided for convenience — if you already run your own reverse proxy (Caddy, Traefik, etc.), you can skip it and route traffic to the `server` and `web` containers directly. See `docker/nginx.conf` for an example configuration.\n\n### Deploy to Fly.io\n\n```bash\ncp fly.toml.example fly.toml\nfly launch --copy-config --no-deploy\nfly volumes create atomic_data --region \u003cyour-region\u003e --size 1\nfly deploy\n```\n\nOpen `https://your-app.fly.dev` and claim your instance. The public URL for OAuth/MCP is auto-detected from the Fly app name.\n\n### Standalone Server\n\n```bash\ncargo run -p atomic-server -- --data-dir ./data serve --port 8080\n```\n\nOn first run, create an API token:\n\n```bash\ncargo run -p atomic-server -- --data-dir ./data token create --name default\n```\n\n## AI Provider Setup\n\nAtomic needs an AI provider for embeddings, tagging, wiki generation, and chat.\n\n- **OpenRouter** — Get an API key from [openrouter.ai](https://openrouter.ai). Supports separate model selection for embedding, tagging, wiki, and chat.\n- **Ollama** — Install [Ollama](https://ollama.com) and pull models (e.g., `ollama pull nomic-embed-text`). Atomic auto-discovers available models.\n- **OpenAI-compatible** — Any provider with an OpenAI-compatible API (e.g., OpenAI, Azure OpenAI, Together, Groq). Configure the base URL and API key.\n\nConfigure via the setup wizard on first launch, or later in Settings.\n\n## Browser Extension\n\nThe Atomic Web Clipper captures web content as atoms. Install from the [Chrome Web Store](https://chromewebstore.google.com/detail/bknijbafnefbaklndpglcmlhaglikccf), then configure your server URL and API token in the extension options.\n\nCaptures are queued offline and synced when the server is available.\n\n## MCP Server\n\nAtomic exposes an MCP endpoint for Claude and other AI tools to search and create atoms.\n\n### Desktop App (Local Mode)\n\nThe desktop app bundles `atomic-mcp-bridge`, a stdio-to-HTTP bridge that reads the local auth token automatically. No token configuration needed — just point your MCP client at the binary:\n\n```json\n{\n  \"mcpServers\": {\n    \"atomic\": {\n      \"command\": \"/Applications/Atomic.app/Contents/MacOS/atomic-mcp-bridge\"\n    }\n  }\n}\n```\n\nThe app's Settings \u003e Integrations page shows the exact path for your system.\n\n### Remote / Self-Hosted\n\nFor remote servers or the web app, connect via the HTTP endpoint at `/mcp` with a Bearer token:\n\n```json\n{\n  \"mcpServers\": {\n    \"atomic\": {\n      \"type\": \"url\",\n      \"url\": \"https://your-server.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\nCreate a token from Settings \u003e Connection \u003e API Tokens, or via the CLI:\n\n```bash\natomic-server token create --name \"claude\"\n```\n\n**Available tools:** `semantic_search`, `read_atom`, `create_atom`, `update_atom`\n\n## Architecture\n\nAll business logic lives in `atomic-core`, a standalone Rust crate with no framework dependencies. `atomic-server` wraps it with a REST API, WebSocket events, and an embedded MCP endpoint. Every client connects to `atomic-server` over HTTP:\n\n```\n                    +------------------+\n                    |   atomic-core    |\n                    |   (all logic)    |\n                    +--------+---------+\n                             |\n                    +--------v---------+\n                    |  atomic-server   |\n                    | (REST + WS + MCP)|\n                    +--------+---------+\n              +---------+----+----+---------+\n              v          v        v         v\n    +-----------+  +----------+  +------+  +----------+\n    | src-tauri |  | React UI |  | iOS  |  |mcp-bridge|\n    | (sidecar) |  | (browser)|  | app  |  | (stdio)  |\n    +-----+-----+  +----------+  +------+  +-----+----+\n          |                                       |\n    +-----v-----+                           +-----v-----+\n    |  React UI  |                          | MCP clients|\n    | (desktop)  |                          |(Claude,etc)|\n    +------------+                          +------------+\n```\n\n## Project Structure\n\n```\nCargo.toml                  # Workspace root\ncrates/atomic-core/         # All business logic\ncrates/atomic-server/       # REST + WebSocket + MCP server\ncrates/mcp-bridge/          # HTTP-to-stdio MCP bridge\nsrc-tauri/                  # Tauri desktop app (launches server as sidecar)\nsrc/                        # React frontend (TypeScript)\nios/                        # Native iOS app (SwiftUI)\nextension/                  # Chromium browser extension\nscripts/                    # Import and utility scripts\n```\n\n## Development\n\n### Prerequisites\n\n- Node.js 22+\n- Rust toolchain ([rustup](https://rustup.rs))\n- For the desktop app: platform-specific [Tauri v2 dependencies](https://v2.tauri.app/start/prerequisites/)\n\n### Commands\n\n```bash\nnpm install                       # Install frontend dependencies\n\n# Desktop app\nnpm run tauri dev                 # Dev with hot reload\nnpm run tauri build               # Production build\n\n# Server only\ncargo run -p atomic-server -- serve --port 8080\n\n# Frontend only\nnpm run dev                       # Vite dev server\n\n# Checks\ncargo check                       # All workspace crates\ncargo test                        # All tests\nnpx tsc --noEmit                  # Frontend type check\n```\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|------------|\n| Core | Rust, SQLite + sqlite-vec, tokio |\n| Desktop | Tauri v2 |\n| Server | actix-web |\n| Frontend | React 18, TypeScript, Vite 6, Tailwind CSS v4, Zustand 5 |\n| Editor | CodeMirror 6 |\n| Canvas | Sigma.js, Graphology |\n| iOS | SwiftUI, XcodeGen |\n| AI | OpenRouter, Ollama, or OpenAI-compatible (pluggable) |\n\n## License\n\nMIT\n","funding_links":[],"categories":["Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenforthewin%2Fatomic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkenforthewin%2Fatomic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenforthewin%2Fatomic/lists"}