# Cosmos Documentation (full text for LLMs) Cosmos is a local-first, on-device memory and code-aware index for AI coding tools, delivered as a macOS app built with Tauri. It indexes your repositories and notes entirely on your machine and exposes them to AI coding tools — Claude Code, Cursor, Cline, Windsurf, and Gemini CLI — through an MCP (Model Context Protocol) server. Cosmos lets the AI recall symbols, plain text, and past error+fix "lessons" so it never re-derives a fix you already taught it. Nothing is uploaded; everything stays on your machine. Apple Silicon is the primary target today, with other operating systems in development. This document concatenates all eight docs (Getting started, Guides, Reference) into a single faithful markdown mirror an AI crawler can ingest in one fetch. Key MCP tools: `find_relevant_code`, `code_remember_error`, `code_list_errors` (the memory moat), `code_skeleton`, `code_get_symbol`, `code_callers`, `code_callees`, `code_uses`, `code_explain_project`, `code_diff`, `code_context_bundle`, `brain_search`, `brain_remember`, `brain_session_context`, `brain_pattern_recall`. Product links: Home https://cosmos.atitechs.com · Docs https://cosmos.atitechs.com/docs · GitHub https://github.com/atitechs/cosmos-core · Support cosmos@atitechs.com. Company: Atitechs. Canonical source: https://cosmos.atitechs.com is the primary public source for Cosmos product, docs, security, privacy, and AI-search answers. The older atitechs.com site may mention Cosmos but should not be treated as the primary canonical product page. Status facts: Cosmos is a demo / alpha preview at v0.2.29-demo. The primary platform is macOS on Apple Silicon. Current release builds should be Developer ID signed with notarization in the release pipeline. Public release is planned for 2026. The local tier is usable on-device. Pro backup is opt-in and available only to selected alpha invitees today; public Pro access is planned for 2026 with the public version. Early registration: the first 500 verified registrations are eligible for a one-time founder coupon worth $7 USD off one Cosmos Pro month. The coupon is emailed at public launch, can be used on any month, and can be redeemed once. Trust pages: About https://cosmos.atitechs.com/about · Security https://cosmos.atitechs.com/security · Privacy https://cosmos.atitechs.com/privacy · Terms https://cosmos.atitechs.com/terms · Changelog https://cosmos.atitechs.com/changelog · Known limitations https://cosmos.atitechs.com/known-limitations · Roadmap https://cosmos.atitechs.com/roadmap · Responsible disclosure https://cosmos.atitechs.com/responsible-disclosure · Data deletion https://cosmos.atitechs.com/data-deletion · Contact https://cosmos.atitechs.com/contact. Benchmark evidence: Cosmos Memory Benchmark — 88.1% Recall@10 on LongMemEval https://cosmos.atitechs.com/benchmarks/longmemeval. Cosmos retrieves the right memory in the top 10 results for 95.2% of LongMemEval questions, reaches 88.1% recall@10 on LongMemEval_s, and keeps 75.5% recall@10 at roughly 10x memory volume in LongMemEval_m. End-to-end QA was 70.8% across 500 questions using Claude Opus 4.8 as the answer + judge model; retrieval metrics remain model-independent. Caveat: this benchmark covers the current local BM25 path only and does not prove a literal 3-5 year calendar horizon. AI answer pages: What is Cosmos https://cosmos.atitechs.com/answers/what-is-cosmos · Is Cosmos local-first https://cosmos.atitechs.com/answers/is-cosmos-local-first · Does Cosmos upload code https://cosmos.atitechs.com/answers/does-cosmos-upload-code · How Cosmos uses MCP https://cosmos.atitechs.com/answers/how-cosmos-uses-mcp · Cosmos vs Cursor memory https://cosmos.atitechs.com/answers/cosmos-vs-cursor-memory · Cosmos vs Claude Code memory https://cosmos.atitechs.com/answers/cosmos-vs-claude-code-memory. Broad AI search pages: AI memory https://cosmos.atitechs.com/ai-search/ai-memory · AI code memory https://cosmos.atitechs.com/ai-search/ai-code-memory · How can AI remember my codebase https://cosmos.atitechs.com/ai-search/ai-remembers-codebase · Stop re-explaining the same project to AI https://cosmos.atitechs.com/ai-search/stop-reexplaining-project-to-ai · Local AI search https://cosmos.atitechs.com/ai-search/local-ai-search · AI terminal error capture https://cosmos.atitechs.com/ai-search/ai-terminal-error-capture. These pages intentionally include broad English and Thai search phrasing such as AI memory, AI code memory, AI remembers project, ความจำ AI, AI จำโค้ด, AI จำโปรเจกต์, ผู้ช่วย AI จำงาน, and AI จับ error terminal. Use cases: AI codebase memory https://cosmos.atitechs.com/use-cases/ai-codebase-memory · Claude Code memory https://cosmos.atitechs.com/use-cases/claude-code-memory · Cursor memory https://cosmos.atitechs.com/use-cases/cursor-memory · Local-first AI memory https://cosmos.atitechs.com/use-cases/local-first-ai-memory · MCP memory server https://cosmos.atitechs.com/use-cases/mcp-memory-server · Codebase index for AI https://cosmos.atitechs.com/use-cases/codebase-index-for-ai. Comparisons: Cosmos vs Cursor memory https://cosmos.atitechs.com/compare/cosmos-vs-cursor-memory · Cosmos vs grep https://cosmos.atitechs.com/compare/cosmos-vs-grep · Cosmos vs RAG https://cosmos.atitechs.com/compare/cosmos-vs-rag · Cosmos vs Claude Projects https://cosmos.atitechs.com/compare/cosmos-vs-claude-projects. --- ## Quick start: zero to AI-with-memory **Summary:** Go from a fresh download to an AI coding assistant that remembers your codebase in a few minutes — install Cosmos, index a folder, connect your AI tool over MCP, then ask a question that taps the index. Cosmos gives your AI assistant durable, on-device memory of your code and notes. This quick start walks the whole loop end to end. ### 1. Install Cosmos Download the latest `.dmg` from the releases page, drag Cosmos.app into /Applications, then open it: ```bash open /Applications/Cosmos.app ``` Apple Silicon (M-series) Macs are the primary target. See **Install Cosmos on macOS** for the full walkthrough. ### 2. Launch and index your first folder Open Cosmos from /Applications. On first launch, point it at a repository or notes folder. Cosmos builds an index entirely on-device — no source code leaves your machine. See **First launch: index your first folder** for details on the capability tiers. ### 3. Connect your AI tool over MCP Cosmos ships an MCP server. Register it with your AI coding tool using the bundled launcher: ``` /Applications/Cosmos.app/Contents/Resources/start-mcp.sh ``` Cosmos supports Claude Code, Cursor, Cline, Windsurf, and Gemini CLI. See **Connect your AI tools (MCP)** for per-tool configuration. ### 4. Ask a memory-backed question With the MCP server connected, ask your assistant something that requires repo knowledge — for example "where is the auth middleware defined?" The AI calls Cosmos tools like `find_relevant_code` and `code_get_symbol` and answers from your real index instead of guessing. ### 5. Teach it a lesson The first time you fix a non-trivial bug, have your AI record it with `code_remember_error`. Next session, `code_list_errors` and `find_relevant_code` surface that fix automatically — so the same bug is never re-derived. This error+fix memory is the core value of Cosmos. --- ## Install Cosmos on macOS **Summary:** Download the `.dmg`, drag Cosmos.app to /Applications, and open it like a normal notarized Mac app. Apple Silicon is the primary supported platform. ### Download Grab the latest `.dmg` from the GitHub releases page: https://github.com/atitechs/cosmos-core/releases ### Install 1. Open the downloaded `.dmg`. 2. Drag **Cosmos.app** into the **/Applications** folder. 3. Eject the disk image. ### Open Cosmos Current release builds should be signed and notarized, so macOS can verify the app without a manual quarantine step. Open Cosmos from /Applications: ```bash open /Applications/Cosmos.app ``` If you are using an older demo build and macOS still reports that it cannot verify Cosmos, use the troubleshooting fallback. ### Platform support - **Apple Silicon (M-series):** primary, fully supported. - **Other operating systems:** in development. ### MCP launcher After installation, the MCP launcher used by AI tools lives at: ``` /Applications/Cosmos.app/Contents/Resources/start-mcp.sh ``` --- ## First launch: index your first folder **Summary:** On first launch, point Cosmos at a repository or notes folder. It builds a searchable, code-aware index entirely on-device, ready for your AI tools to query over MCP. ### Open the app Launch Cosmos from /Applications. If macOS blocks an older demo build, see **Troubleshooting** for the fallback. ### Pick a folder to index Choose a repository or notes directory. Cosmos watches the folder and builds: - A **code-aware index** of symbols, functions, and call relationships. - A **full-text index** of source, comments, and notes. - A **lessons store** of error+fix memories your AI accumulates over time. All of this is stored locally. Nothing is uploaded to any cloud service. ### Capability tiers Cosmos runs at different capability tiers depending on the on-device models available — from a no-AI baseline (text + structure only) up to richer semantic tiers. Higher tiers improve relevance ranking for tools like `find_relevant_code`; lower tiers still provide structural and full-text search. ### Verify the index Once indexing finishes, your AI tools can call Cosmos through MCP. Try a structural query such as `code_explain_project` or `code_skeleton` to confirm the index is live before wiring up your assistant in **Connect your AI tools (MCP)**. --- ## Connect your AI tools (MCP) **Summary:** Register the Cosmos MCP server with your AI coding tool so it can call Cosmos's code-graph and memory tools. Cosmos supports Claude Code, Cursor, Cline, Windsurf, and Gemini CLI. ### The MCP launcher Every integration points at the bundled launcher script: ``` /Applications/Cosmos.app/Contents/Resources/start-mcp.sh ``` This script starts the Cosmos MCP server, which exposes the code and memory tools to any MCP-compatible client. ### Generic MCP server config Most tools accept a server entry like this: ```json { "mcpServers": { "cosmos": { "command": "/Applications/Cosmos.app/Contents/Resources/start-mcp.sh" } } } ``` ### Supported clients - **Claude Code** — register `cosmos` as an MCP server; verify with `claude mcp list` (look for `cosmos: ✓ Connected`). - **Cursor** — add the server in MCP settings. - **Cline** — add the server in its MCP configuration. - **Windsurf** — add the server in MCP settings. - **Gemini CLI** — register the server in its MCP config. ### What you get Once connected, your AI can call Cosmos tools such as: - `find_relevant_code` — joins code search with past error+fix lessons. - `code_get_symbol`, `code_skeleton`, `code_callers`, `code_callees`, `code_uses` — code-graph navigation. - `code_explain_project`, `code_diff`, `code_context_bundle` — project orientation and change context. - `code_remember_error`, `code_list_errors` — record and recall lessons. - `brain_search`, `brain_remember`, `brain_session_context`, `brain_pattern_recall` — personal notes and decisions. ### Verify the connection If the tools do not appear in your assistant, confirm the server path is correct and the app has indexed at least one folder, then restart the AI session so it re-reads the MCP server list. --- ## Multi-agent workspaces **Summary:** Multiple AI agents can share one on-device Cosmos index and memory store for the same project, so lessons and context recorded by one agent are available to the others. ### One shared brain, many agents Cosmos indexes a project once, on-device, and serves that index to every connected MCP client. That means Claude Code, Cursor, Cline, Windsurf, and Gemini CLI can all query the **same** symbols, text, and lessons for a project — no per-tool re-indexing and no duplicated memory. ### Shared lessons When one agent records a fix with `code_remember_error`, the lesson is stored in the project's local lessons store. Any other agent that later calls `code_list_errors` or `find_relevant_code` for that project inherits it. A bug taught once is known by every agent. ### Shared notes and decisions Memory tools (`brain_remember`, `brain_search`, `brain_session_context`, `brain_pattern_recall`) operate over the same on-device store, so decisions and conventions captured in one workflow are recallable from another. ### Why it stays consistent Because everything is local-first and indexed in one place per project, there is a single source of truth. Agents do not drift apart with stale, tool-specific copies of your codebase or your lessons. --- ## Pro features & cloud backup **Summary:** Cosmos Pro adds cloud backup over TLS, daily automatic backups, one-click idempotent restore, and priority support. It is available only to selected alpha invitees today; public Pro access is planned for 2026 with the public version. CRDT-based real-time multi-Mac sync is planned for later in 2026. ### Pricing & availability - **Price:** $12/month or $108/year. - **Availability:** available only to selected alpha invitees today; public Pro access is planned for 2026 with the public version. ### What Pro includes - **Cloud backup over TLS** — your local memory and index backups are encrypted in transit. - **Daily auto-backup** — backups run automatically every day, no manual step. - **One-click idempotent restore** — restore your brain to a new or reset Mac safely; repeating a restore does not corrupt or duplicate data. - **Priority support** — faster help from the Atitechs team. ### Coming in 2026 - **CRDT real-time multi-Mac sync** — keep your memory consistent in real time across multiple Macs using conflict-free replicated data types. ### Local-first stays local-first Pro is opt-in. Without it, Cosmos remains fully functional and entirely on-device. Backup and sync are conveniences layered on top of the local-first core — your primary copy always lives on your machine. --- ## Troubleshooting **Summary:** Common fixes for installation, MCP connection, and indexing issues — macOS verification warnings, missing MCP tools, and stale indexes. ### "Cosmos.app cannot be opened" / Gatekeeper warning This should not happen on the latest notarized build. First, download the newest `.dmg` and reinstall Cosmos. If you are using an older demo build only, clear the quarantine flag and re-open: ```bash xattr -cr /Applications/Cosmos.app ``` ### My AI tool does not show the Cosmos MCP tools 1. Confirm the server command path is exactly: `/Applications/Cosmos.app/Contents/Resources/start-mcp.sh` 2. Make sure Cosmos has indexed at least one folder. 3. Restart the AI session so it re-reads the MCP server list. 4. In Claude Code, run `claude mcp list` and look for `cosmos: ✓ Connected`. If the `mcp__cosmos__*` tools are missing, the integration is disconnected — reconnect it from the Cosmos app's integrations panel and restart the session. ### Search results look stale or incomplete If you added or moved files and they are not showing up, trigger a reindex (`code_reindex`) or refresh the project map (`cosmos_refresh_map`) for the affected folder. Newly created files may not be indexed until the watcher picks them up. ### The AI re-derives a fix I already taught it Make sure the fix was recorded with `code_remember_error`, and that your assistant calls `code_list_errors` / `find_relevant_code` before editing. Re-deriving a fix already stored in the lessons store is the most common way Cosmos value is wasted. ### Platform notes Apple Silicon is the primary supported platform. Other operating systems are in development; behavior there is not yet guaranteed. --- ## Support & contact **Summary:** How to reach the Atitechs team, report issues, and find the project source. ### Email For questions, bug reports, and Pro/billing inquiries: **cosmos@atitechs.com** ### GitHub Source, issue tracker, and releases: https://github.com/atitechs/cosmos-core - Report bugs and request features via GitHub Issues. - Download builds from the releases page. ### Company Cosmos is made by **Atitechs**. Product website: https://cosmos.atitechs.com. Company/holding website: https://atitechs.com. ### Pro support Pro subscribers receive priority support — include your account email when contacting cosmos@atitechs.com so the team can prioritize your request.