AtlasBrain

A local, open-source second brain for your code, notes, and AI assistants.

AtlasBrain turns a project folder into searchable knowledge: it maps code relationships, connects documents, and stores decisions and learnings as Markdown. Through MCP (Model Context Protocol), Claude Code, Codex, and Antigravity can retrieve that knowledge and save useful context for your next conversation.

Use it to understand an unfamiliar repository, investigate a bug, prepare a refactor, or build a lasting knowledge base alongside your work. It also works with folders of notes and research, without a code repository.

Why use AtlasBrain?

Your Markdown notes remain usable in Obsidian or any text editor. AtlasBrain runs independently of Obsidian and does not require a plugin inside it.

Related MCP server: KnowledgeRail

Preview

The light pulse is disabled by default. When enabled, it illuminates nodes and connections while idle. Toggle it with the pulse icon beside settings. The 3D brain rotates automatically while idle and pauses for interaction; drag to rotate it yourself.

Dependency map

Open a code file and select Dependency map to inspect its incoming and outgoing relationships.

These screenshots and GIFs use a demo made from public code and sample notes.

What you can do

• Search code and knowledge together. Combine keyword search, local multilingual embeddings, exact names, and symbol lookup. Filter by folder, tag, type, status, date, exact phrase, or excluded terms. PDFs, DOCX, and HTML are also searchable.

• Explore your project visually. Browse a brain-shaped 2D or 3D graph, or an orbital view. Inspect files, dependencies, notes, and connections; find isolated indexed files and review suggested links. Large projects use bounded pages of real file nodes to keep rendering manageable: 500 nodes per page by default, adjustable from 50 to 800 in the graph controls. The preference is saved per project. A pulse icon beside the settings icon toggles cortex animation; idle 3D rotates automatically and pauses during interaction.

• Maintain project memory. Create and edit Markdown notes, decisions, and learnings through the interface or MCP. Explicitly supersede or revoke outdated decisions; active task context favors their current replacements.

• Update notes with recovery in mind. Use atomic saving, revision checks, section updates, and local version history. Rename or move indexed Markdown notes while updating resolved wikilinks and supported relative Markdown links.

• Keep growing knowledge readable. Create linked extractive summaries of eligible annotations, or provide a reviewed summary through MCP. Source notes remain intact, and changed sources flag their summaries as stale.

• Bring references into the project. Import public web pages and text-based PDFs as Markdown snapshots with their source URL and retrieval metadata.

• Keep the index current. The shared service watches external file changes and updates the index incrementally. Assistants record conversation memory through MCP in the current conversation; separate transcript extraction is off by default. Version updates run when the service finds a newer release in a clean clone.

Code relationships extracted from source are distinguished from inferred similarities and reviewed links. Suggested links need review. An isolated file has no indexed connections; it is not necessarily unused.

What gets indexed

In Git repositories, AtlasBrain includes tracked files and untracked files that Git does not ignore. It skips dependency and build folders such as node_modules, .next, dist, build, and Python virtual environments. Files already tracked by Git remain eligible even if later added to .gitignore. Hidden folders are skipped except for project memory notes in .atlasbrain/.

For additional exclusions, add patterns to .atlasbrainignore. In folders without a Git repository, AtlasBrain uses its built-in exclusions and .atlasbrainignore; .gitignore rules are not applied. Only supported file formats are indexed.

Get started

For installation with automatic startup at login on macOS or native Windows, follow the automated installation guide. It installs Python and dependencies and configures HTTP clients. The manual steps below remain available.

Requirements: Git and uv, on macOS, Windows or Linux. Windows runs natively; WSL is not required. uv downloads Python 3.12 and installs the project's dependencies automatically.

1. Clone

Clone the public repository:

git clone https://github.com/danilofacco/atlasbrain.git
cd atlasbrain

2. Generate your MCP configuration

Replace /absolute/path/to/my-project with the folder you want to index. It can be a code repository or a folder of notes. Choose your client:

uv run --python 3.12 atlasbrain setup --vault /absolute/path/to/my-project --client claude
# Or: --client antigravity
# Or: --client codex

On Windows, use a native folder such as --vault "C:\Projects\my-project".

This installs dependencies, creates the project's .atlasbrain/, starts or reuses the shared service, and prints the configuration to paste into your client. No global Python install, symlink, API key, or manually installed dependency is needed. It does not edit your client's configuration automatically.

The first index downloads the local embedding model and can take longer. The service is available while indexing continues. To disable embeddings before starting it, set ATLASBRAIN_NO_EMBED=1; keyword search and code graphs still work.

3. Paste the configuration

Merge the generated entry into an existing configuration rather than replacing other servers. Reconnect/reload the MCP client after changing its configuration. These Claude instructions are for Claude Code. For Claude Desktop chat, follow the Desktop connection instructions to reach the same service.

Step-by-step AtlasBrain guides: Claude Code CLI, Codex Desktop, Codex CLI, Antigravity, and OpenCode.

Official instructions: Claude Code, Antigravity, Codex.

Use one global URL for every client and project: http://127.0.0.1:8765/mcp. Setup registers an initial folder but does not bind the MCP configuration to it. No per-project MCP entry is required.

When the client supplies one local workspace root, AtlasBrain identifies and registers that project automatically. Otherwise the assistant supplies project_folder from the working folder in its conversation context. Multiple roots require the assistant to choose the relevant folder. Missing context is rejected to avoid mixing projects; the selected browser folder and daemon working directory are never used to guess the client project. The optional project argument is a folder selector, not the note's project label.

Open the visual interface

Default web port: 8765. After starting the service, open http://127.0.0.1:8765 in your browser. The web interface and MCP share this local service and port.

From the AtlasBrain checkout, run:

uv run atlasbrain serve --vault /absolute/path/to/my-project

This opens the project in your browser and reuses the shared service. The default address is http://127.0.0.1:8765.

After restarting your computer, start the service again before using MCP:

uv run atlasbrain start --vault /absolute/path/to/my-project

Use uv run atlasbrain status to check it. The operation guide explains service controls, automatic updates, optional hooks, and language coverage. Claude Desktop can use its HTTP connector route; the optional command-based compatibility bridge also reaches the same shared service.

Uninstall

From the AtlasBrain checkout, disable automatic startup and stop the service before removing installation files.

macOS

bash scripts/uninstall-startup.sh
.venv/bin/python -m atlasbrain.cli stop

Windows (PowerShell)

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1 -UninstallStartup

These commands remove automatic startup and preserve client settings, installation files, and project memory. To finish uninstalling, remove only the atlasbrain entry from each configured MCP client, remove the AtlasBrain Desktop shortcut, and delete the installation checkout if you no longer need it. Remove the Claude Desktop connector through its Connectors settings.

See the macOS and Windows uninstall guide for configuration locations, optional cleanup, and instructions for preserving your notes. Uninstalling AtlasBrain does not require removing Python, Git, or uv.

Try it with your assistant

• “Find where authentication is implemented and explain who depends on it.”

• “Gather context for investigating why notifications are duplicated.”

• “What would be affected if I changed this function?”

• “Record this decision, including the alternatives and our reasoning.”

• “Mark the old decision as superseded by this one.”

• “Rename this note and update its Markdown links.”

• “Import this documentation URL and connect it to our project notes.”

• “Find isolated files and suggest connections for me to review.”

The interface defaults to English. Choose PT-BR in the top bar for Brazilian Portuguese; the preference persists in your browser. Your file contents keep their original language.

Ask in Portuguese or English. MCP tool names, arguments and instructions use English:

For example, authentication folder:src type:code searches code inside src; queue type:decision status:active searches active decisions about queues. Legacy Portuguese tool names remain callable for existing clients, but only the English names are advertised. Reconnect the MCP client to refresh its tool list. On the global MCP endpoint, pass project_folder with the absolute project folder; one client workspace root selects that folder automatically when available.

Queries containing only filters, such as type:decision, can also list matches.

Where your data lives

my-project/
├── .atlasbrain/
│   ├── Decisions/          # recorded decisions
│   ├── Learnings/     # learnings
│   ├── Imports/      # imported references
│   ├── Summaries/         # linked summaries
│   ├── REPORT.md      # generated architecture report
│   └── index.db          # local SQLite index
└── your code, notes, and documents

New memory folders use English names. Existing notes in Portuguese folders remain indexed in place, preserving their paths and links. Existing imports and summaries are reused; older MCP tool names and CLI flags remain compatibility aliases. Python modules, functions, and variables use English; persisted metadata and bilingual source content retain their original format.

Indexing and embedding inference run locally. Project memory in .atlasbrain/ is ignored by Git by default. Add paths to .atlasbrainignore to exclude them from indexing. Shared service state and logs live in ~/.config/atlasbrain/.

MCP returns requested content to your connected assistant, whose own data policies still apply. Dependencies and the embedding model need internet access on first installation, as do URL imports and version checks. Optional conversation capture can invoke your configured Claude or Codex CLI.

Automatic consolidation selects excerpts; it does not independently generate new reasoning or delete source files. URL imports read a single public page or PDF; they do not crawl websites, execute JavaScript, or OCR scanned documents.

Search quality and performance

Search is evaluated with source-reviewed questions in Portuguese and English, separating calibration from validation and ranking accuracy from filter behavior. The latest local comparison used 80 questions with reviewed answers plus 20 empty filter scopes across five projects. With the model loaded, positive-query median engine latency was 37.72 ms and the expected file appeared in the top three in 76.25% of those questions. These describe one development benchmark; results depend on the project, query, index, and hardware.

See the performance report, bilingual evaluation, and benchmark instructions for the method and reproducible runs.

Further documentation

• Uninstall on macOS and Windows

• Features, language coverage, hooks, and service operation

• Claude Desktop connection

• Claude Code CLI installation and connection

• Codex Desktop installation and connection

• Codex CLI installation and connection

• Antigravity installation and connection

• OpenCode installation and connection

• Task context and Markdown renaming

• Reliable memory updates and recovery

• Memory consolidation

• Engine reliability and evaluation

Development

uv sync --locked
uv run pytest -q
# Optional visual interaction checks; Node.js is needed only for these tests:
node --test tests/viewer.test.cjs

Contributions are welcome. Include a reproducible example when reporting a bug; for search issues, describe the question and expected file without sharing private project contents.

Created by Danilo Facco (@danilofacco). Licensed under MIT.