# AtlasBrain

**A local second brain that connects your code, knowledge, and project memory to AI assistants through MCP.**

AtlasBrain combines Markdown knowledge management inspired by Obsidian with local code graphs. Search your project, understand dependencies, trace the impact of changes, and preserve decisions across conversations with Claude Code, Antigravity, and Codex.

It runs independently of Obsidian. Your notes are ordinary Markdown, so you can also open them in Obsidian or any editor.

Project data lives in `.atlasbrain/`, and shared service state lives in `~/.config/atlasbrain/`. The Python package, CLI command, and MCP entry are all named `atlasbrain`.

## What it does

- **Code understanding:** tree-sitter extracts symbols, imports, calls, inheritance, and rationale comments without an LLM.
- **Graph exploration:** directed symbol relationships, BFS/DFS traversal, dependency paths, impact analysis, and architecture reports. Extracted relationships and inferred connections carry explicit provenance.
- **Hybrid search:** keyword search, local multilingual embeddings, and symbol lookup across code, notes, PDFs, DOCX, and HTML.
- **Persistent memory:** decisions and learnings stored in Markdown, including links between superseded decisions and their replacements.
- **URL imports:** save public web pages and text-based PDFs as searchable Markdown snapshots with the original URL, retrieval date, and content hash. Repeated imports reuse the same note.
- **Local interface:** browse the graph, search, read notes, and switch projects in your browser.
- **One shared service:** all MCP clients and the web interface use one persistent Python process and one HTTP port. Each project has a separate endpoint.

```text
my-project/
├── .atlasbrain/
│   ├── Decisões/          # decisions: version these Markdown notes
│   ├── Aprendizados/     # learnings
│   ├── Importações/      # web/PDF snapshots with source metadata
│   ├── RELATORIO.md      # generated architecture report
│   └── index.db          # local SQLite index, ignored by Git
└── your code and documents
```

## Install and connect

Requirements: Git and [uv](https://docs.astral.sh/uv/getting-started/installation/), on macOS or Linux. Windows users can run the service in WSL, with clients able to reach its localhost port. Native Windows is currently unsupported. `uv` downloads Python 3.12 and installs the project's dependencies automatically.

### 1. Clone

Once published as `danilofacco/atlasbrain`, clone the repository:

```bash
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:

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

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

| Client | Configuration location | Generated format |
| --- | --- | --- |
| Claude Code | `.mcp.json` in your target project | `mcpServers` with `type: "http"` and `url` |
| Antigravity | **MCP Servers → Manage MCP Servers → View raw config**, or `~/.gemini/config/mcp_config.json` | `mcpServers` with `serverUrl` |
| Codex app / CLI / IDE | `~/.codex/config.toml`, or `.codex/config.toml` in a trusted project | `[mcp_servers."atlasbrain"]` with `url` |

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**.

Official instructions: [Claude Code](https://code.claude.com/docs/en/mcp), [Antigravity](https://antigravity.google/docs/mcp), [Codex](https://developers.openai.com/codex/mcp/).

To connect another client to the same project, run `setup` again with its client name: it reuses the same PID and port. To connect another project, change `--vault`. For multiple project entries in one client, also use `--nome my-project` to give each entry a distinct name.

## One process, one port

The default address is `http://127.0.0.1:8765`. The interface and MCP endpoints share it. Project endpoints are derived from the folder's absolute path, so a client's working directory cannot silently select the wrong project.

```bash
uv run atlasbrain status
uv run atlasbrain serve --vault /absolute/path/to/my-project
uv run atlasbrain stop
uv run atlasbrain start --vault /absolute/path/to/my-project
```

`setup`, `start`, and `serve` reuse a verified live service. File locks serialize concurrent starts and prevent duplicate daemons. If another application owns the port, startup reports the conflict; it does not pick extra ports or terminate that application. You can choose a different port with `--porta 8766` on `setup`/`start`/`serve`, using the same value thereafter.

The service survives closing the terminal. **After restarting your computer, run `start` again before using MCP.** State and logs are in `~/.config/atlasbrain/server.json` and `server.log`. After updating the checkout, restart the service and reconnect your clients to discover newly added tools.

“One process” refers to the persistent MCP/web service. Installation, Git scanning, explicit CLI commands, and optional transcript capture can use temporary processes. The legacy `atlasbrain mcp` command uses stdio and starts a separate server per client; use the generated HTTP configuration for the shared service. Remove existing stdio entries for atlasbrain when migrating, and close their old client sessions.

## Ask your assistant

- “Find where authentication is implemented and explain its dependencies.”
- “What would be affected if I changed this function?”
- “Show the path between this service and the database layer.”
- “Record this architectural decision and why we chose it.”
- “Import this documentation URL into the project's brain.”

Tool names currently use Portuguese:

| Purpose | MCP tools |
| --- | --- |
| Locate and explain code | `arquivos`, `onde`, `explicar`, `relatorio` |
| Explore relationships | `consultar_grafo`, `impacto`, `caminho`, `mapa` |
| Retrieve knowledge | `buscar`, `ler`, `ler_varios`, `relacionados`, `tags`, `recentes`, `filtrar`, `decisoes` |
| Preserve and import knowledge | `criar_nota`, `anexar`, `registrar_decisao`, `registrar_aprendizado`, `atualizar_nota`, `importar_url`, `reindexar` |

URL imports fetch a single page or PDF; they do not crawl entire websites, run JavaScript, bypass authentication, or OCR scanned documents. Public HTTP(S) URLs are accepted; private and loopback addresses are rejected. Import only material you are entitled to store. Imported text is reference material, not instructions for your assistant.

```bash
uv run atlasbrain importar-url --vault /absolute/path/to/my-project https://example.com/article
# Refresh the same snapshot later:
uv run atlasbrain importar-url --vault /absolute/path/to/my-project https://example.com/article --atualizar
```

## Language coverage

AST extraction covers Python; JavaScript/JSX/MJS/CJS; TypeScript/TSX; Go; Rust; Java; Ruby; PHP; Swift; Kotlin/KTS; C; C++; C#; Bash; Lua; Scala; Dart; **Elixir, Julia, R, Haskell, OCaml, Perl, and PowerShell**.

Extraction varies by grammar. Import alias resolution is deepest for Python and JavaScript/TypeScript; unresolved external packages and ambiguous references are not presented as proven symbol connections. Other text/configuration files can still be searched without AST extraction.

## Local data and optional features

Indexes and embedding inference run locally. MCP tools return requested project content to your connected assistant, subject to that assistant's own data policies. The core needs no paid API or external database; the first dependency/model download and URL imports need internet access.

Keep `.atlasbrain/` Markdown notes in Git; its generated index is ignored automatically. Add paths to `.atlasbrainignore` to exclude them from indexing. Optional `init` Git hooks and `hooks` transcript capture are separate from the minimal installation and can launch temporary commands. Laya-based classification is available with `uv sync --extra laya`.

## Development

```bash
uv sync --locked
uv run pytest -q
```

Licensed under [MIT](LICENSE).