OpenLore

📜 OpenLore

Patrocinado por

Sirva sua documentação para agentes de IA via SSH.

OpenLore é uma base de conhecimento mínima, extensível e nativa para agentes, que mantém o contexto compartilhado atualizado e inspecionável.

---

Sobre

Agentes de IA de codificação já sabem explorar arquivos com ls, cat, grep, find, pipes e loops de shell. O OpenLore oferece a eles essa mesma interface via SSH, respaldada pela sua documentação em vez de uma máquina real.

Agent ──SSH or MCP──▶ OpenLore ──▶ docs, knowledge, and artifacts

Ele começa como um servidor de documentação somente leitura, de binário único e sem configuração. Quando você precisar de uma base de conhecimento ao vivo, pode adicionar acesso com escopo por identidade, publicação controlada, gravações atômicas, validação e aprovação humana sem alterar a forma como os agentes leem ou navegam pelo conteúdo.

Armazenar e recuperar Markdown

Coloque documentação, runbooks, contexto de projeto ou notas escritas por agentes em arquivos Markdown comuns. Não há pipeline de ingestão: aponte o OpenLore para um diretório e ele serve a hierarquia existente diretamente. Organize documentos com pastas, conecte-os com links Markdown padrão e agrupe-os em docsets quando pessoas ou agentes diferentes precisarem de acessos distintos. O OpenLore é somente leitura por padrão; habilite a gravação quando quiser que agentes criem e atualizem Markdown também.

Início Rápido

O caminho mais rápido é deixar seu agente configurar o OpenLore:

# Teach your agent how to install, configure, and bundle OpenLore
ssh openlore.sh teach | your-agent-cli

# Add documentation access instructions to AGENTS.md
ssh openlore.sh agents >> AGENTS.md

Ou instale e execute diretamente:

go install github.com/aakarim/go-openlore/cmd/openlore@latest

openlore ./docs

ssh -p 2222 localhost
ssh -p 2222 localhost "grep -r 'authentication' /docs"

Por padrão, isso inicia:

• SSH na porta localhost:2222
• a visualização web para humanos na porta http://localhost:8080
• MCP sobre HTTP na porta http://localhost:8080/mcp

Consulte Instalação para mais formas de instalar e empacotar o OpenLore.

Recursos

• Recuperação nativa para agentes — Os agentes usam as ferramentas de shell e os padrões de composição que já conhecem, em vez de aprender uma API de recuperação personalizada.
• Uma superfície de conhecimento, múltiplos transportes — Sirva o mesmo sistema de arquivos virtual via SSH, SFTP/SSHFS, MCP e uma visualização web amigável para humanos.
• Conhecimento vivo e governado — Mantenha o conteúdo somente leitura, permita publicação com escopo ou habilite gravações completas por docset. As gravações são atômicas, conscientes de conflitos e podem exigir aprovação humana.
• Visualizações com escopo por identidade — Dê a cada pessoa ou agente apenas os docsets necessários, com concessões baseadas em papéis para ro, publish e rw, aliases de caminho e diretórios pessoais privados.
• Seguro por construção — O shell é um interpretador Go em memória, não um shell real de sistema operacional. Não há escape de shell, execução arbitrária de processos ou acesso de rede ambiente em uma sessão normal.
• Pacotes de conhecimento portáteis — Incorpore documentos em um binário autocontido, crie pacotes multiplataforma com a GitHub Action ou empacote-os como uma extensão MCP de desktop.
• Conhecimento estruturado sem uma nova linguagem de consulta — Inspecione frontmatter como NDJSON com lore meta, consulte-o com jq e valide os pacotes do Open Knowledge Format (OKF) do Google e Agent Skills próximos ao caminho de gravação.
• Política e processamento extensíveis — Plugins podem adicionar validação, concessões, middleware de leitura/gravação, metadados e processamento pós-commit preservando a mesma interface de sistema de arquivos.

Casos de Uso

• Repositório de Aprendizado Contínuo — armazene sessões e aprendizados em um único servidor compartilhado. Adicione métricas para otimizar. Permita que agentes compartilhem aprendizados entre si mantendo o isolamento do usuário.
• Repositório de Artefatos da Equipe — compartilhe documentos Markdown, HTML, JSON, Excel etc. que você criou mantendo controles de acesso. Muito mais natural que git, mais nativo para agentes que Confluence/Notion.
• Documentação para agentes de codificação — Coloque documentação de API interna, runbooks, contexto de produto e notas de arquitetura atrás de uma interface familiar e pesquisável.
• Uma memória viva compartilhada para equipes de agentes — Dê aos agentes docsets separados ou compartilhados para que publiquem descobertas, façam handoff de trabalho e acumulem contexto durável entre sessões.
• Site de documentação pública — adicione quaisquer arquivos ao seu docset público, habilite acesso público e ele será exibido para qualquer agente que encontrar seu site. Melhora AEO/GEO sem necessidade de editar sua documentação existente.
• Compartilhamento de skills — Publique Agent Skills em coleções compartilhadas para que todo agente autorizado possa descobrir e usar os mesmos procedimentos governados.
• Repositório de Agent Plugins — Fixe versões de repositórios de Agent Plugins do GitHub e sirva-os aos agentes da sua equipe. Skills empacotadas no padrão aberto permanecem atualizadas automaticamente.
• Contribuição de conhecimento governada — Permita que contribuidores publiquem em caixas de entrada enquanto reserva caminhos sensíveis para aprovadores e evita sobrescritas acidentais.
• Revisão remota de artefatos de agentes — Exponha relatórios, logs, capturas de tela e arquivos gerados pelo navegador ou SSH sem criar um visualizador de artefatos personalizado ou conceder acesso à máquina do agente.
• Espaços de trabalho específicos por identidade — Monte um diretório pessoal privado para cada agente, além do conhecimento compartilhado da equipe, tudo por meio de um único servidor e um único modelo de autorização.
• Conhecimento portátil de cliente ou projeto — Envie um executável versionado com os documentos relevantes incorporados ou distribua o mesmo conhecimento como uma extensão de desktop MCPB.
• Catálogos de conhecimento validados — Imponha convenções de frontmatter e pacotes, inspecione metadados de forma econômica e impeça conhecimento malformado na admissão.

Como Funciona

O OpenLore é construído sobre o Wish para transporte SSH. Uma conexão é tratada inteiramente contra um sistema de arquivos virtual:

1. Autentique — conecte-se sem chave ou resolva uma chave SSH, certificado, passkey ou login OAuth para uma identidade.
2. Componha uma visualização — monte apenas os docsets e caminhos concedidos àquela identidade.
3. Explore — execute comandos de shell implementados como funções Go puras sobre essa visualização ou use a ferramenta MCP shell equivalente.
4. Contribua com segurança — se a gravação estiver habilitada, autorize e valide uma alteração de arquivo inteiro antes de confirmá-la atomicamente ou encaminhá-la para aprovação.

Clientes OAuth usam identidades delegadas, então a proveniência durável de gravação distingue trabalho direto por adil de trabalho realizado como adil/claude@claude.ai. Delegados podem herdar no máximo a autoridade de seu principal e podem ser restringidos por docset e listas de negação de capacidade. Clientes CIMD também podem autenticar com metadados hospedados pelo fornecedor e private_key_jwt; consulte Clientes OAuth Autenticados.

O shell normal não pode invocar bash, exec, curl ou processos arbitrários do host. A documentação incorporada é sempre somente leitura. Identidades explicitamente confiáveis podem receber processamento assíncrono com escopo restrito por meio da capacidade spawn.

Gravação Governada

O OpenLore é somente leitura por padrão. Implantações graváveis mantêm um único caminho de gravação controlado por política para redirecionamentos, anexos, tee, patch, sed -i, movimentação de arquivos, publicação e trabalhos externos aprovados.

echo "# Research" | publish backend findings.md
cat change.diff | patch /backend/api.md
sed -i 's/old/new/g' /backend/runbook.md

Gravações são trocas atômicas de objeto inteiro. A proteção compare-and-swap rejeita edições desatualizadas por padrão, concessões de docset restringem o destino e caminhos selecionados podem produzir changesets revisáveis sob /requests em vez de confirmar diretamente.

Consulte Gravação e publicação para configuração voltada ao usuário e Internals do sistema de gravação para o modelo de implementação.

Instalação

Instalar com Go

Requer Go 1.26 ou posterior:

go install github.com/aakarim/go-openlore/cmd/openlore@latest

Compilar a partir do código-fonte

git clone https://github.com/aakarim/go-openlore.git
cd go-openlore
go build -o openlore ./cmd/openlore

Incorporar documentos em um binário

Coloque a documentação em assets/lore/ e compile. O binário resultante contém os documentos e os serve somente leitura em /docs quando executado sem argumento de diretório:

go build -o my-docs ./cmd/openlore

Compilar com a GitHub Action

Produza binários multiplataforma com seus documentos incorporados:

- uses: aakarim/openlore@v1
  with:
    docs-dir: ./docs
    config: ./openlore.yml

Consulte Formas de usar o OpenLore para MCP stdio, empacotamento de desktop MCPB, SSHFS e uso como biblioteca Go.

Criar uma implantação personalizada

Use a skill setup incluída para criar <team>-lore, um pequeno repositório de propriedade do cliente contendo openlore.yml, um Containerfile fino fixado em uma versão oficial do OpenLore e artefatos de implantação. Ele compila um servidor local funcional e verifica HTTP, MCP, SSH autenticado, gravações e persistência antes da implantação:

ssh openlore.sh setup | amp

O repositório gerado mantém a política inicial de lore.json e arquivos visíveis via SSH sob .local/ ignorado pelo git. A primeira implantação inicializa um volume persistente vazio a partir desse estado. O openlore.yml raiz permanece como autoridade Git/IaC e é implantado separadamente em /var/lib/openlore/config/openlore.yml; ele não é incorporado à imagem. Edições posteriores de lore.json e do sistema de arquivos no servidor são autoritativas e nunca são sobrescritas por atualizações de imagem.

Comandos de instrução adicionais suportam o ciclo de vida completo:

• onboarding adiciona identidades, papéis, diretórios pessoais e pastas iniciais localmente;
• deploy seleciona Fly.io, Railway, AWS, Google Cloud, Azure, DigitalOcean ou uma implantação personalizada e verifica um contrato compartilhado de persistência/rede;
• upgrade prepara apenas a mudança de versão da imagem base fixada para que a CD existente possa implantá-la.

Implantações de provedores exigem HTTPS/MCP, SSH OpenLore autenticado, acesso administrativo ao shell e um volume persistente /var/lib/openlore. Quando o provedor suporta, a implantação configura a porta pública 22 para encaminhar para a porta 2222 do OpenLore. Caso contrário, ela relata a porta atribuída e recomenda um sistema externo de encaminhamento TCP.

O contêiner publicado contém apenas o OpenLore. Ele deliberadamente não contém política de onboarding ou configuração de servidor. Antes de o serviço iniciar, a implantação deve colocar openlore.yml e lore.json no diretório de configuração persistente e executar:

./out --config /var/lib/openlore/config/openlore.yml

Isso mantém a configuração implantável de forma independente: uma implantação simples pode copiar openlore.yml para o volume, enquanto o Kubernetes pode projetar o mesmo arquivo a partir de um ConfigMap. Use a skill deploy para Fly.io, Railway, AWS, Google Cloud, Azure, DigitalOcean ou infraestrutura personalizada. Os arquivos Railpack e Fly do repositório fornecem a imagem, o volume persistente e a fiação de portas; eles não semeiam nem mutam a configuração na inicialização do processo.

O Railway atribui ao seu proxy TCP SSH um hostname e porta públicos. A porta SSH padrão 22 exige um balanceador de carga TCP bruto externo. O Fly.io pode mapear a porta pública 22 para a porta interna 2222 do OpenLore com um endereço dedicado. SSH bruto não tem hostname ou roteamento SNI, então um único listener não pode rotear múltiplos domínios na porta 22.

O fluxo de trabalho do contêiner publica latest a partir de main; as versões também publicam VERSION, vVERSION, tags de imagem major e minor.

Uploads de caixa de entrada via HTTP

Configure um docset inbox e um papel com sua concessão publish, depois crie uma credencial para uma identidade existente (a configuração do servidor deve nomear auth_file para que a CLI possa validá-la):

openlore inbox token create --identity alice --label webhook --config openlore.yml
curl -H 'Authorization: Bearer olin_ID_SECRET' -H 'Content-Type: text/markdown' \
  --data-binary @note.md 'https://docs.example.com/inbox/docs?name=note.md'

POST /inbox/{docset} aceita credenciais bearer ou um HMAC de corpo exato usando X-OpenLore-Token-Id e X-OpenLore-Signature. Tokens de acesso OAuth são usados apenas para POST/GET /inbox/tokens e DELETE /inbox/tokens/{id}; as credenciais de caixa de entrada são separadas e revogáveis. Consulte Configuração e identidade.

Documentação

Guia	Conteúdo
Formas de usar o OpenLore	SSH, MCP, web, SSHFS, binários embutidos, GitHub Action, MCPB e uso como biblioteca
Referência de comandos	Referência completa de shell, introspecção, publicação, sintaxe, comandos CLI e flags
Configuração e identidade	openlore.yml, autenticação, papéis, docsets, aliases, homes e verificação de host
Federação de identidade de carga de trabalho	Autentique CI e agentes com tokens de identidade externos de curta duração
Escrita e publicação	Modos de escrita, caixas de entrada, tratamento de conflitos, aprovações e jobs
Plugins e formatos de conhecimento	Instalação de plugins, interfaces, validação OKF, lore validate e lore meta
Internals do sistema de escrita	Camadas do sistema de arquivos, costura de escrita, changesets, hooks e jobs assíncronos
Avaliação de segurança	Modelo de ameaças e propriedades de segurança

Segurança

• Comandos são executados em um interpretador puro em Go, não via os/exec.
• O sistema de arquivos virtual limpa caminhos e impõe limites de docset.
• Padrões de arquivos permitidos e diretórios ignorados mantêm segredos fora da visão.
• RBAC controla leituras, publicação, escritas, aprovações e capacidades confiáveis.
• O endpoint web pode publicar a chave de host SSH via TLS para evitar confiança cega no primeiro uso; certificados de usuário e host SSH também são suportados.

Consulte SECURITY.md para a avaliação de segurança completa.

Licença

MIT — Adil Karim

O OpenLore inclui componentes de código aberto de terceiros. Suas licenças e avisos exigidos estão listados em assets/legal/THIRD_PARTY_NOTICES.md, com textos completos das licenças em assets/legal/licenses/. Eles estão embutidos no binário e servidos pelo serviço em execução em /legal.