Nix

Nix

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- no Windows, ~/Library/Caches/nix/onefile- no macOS, ~/.cache/nix/onefile- 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- na mesma pasta.

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- ). 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.git

cd nix python 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.txt pip 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 project

nix 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/ /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