Nix

Nix

[Nix, a Lulu da Pomerânia que inspirou o nome do projeto]

[Baixar a última versão] [Python 3.11+ / 3.14]

https://paulocesaaars.github.io/nix/

Servidor MCP que expõe wikis em Markdown a agentes de desenvolvimento (Cursor, VS Code, Claude Code e Codex). Busca híbrida, leitura e escrita nas notas — com embeddings e banco vetorial locais e gratuitos. O raciocínio fica no cliente; o Nix só entrega ferramentas. O Mega Brain, desligado por padrão, guarda memória entre agentes na wiki que você escolher.

Transporte: MCP stdio. No terminal, nix sem subcomando abre a interface. O cliente MCP, sem terminal, continua recebendo o servidor.

Por que usar

• O agente do editor encontra ideias, não só palavras: busca semântica + léxica no vault.
• Cria e atualiza notas em Markdown, sem sair do Cursor.
• Tudo roda na sua máquina. Nenhum trecho do vault vai para API de embedding.
• Você controla quando o índice muda: não há watcher em segundo plano.

Requisitos

• Windows amd64, Linux (amd64 ou arm64) ou macOS Apple Silicon
• Uma pasta de notas Markdown (.md)
• ~220 MB livres na primeira sincronização (modelo padrão lulu). O spitz (BAAI/bge-m3) pesa ~2,3 GB

Não é preciso instalar Python para o binário da release: o arquivo baixado já traz o runtime. Se a empresa bloqueia o .exe, o PowerShell e os links de download do instalador, baixe o zip do código na release e instale pelo Python no Git Bash, na seção Quando o executável, o PowerShell e os links de download estão bloqueados.

Instalação

O instalador baixa nix e nix-hook da última release, confere o SHA-256 de cada um e grava NIX_HOME. A wiki é cadastrada depois, na interface. Os hooks de sessão chamam o nix-hook.

Windows (PowerShell):

irm https://raw.githubusercontent.com/paulocesaaars/nix/main/install.ps1 | iex

Linux e macOS:

curl -fsSL https://raw.githubusercontent.com/paulocesaaars/nix/main/install.sh | sh

Ao terminar, execute nix para abrir a interface. Se o comando não funcionar, feche o terminal, abra outro e tente de novo.

A pasta da instalação é %LOCALAPPDATA%\nix no Windows, ~/Library/Application Support/nix no macOS e ~/.local/share/nix no Linux (ou o NIX_HOME que já existir). Os binários ficam em {NIX_HOME}/bin. Windows arm64 e macOS Intel não têm binário: o instalador diz isso e para.

A primeira execução descompacta o binário num cache (%LOCALAPPDATA%\nix\onefile-<versão> no Windows, ~/Library/Caches/nix/onefile-<versão> no macOS, ~/.cache/nix/onefile-<versão> no Linux). O instalador já faz essa partida. As seguintes reutilizam o cache. O nix-hook fica ao lado de nix: o binário completo confere o CRC de todo o payload a cada partida e não cabe no orçamento de 300 ms do hook de sessão. O nix hooks install aponta os agentes para o nix-hook, cujo cache fica em hook-<versão> na mesma pasta.

[Nix, a Lulu da Pomerânia que inspirou o nome do projeto]

Depois registre o servidor no editor — veja Registro no cliente MCP. O instalador grava NIX_HOME e coloca nix no PATH. Execute nix para abrir a interface. Se o comando não funcionar, feche o terminal, abra outro e tente de novo. Se o registro automático falhar, veja Registrar NIX_HOME e o PATH à mão. Se o gerenciador Nix (NixOS) já estiver no PATH, o instalador avisa: este nix passa a ter prioridade.

NIX_VERSION=1.2.3 (com ou sem o v) instala uma release específica.

Quando o executável, o PowerShell e os links de download estão bloqueados

Algumas redes bloqueiam o .exe, a execução do PowerShell e o download que o install.ps1 faz (irm do script e dos binários da release). O caminho é baixar o zip do código-fonte na última release — o arquivo Source code (zip) — e usar a instalação por Python, a mesma base da seção A partir do código (desenvolvedor). Nenhum nix.exe entra na máquina.

Se o computador da empresa não abre o GitHub, baixe esse zip em outra máquina e copie o arquivo. Descompacte e entre na pasta (nix-<versão>). No Git Bash, com Python 3.11 ou mais novo:

python scripts/bootstrap.py

O bootstrap.py cria o .venv, instala os pacotes de requirements.txt, grava NIX_HOME e coloca nix no PATH. A wiki é cadastrada depois, na interface. O zip da release traz esse script e o requirements.txt. O requirements-dev.txt fica só no clone completo do Git: a lista de comandos da seção do desenvolvedor que usa esse arquivo vale para quem alterou o código a partir do clone. O pip precisa alcançar o PyPI.

Se python não existir nesse bash, use py ou python3. Com Git liberado, o mesmo script roda depois de um clone:

git clone https://github.com/paulocesaaars/nix.gitcd nixpython scripts/bootstrap.py

Execute nix para abrir a interface. Se o comando não funcionar, feche o terminal, abra outro e tente de novo. No terminal que já está aberto:

source bin/env.sh

No MCP não há nix.exe. Aponte command para o Python do ambiente e passe o módulo em args. Troque a pasta se o zip ou o clone ficou em outro lugar:

{  "mcpServers": {    "nix": {      "command": "C:/Git/nix/.venv/Scripts/python.exe",      "args": ["-P", "-m", "nix"]    }  }}

Os hooks dessa instalação chamam python -m nix hook. O nix-hook.exe da release não entra.

Para desfazer essa instalação, na pasta descompactada ou no clone: python scripts/uninstall.py. A pasta da wiki não é alterada. --yes pula a pergunta; --keep-data preserva settings.db e o índice. O binário instalado por install.ps1 ou install.sh sai pelos comandos da seção Desinstalar.

A primeira sincronização ainda baixa o modelo de embedding (cerca de 220 MB, o lulu).

A partir do código (desenvolvedor)

Quem altera o Nix usa um venv. O install.ps1 da raiz baixa o binário publicado; não instala este checkout.

python -m venv .venv# Windows (Git Bash): source .venv/Scripts/activate# Linux/macOS:        source .venv/bin/activate
pip install -r requirements-dev.txtpip install -e .python -m nix init                # ou: python -m nix init --wiki "C:/Notas/MinhaWiki"

O mesmo fluxo, com registro de PATH, é python scripts/bootstrap.py. Para desfazer o checkout: python scripts/uninstall.py.

python -m nix vale depois de ativar o venv. O Cursor não herda o PATH do terminal — no MCP de desenvolvimento aponte command para o Python do .venv com -P -m nix, ou para o shim bin/nix deste checkout.

Skills de agente (desenvolvedor)

As skills de desenvolvimento (implementar SDD pelo fluxo inteiro, especificar, criar testes, revisar código, atualizar a documentação, commitar, guardrails, gerar uma skill, iniciar o projeto e publicar a release) ficam versionadas neste repositório, em .claude/skills/ (Claude Code e Cursor) e .agents/skills/ (Cursor e VS Code). O skills-lock.json registra a origem das que estão sincronizadas.

Mega Brain

Na interface, abra Mega Brain → Configuração para selecionar uma wiki cadastrada e habilitar ou desabilitar o recurso. Salve e reinicie o cliente MCP. As ferramentas de memória funcionam sem hooks; a captura automática das sessões exige hooks. Um campo definido por variável de ambiente fica bloqueado individualmente; o outro continua editável.

Desligado por padrão. Escolha a wiki das páginas e ligue:

nix brain enable --wiki Default

Essa wiki conta no limite de 100 e não pode ser removida enquanto o Mega Brain estiver ligado. A captura ainda exige um hook. Nenhum agente vem marcado. Há prévia, confirmação e backup antes de alterar um arquivo que já existe. O escopo global avisa que eventos de outros repositórios podem ser gravados.

nix brain hooks install --scope projectnix brain hooks install --scope global

O projeto é a raiz Git, ou a pasta se não houver repositório. Um .nix.toml pode definir project, [capture] enabled / exclude e [profile] contribute / consume. Toml ilegível desliga a captura.

nix brain hooks install --all instala esses clientes, nesta ordem. Os outros clientes da lista (Command Code, OpenCode, Gemini CLI, GitHub Copilot CLI e demais) ficam com captura parcial: nenhum JSON é inventado. O escopo global grava arquivo só quando o caminho está confirmado.

A página da sessão vai para projects/<projeto>/sessions/ na wiki do Mega Brain. Ela só é gravada quando a sessão encerra e o nix brain work roda. O handoff e o recado ficam na base, não nessa página.

Painel. Cada cartão é um projeto: a raiz Git da pasta em que o agente trabalhou, ou a própria pasta se não houver repositório. O nome é o da pasta, ou o campo project do .nix.toml. O cartão aparece depois da primeira sessão capturada e mostra a quantidade de sessões, os agentes e a última atividade. Abrir o projeto mostra visão geral, agentes, tokens, sessões e conhecimento.

Caixa de entrada. É a fila de recados entre agentes, separada do handoff. brain_message_send grava o texto para um destinatário ou para qualquer um do projeto. O estado fica esperando. brain_message_pop entrega o mais antigo uma única vez e marca entregue. Cancelar tira da fila antes disso. A tela lista projeto, destinatário, texto e estado, inclusive os já entregues.

Perfil. São preferências que você escreveu nos pedidos, sem modelo de linguagem. A Nix procura “sempre use”, “prefiro”, “nunca use” e o equivalente em inglês, seguidos de uma palavra. Ferramentas conhecidas (pnpm, pytest, ruff, docker, git e outras) vão para profile/tools/. O resto vai para profile/habits/. A frase só entra quando o mesmo assunto apareceu em pelo menos dois projetos (profile.min_projects, padrão 2). A frase mais nova prevalece. nix brain profile rebuild reaprende; forget vira lápide e a passada seguinte não recria a entrada. No início da sessão o briefing inclui as frases ativas, salvo [profile] consume = false no .nix.toml.

nix brain handoff create --text "..." abre no máximo um handoff por projeto. nix brain handoff accept --agent NOME reivindica uma única vez. O início da sessão mostra o briefing como histórico, não como ordem.

nix run claude (ou outro agente) instala o hook e o MCP se faltarem. --no-autowire desliga isso. Para Claude Code e Codex, uma cópia só leitura do histórico anterior fica em NIX_PREVIOUS_SESSION_HISTORY e some quando o agente termina. Sem leitor, o comando segue com aviso.

remember continua gravando na wiki padrão e não faz parte do Mega Brain.

Atualizar

Para trocar a versão que já está instalada, encerre nix e nix-hook, apague só esses dois binários e rode o instalador de novo. A wiki, o settings.db e a pasta .nix (índice e Mega Brain) ficam. O desinstalador da seção seguinte também apaga settings.db e .nix, salvo --keep-data.

Windows (PowerShell):

Stop-Process -Name nix,nix-hook -Force -ErrorAction SilentlyContinue$root = if ($env:NIX_HOME) { $env:NIX_HOME } else { Join-Path $env:LOCALAPPDATA "nix" }Remove-Item -Force (Join-Path $root "bin\nix.exe"), (Join-Path $root "bin\nix-hook.exe")irm https://raw.githubusercontent.com/paulocesaaars/nix/main/install.ps1 | iex

Feche e abra de novo o cliente MCP para ele carregar o binário novo.

Linux e macOS: o instalador substitui os arquivos. Encerre os processos e rode o instalador de novo:

pkill -x nix || truepkill -x nix-hook || truecurl -fsSL https://raw.githubusercontent.com/paulocesaaars/nix/main/install.sh | sh

Desinstalar

O desinstalador remove NIX_HOME e o comando nix do PATH, apaga nix e nix-hook, o cache de extração (onefile-* e hook-*) e, por padrão, também .nix/ (índice, backups, logs) e settings.db. Se a pasta da instalação ficar vazia, ela também sai. A pasta da wiki não é alterada. Para só trocar a versão, use Atualizar.

No Windows, se nix.exe ou nix-hook.exe estiver aberto, o desinstalador para antes de alterar o PATH e avisa que o arquivo está em uso. Feche o cliente que mantém o Nix aberto, ou encerre os processos, e rode de novo.

Confirme com s. Em script, passe --yes. --keep-data preserva settings.db e o índice.

Nix instalado pelo PowerShell

Quem instalou com install.ps1 desinstala sem a pasta do repositório. No PowerShell:

irm https://raw.githubusercontent.com/paulocesaaars/nix/main/uninstall.ps1 -OutFile "$env:TEMP\uninstall-nix.ps1"& "$env:TEMP\uninstall-nix.ps1"

Responda s em Continuar? [s/N]. Se a resposta for que o arquivo está em uso, encerre os processos e rode o mesmo desinstalador de novo:

Stop-Process -Name nix,nix-hook -Force -ErrorAction SilentlyContinue& "$env:TEMP\uninstall-nix.ps1"

O script também apaga o cache onefile-* e hook-*. Se %LOCALAPPDATA%\nix ficar vazia, a pasta sai. A linha que confirma o fim diz que a pasta foi apagada, ou que o que restava foi removido dela. Abra um terminal novo em seguida.

& "$env:TEMP\uninstall-nix.ps1" --yes# para manter settings.db e o índice:& "$env:TEMP\uninstall-nix.ps1" --keep-data --yes

No Linux e no macOS, o script da release:

curl -fsSL https://raw.githubusercontent.com/paulocesaaars/nix/main/uninstall.sh | sh# ou: curl -fsSL .../uninstall.sh -o uninstall.sh && sh uninstall.sh --yes

Na pasta do repositório ou do zip

Na pasta do clone, ou na pasta descompactada do Source code (zip) — a instalação por bootstrap.py:

python scripts/uninstall.py# ou: python scripts/uninstall.py --yes# ou: python scripts/uninstall.py --keep-data --yes

Esse comando tira o NIX_HOME se ele apontar para essa pasta, apaga o .venv e, salvo --keep-data, também .nix/ e settings.db. O código-fonte da pasta permanece.

Com os scripts da raiz do repositório:

uninstall.bat:: ou, sem pergunta:uninstall.bat --yes:: para manter settings.db e o índice:uninstall.bat --keep-data --yes

.\uninstall.ps1# ou: .\uninstall.ps1 --yes# ou: .\uninstall.ps1 --keep-data --yes

sh uninstall.sh# ou: sh uninstall.sh --yes# ou: sh uninstall.sh --keep-data --yes

Abra um novo terminal depois: o nix deste projeto deixa de valer. Se o registro permanente falhar, veja Remover NIX_HOME e o PATH à mão. Remova também o servidor nix do mcp.json do editor.

O modelo de embedding pode permanecer no cache do Hugging Face (BAAI/bge-m3 pesa ~2,3 GB). Esse cache é compartilhado com outros programas, e o desinstalador não o apaga. O servidor nix no mcp.json de cada projeto também fica: apague essa entrada no editor.

Registro no cliente MCP

O cliente inicia o processo. Recarregue os servidores MCP depois de salvar.

command deve apontar para o binário dentro da pasta da instalação (NIX_HOME), não para o nome nix no PATH. O editor aberto pelo Dock ou pelo menu não herda o PATH do terminal (spawn nix ENOENT). O caminho aparece em nix doctor, na linha comando nix:.

Cursor — .cursor/mcp.json no workspace:

Windows

{  "mcpServers": {    "nix": {      "command": "${env:NIX_HOME}/bin/nix.exe"    }  }}

No Windows a IDE lê a variável de usuário NIX_HOME. Também vale o caminho absoluto, por exemplo C:/Users/voce/AppData/Local/nix/bin/nix.exe.

macOS / Linux

{  "mcpServers": {    "nix": {      "command": "/Users/voce/Library/Application Support/nix/bin/nix"    }  }}

Troque pelo caminho da linha comando nix: do nix doctor. No Linux a pasta padrão é ~/.local/share/nix/bin/nix. "command": "nix" falha na IDE. ${env:NIX_HOME} em geral não expande: o app não lê .zshrc / .bashrc.

Na interface, abra Integração → Conectar cliente para copiar a configuração com o caminho absoluto desta instalação. As instruções dos clientes com formato confirmado usam o escopo de projeto:

• Cursor: .cursor/mcp.json, com o bloco mcpServers dos exemplos acima.
• VS Code: .vscode/mcp.json, com servers.nix contendo type: "stdio" e command apontando para o executável.
• Claude Code: na pasta do projeto, execute claude mcp add nix --scope project -- "CAMINHO_ABSOLUTO_DO_NIX". A configuração fica em .mcp.json.
• Codex: crie ou edite .codex/config.toml no projeto confiável:

[mcp_servers.nix]command = "C:/Users/voce/AppData/Local/nix/bin/nix.exe"

Confie no projeto no Codex para carregar essa configuração. No Linux ou macOS, substitua o comando pelo caminho absoluto do executável correspondente.

• Devin: .devin/mcp_config.json, com o bloco mcpServers dos exemplos acima.

Reinicie o cliente ou recarregue os servidores MCP depois de salvar. stdout é do protocolo MCP: logs só em .nix/logs/nix.log na pasta do Nix.

Na instalação por Python, sem nix.exe, use o interpretador do .venv como em Quando o executável, o PowerShell e os links de download estão bloqueados.

Primeiros passos

A instalação não roda nix init. No terminal, execute nix para abrir a interface. Se o comando não existir, feche o terminal, abra outro e tente de novo.

A primeira wiki entra na tela Wikis ou com nix init. A tela grava a pasta (a primeira vira o padrão). O nix init também escolhe o modelo e grava a marca que o servidor MCP e o comando nix ui exigem. Sem essa marca, o editor não conecta.

nix initnix doctornix syncnix status

O primeiro sync (ou qualquer operação que embede) baixa o modelo configurado. O padrão é a lulu (~220 MB). O embedding roda na CPU; a barra só avança ao terminar o arquivo. O spitz (BAAI/bge-m3, ~2,3 GB) melhora a busca e cada nota pode levar minutos. Troque no nix init ou com nix config set index.embedding_model spitz e rode nix sync --full.

Notas novas sem pasta no caminho vão para default_new_note_folder da wiki (padrão Inbox).

Registrar NIX_HOME e o PATH à mão

O instalador tenta gravar NIX_HOME (pasta do Nix) e {NIX_HOME}/bin no PATH do usuário. Se isso falhar (permissão, política, registro bloqueado), a instalação dos binários continua. Registre as variáveis você mesmo e abra um terminal novo.

Use a pasta real da instalação no lugar dos exemplos.

Windows (interface)

1. Win+R, rode sysdm.cpl → Avançado → Variáveis de Ambiente.
2. Em Variáveis do usuário, Novo:
   • Nome: NIX_HOME
   • Valor: pasta do Nix, por exemplo C:\Users\voce\AppData\Local\nix
3. Selecione Path (usuário) → Editar → Novo → %NIX_HOME%\bin
4. Confirme com OK em todas as janelas.

Windows (PowerShell, permanente)

$nixHome = "$env:LOCALAPPDATA\nix"[Environment]::SetEnvironmentVariable("NIX_HOME", $nixHome, "User")$expand = "%NIX_HOME%\bin"$p = [Environment]::GetEnvironmentVariable("Path", "User")if ($p -notlike "*$expand*") {  [Environment]::SetEnvironmentVariable("Path", "$p;$expand", "User")}

Linux, macOS e Git Bash

Acrescente ao ~/.bashrc (e ao ~/.profile se o terminal for de login). No macOS o caminho é $HOME/Library/Application Support/nix; no Linux, $HOME/.local/share/nix.

# >>> nix >>>export NIX_HOME="$HOME/.local/share/nix"case ":$PATH:" in *":$NIX_HOME/bin:"*) ;; *) export PATH="$NIX_HOME/bin:$PATH" ;; esac# <<< nix <<<

Depois: source ~/.bashrc ou abra um terminal novo.

Só nesta sessão (não grava)

$env:NIX_HOME = "$env:LOCALAPPDATA\nix"$env:Path = "$env:NIX_HOME\bin;$env:Path"

export NIX_HOME="${XDG_DATA_HOME:-$HOME/.local/share}/nix"export PATH="$NIX_HOME/bin:$PATH"

Remover NIX_HOME e o PATH à mão

Se o desinstalador não desfizer as variáveis, apague o que o instalador gravou e abra um terminal novo. A pasta da wiki continua intacta.

Use a pasta real da instalação no lugar de %LOCALAPPDATA%\nix.

Windows (interface)

1. Win+R, rode sysdm.cpl → Avançado → Variáveis de Ambiente.
2. Em Variáveis do usuário, selecione NIX_HOME → Excluir (só se o valor for a pasta deste Nix).
3. Selecione Path (usuário) → Editar → remova %NIX_HOME%\bin (e o caminho absoluto ...\nix\bin, se existir).
4. Confirme com OK em todas as janelas.

Windows (PowerShell, permanente)

$nixHome = "$env:LOCALAPPDATA\nix"$stored = [Environment]::GetEnvironmentVariable("NIX_HOME", "User")if ($stored -and ($stored -ieq $nixHome)) {  [Environment]::SetEnvironmentVariable("NIX_HOME", $null, "User")}$bin = Join-Path $nixHome "bin"$p = [Environment]::GetEnvironmentVariable("Path", "User")if ($p) {  $kept = $p.Split(";") | Where-Object {    $t = $_.Trim().Trim('"')    $t -and $t -ne "%NIX_HOME%\bin" -and $t -ne $bin  }  [Environment]::SetEnvironmentVariable("Path", ($kept -join ";"), "User")}

Linux, macOS e Git Bash

Apague o bloco entre # >>> nix >>> e # <<< nix <<< em ~/.bashrc, ~/.zshrc, ~/.bash_profile e ~/.profile (só os arquivos que existirem), se NIX_HOME nesse bloco for a pasta desta instalação.

Depois: source ~/.bashrc ou abra um terminal novo.

Indexação

Esta é a regra central:

Alterações feitas fora do Nix, por exemplo, em um editor de texto, não são indexadas sozinhas. Alterações feitas pelas ferramentas MCP atualizam o índice na mesma operação.

Depois de editar as notas fora do Nix, rode nix sync ou peça sync_index ao agente. Se a vetorização de uma escrita falhar, o arquivo permanece na wiki (fonte da verdade) e um nix sync corrige o índice.

CLI

Estes são os comandos que você roda no terminal. nix --help lista os grupos. nix COMANDO --help mostra as opções daquele comando. A wiki não entra no índice sozinha: o índice muda com nix sync ou com uma escrita feita pelas ferramentas MCP.

nix hook, nix banner e nix brain work existem para o processo interno. Não fazem parte do uso no terminal.

Casos de uso

• Abrir a interface. Depois de instalar, execute nix. Se o comando não existir, feche o terminal, abra outro e tente de novo. nix ui abre a mesma interface quando a wiki já está cadastrada.
• Cadastrar a primeira wiki. nix init grava a pasta e o modelo. A instalação não faz mais essa pergunta.
• Achar uma ideia no editor. Com o MCP da Nix ligado, peça ao agente para buscar nas notas. Ele usa search_notes no índice da wiki.
• Registrar uma nota sem sair do editor. Peça ao agente para criar ou atualizar a nota. A escrita passa pelas ferramentas do MCP e o índice daquela nota é atualizado na hora.
• Trazer para o índice o que você editou fora do Nix. Rode nix sync. --dry-run mostra o que mudaria. --full reconstrói o índice, e é obrigatório depois de trocar o modelo de embedding.
• Usar mais de uma wiki. nix wiki add Trabalho C:/Notas/Trabalho cadastra a segunda. nix wiki default Trabalho passa a usá-la quando o nome é omitido. A busca pode pedir uma, várias ou todas.
• Descobrir por que o editor não conecta. nix doctor confere o comando, a configuração e o índice.
• Guardar memória entre agentes. nix brain enable --wiki Default liga o Mega Brain. nix brain hooks install --scope global --all faz Cursor, VS Code, Claude Code, Codex e Devin chamarem o Nix a cada evento da sessão. O VS Code não tem arquivo global: a captura dele fica parcial.
• Continuar no Codex o que estava fazendo no Claude. Os dois clientes precisam ter o MCP da Nix, o Mega Brain ligado e a mesma pasta do projeto. No Claude, peça para deixar registrado onde a sessão parou: ele chama brain_handoff_create. Abra o Codex e diga para continuar o que estava fazendo no Claude: ele chama brain_handoff_accept com o agente codex e, se precisar do resto, brain_query ou brain_read_page. Sem o MCP, o mesmo texto pode ser aberto e reivindicado no terminal com nix brain handoff create e nix brain handoff accept --agent codex. O hook, sozinho, só entrega no início da sessão um briefing com os últimos pedidos.
• Deixar um recado para o outro agente. Com o Mega Brain ligado, brain_message_send coloca uma mensagem na fila do projeto. O outro agente pega com brain_message_pop, uma única vez.
• Ler o que o Mega Brain já guardou. brain_query busca na wiki do Mega Brain e nas observações. brain_recent_pages lista as páginas de sessão. brain_read_page lê uma página pelo caminho. O texto encontrado é histórico.
• Reaprender o perfil. nix brain profile rebuild relê os pedidos gravados. nix brain profile list mostra as frases. nix brain profile forget CAMINHO esquece uma. nix brain profile apply regrava as páginas na wiki.
• Corrigir uma configuração. nix config history mostra a alteração. nix config undo volta o valor anterior.

Servidor

No terminal, nix sem subcomando abre a interface. O cliente MCP inicia o mesmo comando sem terminal e recebe o servidor stdio. nix --version imprime a versão e termina.

Primeira configuração

nix init grava a primeira wiki e o modelo de embedding no settings.db. A instalação não faz mais esse passo.

• --wiki CAMINHO informa a pasta. Sem isso, o terminal pergunta.
• --name NOME batiza a primeira wiki. Sem a opção, o nome é Default. Vale só na criação. A seguinte entra com nix wiki add.
• --embedding-model NOME escolhe o modelo (lulu ou spitz). Sem a opção, o terminal pergunta na criação.
• --force regrava a configuração do zero, sem alterar as notas.

Wikis

De 1 a 100 wikis na mesma instalação. Omitir a wiki no sync e no status usa a padrão.

• nix wiki list mostra nome, pasta e qual é a padrão. --json entrega a mesma lista em JSON.
• nix wiki add NOME CAMINHO cadastra outra. Um nome no formato AAAAMMDDTHHMMSS é recusado.
• nix wiki rename ANTIGO NOVO troca o nome. O índice e os backups ficam onde estão. Se a busca ficar vazia, rode nix sync --full --wiki NOVO.
• nix wiki default NOME escolhe a padrão. Remover a padrão é recusado até outra ocupar o lugar. A última wiki não sai.
• nix wiki remove NOME tira o cadastro. A pasta das notas permanece. A wiki das páginas do Mega Brain também não sai enquanto ele estiver ligado.
• nix wiki path NOME CAMINHO aponta o mesmo nome para outra pasta.
• nix wiki set NOME CAMPO VALOR grava um ajuste daquela wiki: include, exclude, follow_symlinks, default_new_note_folder, default_frontmatter ou longterm_folder. Listas e objetos entram como JSON. Não mexe na configuração global.

Renomear, remover, path e set esperam se aquela wiki estiver sincronizando.

Nas ferramentas MCP, omitir wiki usa a padrão. Busca, listas, status e sync aceitam um nome, uma lista ou "*" (todas). Escrita aceita um nome só.

Configuração global

Os campos ficam no settings.db da instalação (NIX_HOME; no checkout por Python, a pasta do clone). nix config set secao.chave valor grava um campo. Listas e objetos entram como JSON.

• nix config list mostra os campos. --json muda o formato.
• nix config get secao.chave lê um.
• nix config unset secao.chave volta o campo ao padrão.
• nix config history mostra as alterações. --limit N corta a lista (padrão 20).
• nix config undo desfaz a última. nix config undo ID desfaz uma entrada do histórico.

Para o Mega Brain: nix brain enable --wiki NOME. Reinicie o cliente MCP em seguida para as ferramentas brain_* aparecerem.

Uma variável NIX_SECAO__CAMPO ganha do banco naquele campo e o trava no nix config e na interface. O cadastro das wikis não usa essa variável.

Índice

Editar notas fora do Nix não atualiza o índice. Rode nix sync quando quiser alinhar.

• Sem --wiki e sem --all, vale a wiki padrão.
• --wiki NOME pode repetir. --all percorre todas, em sequência. Não combine os dois.
• --full reconstrói o índice inteiro. Use depois de trocar o modelo (nix config set index.embedding_model spitz).
• --dry-run só mostra o que mudaria.
• --json entrega o relatório em JSON. O mesmo vale para nix status e nix doctor.

nix status mostra notas, chunks, o último sync e se a wiki está à frente do índice. nix doctor confere ambiente, configuração, o comando que o MCP deve chamar e o índice de cada wiki. Comece por ele quando o editor não conecta.

Interface

nix ui abre o navegador em 127.0.0.1 com status, sync, diagnóstico, busca, Mega Brain (painel, configuração, caixa de entrada e perfil), conexão dos clientes, tráfego MCP, backups, wikis e configuração. Exige o nix init. Encerra com Ctrl+C ou pelo botão Encerrar. --no-browser só imprime a URL. --port N fixa a porta.

Mega Brain

O passo a passo está em Mega Brain.

• nix brain enable --wiki NOME liga e escolhe a wiki. status mostra o estado.
• nix brain hooks install --scope project|global pede os agentes. remove e status usam o mesmo --scope.
• nix brain handoff create --text "..." abre o handoff. list, accept --agent NOME e cancel completam o ciclo.
• nix brain profile rebuild reaprende. list, review, forget CAMINHO e apply consultam e regravam.
• nix run AGENTE encaminha os argumentos seguintes ao executável. --no-autowire não mexe em hook nem MCP. --project PASTA escolhe o repositório.

Ferramentas MCP

O agente não executa nix no terminal. Você pede em linguagem normal e ele chama uma ferramenta. As de wiki ficam sempre disponíveis. As brain_* só entram no MCP com o Mega Brain ligado; reinicie o cliente depois de nix brain enable. A definição está em src/nix/core/tools/registry.py. Notas da wiki padrão aparecem como recurso nix://note/{+rel_path}; uma wiki nomeada, como nix://wiki/{name}/note/{+rel_path}. Os nomes atuais de lista e de qualidade são list_wikis e wiki_insights.

nix, nix init, nix doctor, nix ui, nix run, nix config, o restante de nix wiki, nix brain enable, nix brain hooks e nix brain profile ficam no terminal. O hook dispara sozinho a cada evento da sessão.

Estas ferramentas não têm comando equivalente. Você as estimula pela frase:

Referência

Configuração

Fica em settings.db, na pasta do Nix (NIX_HOME; no checkout de desenvolvimento, a pasta do repositório). Caminhos relativos resolvem contra essa pasta. Variáveis NIX_SECAO__CAMPO ganham do banco nos campos globais (ex.: NIX_INDEX__EMBEDDING_MODEL) e o campo correspondente fica travado no nix config e na interface. O cadastro das wikis não usa essa variável: nome, pasta, padrão e ajustes (include, exclude, pastas) ficam no nix wiki. nix wiki set NOME CAMPO VALOR grava um ajuste; listas e objetos entram como JSON. nix wiki path NOME CAMINHO troca a pasta. nix init grava a primeira wiki e o modelo. nix config set secao.chave valor altera um campo global; listas e objetos entram como JSON. nix config undo restaura o valor anterior.

nix ui abre as mesmas operações no navegador, sem precisar de um LLM:

• Operação: status (o bloco Para começar fica até a wiki escolhida ter sido sincronizada e o editor ter chamado uma ferramenta; o aviso de índice desatualizado só aparece depois dessa sincronização), sincronização com prévia e progresso (os botões ficam desligados até o job terminar, também se a página for recarregada) e diagnóstico.
• Wiki (somente leitura): busca em uma, em várias ou em todas, notas (com outline e trechos), tags e insights. A página de insights explica órfãs, duplicadas, sugestões de link e o resumo. O seletor "Wiki ativo", na faixa acima do conteúdo, usa ?wiki=; sem ele, vale o padrão.
• Mega Brain: painel, configuração da wiki e do estado, caixa de entrada e perfil. Os links de uma página de perfil ou de sessão abrem a wiki configurada no Mega Brain.
• Integração: trechos prontos para conectar Cursor, VS Code, Claude Code, Codex, Devin e outros 19 clientes; tráfego MCP, com as chamadas que os clientes fazem, gravadas em .nix/traffic.db.
• Manutenção: backups das escritas (comparação e download) e a restauração de um backup, a única escrita na wiki feita pela interface, com confirmação; tela Wikis; formulário de configuração e histórico.

O comando exige o nix init, escuta só em 127.0.0.1 e encerra com Ctrl+C ou pelo botão Encerrar. --no-browser só imprime a URL; --port fixa a porta.

Publicar uma versão

Uma release no GitHub é criada automaticamente quando uma tag vX.Y.Z chega no remoto. O workflow .github/workflows/release.yml confere a versão, roda ruff e mypy, compila nix e nix-hook por plataforma (Windows amd64, Linux amd64, Linux arm64, macOS arm64) e publica os arquivos com checksums.txt em Releases.

1. Atualize [project].version em pyproject.toml (ex.: 1.2.3). A tag precisa bater com esse valor — senão o job falha.
2. Faça o commit e o push na branch principal.
3. Crie e envie a tag (o v no prefixo é obrigatório):

git tag v1.2.3git push origin v1.2.3

4. Acompanhe o workflow Release em Actions. Em caso de sucesso, a release traz nix e nix-hook por plataforma, um .mcpb por plataforma, o checksums.txt e o server.json. O mesmo job publica a ficha no MCP Registry. O zip de código-fonte da tag traz só o que instala e usa o Nix; skills de desenvolvimento, documentação e testes ficam de fora.

O guia em site/ é publicado à parte, em paulocesaaars.github.io/nix, quando um push na main altera essa pasta.

Para republicar os artefatos de uma tag que já existe, dispare o workflow à mão: Actions → Release → Run workflow, e informe a tag (ex.: v1.2.3).

Documentação

• PRD.md — produto, requisitos e regras de negócio
• TDD.md — especificações técnicas: componentes, indexação, recuperação e MCP stdio