Cairn Remembers

Cairn

Construa conhecimento. Deixe sinais. — Ferramentas para exploradores modernos.

Memória episódica local-first para agentes de IA — e para você.

Um cairn é uma pilha de pedras que marca uma trilha. Este marca a trilha do seu pensamento: cada decisão, beco sem saída e motivo vira um nó que você — e qualquer modelo — pode encontrar novamente, entre sessões e entre gerações de modelos.

• Local-first — tudo vive em um único arquivo SQLite em ~/.cairn/. Sem nuvem, sem conta, sem telemetria.
• Independente de modelo — qualquer agente que execute um comando de shell ou fale MCP: Claude, GPT/Codex, Gemini, modelos locais.
• Somente acréscimo — memórias são anuladas, nunca deletadas. O registro é o registro.
• Seu — Cairn não envia nada da sua máquina. Seu chat continua indo para o modelo que você escolheu, exatamente como iria sem Cairn — use um modelo local e nada sai de jeito nenhum.

Duas formas de entrar:

• 🧑 Uma pessoa configurando isso? Continue lendo — Início rápido leva cerca de 5 minutos. Cada opção e correção: QUICKSTART.md.
• 🤖 Um agente de IA instalando Cairn para alguém? → SETUP_FOR_AGENTS.md foi escrito para você (instalação, consentimento, atribuição).

Veja por dentro do Cairn

Guarde as decisões, motivos e trabalhos inacabados aos quais você quer voltar. Cairn os armazena em um cofre local que você e suas ferramentas de IA conectadas podem ler e adicionar. Cada IA mantém sua própria memória e contexto. Estas demonstrações mostram o painel opcional para explorar o registro.

Hub	Projetos	Conexões
Retome trabalhos inacabados.	Mantenha trabalhos relacionados juntos.	Explore memórias vinculadas.

Explore todas as cinco demonstrações e descrições.

• Hub — 9 segundos
• Projetos — 18 segundos
• Índice — 6 segundos
• Feed ao vivo — 14 segundos
• Conexões — 8 segundos

Gravado em uma instalação local. Texto privado usa exemplos; controles e atribuição de fonte são mantidos. A instalação filmada não foi verificada contra todos os controles na versão 0.3.3. Descrições das demonstrações e notas de gravação.

Conteúdo

• Início rápido
• Conecte sua IA
• O que você obtém
• Instalação avançada
• Múltiplas contas
• O que fazer backup
• Comandos comuns
• Licença

Início rápido

Dois lugares, nunca confunda: 🖥️ Seu terminal (PowerShell / Terminal) — todo comando nesta página roda aqui, no seu computador. A conexão é sempre um comando de terminal ou uma edição de arquivo de configuração — uma IA pode executar esses passos de terminal por você (esse é o caminho mais rápido abaixo), mas a conexão nunca é algo que você cola na caixa de chat. 💬 O chat da IA — onde a memória aparece, e onde você testa a conexão pedindo à IA para usá-la.

Mais rápido — deixe sua IA fazer

Abra Claude Code, Codex ou Cursor e cole:

Instale e configure Cairn para mim a partir de https://github.com/CairnRemembers/cairn

Sua IA executa os passos de terminal e pergunta antes de ativar a memória — um sim/não por IA na sua máquina, padrão Não. Nada é gravado sem o seu sim. (Usando Codex? Há uma colagem extra depois disso — veja Conecte sua IA.)

Ou faça você mesmo

1 — Instale 🖥️ (instala apenas software — não grava nada, o cofre começa vazio)

⚠️ Instalando [all] no Linux / WSL? Execute pip install torch --index-url https://download.pytorch.org/whl/cpu primeiro, ou o pip puxa uma pilha CUDA torch de vários GB que você não precisa. As rodas torch do Windows e macOS já são apenas CPU.

pip install cairn-remembers            # base install
pip install "cairn-remembers[all]"     # + embedder + dashboard

A partir do código-fonte

Ainda o caminho mais rico — o instalador cuida do passo CPU-torch para você:

Obtenha o código 🖥️

git clone https://github.com/CairnRemembers/cairn
cd cairn

Execute o instalador 🖥️

# Windows:      .\install.ps1      (blocked? powershell -ExecutionPolicy Bypass -File .\install.ps1)
# macOS/Linux:  ./install.sh

O instalador encontra Python 3.11+, instala tudo (a primeira execução baixa PyTorch — a build CPU enxuta no Linux/Windows, alguns minutos) e verifica a si mesmo.

2 — Conecte sua IA. É aqui que a memória realmente liga, e cada IA precisa de conexão diferente — um y na configuração termina o trabalho para Claude Code, mas não para Codex ou Claude Desktop. Encontre sua IA abaixo e siga até o ✅.

Conecte sua IA

Cairn tem dois fios separados, e saber a diferença previne toda surpresa comum:

• Captura — seus chats são lembrados automaticamente (grava no cofre).
• Ferramentas — a IA pode buscar e anotar seu cofre de dentro do chat (leituras + gravações sob demanda).

Algumas IAs precisam de um fio, algumas precisam de ambos. Não pare no primeiro ✓ — siga sua IA até a linha ✅.

Claude Code — um comando

🖥️ No terminal:

python -X utf8 -m cairn setup        # answer y for Claude Code

Isso conecta a captura: cada novo chat do Claude Code se orienta automaticamente (você verá o banner), grava enquanto você trabalha e compila quando termina. Em toda a máquina, único, reversível (cairn disconnect --global). Prefere apenas um projeto? Execute cairn connect dentro desse repositório (global e por projeto são mutuamente exclusivos — doctor sinaliza isso).

✅ Concluído quando: um novo chat abre com um banner "CAIRN — contexto herdado", e 🖥️ python -X utf8 -m cairn doctor mostra ✓ captura.

Opcional — ferramentas nativas: Claude Code já pode ler o cofre executando comandos cairn no shell dele. Para ferramentas nativas cairn_* em vez disso, registre o servidor MCP em todo o usuário, apontando para o Python que pode import cairn (um python puro que não consegue é a falha nº 1 — prove o caminho primeiro, QUICKSTART §6a):

claude mcp add --scope user cairn -- <full-path-to-python> -X utf8 -m cairn mcp

💬 Prova: peça ao chat para "chamar cairn_orient". (doctor não consegue ver este fio — o pedido é o teste.)

OpenAI Codex — três peças, cada uma com um trabalho diferente

1. Captura 🖥️ — python -X utf8 -m cairn setup → y para Codex (= codex-hook install). Captura turnos ao vivo conforme Codex dispara notify (deduplicado por id de turno). Para uma varredura abrangente de tudo no disco, execute 🖥️ python -X utf8 -m cairn import codex-sessions --apply a qualquer momento.
2. Ferramentas 📄 — adicione a ~/.codex/config.toml, então reinicie completamente o Codex (passo a passo completo §6):

[mcp_servers.cairn]
command = "<full-path-to-python>"
args = ["-X", "utf8", "-m", "cairn", "mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120
default_tools_approval_mode = "approve"

3. Hábito 📄 — crie ~/.codex/AGENTS.md e cole o protocolo de memória de QUICKSTART §6c para que Codex se oriente, busque e anote sem ser solicitado. (Precisa da peça 2 — o protocolo chama essas ferramentas.)

✅ Concluído quando: 🖥️ python -X utf8 -m cairn codex-hook status imprime INSTALLED, e 💬 um chat do Codex responde "chamar cairn_orient" com um resumo (com a peça 3, a primeira resposta começa com [cairn: oriented — N]). ⚠️ Nota honesta: cairn doctor detecta estruturalmente o registro MCP do Codex (o bloco [mcp_servers.cairn]), mas não prova que o servidor inicia ou que o hook de notificação captura — as verificações acima são a prova real disso.

Claude Desktop / Cursor — uma colagem

📄 Adicione a claude_desktop_config.json (ou às configurações MCP do Cursor), então reinicie o aplicativo:

{
  "mcpServers": {
    "cairn": { "command": "python", "args": ["-X", "utf8", "-m", "cairn", "mcp"] }
  }
}

Esse é o fio de ferramentas — buscar, buscar, vagar, anotar de dentro do chat. Essas superfícies não têm captura ambiente; o que você pedir à IA para cairn_note é o que entra. (Se o aplicativo não encontrar Python, use o caminho completo do Python que instalou Cairn.)

✅ Concluído quando: doctor mostra ✓ MCP — registrado na configuração do Claude Desktop (Desktop), ou 💬 o teste de fumaça "chamar cairn_orient" responde (Cursor).

Aplica-se a toda IA acima:

• A conexão é única. Novos chats apenas lembram — você nunca ativa por chat. orient lê memória; nunca liga nada. O escopo varia por fio: hooks do Claude Code são em toda a máquina (ou um projeto via cairn connect); Desktop/Cursor e Codex vivem na configuração de cada aplicativo, por conta.
• Apenas NOVOS chats captam nova conexão — termine a conexão, então abra um chat novo. (Clientes MCP de longa duração releem as ferramentas apenas em uma reinicialização completa.)
• Controles de privacidade: pule um chat — CAIRN_CAPTURE=0 nesse shell (PowerShell $env:CAIRN_CAPTURE="0" · cmd set CAIRN_CAPTURE=0 · bash export CAIRN_CAPTURE=0) · pause em todo lugar: cairn capture off / on · segredos removidos antes da gravação (somente acréscimo, falha fechada).
• Desfazer: cairn disconnect [--global] · cairn codex-hook uninstall · execute novamente cairn setup para revisar.

O que você obtém

• Um cofre, todo modelo. Qualquer agente que fale MCP ou possa executar cairn lê e grava a mesma memória — então um agente constrói sobre o que outro escreveu, mesmo entre fornecedores concorrentes.
• Mantenha seu lugar através de um limite de uso. Atingiu um limite em um modelo, continue em outro e aponte-o para onde você parou — a trilha está no cofre, não no contexto de um modelo.
• Capturado enquanto você trabalha — decisões, becos sem saída, chamadas de ferramenta e turnos viram nós pesquisáveis, desde o momento em que você conecta.
• Nada que vale a pena manter desaparece. Cada turno capturado armazena seu texto completo: resultados de busca são resumos — um índice — cairn read <id> imprime qualquer nó por completo, e MCP cairn_read puxa tudo com um max_chars elevado.
• Uma passagem de manutenção local que você executa — cairn sleep, à noite por hábito ou no seu próprio agendador (não se agenda sozinho): incorporar → consolidar → podar → reconstruir o grafo → compilar, tudo na sua máquina. Uma exceção ao "sem rede": a primeira incorporação baixa o modelo de ~80 MB, uma vez.
• Um mapa do seu pensamento — a galáxia do painel (cairn dashboard → http://127.0.0.1:7331), além de um Hub / Livro / Índice legível por humanos.
• Backfill — destile conversas antigas em nós claim nítidos e conectados.

Instalação avançada

# Linux / WSL: install the CPU-only PyTorch first, or pip pulls a ~4.6 GB CUDA
# stack you don't need. (Want a GPU build? Install your torch first, then run the
# line below — it's preserved.) macOS: skip this line — its default wheel is CPU/MPS.
pip install torch --index-url https://download.pytorch.org/whl/cpu

pip install -e ".[all]"      # package + embedder + dashboard

pip install -e ".[embeddings]"   # no dashboard
pip install -e ".[dashboard]"    # no embedder

python3 -m venv .venv && source .venv/bin/activate && ./install.sh

Múltiplas contas

Um login por IA? Pule isso — funciona sozinho. Cada IA entra com sua própria conta, e Cairn arquiva o trabalho dessa IA sob sua própria galáxia automaticamente — Claude e GPT nunca se misturam, com zero configuração.

Continue lendo apenas se você executa duas contas da mesma IA (dois logins Claude, dois logins ChatGPT/Codex — digamos, pessoal e da empresa). Galáxias são vinculadas ao id estável de cada login e nunca se fundem — mas com dois logins da mesma IA em uma máquina, Cairn nem sempre consegue provar qual está ativo. A regra que mantém tudo limpo:

Declare, não detecte: defina CAIRN_ACCOUNT por conta, antecipadamente.

# Claude Code — launch each account with its label:
export CAIRN_ACCOUNT=work && claude        # bash/zsh (or set it in that profile)
#   PowerShell: $env:CAIRN_ACCOUNT="work"; claude
# Codex — put it in that account's ~/.codex/config.toml:
#   [mcp_servers.cairn]  env = { CAIRN_ACCOUNT = "work" }
# Importing old history? Always pass the flag:
cairn import <export> --source=claude --account=work

Nomeie e gerencie a qualquer momento:

cairn account                          # list galaxies + node counts
cairn account rename <key> "Company"   # display label only — never merges or deletes
cairn account doctor                   # read-only check — prints the exact fix command per mismatch
cairn account fix-session <session-id> <slug>   # re-file ONE named session (backed up, then locked)
cairn account fix-session <slug>                # same, for the current session only

Limites honestos — para você nunca ser surpreendido:

• Claude Desktop prova a conta ativa por sessão automaticamente. Claude Code CLI e Codex não conseguem — eles seguem o arquivo de login atual da máquina, então uma troca de conta no meio do fluxo pode rotular sessões com a conta anterior, silenciosamente. CAIRN_ACCOUNT é a garantia; detecção não é.
• account doctor verifica o que é comprovável (sessões do Claude Desktop); não consegue auditar histórico de CLI puro ou Codex.
• Somente acréscimo se aplica aqui também: renomeações mudam apenas rótulos de exibição; nada se funde, nada se deleta.

O que fazer backup

Uma pasta: seu cofre em ~/.cairn/ (que é cairn.db — suas memórias reais). Faça backup disso. Todo o resto é substituível — o código está aqui no GitHub, e reinstalar nunca toca no seu cofre.

Comandos comuns

orient · note · fetch · wander · query · read (qualquer nó completo) · dashboard · doctor · setup · connect / disconnect / capture · account · backfill · sleep (o ciclo de manutenção — você o executa) · edges · book · import

Referência completa com todas as opções: QUICKSTART.md.

Licença

Gratuito para uso pessoal e não comercial sob a Business Source License 1.1 — leia, execute, modifique, hospede você mesmo. Uso comercial ou empresarial exige uma licença comercial — envie um e-mail para licensing@cairnremembers.com. Código-fonte disponível (não é "open source" da OSI); cada versão é convertida para a licença permissiva MIT na Data de Alteração em sua LICENÇA.

Patente pendente — um pedido de patente provisória nos EUA cobrindo os mecanismos centrais do Cairn foi protocolado em 07/07/2026. Cairn Remembers™ é uma marca registrada de James Wescott Maitland IV.

Conhecimento é uma trilha, não um destino.