agentRamen MCP

agentRamen

Licenciado sob Apache-2.0. Consulte a política de segurança e o código de conduta da comunidade.

O agentRamen indexa a estrutura do código-fonte e o histórico do Git e, em seguida, recupera arquivos e trechos relevantes para a tarefa. Ele é local-first por padrão: cada desenvolvedor mantém um índice SQLite privado. As equipes podem, opcionalmente, publicar snapshots sanitizados e fixados por commit em um serviço MCP somente leitura, hospedado centralmente e protegido por OIDC.

Início rápido

Instale o agentRamen e execute-o a partir do repositório que você deseja explorar:

python -m pip install agentramen
cd /path/to/your/repository
agentramen init
agentramen context "Add authentication" --budget 2000
agentramen impact src/auth.py

O agentramen init cria a configuração, indexa o repositório e oferece um fluxo de trabalho opcional de chamada do GitHub Actions. O índice é armazenado localmente em .agentramen/graph.db.

Experimente em 30 segundos com examples/demo.sh. Consulte o roteiro e o guia de contribuição.

Uma extensão mínima para VS Code também está disponível.

O que ele pode fazer

• Encontrar contexto de tarefa: classificar arquivos usando caminhos, símbolos, imports, histórico do Git e similaridade semântica local opcional.
• Explicar impacto de mudanças: inspecionar dependências, dependentes, co-mudanças, pontos críticos e histórico de arquivos.
• Mapear a estrutura do repositório: explorar a arquitetura, exportar o grafo e consultar snapshots de commits em cache.
• Conectar-se a agentes de codificação: usar MCP stdio local, a interface do navegador ou um serviço MCP centralizado autenticado e opcional.
• Manter índices locais privados: no modo local, o banco de dados e os embeddings opcionais permanecem em cada checkout; o modo central transfere apenas um snapshot sanitizado explícito para a infraestrutura que você opera.

Como funciona

flowchart LR
  repo[Working tree and Git history] --> indexer[Indexer and language analyzers]
  indexer --> db[(Local SQLite graph)]
  optional[Optional local embeddings] --> db
  task[Task or query] --> clients[CLI, MCP, or local HTTP]
  clients --> retrieve[Retrieval and graph queries]
  retrieve <--> db
  retrieve --> excerpts[Ranked files and source excerpts]

A instalação padrão usa a biblioteca padrão do Python e análise conservadora para outras linguagens. Extras opcionais adicionam parsing Tree-sitter, recuperação semântica local e contagem de tokens ciente do modelo.

Como ele se compara

Projeto	Estrelas	Abordagem	vs. agentRamen
Serenagithub	~30.1k	Kit de ferramentas de recuperação semântica + edição baseado em LSP, MCP	Kit de ferramentas de agente muito mais amplo e amplamente adotado
Aider's RepoMapgithub	~49.4k	Tree-sitter + PageRank com orçamento de tokens para mapa de repositório	Exemplo estabelecido de contexto de repositório classificado por grafo e com orçamento de tokens (adjacente: um recurso dentro de um aplicativo de codificação)
Repomixgithub	~28.7k	Empacota o repositório inteiro em um único arquivo amigável para IA	Fluxo de trabalho adjacente: empacotamento do repositório inteiro vs. contexto seletivo
code-index-mcpgithub	~1k	AST Tree-sitter para 10 linguagens, índice persistente, MCP stdio	O servidor de índice autônomo estruturalmente mais comparável; sem busca semântica ou integração com CI declarada
agentRamen	1	Grafo SQLite, classificação por histórico do Git, MCP+CLI+HTTP+VS Code	Alfa funcional desde o primeiro dia

Extras opcionais

python -m pip install 'agentramen[treesitter]'
python -m pip install 'agentramen[semantic]'
python -m pip install 'agentramen[tokenizer]'
python -m pip install 'agentramen[central]'

A instalação padrão não tem dependências em tempo de execução. Tree-sitter, embeddings semânticos, tokenizadores e o serviço MCP remoto são opcionais. A configuração do modelo semântico pode baixar pesos no primeiro uso; a inferência é executada localmente.

O agentramen init cria .agentramen.yml e um fluxo de trabalho de chamada do GitHub Actions se eles não existirem e, em seguida, cria/atualiza .agentramen/graph.db. O agentramen update e o agentramen index atualizam incrementalmente os arquivos alterados. O banco de dados é ignorado pelo Git.

No modo local, trechos do código-fonte e embeddings opcionais permanecem em .agentramen/graph.db. O modo de snapshot central transfere código-fonte indexado que passa pelas heurísticas de credenciais para o seu serviço central privado; revise os requisitos de tratamento de dados da sua organização antes de ativá-lo.

Publicando versões

Configure um publicador confiável do PyPI para palrajjp/agentRamen, usando o fluxo de trabalho .github/workflows/publish.yml e o ambiente pypi. Para publicar uma versão, atualize a versão em pyproject.toml e agentramen/__init__.py, crie uma tag Git correspondente com prefixo v e publique uma versão no GitHub para essa tag. O fluxo de trabalho compila as distribuições e as publica no PyPI usando OIDC.

Configuração

O agentRamen lê os seguintes campos de .agentramen.yml:

version: 1
indexing:
  incremental: true
git:
  history: true
  co_changes: true
history:
  commits: 100
semantic:
  enabled: false
  model: BAAI/bge-small-en-v1.5
context:
  default_budget: 2000
  tokenizer_model: ""
ignore:
  - .env
  - "*.pem"
  - private/

O indexing.incremental: false reanalisa cada arquivo elegível a cada indexação. O git.history: false remove o histórico armazenado de commits, renomeações e co-mudanças; ativá-lo posteriormente reconstrói o histórico recente configurado. O history.commits controla os commits retidos (1–100.000), e o git.co_changes alterna as arestas de co-mudança. O context.default_budget é usado pela CLI, MCP e API HTTP quando nenhum orçamento é passado. A configuração é um subconjunto YAML sem dependências; valores não suportados/malformados são rejeitados com um erro específico da configuração. Os padrões .agentramenignore são adicionados às regras de ignorar embutidas e do YAML, em vez de substituí-las.

O semantic.enabled: true opta pela geração de embeddings locais e classificação de contexto semântico; instale o agentramen[semantic] primeiro. O semantic.model seleciona um modelo FastEmbed. O agentramen[treesitter] opta pela análise baseada em Tree-sitter para linguagens não Python suportadas; sem ele, ou se uma gramática não estiver disponível, o agentRamen recorre à análise por regex.

O context.tokenizer_model seleciona opcionalmente um modelo suportado pelo tiktoken para orçamentos de contexto baseados em tokenizador; instale o agentramen[tokenizer] para usá-lo. O vocabulário do tokenizador pode ser baixado e armazenado em cache no primeiro uso; depois, a contagem é executada localmente. Deixe vazio para usar o fallback aproximado baseado em caracteres, sem dependências. As respostas de contexto identificam token_count_method (tiktoken ou approximate) e o modelo do tokenizador quando configurado. O total relatado orça os arquivos selecionados, memórias da equipe e evidências de caminho/digest/commit juntos; contagens por arquivo são fornecidas como estimated_tokens.

Comandos

agentramen init
agentramen index [--json]
agentramen update [--json]
agentramen status [--json]
agentramen context "Add OAuth login" [--budget 2000] [--json]
agentramen impact src/auth/AuthService.ts [--json]
agentramen explain src/auth/AuthService.ts [--json]
agentramen history src/auth/AuthService.ts [--json]
agentramen search "auth login" [--limit 20] [--json]
agentramen architecture [--at <commit>] [--json]
agentramen hotspots [--limit 20] [--json]
agentramen changes [--limit 20] [--json]
agentramen diff <commit1> <commit2> [--json]
agentramen pr [--base origin/main] [--json]
agentramen export [--at <commit>] [--json]
agentramen benchmark --files 10 1000
agentramen serve [--host 127.0.0.1] [--port 8765]
agentramen mcp

Exemplo de resposta de contexto:

{
  "task": "Add authentication",
  "files": [
    {
      "path": "src/auth_service.py",
      "language": "python",
      "symbols": ["AuthService"],
      "imports": [],
      "recent_change": "add authentication",
      "estimated_tokens": 18
    }
  ],
  "token_budget": 2000,
  "files_avoided": 12,
  "confidence": "medium"
}

O contexto inclui trechos do código-fonte somente quando o arquivo ainda corresponde ao hash indexado e não contém um padrão de credencial detectado. As contagens de tokens usam o tokenizador do modelo configurado quando disponível; caso contrário, são estimativas aproximadas baseadas em caracteres, não medições de tokenizador ou alegações de desempenho.

GitHub Actions

O fluxo de trabalho criado pelo agentramen init chama o fluxo de trabalho reutilizável neste repositório:

name: agentRamen
on:
  push:
    branches: ["**"]
  pull_request:
  workflow_dispatch:
  schedule:
    - cron: "17 4 * * 1"
jobs:
  agentramen:
    uses: palrajjp/agentRamen/.github/workflows/index.yml@main

O fluxo de trabalho reutilizável busca o histórico do Git, restaura um cache, testa o pacote instalado, indexa a revisão com checkout, resume pull requests e publica o artefato SQLite local. Use um checkout de profundidade total ao executar a CLI fora deste fluxo de trabalho reutilizável para reter o histórico.

Uso a partir do gha-cd ou de outro fluxo de trabalho

Chame o fluxo de trabalho reutilizável antes de uma implantação ou job de agente. Fornecer task também cria um artefato de contexto JSON limitado; o fluxo de trabalho não envia conteúdo do repositório a um provedor de IA.

jobs:
  agentramen:
    uses: palrajjp/agentRamen/.github/workflows/index.yml@main
    with:
      task: "Trace the deployment workflow and identify rollback dependencies"
      token_budget: 1200

O artefato é nomeado agentramen-context-${{ github.sha }}. Um job downstream pode buscá-lo e passar .agentramen-context/agentramen-context.json para a etapa do agente:

- uses: actions/download-artifact@v4
  with:
    name: agentramen-context-${{ github.sha }}
    path: .agentramen-context

O orçamento de contexto é padronizado para 2000 se omitido. Trate o artefato como código-fonte: ele pode conter trechos e segue a política de acesso e retenção do GitHub Actions do repositório.

Integrações com agentes

O servidor MCP do agentRamen é executado localmente via stdio. Instale o agentRamen uma vez em cada máquina de desenvolvedor e adicione um .mcp.json portátil na raiz do repositório para que o VS Code Copilot e o Claude Code possam usar a mesma configuração:

python -m pip install git+https://github.com/palrajjp/agentRamen.git

{
  "mcpServers": {
    "agentramen": {
      "type": "stdio",
      "command": "agentramen",
      "args": ["mcp"]
    }
  }
}

Para o Claude Code, o comando com escopo de projeto cria ou atualiza .mcp.json:

claude mcp add --transport stdio --scope project agentramen -- agentramen mcp

Para o GitHub Copilot CLI, salve o mesmo objeto mcpServers em $COPILOT_HOME/mcp-config.json, ou ~/.copilot/mcp-config.json quando COPILOT_HOME não estiver definido. Consulte o guia de configuração MCP do VS Code e o guia MCP do Claude Code para configuração específica do cliente e prompts de confiança.

No VS Code, confie no workspace e inicie o servidor MCP agentramen na visualização de Servidores MCP. Cada desenvolvedor mantém um .agentramen/graph.db independente; faça commit de .agentramen.yml e .mcp.json para configurações compartilhadas, mas não coloque um banco de dados SQLite ativo em um compartilhamento de rede.

Mantenha o contexto do agente focado

Adicione uma instrução como esta ao AGENTS.md, CLAUDE.md ou às instruções do Copilot do projeto:

Para análise de repositório, chame repo_context com a tarefa atual antes de leituras amplas de arquivos. Comece com um orçamento de 1200 tokens, use os caminhos retornados como limite da investigação e, em seguida, chame repo_explain ou repo_impact para acompanhamento direcionado. Expanda a busca somente quando o contexto indexado for insuficiente. Peça agentramen update se o índice parecer desatualizado.

O orçamento limita o contexto recuperado, não a conversa inteira do modelo. As contagens usam uma estimativa aproximada baseada em caracteres por padrão; instale agentramen[tokenizer] e defina context.tokenizer_model quando a contagem específica do modelo for importante. Execute agentramen update para atualizar incrementalmente o índice local de um desenvolvedor após mudanças.

ChatGPT e GPT Store

GPTs personalizados não podem iniciar o processo stdio local de um desenvolvedor. Uma GPT Action ou um aplicativo ChatGPT hospedado precisa de um serviço HTTPS acessível com autenticação. O agentramen serve escuta apenas em localhost e não tem autenticação, portanto, não o exponha diretamente à internet; uma integração remota segura requer um gateway autenticado ou um serviço MCP hospedado separadamente. A disponibilidade de criação e publicação de GPTs depende do plano atual do ChatGPT e da política do workspace; consulte o guia de criação de GPTs da OpenAI.

MCP

Execute agentramen mcp a partir de um repositório e configure seu agente compatível com MCP para iniciar esse comando no diretório de trabalho do repositório. As ferramentas incluem repo_context, repo_status, repo_history, repo_search, repo_explain, repo_impact, repo_dependencies, repo_tests, repo_changes, repo_architecture, repo_hotspots, repo_graph, repo_stage_memory, repo_review_queue, repo_approve_memory, repo_reject_memory, repo_publish_memory, repo_team_memory_search e repo_memory_audit. O servidor stdio não precisa de chaves de API e não acessa um serviço de rede.

API HTTP local

O agentramen serve escuta somente em 127.0.0.1 por padrão. A interface do navegador está disponível em / e /ui. A API fornece GET /health, GET /api/v1/repository, /architecture, /graph, /files/{path}, /impact?path=..., /history?path=..., /hotspots e POST /api/v1/context ou /api/v1/search. Acrescente ?at=<commit> a /api/v1/graph ou /api/v1/architecture para consultar um snapshot de grafo em cache e endereçável por commit. Solicitações POST aceitam objetos JSON como {"task":"Add OAuth","token_budget":2000}. Nenhuma autenticação é fornecida; não vincule a uma interface pública sem colocar uma camada de controle de acesso autenticada na frente.

Benchmarking

Execute agentramen benchmark --files 10 1000 para medir a indexação sintética inicial, uma atualização incremental de um arquivo e a recuperação de contexto. Adicione --repository /path/to/repo para medir também uma cópia temporária dos arquivos rastreados da árvore de trabalho de um repositório real. Use --semantic-mode both para comparar a recuperação semântica desativada/ativada; a execução ativada requer agentramen[semantic] e baixa o modelo configurado, se necessário. Se a configuração do modelo não estiver disponível, a comparação relata esse modo como erro e ainda retorna medições para o modo bem-sucedido. A saída inclui contagem de candidatos lexicais, tamanho do banco de dados e tempos de recuperação/indexação.

Adicione --quality para relatar precisão/revocação de tarefa-para-arquivo e teste-afetado em um fixture sintético determinístico e rotulado; test_evidence mostra a cadeia de importação usada para confirmar cada teste sugerido:

agentramen benchmark --quality --json

O fixture atual pontua 1,0 de precisão e revocação médias para arquivos e testes. Esta é uma verificação de correção do fixture, não uma afirmação de precisão em repositório real. Para decisões de adoção, selecione rótulos do seu próprio repositório e meça essas tarefas; todos os tempos e pontuações dependem do repositório, rótulos de tarefas e ambiente.

Privacidade e exclusões

O índice permanece em .agentramen/graph.db na máquina local ou no artefato de CI configurado. Com a recuperação semântica desativada, o banco de dados armazena metadados de origem e hashes; quando ativada, armazena adicionalmente embeddings gerados localmente. O agentRamen ignora diretórios gerados comuns, arquivos de ambiente, arquivos de chave privada, arquivos muito grandes, arquivos binários e arquivos contendo padrões reconhecíveis de atribuição de chave privada ou credencial. Adicione mais padrões de caminho a .agentramenignore (um padrão por linha). Revise suas regras de ignorar antes de publicar artefatos gerados.

Recuperação e memória

A recuperação de contexto usa um índice invertido SQLite incremental para candidatos lexicais e, em seguida, combina classificações lexicais, semânticas opcionais e de grafo/histórico com fusão de classificação recíproca antes de aplicar o orçamento de tokens. Memórias revisadas podem ser encenadas, aprovadas ou rejeitadas; aprovar um novo fato substitui fatos ativos conflitantes com o mesmo assunto.

Compartilhe memórias aprovadas com uma equipe

O AgentRamen mantém o banco de dados SQLite ativo privado para cada checkout. Para compartilhar um fato revisado, encene-o, aprove-o e publique-o em .agentramen-shared/memories/<id>.json. Faça commit desse arquivo em uma solicitação de pull para que colegas possam revisar alterações, ver histórico e receber a atualização via Git. Um arquivo por memória evita que adições não relacionadas colidam.

Ferramentas MCP: repo_context retorna caminho de origem, digest e evidência de commit para seus arquivos selecionados. Uma chamada subsequente a repo_stage_memory anexa evidência da chamada de contexto mais recente à proposta pendente privada; a revisão mostra a evidência e se os bytes de origem ainda estão atuais. A aprovação registra o user.name do Git como revisor (recorrendo ao nome da conta local); a publicação preserva esse revisor, o commit de origem, digests e janela de validade. Aprovação e publicação rejeitam evidência alterada. Memórias aprovadas desatualizadas aparecem no topo de repo_review_queue com uma ação restage_with_fresh_context; elas não podem ser reaprovadas como atuais. repo_team_memory_search omite memórias compartilhadas cuja evidência está desatualizada ou ausente. repo_memory_audit relata contagens exclusivas de memórias desatualizadas, caminhos incompatíveis, commits de origem e registros locais/compartilhados não verificados sem editar arquivos Git compartilhados. Fatos substituídos são marcados em seu arquivo existente quando um fato aprovado mais novo com o mesmo assunto é publicado. Conteúdo semelhante a credenciais é bloqueado da publicação; ainda assim, revise o conteúdo da memória para dados confidenciais ou pessoais antes de fazer commit. Agentes nunca devem aprovar ou publicar uma memória sem direção humana explícita.

Pesquisa e publicação via CLI:

agentramen memory search "authentication provider"
agentramen memory publish <approved-memory-id>
agentramen memory audit --json

A memória compartilhada é opcional e versionada; notas rejeitadas ou meramente encenadas permanecem locais. Memórias existentes criadas antes da captura de evidência de origem são relatadas como não verificadas e não são incluídas no contexto de tarefa até serem reencenadas com evidência. Um arquivo de origem alterado ou ausente torna memórias vinculadas desatualizadas mesmo antes de agentramen update; atualize o contexto e proponha uma nova memória em vez de tratar silenciosamente um fato antigo como atual. Não sincronize SQLite por um compartilhamento de rede. Para equipes de 100 pessoas, use branches protegidos e revisão normal de solicitação de pull para alterações de memória compartilhada.

MCP centralizado para um grafo compartilhado

O stdio local permanece o padrão. Para publicar um snapshot de grafo imutável para agentes remotos, habilite as dependências centrais opcionais e a entrada de fluxo de trabalho reutilizável:

jobs:
  index:
    uses: palrajjp/agentRamen/.github/workflows/index.yml@main
    with:
      central_snapshot: true
      repository_id: acme/payments-monorepo

O fluxo de trabalho valida o arquivo com agentramen snapshot verify antes de enviar agentramen-snapshot-${{ github.sha }}. Ele contém o grafo fixado, código-fonte indexado verificado por hash que passou na filtragem de credenciais e memórias de equipe commitadas. Memórias SQLite privadas do desenvolvedor e regras de exclusão locais são removidas. Artefatos expiram após 14 dias, então copie snapshots aceitos para armazenamento durável privado da empresa antes da expiração. Se agentramen init gerou .github/workflows/agentramen.yml, faça commit desse arquivo antes de exportar; a exportação de snapshot requer um checkout de origem limpo.

Implante um serviço MCP somente leitura por snapshot de repositório. Ele valida JWTs OIDC da empresa contra JWKS, emissor, público, expiração, escopo e, opcionalmente, reivindicações de grupo; a proteção contra rebinding de DNS requer uma lista de permissões de Host explícita. Termine o TLS em um ingress confiável e mantenha o arquivo e o snapshot montado dentro da infraestrutura controlada pela empresa.

python -m pip install 'agentramen[central]'
export AGENTRAMEN_OIDC_ISSUER="https://login.example.com/tenant/v2.0"
export AGENTRAMEN_OIDC_JWKS_URL="https://login.example.com/tenant/discovery/v2.0/keys"
export AGENTRAMEN_OIDC_AUDIENCE="agentramen-api"
export AGENTRAMEN_OIDC_RESOURCE_URL="https://agentramen.example.com/mcp"
export AGENTRAMEN_OIDC_REQUIRED_SCOPE="agentramen:read"
export AGENTRAMEN_OIDC_ALLOWED_GROUP="engineering"
export AGENTRAMEN_MCP_ALLOWED_HOSTS="agentramen.example.com"
agentramen mcp-http \
  --snapshot-archive /srv/agentramen/current-snapshot.zip \
  --repository-id acme/payments-monorepo \
  --host 0.0.0.0 --port 8000

Configure clientes MCP para usar o endpoint HTTPS /mcp e conclua o fluxo OAuth/OIDC da empresa. Por exemplo, o Claude Code pode adicioná-lo com claude mcp add --transport http agentramen-central https://agentramen.example.com/mcp; o VS Code suporta servidores MCP HTTP remotos. Defina AGENTRAMEN_OIDC_GROUP_CLAIM quando seu IdP usar uma reivindicação de grupo diferente (padrão groups).

Ferramentas remotas são somente leitura: status, contexto, pesquisa, arquitetura, grafo e pesquisa de memória de equipe aprovada. Cada resposta inclui repository_id e snapshot_commit para que agentes possam identificar conselhos desatualizados.

Para atualização de implantação e reversão, mantenha cada arquivo aceito imutável e chaveado pelo SHA do commit. Verifique-o, inicie um serviço candidato contra esse arquivo e chame repo_status com um cliente autorizado para confirmar o commit esperado. Promova alternando atomicamente o ponteiro de ingress/serviço para o candidato; retenha o serviço/arquivo anterior e reverta alternando o ponteiro de volta. Não sobrescreva o arquivo sob um serviço em execução. agentramen mcp-http executa um processo; use o gerenciador de processos/balanceador de carga da sua plataforma e um mount de snapshot somente leitura compartilhado para réplicas. Upload de armazenamento específico de nuvem e alternância de ponteiro são responsabilidades do pipeline de implantação, não incorporadas a este pacote.

Snapshots contêm código-fonte real, mas sanitizado. Heurísticas de credenciais não substituem ACLs de repositório ou revisão de perda de dados; use armazenamento privado controlado pela empresa com retenção e controles de acesso correspondentes ao repositório de origem.

Limitações conhecidas

• A resolução de importação lida com layouts comuns de arquivo e módulo, mas não com todos os aliases de workspace ou sistemas de build específicos de linguagem.
• Resumos de arquitetura e solicitação de pull usam arestas de dependência indexadas; eles não aplicam regras de limite semântico.
• A recuperação semântica calcula similaridade exata em vez de usar um índice de vizinho mais próximo aproximado.
• Contagens de tokens são estimativas aproximadas baseadas em caracteres, a menos que context.tokenizer_model seja configurado com o extra de tokenizador opcional.
• O histórico mantém 100 commits por padrão, configurável de 1 a 100.000.

Desenvolvimento

python -m unittest discover -s tests -v
python -m agentramen.cli status --json

Se o agentRamen for útil no seu fluxo de trabalho, uma estrela no GitHub ajuda outros desenvolvedores a encontrá-lo. Veja CONTRIBUTING.md, SECURITY.md e CODE_OF_CONDUCT.md. Contribuições que adicionam analisadores de linguagem devem manter o comportamento específico do parser separado das interfaces de indexação e contexto.