Zettelbrain

Python uv Obsidian Zettelkasten Markdown MCP License: MIT

ZettelBrain e um cofre Zettelkasten em Markdown com um motor Python local para automacao, busca, ingestao e exposicao de ferramentas via Model Context Protocol (MCP).

O projeto combina tres superficies:

• zettelbrain/: cofre de conhecimento, com notas de literatura, permanentes, rascunhos, sinteses, visualizacoes e indice.
• skills/: fluxos operacionais usados por agentes para ingestao, busca, manutencao e escrita.
• src/: motor Python com configuracao, ETLs, linter, busca, embeddings, cache PageIndex/PDF e servidor MCP.

Referencias do projeto

Arquivo operacional base:

• Schema operacional do ZettelBrain

Documentacao de consulta para terceiros:

• Manual de funcionalidades e skills
• Arquitetura e estrutura do projeto
• Configuracao e operacao local
• Ferramentas MCP
• Auditoria de alinhamento da documentacao

Inicio rapido

Requisitos principais:

• Python >=3.12
• uv
• Opcional: qmd para busca semantica externa
• Opcional: Ollama local para embeddings com EMBEDDING_PROVIDER=ollama
• Opcional: comando PageIndex ou Docling para indexacao de PDFs

Prepare o ambiente:

uv sync
uv run install bootstrap
Copy-Item .env.example .env
uv run python src/mcp/server.py --health-json

Execute verificacoes locais:

uv run zettelbrain-lint
uv run zettelbrain-lint --json
uv run pytest

Configure um cliente de agente quando necessario:

uv run install gemini
uv run install cursor
uv run install clean

uv run install gemini cria .gemini/settings.json e sincroniza skills/ para .gemini/skills/. uv run install cursor cria .cursor/mcp.json e compila ZETTELBRAIN.md com skills/ em .cursorrules.

Comandos de uso comum

Objetivo	Comando
Validar servidor MCP sem iniciar transporte	uv run python src/mcp/server.py --health-json
Iniciar servidor MCP	uv run zettelbrain-mcp ou uv run zb-mcp
Rodar linter do cofre	uv run zettelbrain-lint ou uv run zb-lint
Gerar JSON do linter	uv run zettelbrain-lint --json
Auditar sem corrigir nomes de notas	uv run zettelbrain-lint --no-fix
Baixar artigo web para raw/articles/	uv run zb-article-etl --url "<URL>"
Ingerir transcricoes novas de playlist YouTube	uv run zb-youtube-etl --limit 5
Ver candidatos YouTube sem escrever arquivos	uv run zb-youtube-etl --dry-run
Criar estrutura local ignorada pelo Git	uv run install bootstrap ou uv run install local
Configurar Gemini CLI	uv run install gemini
Configurar Cursor	uv run install cursor
Remover configuracoes locais de cliente	uv run install clean

Estrutura principal

.
|-- README.md
|-- LICENSE
|-- pyproject.toml
|-- uv.lock
|-- docs/
|-- skills/
|-- src/
|   |-- config.py
|   |-- setup.py
|   |-- zettelbrain_lint.py
|   |-- zettelbrain_mcp.py
|   |-- ingestion/
|   `-- mcp/
|-- tests/
|-- raw/
|   |-- articles/
|   |-- papers/
|   |-- youtube/
|   `-- assets/
|-- zettelbrain/
|   |-- index.md
|   |-- overview.md
|   |-- literature/
|   |-- permanent/
|   |-- drafts/
|   |-- syntheses/
|   |-- visual/
|   |-- presentations/
|   `-- assets/
|-- .state/
`-- .pageindex/

Estado dos artefatos locais

Arquivos gerados localmente, caches, logs, .env, ambientes virtuais, fontes brutas em raw/ e notas de trabalho em zettelbrain/ sao ignorados pelo Git. Em .state/, caches e historicos gerados sao ignorados, enquanto hot.md e log.md podem ser rastreados como estado operacional inicial. Em clones novos, rode uv run install bootstrap para criar a estrutura local.

Licenca

Consulte LICENSE.