codicil

Codicil

Documentação durável e pesquisável para assistentes de codificação compatíveis com MCP.

O Codicil indexa a documentação já presente em um repositório e expõe duas ferramentas MCP: query_docs para recuperação e reindex_docs para atualizações. Ele usa um endpoint de embeddings compatível com Ollama quando disponível. Se o endpoint estiver indisponível, a busca continua com um fallback por palavras-chave que lê os arquivos atuais do disco.

Status: software inicial, para um único usuário. O índice principal e os caminhos de fallback são testados, mas a interface de linha de comando e o formato de armazenamento podem mudar antes de um lançamento estável.

O Que Ele Faz

• Indexa arquivos .md, .mdx, .rst, .txt, .yaml, .yml e .toml.
• Divide Markdown nos cabeçalhos H1 e H2; outros arquivos usam blocos de caracteres sobrepostos.
• Armazena um índice Chroma local em .codicil/ por padrão.
• Retorna correspondências semânticas quando embeddings estão disponíveis, ou correspondências por palavras-chave quando não estão.
• Reindexa incrementalmente usando horários de modificação de arquivos.

Diretórios como .git, .venv, node_modules, dist, build e .codicil são excluídos. Arquivos sem conteúdo indexável são registrados como vazios e removem quaisquer blocos mais antigos.

Início Rápido

Requisitos: Python 3.11+ e um host semelhante ao Unix. O Codicil usa um bloqueio de arquivo consultivo para proteger seu armazenamento local.

python3.11 -m venv .venv
./.venv/bin/pip install -e ".[dev]"

# Optional: works without an embedding server, using keyword fallback.
./.venv/bin/codicil index .
./.venv/bin/codicil serve .

serve inicia o servidor MCP stdio. Se o índice selecionado estiver vazio, ele tenta um índice inicial automaticamente. Sem um endpoint de embeddings acessível, esse índice inicial pula embeddings semânticos e query_docs ainda pesquisa os arquivos diretamente.

Execute o conjunto de testes offline com:

./.venv/bin/python -m pytest -q

Conecte um Cliente MCP

O repositório inclui esta configuração local do Claude Code:

{
  "mcpServers": {
    "codicil": {
      "command": ".venv/bin/codicil",
      "args": ["serve", "."]
    }
  }
}

Coloque uma configuração equivalente no repositório que você deseja pesquisar, ajustando command para o caminho absoluto do executável codicil instalado quando necessário. O caminho passado para serve é o repositório que o Codicil indexa.

Seu cliente pode então chamar:

query_docs(query="How is the reverse proxy configured?", n_results=5)
reindex_docs(force=false)

Ilustrativo — a interface de chat do Claude Code não é algo que uma gravação de terminal possa reproduzir.

O GIF acima é uma saída real e não editada — a mesma função query_docs chamada diretamente em um terminal em vez de via MCP. Nenhum host de embeddings local estava em execução quando isso foi gravado, então está respondendo via fallback por palavras-chave, não por busca semântica — uma demonstração ao vivo do comportamento de degradar-em-vez-de-falhar que este projeto realmente aborda.

n_results deve estar entre 1 e 10. reindex_docs() é a forma suportada de atualizar um índice enquanto o servidor MCP possui o armazenamento.

Embeddings e Fallback

Por padrão, o Codicil chama http://localhost:11434/api/embeddings com o modelo nomic-embed-text. Inicie um serviço local compatível para habilitar a busca semântica e, em seguida, indexe o repositório:

export CODICIL_EMBED_URL=http://localhost:11434
export CODICIL_EMBED_MODEL=nomic-embed-text
./.venv/bin/codicil index .

Para modelos nomic, o Codicil usa automaticamente os prefixos recomendados de tarefa de documento e consulta. Outros nomes de modelos são enviados sem prefixos.

Se o host de embeddings não puder ser alcançado, ou o índice selecionado não tiver blocos, query_docs usa busca por palavras-chave no repositório. Os resultados por palavras-chave classificam arquivos pela correspondência de termos de consulta e incluem linhas próximas; eles são úteis, mas não entendem sinônimos ou similaridade semântica.

Usar um endpoint de embeddings remoto envia texto indexado e consultas de busca para esse endpoint. Mantenha a URL padrão de localhost ou use um endpoint em que você confie. Não envie nomes de host ou credenciais privadas em .mcp.json.

Configuração

A configuração é lida quando o módulo do servidor inicia, então defina variáveis de ambiente antes de executar codicil ou iniciar seu cliente MCP.

Variável	Padrão	Significado
CODICIL_REPO	.	Repositório a indexar. A CLI define isso a partir do argumento de caminho.
CODICIL_STORE	<repo>/.codicil	Dados Chroma locais, estado do índice e arquivo de bloqueio.
CODICIL_EMBED_URL	http://localhost:11434	URL base do host de embeddings compatível com Ollama.
CODICIL_EMBED_MODEL	nomic-embed-text	Modelo de embeddings solicitado ao host.
CODICIL_EMBED_WORKERS	3	Solicitações de embeddings concorrentes durante a indexação.
CODICIL_MIN_SCORE	0.5	Pontuação mínima de similaridade semântica retornada por query_docs.

Alterar CODICIL_EMBED_MODEL seleciona uma coleção separada e um arquivo de estado, evitando dimensões de vetores incompatíveis. Execute codicil index após alterar modelos; coleções existentes permanecem no armazenamento até que você remova deliberadamente o armazenamento enquanto nenhum processo do Codicil estiver em execução.

Operações e Limitações

codicil index [path] indexa um repositório e sai. Adicione --force para ignorar mtimes registrados e re-incorporar cada arquivo indexável. codicil serve [path] executa o servidor MCP.

Apenas um processo do Codicil pode usar um armazenamento por vez. Iniciar codicil index enquanto codicil serve owns the same store fails intentionally. Use reindex_docs do servidor MCP em execução, ou pare o servidor antes de executar o indexador CLI.

O Codicil é atualmente projetado para um repositório local e um usuário. Ele não fornece monitoramento de arquivos, hooks de git, acesso multiusuário ou recuperação entre repositórios.

Solução de Problemas

• “store is already in use”: outro processo do Codicil possui CODICIL_STORE. Pare-o, ou chame reindex_docs através desse servidor MCP em execução.
• Resultados por palavras-chave em vez de pontuações: o endpoint de embeddings está indisponível ou o modelo selecionado ainda não foi indexado. Verifique CODICIL_EMBED_URL e execute codicil index.
• Nenhum arquivo correspondente: confirme se a extensão do arquivo é suportada e se ele não está em um diretório excluído. Consultas com apenas palavras de dois caracteres ou menos não têm termos de busca de fallback.
• Precisa de uma reconstrução limpa: pare todos os processos do Codicil, remova o armazenamento local e execute codicil index. Isso remove permanentemente todas as coleções locais desse armazenamento.

Para detalhes de desenvolvimento e invariantes de confiabilidade, veja CLAUDE.md. Para um guia de instalação mais detalhado, veja docs/SETUP.md.

Licença

Lançado sob a Licença MIT.