agentRamen MCP

Inteligencia de código local-primero y contexto de tareas para agentes de codificación, vía CLI, MCP y HTTP local.

Documentación

agentRamen

Con licencia Apache-2.0. Consulta la política de seguridad y el código de conducta de la comunidad.

agentRamen indexa la estructura del código fuente y el historial de Git, y luego recupera archivos y fragmentos relevantes para la tarea. Es local-primero por defecto: cada desarrollador mantiene un índice SQLite privado. Los equipos pueden publicar opcionalmente instantáneas sanitizadas y ancladas a commits en un servicio MCP centralizado, protegido por OIDC y de solo lectura.

Inicio rápido

Instala agentRamen y luego ejecútalo desde el repositorio que quieras explorar:

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

agentramen init crea la configuración, indexa el repositorio y ofrece un flujo de trabajo opcional de GitHub Actions. El índice se almacena localmente en .agentramen/graph.db.

Pruébalo en 30 segundos con examples/demo.sh. Consulta la hoja de ruta y la guía de contribución.

También está disponible una extensión mínima para VS Code.

Qué puede hacer

Encontrar contexto de tarea: clasifica archivos usando rutas, símbolos, importaciones, historial de Git y similitud semántica local opcional.
Explicar el impacto de los cambios: inspecciona dependencias, dependientes, co-cambios, puntos críticos e historial de archivos.
Mapear la estructura del repositorio: explora la arquitectura, exporta el grafo y consulta instantáneas de commits en caché.
Conectarse a agentes de codificación: usa MCP stdio local, la interfaz de navegador o un servicio MCP centralizado autenticado opcional.
Mantener privados los índices locales: en modo local, la base de datos y las incrustaciones opcionales permanecen en cada checkout; el modo central transfiere solo una instantánea sanitizada explícita a la infraestructura que tú operas.

Cómo 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]

La instalación predeterminada usa la biblioteca estándar de Python y análisis conservador para otros lenguajes. Los extras opcionales añaden análisis Tree-sitter, recuperación semántica local y conteo de tokens consciente del modelo.

Cómo se compara

Proyecto	Estrellas	Enfoque	vs. agentRamen
Serenagithub	~30.1k	Kit de herramientas de recuperación semántica basada en LSP + edición, MCP	Kit de herramientas de agente mucho más amplio y adoptado
Aider's RepoMapgithub	~49.4k	Mapa de repositorio con presupuesto de tokens Tree-sitter + PageRank	Ejemplo establecido de contexto de repositorio clasificado por grafo y con presupuesto de tokens (adyacente: una función dentro de una aplicación de codificación)
Repomixgithub	~28.7k	Empaqueta todo el repositorio en un solo archivo amigable para IA	Flujo de trabajo adyacente: empaquetado de repositorio completo vs. contexto selectivo
code-index-mcpgithub	~1k	AST Tree-sitter para 10 lenguajes, índice persistente, MCP stdio	El servidor de índice independiente estructuralmente más comparable; sin búsqueda semántica ni integración de CI declarada
agentRamen	1	Grafo SQLite, clasificación por historial de Git, MCP+CLI+HTTP+VS Code	Alfa funcional desde el primer día

Extras opcionales

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

La instalación predeterminada no tiene dependencias de ejecución. Tree-sitter, incrustaciones semánticas, tokenizadores y el servicio MCP remoto son opcionales. La configuración del modelo semántico puede descargar pesos en el primer uso; la inferencia se ejecuta localmente.

agentramen init crea .agentramen.yml y un flujo de trabajo de GitHub Actions si no existen, luego crea/actualiza .agentramen/graph.db. agentramen update y agentramen index actualizan incrementalmente los archivos modificados. La base de datos es ignorada por Git.

En modo local, los fragmentos de código fuente y las incrustaciones opcionales permanecen en .agentramen/graph.db. El modo de instantánea central transfiere código fuente indexado que supera las heurísticas de credenciales a tu servicio central privado; revisa los requisitos de manejo de datos de tu organización antes de habilitarlo.

Publicación de versiones

Configura un publicador de confianza de PyPI para palrajjp/agentRamen, usando el flujo de trabajo .github/workflows/publish.yml y el entorno pypi. Para publicar una versión, actualiza la versión en pyproject.toml y agentramen/__init__.py, crea una etiqueta Git con prefijo v que coincida y publica una versión de GitHub para esa etiqueta. El flujo de trabajo compila las distribuciones y las publica en PyPI usando OIDC.

Configuración

agentRamen lee los siguientes 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/

indexing.incremental: false vuelve a analizar cada archivo elegible en cada indexación. git.history: false elimina el historial almacenado de commits, renombramientos y co-cambios; habilitarlo más tarde reconstruye el historial reciente configurado. history.commits controla los commits retenidos (1–100,000) y git.co_changes alterna los bordes de co-cambios. context.default_budget es usado por la CLI, MCP y la API HTTP cuando no se pasa un presupuesto. La configuración es un subconjunto YAML sin dependencias; los valores no admitidos o malformados se rechazan con un error específico de la configuración. Los patrones de .agentramenignore se añaden a las reglas de ignorar integradas y YAML, en lugar de reemplazarlas.

semantic.enabled: true opta por la generación de incrustaciones locales y clasificación de contexto semántico; instala agentramen[semantic] primero. semantic.model selecciona un modelo FastEmbed. agentramen[treesitter] opta por el análisis basado en Tree-sitter para lenguajes no Python compatibles; sin él, o si una gramática no está disponible, agentRamen recurre al análisis por expresiones regulares.

context.tokenizer_model selecciona opcionalmente un modelo compatible con tiktoken para presupuestos de contexto basados en tokenizador; instala agentramen[tokenizer] para usarlo. El vocabulario del tokenizador puede descargarse y almacenarse en caché en el primer uso, luego el conteo se ejecuta localmente. Déjalo vacío para usar el respaldo aproximado basado en caracteres sin dependencias. Las respuestas de contexto identifican token_count_method (tiktoken o approximate) y el modelo del tokenizador cuando está configurado. El total informado presupuesta los archivos seleccionados, memorias del equipo y evidencia de rutas/digest/commits juntos; los conteos por archivo se proporcionan 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

Ejemplo de respuesta 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"
}

El contexto incluye fragmentos de código fuente solo cuando el archivo aún coincide con su hash indexado y no contiene un patrón de credenciales detectado. Los conteos de tokens usan el tokenizador del modelo configurado cuando está disponible; de lo contrario, son estimaciones aproximadas basadas en caracteres, no mediciones del tokenizador ni afirmaciones de rendimiento.

GitHub Actions

El flujo de trabajo creado por agentramen init llama al flujo de trabajo reutilizable en este repositorio:

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

El flujo de trabajo reutilizable obtiene el historial de Git, restaura una caché, prueba el paquete instalado, indexa la revisión verificada, resume las solicitudes de extracción y publica el artefacto SQLite local. Usa un checkout de profundidad completa al ejecutar la CLI fuera de este flujo de trabajo reutilizable para conservar el historial.

Uso desde `gha-cd` u otro flujo de trabajo

Llama al flujo de trabajo reutilizable antes de un despliegue o trabajo de agente. Proporcionar task también crea un artefacto de contexto JSON acotado; el flujo de trabajo no envía contenido del repositorio a un proveedor 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

El artefacto se llama agentramen-context-${{ github.sha }}. Un trabajo posterior puede obtenerlo y pasar .agentramen-context/agentramen-context.json a su paso de agente:

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

El presupuesto de contexto es 2000 por defecto si se omite. Trata el artefacto como código fuente: puede contener fragmentos y sigue la política de acceso y retención de GitHub Actions del repositorio.

Integraciones de agentes

El servidor MCP de agentRamen se ejecuta localmente sobre stdio. Instala agentRamen una vez en cada máquina de desarrollador y luego añade un .mcp.json portátil en la raíz del repositorio para que VS Code Copilot y Claude Code puedan usar la misma configuración:

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

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

Para Claude Code, el comando con ámbito de proyecto crea o actualiza .mcp.json:

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

Para GitHub Copilot CLI, guarda el mismo objeto mcpServers en $COPILOT_HOME/mcp-config.json, o ~/.copilot/mcp-config.json cuando COPILOT_HOME no esté definido. Consulta la guía de configuración de MCP para VS Code y la guía de MCP para Claude Code para la configuración específica del cliente y los avisos de confianza.

En VS Code, confía en el espacio de trabajo e inicia el servidor MCP agentramen desde la vista de Servidores MCP. Cada desarrollador mantiene un .agentramen/graph.db independiente; confirma .agentramen.yml y .mcp.json para configuraciones compartidas, pero no pongas una base de datos SQLite en vivo en un recurso compartido de red.

Mantén el contexto del agente enfocado

Añade una instrucción como esta al AGENTS.md, CLAUDE.md o instrucciones de Copilot del proyecto:

Para análisis de repositorio, llama a repo_context con la tarea actual antes de lecturas amplias de archivos. Comienza con un presupuesto de 1200 tokens, usa las rutas devueltas como límite de investigación, luego llama a repo_explain o repo_impact para seguimiento específico. Expande la búsqueda solo cuando el contexto indexado sea insuficiente. Pide agentramen update si el índice parece desactualizado.

El presupuesto limita el contexto recuperado, no toda la conversación del modelo. Los conteos usan una estimación aproximada basada en caracteres por defecto; instala agentramen[tokenizer] y establece context.tokenizer_model cuando el conteo específico del modelo sea importante. Ejecuta agentramen update para actualizar incrementalmente el índice local de un desarrollador después de cambios.

ChatGPT y GPT Store

Los GPT personalizados no pueden iniciar el proceso stdio local de un desarrollador. Una acción GPT o una aplicación ChatGPT alojada necesita un servicio HTTPS accesible con autenticación. agentramen serve escucha solo en localhost y no tiene autenticación, así que no lo expongas directamente a internet; una integración remota segura requiere una puerta de enlace autenticada o un servicio MCP alojado por separado. La disponibilidad de creación y publicación de GPT depende del plan actual de ChatGPT y la política del espacio de trabajo; consulta la guía de creación de GPT de OpenAI.

MCP

Ejecuta agentramen mcp desde un repositorio y configura tu agente compatible con MCP para lanzar ese comando en el directorio de trabajo del repositorio. Las herramientas incluyen 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 y repo_memory_audit. El servidor stdio no necesita claves de API y no accede a un servicio de red.

API HTTP local

agentramen serve escucha solo en 127.0.0.1 por defecto. La interfaz de navegador está disponible en / y /ui. La API proporciona GET /health, GET /api/v1/repository, /architecture, /graph, /files/{path}, /impact?path=..., /history?path=..., /hotspots y POST /api/v1/context o /api/v1/search. Añade ?at=<commit> a /api/v1/graph o /api/v1/architecture para consultar una instantánea de grafo en caché y direccionable por commit. Las solicitudes POST aceptan objetos JSON como {"task":"Add OAuth","token_budget":2000}. No se proporciona autenticación; no te vincules a una interfaz pública sin colocar una capa de control de acceso autenticada delante.

Evaluación comparativa

Ejecuta agentramen benchmark --files 10 1000 para medir la indexación sintética inicial, una actualización incremental de un archivo y la recuperación de contexto. Agrega --repository /path/to/repo para medir también una copia temporal de los archivos rastreados del árbol de trabajo de un repositorio real. Usa --semantic-mode both para comparar la recuperación semántica desactivada/activada; la ejecución habilitada requiere agentramen[semantic] y descarga su modelo configurado si es necesario. Si la configuración del modelo no está disponible, la comparación informa ese modo como un error y aún así devuelve mediciones para el modo exitoso. La salida incluye el recuento de candidatos léxicos, el tamaño de la base de datos y los tiempos de recuperación/indexación.

Agrega --quality para informar la precisión/recuperación de tarea-a-archivo y pruebas-afectadas en un fixture sintético determinista y etiquetado; test_evidence muestra la cadena de importación utilizada para confirmar cada prueba sugerida:

agentramen benchmark --quality --json

El fixture actual obtiene una precisión y recuperación media de 1.0 tanto para archivos como para pruebas. Esta es una verificación de corrección del fixture, no una afirmación de precisión en un repositorio real. Para decisiones de adopción, selecciona etiquetas de tu propio repositorio y mide esas tareas; todos los tiempos y puntuaciones dependen del repositorio, las etiquetas de tareas y el entorno.

Privacidad y exclusiones

El índice permanece en .agentramen/graph.db en la máquina local o en el artefacto de CI configurado. Con la recuperación semántica desactivada, la base de datos almacena metadatos de origen y hashes; cuando está habilitada, además almacena incrustaciones generadas localmente. agentRamen omite directorios generados comunes, archivos de entorno, archivos de claves privadas, archivos de gran tamaño, archivos binarios y archivos que contienen patrones reconocibles de asignación de claves privadas o credenciales. Agrega más patrones de rutas a .agentramenignore (un patrón por línea). Revisa tus reglas de exclusión antes de publicar artefactos generados.

Recuperación y memoria

La recuperación de contexto utiliza un índice invertido SQLite incremental para candidatos léxicos, luego fusiona clasificaciones léxicas, semánticas opcionales y de grafo/historial con fusión de rango recíproco antes de aplicar el presupuesto de tokens. La memoria revisada puede ser preparada, aprobada o rechazada; aprobar un nuevo hecho reemplaza hechos activos en conflicto con el mismo sujeto.

Compartir memorias aprobadas con un equipo

AgentRamen mantiene la base de datos SQLite en vivo privada para cada checkout. Para compartir un hecho revisado, prepáralo, apruébalo y luego publícalo en .agentramen-shared/memories/<id>.json. Confirma ese archivo en una solicitud de extracción para que los compañeros de equipo puedan revisar los cambios, ver el historial y recibir la actualización a través de Git. Un archivo por memoria evita que adiciones no relacionadas colisionen.

Herramientas MCP: repo_context devuelve la ruta de origen, el digest y la evidencia de confirmación para sus archivos seleccionados. Una llamada posterior a repo_stage_memory adjunta evidencia de la llamada de contexto más reciente a la propuesta pendiente privada; la revisión muestra la evidencia y si sus bytes de origen siguen siendo actuales. La aprobación registra el user.name de Git como revisor (con respaldo al nombre de cuenta local); la publicación preserva ese revisor, la confirmación de origen, los digests y la ventana de validez. La aprobación y la publicación rechazan evidencia modificada. Las memorias aprobadas obsoletas aparecen en la parte superior de repo_review_queue con una acción restage_with_fresh_context; no pueden ser re-aprobadas como actuales. repo_team_memory_search omite memorias compartidas cuya evidencia está obsoleta o falta. repo_memory_audit informa recuentos únicos de memorias obsoletas, rutas no coincidentes, confirmaciones de origen y registros locales/compartidos no verificados sin editar archivos Git compartidos. Los hechos reemplazados se marcan en su archivo existente cuando se publica un hecho aprobado más nuevo con el mismo sujeto. El contenido similar a credenciales se bloquea de la publicación; aún así, revisa el contenido de la memoria en busca de datos confidenciales o personales antes de confirmar. Los agentes nunca deben aprobar o publicar una memoria sin dirección humana explícita.

Búsqueda y publicación CLI:

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

La memoria compartida es opcional y controlada por versiones; las notas rechazadas o simplemente preparadas permanecen locales. Las memorias existentes creadas antes de capturar evidencia de origen se informan como no verificadas y no se incluyen en el contexto de tareas hasta que se vuelvan a preparar con evidencia. Un archivo de origen modificado o faltante hace que las memorias vinculadas queden obsoletas incluso antes de agentramen update; actualiza el contexto y propón una nueva memoria en lugar de tratar silenciosamente un hecho antiguo como actual. No sincronices SQLite a través de un recurso compartido de red. Para equipos de 100 personas, usa ramas protegidas y revisión normal de solicitudes de extracción para cambios de memoria compartida.

MCP centralizado para un grafo compartido

El stdio local sigue siendo el predeterminado. Para publicar una instantánea de grafo inmutable para agentes remotos, habilita las dependencias centrales opcionales y la entrada de flujo de trabajo reutilizable:

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

El flujo de trabajo valida el archivo con agentramen snapshot verify antes de subir agentramen-snapshot-${{ github.sha }}. Contiene el grafo fijado, el código fuente indexado verificado por hash que pasó el filtrado de credenciales y las memorias de equipo confirmadas. Las memorias SQLite privadas del desarrollador y las reglas de exclusión locales se eliminan. Los artefactos caducan después de 14 días, así que copia las instantáneas aceptadas al almacenamiento duradero privado de la empresa antes de la caducidad. Si agentramen init generó .github/workflows/agentramen.yml, confirma ese archivo antes de exportar; la exportación de instantáneas requiere un checkout de origen limpio.

Implementa un servicio MCP de solo lectura por instantánea de repositorio. Valida los JWT OIDC de la empresa contra JWKS, emisor, audiencia, caducidad, alcance y opcionalmente reclamos de grupo; la protección contra el rebinding de DNS requiere una lista de permitidos de Host explícita. Termina TLS en un ingress confiable y mantén el archivo y la instantánea montada dentro de la infraestructura controlada por la 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

Configura los clientes MCP para usar el endpoint HTTPS /mcp y completa el flujo OAuth/OIDC de la empresa. Por ejemplo, Claude Code puede agregarlo con claude mcp add --transport http agentramen-central https://agentramen.example.com/mcp; VS Code admite servidores MCP HTTP remotos. Establece AGENTRAMEN_OIDC_GROUP_CLAIM cuando tu IdP usa un reclamo de grupo diferente (predeterminado groups).

Las herramientas remotas son de solo lectura: estado, contexto, búsqueda, arquitectura, grafo y búsqueda de memoria de equipo aprobada. Cada respuesta incluye repository_id y snapshot_commit para que los agentes puedan identificar consejos obsoletos.

Para la frescura de implementación y el rollback, mantén cada archivo aceptado inmutable y claveado por SHA de confirmación. Verifícalo, inicia un servicio candidato contra ese archivo y llama a repo_status con un cliente autorizado para confirmar la confirmación esperada. Promueve cambiando atómicamente el puntero de ingress/servicio al candidato; conserva el servicio/archivo anterior y revierte cambiando el puntero de vuelta. No sobrescribas el archivo debajo de un servicio en ejecución. agentramen mcp-http ejecuta un proceso; usa el administrador de procesos/balanceador de carga de tu plataforma y un montaje de instantánea de solo lectura compartido para réplicas. La carga de almacenamiento específica de la nube y el cambio de puntero son responsabilidades de la canalización de implementación, no integradas en este paquete.

Las instantáneas contienen código fuente real pero saneado. Los heurísticos de credenciales no son un sustituto de las ACL del repositorio o la revisión de pérdida de datos; usa almacenamiento privado controlado por la empresa con retención y controles de acceso que coincidan con el repositorio de origen.

Limitaciones conocidas

La resolución de importaciones maneja diseños comunes de archivos y módulos, pero no todos los alias de espacio de trabajo o sistemas de compilación específicos de lenguaje.
Los resúmenes de arquitectura y solicitudes de extracción usan bordes de dependencia indexados; no aplican reglas de límites semánticos.
La recuperación semántica calcula similitud exacta en lugar de usar un índice de vecinos más cercanos aproximados.
Los recuentos de tokens son estimaciones aproximadas basadas en caracteres a menos que context.tokenizer_model esté configurado con el extra de tokenizador opcional.
El historial mantiene 100 confirmaciones por defecto, configurable de 1 a 100,000.

Desarrollo

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

Si agentRamen es útil en tu flujo de trabajo, una estrella de GitHub ayuda a otros desarrolladores a encontrarlo. Consulta CONTRIBUTING.md, SECURITY.md y CODE_OF_CONDUCT.md. Las contribuciones que agregan analizadores de lenguaje deben mantener el comportamiento específico del analizador separado de las interfaces de indexación y contexto.