Codevira MCP

Memoria adaptativa persistente para agentes de codificación de IA: aprende de cada sesión, funciona con cada herramienta, recuerda en cada proyecto.

Funciona con: Claude Code · Cursor · Windsurf · Google Antigravity · cualquier herramienta de IA compatible con MCP

El problema

Cada vez que inicias una nueva sesión de codificación con IA, tu agente comienza desde cero.

Vuelve a leer archivos que ya ha visto. Redescubre patrones ya establecidos. Toma decisiones que contradicen las decisiones de la semana pasada. No tiene idea de en qué fase se encuentra el proyecto, qué se ha intentado ya o por qué ciertos archivos están fuera de los límites.

Terminas gastando miles de tokens en redescubrimiento, en cada sesión.

Codevira soluciona esto.

Qué hace

Codevira es un servidor del Protocolo de Contexto de Modelo (MCP) que integras en cualquier proyecto. Proporciona a cada agente de IA que trabaja en tu base de código una memoria compartida y persistente:

El resultado: ~1,400 tokens de sobrecarga por sesión en lugar de más de 15,000 tokens de redescubrimiento.

Cómo funciona

Ciclo de vida de la sesión del agente

flowchart TB

Start([Start Session])

subgraph Orientation
A[Check Open Changesets]
B[Get Project Roadmap]
C[Search Past Decisions]
D[Load Graph Context\nget_node • get_impact]
end

subgraph Execution
E[Plan Task]
F[Implement Code]
G[Run Tests / Validation]
end

subgraph Completion
H[Update Graph Metadata]
I[Write Session Log]
J[Complete Changeset]
end

Start --> A
A --> B
B --> C
C --> D
D --> E
E --> F
F --> G
G --> H
H --> I
I --> J

Modelo de inteligencia de código

flowchart TB

A[Source Code]

subgraph Structural Analysis
B[AST Parser]
C[Function / Class Extraction]
D[Dependency Analysis]
end

subgraph Knowledge Stores
E[(Semantic Index<br/>ChromaDB)]
F[(Context Graph<br/>SQLite DB)]
end

subgraph Runtime Access
G[MCP Query Layer<br/>search_codebase • get_node • get_impact]
end

H[AI Coding Agent<br/>Claude Code • Cursor]

A --> B
B --> C
C --> E

B --> D
D --> F

E --> G
F --> G

G --> H

Inicio rápido

1. Instalar

pip install codevira-mcp

2. Inicializar en tu proyecto

cd your-project
codevira init

Este comando único:

• Crea .codevira/ con directorios de configuración, grafo y registro

• Añade .codevira/ a .gitignore (el índice se regenera automáticamente, no es necesario hacer commit)

• Solicita el nombre del proyecto, el lenguaje, los directorios fuente (separados por comas) y las extensiones de archivo

• Construye el índice completo de código usando hashing de contenido SHA-256 (solo se reindexan los archivos modificados)

• Genera automáticamente stubs de grafo para todos los archivos fuente

• Arranca .codevira/roadmap.yaml desde el historial de git

• Instala un hook de git post-commit para la reindexación automática

• Imprime el bloque de configuración de MCP para pegar en tu herramienta de IA

Auto-observación en vivo: Cuando el servidor MCP se inicia, lanza automáticamente un observador de archivos en segundo plano. Cada vez que guardas un archivo fuente, el índice se actualiza en 2 segundos; no se necesitan comandos manuales. El hook post-commit y la CLI codevira index siguen estando disponibles como alternativas.

3. Conectar a tu herramienta de IA

Dependiendo de tu IDE y entorno, es posible que codevira-mcp no esté automáticamente en tu PATH. Puedes usar uvx (la opción más fácil) o proporcionar la ruta absoluta a tu entorno virtual de Python.

Opción A: Usar uvx (Recomendado para todos los IDEs sin instalación local) Si usas uv, puedes ejecutar el servidor MCP sin problemas sin gestionar entornos virtuales por proyecto.

Claude Code (.claude/settings.json), Cursor / Windsurf (Configuración → MCP):

{
  "mcpServers": {
    "codevira": {
      "command": "uvx",
      "args": ["codevira-mcp", "--project-dir", "/path/to/your-project"]
    }
  }
}

Opción B: Usar Venv local (Recomendado, funciona en todas partes) Señala tu herramienta de IA directamente al tiempo de ejecución de Python dentro de tu .venv donde está instalado codevira-mcp.

Claude Code (.claude/settings.json) o Cursor / Windsurf (Configuración → MCP):

{
  "mcpServers": {
    "codevira": {
      "command": "/path/to/your-project/.venv/bin/python",
      "args": ["-m", "mcp_server", "--project-dir", "/path/to/your-project"]
    }
  }
}

Google Antigravity — añadir a ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "codevira": {
      "$typeName": "exa.cascade_plugins_pb.CascadePluginCommandTemplate",
      "command": "/path/to/your-project/.venv/bin/python",
      "args": ["-m", "mcp_server", "--project-dir", "/path/to/your-project"]
    }
  }
}

⚠️ IMPORTANTE: Uso de clientes globales (Antigravity / Claude Desktop) con múltiples proyectos

A diferencia de Cursor, que inicia servidores MCP aislados por proyecto automáticamente, los clientes globales como Antigravity comparten un único mcp_config.json en todos tus proyectos abiertos.

Si configuras codevira una vez para Proyecto A, y luego haces una pregunta sobre Proyecto B, el agente leerá el grafo y la hoja de ruta del Proyecto A.

Para solucionar esto: Debes registrar servidores con nombres únicos para cada proyecto en tu configuración global. La IA elegirá dinámicamente el prefijo de herramienta correcto según el contexto de tu conversación:

{
  "mcpServers": {
    "codevira-project-a": {
      "$typeName": "exa.cascade_plugins_pb.CascadePluginCommandTemplate",
      "command": "uvx",
      "args": ["codevira-mcp", "--project-dir", "/path/to/project-a"]
    },
    "codevira-project-b": {
      "$typeName": "exa.cascade_plugins_pb.CascadePluginCommandTemplate",
      "command": "uvx",
      "args": ["codevira-mcp", "--project-dir", "/path/to/project-b"]
    }
  }
}

4. Verificar

Pide a tu agente que llame a get_roadmap(): debería devolver tu fase actual y la siguiente acción.

Estructura del proyecto después de la inicialización

your-project/
├── src/                   ← your code (indexed)
├── .codevira/             ← Codevira data directory (git-ignored)
│   ├── config.yaml        ← project configuration
│   ├── roadmap.yaml       ← project roadmap (auto-generated, human-enrichable)
│   ├── codeindex/         ← ChromaDB index (auto-regenerated)
│   └── graph/             ← context graph and session memory
│       ├── graph.db       ← SQLite database for nodes, edges, logs, and decisions
│       └── changesets/    ← active multi-file change records
└── requirements.txt       ← add: codevira-mcp>=1.0.0

Ciclo de vida de la hoja de ruta: La hoja de ruta se genera automáticamente durante la inicialización y es actualizada por el agente a través de llamadas a herramientas MCP. Consulta docs/roadmap.md para obtener la guía completa del ciclo de vida, pasos de edición manual y solución de problemas.

Protocolo de sesión

Cada sesión de agente sigue un protocolo simple. Configúralo una vez en el prompt del sistema de tu agente, y tus agentes se encargarán del resto.

Inicio de sesión (obligatorio):

list_open_changesets()      → resume any unfinished work first
get_roadmap()               → current phase, next action
search_decisions("topic")   → check what's already been decided
get_node("src/service.py")  → read rules before touching a file
get_impact("src/service.py") → check blast radius

Fin de sesión (obligatorio):

complete_changeset(id, decisions=[...])
update_node(file_path, changes)
update_next_action("what the next agent should do")
write_session_log(...)

Este bucle mantiene cada sesión rápida, enfocada y reanudable.

33 Herramientas MCP

Herramientas de grafo

Herramientas de hoja de ruta

Herramientas de conjuntos de cambios

Herramientas de búsqueda

Herramientas de aprendizaje adaptativo (v1.4)

Herramientas de lectura de código

Herramienta de libro de jugadas

Personas de agente

Siete definiciones de roles en agents/ dicen a cada agente exactamente qué hacer y cuándo:

Estructura del proyecto

.agents/
├── PROTOCOL.md              # Session protocol — read this first
├── config.example.yaml      # Config template
├── config.yaml              # Your config (git-ignored)
├── roadmap.yaml             # Phase tracker (auto-created, git-ignored)
├── mcp-server/
│   ├── server.py            # MCP server entry point
│   └── tools/
│       ├── graph.py
│       ├── roadmap.py
│       ├── changesets.py
│       ├── search.py
│       ├── playbook.py
│       └── code_reader.py
├── indexer/
│   ├── index_codebase.py    # Build/update ChromaDB index + background file watcher
│   ├── chunker.py           # AST-based code chunker
│   ├── treesitter_parser.py # Multi-language AST parsing (16+ languages)
│   ├── sqlite_graph.py      # SQLite graph database backend
│   └── graph_generator.py   # Auto-generate graph stubs
├── requirements.txt         # Python dependencies
├── agents/                  # Role definitions
│   ├── orchestrator.md
│   ├── planner.md
│   ├── developer.md
│   ├── reviewer.md
│   ├── tester.md
│   ├── builder.md
│   └── documenter.md
├── rules/                   # Engineering standards
│   ├── master_rule.md
│   ├── coding-standards.md
│   ├── testing-standards.md
│   └── ...13 more
├── graph/
│   ├── graph.db             # SQLite Context Graph and Session Memory (git-ignored)
│   └── changesets/
├── hooks/
│   └── install-hooks.sh
└── codeindex/               # ChromaDB files (git-ignored)

Soporte de idiomas

Toda la gestión de sesiones, el grafo, la hoja de ruta y las funciones de búsqueda funcionan para cualquier idioma. El análisis y la extracción de código (búsqueda, generación de grafos, lecturas de firmas) están impulsados por integraciones robustas de AST y Tree-Sitter.

Requisitos

• Python 3.10+

• ChromaDB

• sentence-transformers

• PyYAML

pip install -r .agents/requirements.txt

Antecedentes

¿Quieres entender la historia completa detrás de por qué se construyó esto, las decisiones de diseño, qué no funcionó y cómo se compara con otras herramientas en el ecosistema?

Lee el artículo completo: Cómo redujimos el uso de tokens de agentes de codificación de IA en un 92%

Contribuyendo

Las contribuciones son bienvenidas: este es un proyecto de código abierto en etapa inicial y hay mucho espacio para crecer.

Lee CONTRIBUTING.md para la guía completa: bifurcación, nombres de ramas, formato de commit y proceso de PR.

Buenas áreas iniciales:

• Exportaciones de visualización de grafos (Dot/Mermaid)

• Entradas adicionales de libro de jugadas para tipos de tareas comunes

• Guías de configuración específicas para IDE

• Informes de errores y correcciones de casos extremos

¿Informar un error? → Abrir un informe de error

¿Solicitar una función? → [Abrir una solicitud de función](https://github.com/sachinshelke/codevira