CodeGraph

Synaptic

Synaptic es una plataforma de mantenimiento de código basada en el código fuente, construida alrededor de tres sistemas conectados: mantenimiento de API, memoria de repositorio y un grafo de conocimiento persistente. Juntos permiten que un ingeniero o asistente de IA entienda lo que hace el código, recuerde lo que le ha sucedido y realice reparaciones acotadas sin adivinar.

1. Mantenimiento de API mantiene las dependencias externas y los SDK seguros de modificar. Los bots de dependencias pueden decirte que existe una nueva versión; Synaptic inventaría las APIs que tu código realmente usa, detecta cambios incompatibles basados en el código fuente, encuentra los sitios de llamada afectados, planifica una reparación acotada en un árbol de trabajo aislado, verifica invariantes del grafo y pruebas seleccionadas, y solo publica un borrador de PR cuando la evidencia está completa.
2. Memoria de repositorio preserva la historia que normalmente vive en personas, chats, ramas fallidas, notas de incidentes y PRs antiguos. Registra cambios previos, regresiones, decisiones, procedimientos, resultados de verificación y artefactos externos como evidencia vinculada al código fuente, y luego recupera esa memoria a través de la CLI o el servidor MCP para que el trabajo futuro comience con contexto en lugar de arqueología.
3. El grafo de conocimiento es el mapa estructural que subyace a todo. Synaptic convierte cualquier carpeta, monorepo o conjunto federado de repositorios en un grafo persistente y consultable de símbolos, archivos, recursos, llamadas, importaciones, herencia, uso de SQL, peligros de despacho dinámico y aristas entre repositorios en más de 30 lenguajes con tree-sitter.

El grafo responde preguntas arquitectónicas, traza impacto inverso ("¿qué rompería este cambio?"), pronostica y ejecuta especulativamente cambios antes de que los hagas, planifica refactorizaciones seguras, compara la arquitectura a través del historial de git y audita SQL en busca de rendimiento y seguridad. La memoria añade lo que el grafo no puede inferir solo del árbol actual. El mantenimiento de API usa ambos para convertir cambios ascendentes en planes de reparación respaldados por evidencia. El motor y el flujo de trabajo de terminal se distribuyen como un único binario estático de Rust (synaptic) sin tiempo de ejecución ni intérprete. Un complemento nativo opcional de synaptic-ui proporciona una vista visual de repositorio único, federación de espacios de trabajo y configuración de MCP, además de una vista de Herramientas buscable para cada tarea de Synaptic en Windows, Linux y macOS. Synaptic escribe grafos legibles por máquina junto con informes legibles por humanos y visualizaciones 2D/3D/SVG, y expone un servidor MCP para que un asistente de codificación con IA pueda usar estos sistemas antes de hacer grep o leer archivos.

Explorador de arquitectura

Convierte un graph.json existente en un mapa de arquitectura autónomo y sin conexión:

synaptic chart

La vista general clasifica comunidades basadas en el código fuente y sus relaciones exactas más fuertes. Busca, cambia de tema o abre cualquier subsistema sin reconstruir el grafo.

Dentro de un subsistema, selecciona un símbolo para aislar sus dependencias reales de un solo salto. El inspector muestra relaciones entrantes y salientes, y cada fila continúa directamente al símbolo conectado.

La pantalla App de la aplicación de escritorio verifica la Release de GitHub publicada por el flujo de trabajo de lanzamiento, descarga el archivo correspondiente, verifica su checksum publicado y actualiza los ejecutables incluidos. Añadir a aplicaciones la instala para el usuario actual y la hace buscable desde Inicio de Windows, Aplicaciones de macOS o el menú de aplicaciones de Linux sin acceso de administrador. Eliminar la instalación de escritorio no afecta los datos del proyecto, grafos, configuraciones ni una CLI instalada por separado.

La aplicación de escritorio sigue la preferencia de claro u oscuro del sistema operativo en el primer inicio y guarda la elección del usuario después.

Si alguien descarga solo synaptic-ui, su pantalla de primer inicio descarga automáticamente las herramientas de comando verificadas desde la última Release de GitHub y las coloca junto a la aplicación. No se requiere terminal, cambio de PATH ni instalación en todo el sistema.

Si no quieres ejecutar el servidor MCP tú mismo, Synaptic Cloud es un servicio MCP alojado de pago para usar Synaptic con tus proyectos: synapticgraph.com. Para sincronización de grafos activada por commits y reparaciones verificadas de API o dependencias en borrador, sigue la guía de automatización de GitHub.

Usar Synaptic con un proyecto

Comienza desde la raíz de cualquier repositorio. Synaptic escribe su índice e informes en synaptic-out/ y mantiene la configuración específica del proyecto en .synaptic/.

La forma más fácil es pedirle a tu agente de codificación con IA que instale y configure Synaptic para el repositorio actual, y luego que siga las guías de Instalación, Inicio rápido e Integración con asistentes. Si prefieres hacerlo tú mismo, el camino manual es:

# 1. Install the binary from this repository
cargo install --path bin/synaptic

# Or download a prebuilt binary from GitHub Releases, then confirm it works
synaptic --version

# Optional: install and launch the native setup UI
cargo install --path bin/synaptic-ui
synaptic-ui

# 2. Build the first graph for your project
cd path/to/your/project
synaptic extract .

# 3. Ask structural questions without rereading the whole codebase
synaptic query "authentication flow"
synaptic affected parse_config
synaptic search --pattern god-class

# 4. Keep the graph current as the project changes
synaptic update
synaptic watch
synaptic hook install

Para una configuración normal de proyecto, añade un .synapticignore si hay rutas generadas, de proveedores o sensibles que no quieras indexar; extract también respeta .gitignore y omite secretos comunes como .env y archivos de claves. Usa synaptic hook install cuando quieras que los commits de Git, checkouts y fusiones de grafos mantengan synaptic-out/graph.json actualizado automáticamente.

Una vez que el grafo existe, activa los sistemas de nivel superior según sea necesario:

# Repository memory: ingest history, docs, decisions, and outcomes
synaptic memory refresh --root .
synaptic memory search "previous auth migration"

# API maintenance: configure monitored APIs and check real usage
synaptic api init
synaptic api discover --json
synaptic api coverage --json
synaptic api scan --offline --json

# AI assistant integration: serve the graph and memory over MCP
synaptic serve
synaptic install codex --global

El modelo mental más seguro: ejecuta extract primero, usa query / affected / search para explorar, añade hooks o watch cuando el proyecto esté activo, y luego habilita los flujos de trabajo de memory y api cuando quieras que Synaptic preserve la historia o mantenga contratos externos.

---

Por qué

• Claridad estructural. Nodos dios, conexiones sorprendentes entre módulos, ciclos de importación y estructura de comunidades se calculan por ti.
• Impacto y previsión. Impacto inverso, pronóstico de cambios y ejecuciones especulativas de pruebas responden "¿qué depende de esto?" y "¿qué rompería este cambio?" antes de tocar el código.
• Economía de tokens. Consultar un grafo compacto cuesta una fracción de alimentar archivos crudos a un LLM, por lo que un asistente puede responder esas preguntas sin cargar el repositorio.
• Confianza auditable. Cada relación inferida está etiquetada como EXTRACTED, INFERRED o AMBIGUOUS.
• Escala más allá de un repositorio. Un espacio de trabajo puede federar muchos repositorios con resolución real de aristas entre repositorios (superficies exportadas más alias de importación / tsconfig / module-federation).
• Sin conexión por defecto. Un corpus solo de código nunca hace una llamada de red. El paso semántico opcional sobre documentación y artículos es la única función que necesita una clave de API.

Destacados

• Más de 30 lenguajes mediante tree-sitter, cada uno compilado y probado de forma aislada en CI, además de extractores basados en regex para algunos formatos y extracción de scripts para Vue/Svelte/Astro y Razor/Blazor. Ver Languages.
• Un solo comando para un grafo completo más visualizaciones 2D, 3D y SVG, un informe Markdown y exportaciones GraphML / Cypher / DOT / Obsidian / wiki. Ver Output Formats.
• Consultas de grafo: búsqueda de subgrafo relevante, camino más corto, explicación de nodo, impacto inverso ("qué depende de esto"), búsqueda de todas las referencias (synaptic references / la herramienta find_references: todos los lugares donde se usa un símbolo, incluidos los imports y la herencia que una vista solo de llamadores pasa por alto), y esquemas de símbolos por archivo. Ver Querying.
• Conciencia de despacho dinámico: buses de eventos (Node EventEmitter, DOM CustomEvent, eventos de C#) e IPC de Electron enlazan un publicador con su suscriptor a través de un nodo de canal, de modo que un manejador alcanzado solo a través del bus no es un fantasma con 0 llamadores. La reflexión y el despacho dinámico que no se pueden resolver estáticamente (búsquedas por nombre, tablas de despacho, eval, import dinámico, reflexión .NET/Python/JVM) se catalogan para que una respuesta de "0 dependientes" nunca se confunda con "seguro de cambiar": synaptic hazards (y la herramienta MCP dynamic_hazards) enumeran los sitios, y affected adjunta una advertencia cuando un símbolo solo es alcanzable dinámicamente.
• Diff con viaje en el tiempo: synaptic diff <rev1> [rev2] (o --since <date>) informa cómo cambió el grafo entre dos revisiones de git, dependencias añadidas/eliminadas, APIs eliminadas, deriva arquitectónica, nuevos ciclos y puntos calientes, con un informe Markdown o HTML autocontenido.
• Búsqueda arquitectónica (SYNQL): synaptic search ejecuta un pequeño lenguaje de consulta inspirado en Cypher sobre el grafo, haciendo coincidir estructura (tipo, visibilidad, LOC, fan-in/out, caminos de longitud variable) con agregación count(...), --explain, consultas guardadas y una biblioteca de patrones nombrados (singleton, factory, observer, service-locator, god-class). No es búsqueda de texto. synaptic search --file <path> enumera cada símbolo definido en un archivo, ordenado por línea, sin necesidad de consulta.
• Refactor seguro: synaptic refactor rename / move / extract emiten un plan de ejecución con puntuación de confianza (plan.json + plan.md) para que un agente de IA lo aplique, luego refactor verify reconstruye y verifica que el grafo se mantuvo (la definición se movió/renombró, no se perdieron referencias, no hay nuevos ciclos). Synaptic nunca edita el código fuente por sí mismo.
• Pronóstico de cambios y ejecución especulativa: synaptic predict pronostica el radio de explosión de un cambio, las APIs públicas en riesgo, las pruebas en riesgo, los nuevos ciclos, la puntuación de riesgo y una lista de verificación antes de editar (--edit "<kind>:<symbol>" pronostica un cambio descrito antes de escribir cualquier código); synaptic speculate luego aplica el cambio en un worktree de git desechable y realmente ejecuta las pruebas en riesgo más una compilación/verificación de tipos, informando aprobado/fallido real: la mitad de verdad fundamental de la predicción; y synaptic eval replay reproduce el historial para puntuar la calidad del pronóstico contra la verdad fundamental de git (pruebas coeditadas, APIs eliminadas), convirtiendo la precisión de la predicción en una métrica comprobable en CI. Ver Commands.
• Auditoría de rendimiento y seguridad SQL: synaptic sql audit señala brechas de seguridad a nivel de fila, concesiones demasiado amplias, posible inyección SQL, índices faltantes en columnas de filtro/clave foránea, SELECT *, predicados no sargables, patrones N+1 y claves primarias faltantes sobre el grafo consciente de SQL (la extracción ahora modela columnas, índices, políticas RLS y concesiones, y enlaza las consultas de la aplicación con las tablas que tocan). synaptic sql advise --query "<sql>" critica una consulta candidata antes de que la escribas, referenciada de forma cruzada con las tablas/índices/RLS del grafo. Ver SQL Auditing.
• Grafo de recursos (universal, activado por defecto): los archivos de datos/recursos (JSON de datos y .mcmeta bajo assets/, data/ y directorios generados) se indexan como nodos del grafo, y las cadenas similares a referencias dentro de ellos se vinculan al archivo, recurso (por id derivado de la ruta como ns:path) o símbolo de código que nombran, de modo que affected y query_graph abarcan código y recursos. Un recurso generado que duplica uno creado a mano en la misma ruta lógica recibe un borde shadows (superficie por readiness_audit). Agnóstico al framework: un ResourceLocation de Minecraft es solo una instancia de la forma de id lógico. El JSON de localización también contribuye con un conjunto acotado de alias de búsqueda solo de claves (nunca prosa traducida), de modo que los catálogos de mensajes sean descubribles sin un nodo de grafo por traducción. extract --no-resources restaura el grafo solo de código.
• Auditoría de puerto/disponibilidad: synaptic audit readiness clasifica los posibles bloqueadores de puerto a partir de señales del grafo, fuente y configuración: retornos centinela de framework, marcadores de posición/stubs, ruido de recursos generados y metadatos del proyecto. La herramienta MCP readiness_audit expone el mismo informe estructurado.
• Servidor MCP (protocolo sin estado 2026-07-28 con compatibilidad heredada hasta 2025-11-25) que expone 30 herramientas principales, cinco herramientas de vulnerabilidad y cinco herramientas de memoria de repositorio de solo lectura sobre stdio o HTTP: búsqueda de subgrafo, lectura de fuente, impacto inverso, búsqueda de todas las referencias, peligros de despacho dinámico, radio de explosión de PR/árbol de trabajo, pronóstico de cambios, selección predictiva de pruebas, predicción de impacto de edición, búsqueda estructural, diff con viaje en el tiempo, renombrado solo de plan y auditoría/asesoría SQL, además de prompts, completions, suscripciones de recursos y salida de herramientas estructurada. Ver MCP Server.
• Memoria de repositorio basada en fuente: una superposición temporal para cambios anteriores, intentos fallidos, regresiones, decisiones, procedimientos, verificación, artefactos externos de issue/PR/CI/incidente, resúmenes semánticos de comunidad y linaje de archivos/símbolos consciente de revisión. Los ganchos de git capturan commits exactos y actualizan el conocimiento; la política principal, los almacenes compactos/federados, los paquetes de equipo con suma de verificación, los benchmarks de recuperación y la evidencia de impacto agregada están integrados en la CLI y la superficie MCP. Ver Repository Memory.
• Flujos de trabajo de API automantenidos: synaptic api inventaría versiones de SDK, descubre contratos, registra brechas de cobertura, detecta cambios disruptivos basados en fuente, localiza sitios de llamadas afectados y prepara reparaciones acotadas en un worktree aislado. La verificación falla de forma cerrada ante evidencia incompleta, y solo la etapa explícita publish puede crear o actualizar un PR de borrador idempotente. Ver API maintenance.
• Gestión de vulnerabilidades de dependencias: synaptic vuln lee cada lockfile en un repositorio en 12 ecosistemas de paquetes, compara las versiones resueltas contra un corpus OSV y decide si cada aviso realmente aplica aquí en lugar de detenerse en una coincidencia de versión. Los hallazgos llevan una escalera de evidencia, una ruta de dependencia, una prioridad derivada de CVSS, sitios de llamadas respaldados por grafo y exposición de puntos de entrada, y un plan de remediación; los hallazgos aplicables con un objetivo corregido pueden convertirse en reparaciones acotadas y aisladas cuya resolución de dependencia parcheada y pruebas de repositorio deben pasar antes de que Synaptic pueda crear un PR de GitHub o MR de GitLab de borrador determinista. La exportación/importación con suma de verificación mantiene separadas las credenciales de reparación y proveedor, y Synaptic nunca aprueba ni fusiona. Los riesgos aceptados tienen límite de tiempo y expiran por sí solos. Cinco herramientas MCP permiten a los asistentes verificar paquetes, ejecutar un escaneo respaldado por grafo, inspeccionar evidencia de exposición y solicitar una transferencia de reparación acotada. Los escaneos de todo el repositorio permanecen locales por defecto; un agente debe optar por participar antes de que la lista de dependencias se envíe a OSV. Ver Vulnerability Management.
• Reconstrucciones incrementales, vigilancia de archivos y ganchos de git mantienen el grafo actualizado. Ver Incremental Updates.
• Panel de PR consciente del grafo con detección de radio de explosión y conflictos de orden de fusión. Ver PR Dashboard.

---

Economía de tokens

Un beneficio central de consultar un grafo compacto es leer una respuesta pequeña en lugar de todo el código fuente. query_graph por defecto devuelve una lista concisa y clasificada de los símbolos más relevantes (unos pocos cientos de tokens); pasa full=true para el subgrafo completo con sus bordes. Las cifras a continuación miden una respuesta de subgrafo completa (con un presupuesto de 2,000 tokens) en el propio código fuente de Synaptic (199 archivos Rust, 56,408 líneas, 510,966 tokens cl100k): una de esas respuestas a una pregunta estructural es ~1,950 tokens, frente a leer los archivos fuente que realmente toca:

En seis preguntas que abarcan diferentes subsistemas, consultar el grafo usó 27-38x menos tokens (aproximadamente 31x en general) que leer los archivos a los que la respuesta hace referencia:

Pregunta	Respuesta de consulta	Leer los archivos	Menos tokens
manejo de solicitudes http	1,804	48,803	27x
creación/recolección de sesión	1,974	65,578	33x
subgrafo query_graph	2,011	53,759	27x
caminante de extracción	1,977	70,443	36x
obtención/clasificación de PR	1,926	73,231	38x
fusión incremental	2,010	53,440	27x

Una respuesta de consulta permanece pequeña sin importar cuán grande sea el repositorio (está limitada por el presupuesto de tokens), por lo que la proporción crece con el código base. Ten en cuenta que el índice graph.json en sí es grande porque codifica cada símbolo y borde; nunca lo cargas en el contexto, lo consultas y obtienes solo la porción anterior.

Reproducible. Los tokens son conteos exactos de cl100k_base mediante cargo run -p synaptic-server --example tokcount. La línea base son los archivos fuente únicos referenciados por el resultado (archivos completos, el caso conservador de grep-y-luego-leer; no cuenta los archivos sin salida que abrirías sin el grafo). Ejecuta synaptic extract . en cualquier repositorio y compara por ti mismo. Esta es una medición de compresión de contexto, no una afirmación de ahorro de agente de extremo a extremo; la metodología emparejada SWE-bench/BEIR está en BENCHMARKS.md.

Rendimiento de herramientas avanzadas

Las herramientas de análisis responden en milisegundos porque se ejecutan sobre el grafo en memoria, no sobre la fuente. Micro-benchmarks de Criterion (máquina de desarrollo; ejecuta cargo bench -p synaptic-synql -p synaptic-refactor):

Operación	Carga de trabajo	Tiempo
Consulta de propiedad SYNQL (search)	WHERE/loc/fan_out sobre un grafo de 2,000 nodos	~0.47 ms
Unión de patrón de relación SYNQL (search)	unión de un salto sobre un grafo de 2,000 nodos	~0.97 ms
Plan de renombrado de refactor seguro (refactor rename)	símbolo caliente, ~120 sitios de llamadas en 40 archivos, incl. el escaneo textual	~4.9 ms

La auditoría de la tubería de grafo 0.6.3 agregó cobertura dedicada de Criterion para construcción, comparación incremental y federación (cargo bench -p synaptic-graph -p synaptic-incremental -p synaptic-workspace). En los fixtures de auditoría, la federación de una pasada de 16 x 500 nodos midió 136.1 -> 6.07 ms, una comparación de topología de 10k nodos 54.92 -> 9.77 ms, y un borde duplicado de 1,000 sitios 240.74 -> 0.56 ms. Estos son micro-benchmarks dependientes de la máquina; los fixtures comprometidos y las curvas de crecimiento son la evidencia reproducible.

El diff de viaje en el tiempo está limitado por la compilación, no por la consulta: el delta del grafo en sí es casi instantáneo, y el costo es compilar cada revisión en un worktree de git desechable. Los grafos compilados se almacenan en caché por SHA de commit bajo synaptic-out/history/, por lo que un diff repetido de los mismos commits regresa inmediatamente y solo se reconstruye el lado del árbol de trabajo.

Precisión

El estudio de tokens anterior es una prueba de humo en un repositorio. Las relaciones que Synaptic extrae se validan por separado, contra un corpus etiquetado a mano de mini-repositorios cuyos bordes de llamadas reales, enlaces de pruebas, radios de explosión (incluyendo nodos de distracción que no deben marcarse), y acoplamientos entre lenguajes (incluyendo imitaciones que no deben conectarse) están escritos a mano en un ground_truth.toml. Una verificación previa falla la ejecución si algún símbolo etiquetado no se resuelve, por lo que un nodo eliminado se convierte en un fallo ruidoso en lugar de un denominador más pequeño silencioso. Cada número a continuación es una comparación exacta de conjuntos contra esas etiquetas, reproducible con synaptic eval corpus:

Fixture	Familia	Llamadas P/R/F1	Rec. pruebas afectadas	Rec. explosión / excl. / tamaño	Cruzado P/R/F1
systems-rust	systems-rust	100/50/66	—	100% / 100% / 1.0	—
scripting-python	scripting-python	100/100/100	100%	100% / 100% / 2.0	—
web-ts	web-ts	100/100/100	—	100% / 100% / 1.0	—
oo-java	oo-java	100/100/100	—	100% / 100% / 1.0	—
systems-go	systems-go	100/100/100	—	100% / 100% / 1.0	—
deep-python (multi-salto)	scripting-python	100/100/100	100%	100% / 100% / 3.0	—
cross-lang-ts-rust	cross-lang	—	—	—	100/100/100
cross-lang-grpc	cross-lang	—	—	—	100/100/100
cross-lang-queue	cross-lang	100/100/100	—	—	100/100/100
cross-lang-pyo3	cross-lang	100/100/100	—	—	100/100/100
cross-lang-ws	cross-lang	100/100/100	—	—	100/100/100

En 11 fixtures / 6 familias de lenguajes / 42 símbolos etiquetados (todos resueltos): bordes de llamadas agrupados precisión 100% / recuperación 94% / F1 97% sobre 18 bordes etiquetados; radio de explosión recuperación 100% con 0 distractores filtrados; pruebas afectadas recuperación 100% sobre los enlaces etiquetados con la única prueba etiquetada como no relacionada correctamente no seleccionada; entre lenguajes precisión 100% / recuperación 100% / F1 100% sobre 6 acoplamientos etiquetados con 6 acoplamientos de distracción (rutas imitadoras, un stub gRPC de servicio incorrecto, un helper PyO3 no registrado, ...) correctamente no conectados. Leyendo los números honestamente:

• No se observaron bordes de llamadas falsos en este corpus de 18 bordes (precisión 100%); eso es un resultado en el corpus, no una garantía a escala.
• La recuperación es 100% para Python/TypeScript/Java/Go, que resuelven llamadas entre archivos. El 50% en Rust es real y esperado: la resolución de llamadas en Rust es dentro del archivo, por lo que una llamada entre archivos calificada por módulo es una omisión real. La alcanzabilidad entre archivos aún se preserva a través de bordes imports, por lo que la recuperación del radio de explosión se mantiene en 100%.
• El radio de explosión se puntúa por ruido, no solo por omisiones: cada semilla etiqueta nodos de distracción que deben permanecer fuera, y ninguno se filtró (exclusión 100%); el tamaño promedio del conjunto de impacto reportado es igual al tamaño real del conjunto afectado, por lo que el recorrido no es demasiado amplio.
• La selección de pruebas afectadas es de múltiples saltos: el fixture deep-python cambia una hoja a tres saltos de llamada por debajo de su prueba y aún así la selecciona, mientras que una prueba deliberadamente no relacionada se excluye (por lo que la recuperación no se compra con precisión).
• La precisión entre lenguajes se gana en cinco tipos de límites: un fetch("/session") de TypeScript se conecta al manejador axum de Rust que lo sirve (y un cliente /api/users montado alcanza su ruta compuesta por prefijo); un cliente gRPC de Python alcanza su servidor tonic; un productor de Kafka alcanza su consumidor; un import de Python alcanza su función de Rust exportada por PyO3; un comando WebSocket de JS alcanza su manejador de C# — mientras que cada distractor imitador (una ruta /sessions, un stub de servicio incorrecto, un tema incorrecto, un helper PyO3 no registrado, un mensaje no manejado) se deja correctamente sin conectar.

El corpus es intencionalmente pequeño y verificado a mano; valida la corrección de la extracción en formas representativas, no la cobertura a escala de internet. La sección de escala mide repositorios reales. Consulte BENCHMARKS.md para la metodología y el formato de verdad fundamental.

Calibración de predicciones

La capa de pronóstico de cambios adjunta una confianza a cada co-cambio predicho. synaptic eval calibrate mide si esa confianza es significativa: recorre el historial reciente, y para cada commit usa cada archivo cambiado como semilla, le pide al predictor (entrenado solo en commits anteriores) qué archivos deberían co-cambiar, luego puntúa la confianza de cada predicción contra lo que realmente cambió. Reporta una tabla de confiabilidad (tasa de aciertos predicha vs. observada por contenedor de confianza), una puntuación de Brier, la puntuación de habilidad de Brier contra una línea base de siempre-adivinar-la-tasa-base (para que el número de Brier sea interpretable), y el error de calibración esperado.

Esta es una propiedad por repositorio: la confianza refleja los hábitos de commits de cada repositorio, así que ejecútelo en el suyo. En el historial propio de este repositorio (con muchos squashes, sintético) la puntuación de habilidad es negativa — la predicción de co-cambios allí es peor que adivinar la tasa base, porque los commits con squash tocan muchos archivos a la vez e inflan el co-cambio aparente. Eso es la métrica funcionando: se niega a disfrazar un predictor que está mal calibrado en este historial. Metodología en BENCHMARKS.md.

Escala

Rendimiento de extracción en repositorios OSS reales que abarcan niveles de tamaño y familias de lenguajes, cada uno clonado en un SHA fijado (synaptic eval scale; red + git, opcional). Cada tiempo es la mediana de 5 repeticiones. La ejecución del 2026-08-12 cubrió 10 repositorios, 9 familias de lenguajes, 783,928 LOC compatibles, 71,437 nodos y 111,851 bordes sin omisiones. El rendimiento en caliente varió de 44k a 339k LOC/s; la aceleración mediana de frío a caliente varió de 1.4x a 2.8x. El checkout más grande medido aquí, Humanizer (476,967 LOC compatibles), tomó 7.07s en frío y 2.69s en caliente.

Esos son resultados de árbol de trabajo de desarrollo específicos de la máquina, no afirmaciones universales o de versión limpia. "Frío" limpia el caché de AST de Synaptic pero el checkout y el caché de archivos del sistema operativo estaban calientes; el tiempo incremental re-extrae un archivo fuente nombrado sin cambios y no es latencia de parche. Método completo, resultados por repositorio, limitaciones, SHAs exactos y muestras crudas están en BENCHMARKS.md.

Calidad de extracción a escala

La escala mide qué tan rápido corre la extracción; un grafo que anclara cada declaración a la línea incorrecta publicaría tiempos idénticos. synaptic eval quality mide si el grafo es correcto, en 60 repositorios fijados que cubren los 39 lenguajes incluidos (80,061 archivos, 938,001 nodos), usando propiedades que no necesitan etiquetas manuales: exactitud de anclaje, salud de análisis y recuperación, determinismo, equivalencia incremental y una comparación independiente con universal-ctags.

La ejecución del 2026-08-15: exactitud de anclaje agrupada 735,198 / 735,493 (99.96%), con 60/60 repositorios deterministas e incrementalmente equivalentes y sin omisiones. 30 de 39 lenguajes son exactos en cada declaración verificada.

El corpus es completo en lenguajes por construcción — una prueba falla cuando un extractor incluido no tiene repositorio que lo ejercite — y cada repositorio lleva límites fijados, por lo que una regresión sale con código de salida distinto de cero nombrando el repositorio y la métrica. El oráculo se publica como una diferencia simétrica, nunca una puntuación de recuperación: ctags es una segunda opinión independiente, no una verdad fundamental. Método, resultados por lenguaje y los defectos que este benchmark encontró están en BENCHMARKS.md.

Instalación

Synaptic se compila con un toolchain de Rust estable (fijado a 1.97.1 vía rust-toolchain.toml).

# From a clone, installs the `synaptic` binary onto your PATH:
cargo install --path bin/synaptic

# Optional native workspace/MCP setup app (uses `synaptic` from the same directory or PATH):
cargo install --path bin/synaptic-ui

# ...or build it in-tree:
cargo build --release -p synaptic -p synaptic-ui

Los binarios precompilados de CLI y UI opcional para Linux/macOS/Windows están adjuntos a cada GitHub Release etiquetada (consulte el flujo de trabajo release). Las integraciones opcionales están detrás de banderas de características (desactivadas por defecto): pg (introspección de Postgres), push (exportación en vivo a Neo4j/FalkorDB), y office / gws / media (ingesta de hojas de cálculo / Google-Workspace / audio-video), por ejemplo cargo install --path bin/synaptic --features pg,push. Consulte Instalación, UI de escritorio, y Configuración.

Una vez instalado, actualice en su lugar con synaptic self-update (verifica una suma de verificación SHA-256 y solicita confirmación antes de reemplazar el binario). Opte por un aviso en segundo plano de "actualización disponible" con synaptic self-update --enable — desactivado por defecto, se ejecuta como máximo una vez al día y nunca bloquea comandos normales. Las compilaciones de cargo install / desde fuente también pueden auto-actualizarse, pero el intercambio instala el binario precompilado con características predeterminadas.

Inicio rápido

# 1. Build the graph for the current directory -> synaptic-out/
synaptic extract .

# 2. Ask the graph a question (returns a relevant subgraph)
synaptic query "authentication flow"

# 3. What would changing a symbol break? (reverse impact)
synaptic affected parse_config

# 4. Serve the graph to an AI assistant over MCP
synaptic serve

extract respeta .synapticignore / .gitignore y omite archivos sensibles (.env, claves). Un corpus solo de código se ejecuta completamente sin conexión; el pase semántico opcional de LLM sobre documentos y artículos (extract --semantic) necesita una clave de API (por ejemplo OPENAI_API_KEY). Consulte Inicio rápido.

Artefactos de salida (synaptic-out/)

Artefacto	Qué es
graph.json	Grafo completo (JSON de nodo-enlace), consúltelo sin volver a leer archivos
GRAPH_REPORT.md	Nodos dios, conexiones sorprendentes, preguntas sugeridas, ciclos de importación
graph.html	Explorador 2D interactivo (búsqueda + color de comunidad)
graph-3d.html	Grafo de fuerza 3D interactivo (búsqueda, alternar relaciones, colores de federación)
graph.svg	Diseño estático (Barnes-Hut, empaquetado por componentes, con forma de activo)
chart.html	Mapa de arquitectura bajo demanda con desglose de comunidad a símbolo desde synaptic chart
graph.graphml / graph.cypher / graph.dot	Importar a Gephi / Neo4j / Graphviz
callflow.html / tree.html	Flujo de llamadas Mermaid + árbol de archivos D3
obsidian/, wiki/	Bóveda de Obsidian / wiki Markdown (con --obsidian / --wiki)

Comandos

Comando	Qué hace
extract [path]	Construye el grafo y escribe synaptic-out/. Banderas: --directed, --obsidian, --wiki, --semantic
export <format>	Reemite un formato desde un graph.json existente (sin reconstrucción) o envía en vivo a Neo4j/FalkorDB
chart	Crea un mapa de arquitectura interactivo sin conexión con desglose de subsistemas respaldado por el código fuente. Banderas: --graph, --out, --repo, --max-communities
query <text>	Devuelve un subgrafo clasificado por relevancia (cada nodo puntuado). Banderas: --max-nodes, --repo, --dfs, --since <ref> (impulsa el código modificado en la rama), --seed-changed, --json
path <from> <to>	Camino más corto entre dos nodos
explain <node>	Muestra un nodo y sus vecinos
affected <node>	Nodos que (transitivamente) dependen de un nodo; añade una advertencia cuando un símbolo de "0 dependientes" solo es alcanzable mediante despacho dinámico. Banderas: --depth, --relation
hazards	Lista los sitios de reflexión / despacho dinámico que registra el grafo, para que una respuesta de "0 dependientes" no se confunda con "seguro". Banderas: --repo, --kind, --limit
search [synql]	Búsqueda estructural mediante SYNQL o un --pattern con nombre. Banderas: --explain, --save/--saved, --json
diff <rev1> [rev2]	Diferencia de grafo con viaje en el tiempo entre dos revisiones de git. Banderas: --since, --report, --html, --scope
refactor <action>	Planifica un rename/move/extract seguro para un agente, luego verify el grafo (nunca edita el código fuente)
predict [paths...]	Pronostica un cambio antes de aplicarlo: radio de explosión, pruebas en riesgo, riesgo, APIs eliminadas, ciclos. Banderas: --base, --edit "<kind>:<symbol>", --gate
speculate [paths...]	Ejecuta un cambio de verdad en un árbol de trabajo desechable: pruebas en riesgo + compilación/verificación de tipos, informando aprobado/fallido. Banderas: --patch, --test-cmd, --check-cmd
audit readiness	Auditoría estática de puerto/disponibilidad: clasifica retornos centinela del framework, marcadores de posición/stubs, ruido de recursos generados y metadatos del proyecto. Banderas: --profile, --severity, --repo, --json
sql <action>	audit SQL para rendimiento + seguridad sobre el grafo consciente de SQL, o advise --query "<sql>" en una consulta candidata antes de escribirla. Banderas: --severity, --explain --db-url (EXPLAIN en vivo, requiere --features live-explain)
eval replay [from]	Reproduce el historial para puntuar la calidad del pronóstico contra la verdad de git (comprobable en CI). Bandera: --min-test-recall
eval quality	Mide la corrección de extracción en el corpus del mundo real fijado, con umbrales por repositorio (red + git, opcional). Banderas: --language, --repo, --pin, --update-baselines
update [paths...]	Reconstruye incrementalmente después de cambios en archivos (--full para una reconstrucción completa)
watch	Reconstruye automáticamente a medida que cambian los archivos (repositorio único; usa workspace build --watch para un espacio de trabajo)
serve	Ejecuta el servidor MCP (stdio, o --http <addr> --api-key <key>)
prs [number]	Panel/detalle de PR consciente del grafo. Banderas: --triage, --conflicts, --base, --repo
workspace <action>	Federación multi-repositorio / monorepo (init/add/discover/build/federate/coordinate/sync/status/list). build --watch mantiene un grafo federado en vivo en cada repositorio miembro
global <action>	El almacén de grafo global entre repositorios (~/.synaptic)
memory <action>	Ingiere, registra, busca, compacta, intercambia y evalúa memoria de repositorio duradera y respaldada por el código fuente
api <action>	Inventaría dependencias de API, descubre contratos, mide cobertura, escanea cambios, evalúa impacto y repara/verifica/publica de forma segura un borrador de PR
merge-graphs <graphs...>	Compone varios archivos graph.json en un grafo con espacios de nombres
ingest <source>	Ingiere una fuente externa (cargo / mcp / scip / pg / url; office / gws / media detrás de banderas de características)
hook <action>	Gestiona ganchos de git + el controlador de fusión graph.json
install / uninstall [platform]	Instala la habilidad Synaptic para un asistente anfitrión
cache <action>	Mantiene la caché de extracción en disco
self-update	Actualiza el binario desde la última versión de GitHub (opcional). Banderas: --enable/--disable (aviso en segundo plano), --check, --yes

La referencia completa con cada bandera está en Comandos. Ejecuta synaptic <command> --help para la lista de banderas en la terminal.

Úsalo desde un asistente de IA (MCP)

synaptic serve                                                        # stdio MCP server
synaptic serve --http 127.0.0.1:8765 --api-key "$SYNAPTIC_API_KEY"   # HTTP server
synaptic serve --allow-memory-write                                   # opt-in outcome recording
synaptic serve --memory-principal reviewer \
  --memory-repository-claim owner/repo                                # scope-filtered memory
synaptic serve --graph promoted/graph.json --immutable-graph \
  --expected-graph-sha256 "$GRAPH_SHA256"                             # authenticate exact loaded bytes
synaptic serve --http 127.0.0.1:0 --ready-file /run/synaptic/ready.json # race-free child startup

El servidor expone 30 herramientas principales, cinco herramientas de vulnerabilidad y cinco herramientas de memoria de repositorio de solo lectura: navegación de grafo (query_graph, get_node, get_source, get_neighbors, get_community, god_nodes, graph_stats, shortest_path), análisis de impacto (affected, find_callers, find_callees, find_references, dynamic_hazards, predict_impact, affected_tests, predict_edit), federación (list_repos, repo_stats), revisión de cambios/PR (working_changes_impact, list_prs, get_pr_impact, triage_prs), el trío avanzado (structural_search, time_travel_diff, solo plan plan_rename), auditoría de puerto/disponibilidad (readiness_audit) y auditoría SQL (audit_sql, advise_sql). El trabajo de vulnerabilidades añade vuln_check_dependency, vuln_findings, vuln_explain, vuln_scan y vuln_brief; un escaneo solo escribe con record: true y envía coordenadas de dependencias a OSV solo con online: true. En grafos federados, los agentes seleccionan una etiqueta de list_repos; los escaneos, hallazgos, explicaciones, registros y resúmenes de reparación se aíslan a ese miembro, incluyendo checkouts externos y repositorios en caché de Git. Los miembros solo de artefactos se informan explícitamente como no escaneables. La recuperación de memoria añade search_memory, explain_history, find_similar_change, known_pitfalls y explain_decision; record_change_outcome solo se anuncia con --allow-memory-write. También sirve prompts de MCP, completaciones de argumentos, plantillas de recursos y suscripciones, y una pequeña superficie REST (/api/stats, /api/query, ...) para clientes no MCP. La salida de las herramientas está ajustada para mantenerse ligera en tokens (valores predeterminados concisos, listas limitadas); añade serve --concise (o establece SYNAPTIC_CONCISE) para reducir aún más los tamaños predeterminados. Para implementaciones con digest fijado o de solo lectura, serve --immutable-graph --expected-graph-sha256 <HEX> autentica el búfer de bytes exacto que analiza y desactiva la recarga en caliente del disco, la puesta al día del código fuente y la supervisión del sistema de archivos. --http 127.0.0.1:0 --ready-file <PATH> se vincula antes de publicar atómicamente la dirección asignada por el kernel, evitando carreras de reserva de puertos en supervisores de procesos. synaptic install conecta el grafo a un asistente anfitrión (un gancho PreToolUse para Claude; un servidor MCP nativo para Codex, con synaptic install codex --global para la aplicación de escritorio de Codex). Consulta Servidor MCP y Integración con asistentes.

Idiomas

Más de 30 idiomas mediante tree-sitter, cada uno compilado y probado de forma aislada en CI: Python, JavaScript/TypeScript (+ JSX/TSX, Vue/Svelte/Astro), Go, Rust, Java, C#, Kotlin, Swift, C, C++, Objective-C, Ruby, PHP, Scala, Groovy, Lua, Dart, Elixir, Julia, Zig, Bash, PowerShell, Verilog, Fortran, CodeQL QL y extractores de regex/delegación para Classic ASP, Salesforce Apex, Pascal/Delphi y Razor/Blazor. Además, formatos de datos y proyectos: SQL, JSON, YAML, HCL/Terraform, archivos de proyecto .NET (.csproj/.sln/.slnx) y estructura de Markdown. Aristas conscientes del framework para PHP/Laravel y Dart/Flutter. Desglose completo en Idiomas.

Documentación

El flujo de trabajo de mantenimiento de API autónomo, nativo de grafo y neutral al proveedor está documentado en Mantenimiento de API.

La documentación completa vive en la wiki del proyecto:

• Primeros pasos: Inicio - Instalación - Inicio rápido
• Conceptos: Arquitectura - Idiomas
• Uso: Comandos - Extracción - Consultas - Análisis e informes - Formatos de salida - Visualizaciones
• Integraciones: Servidor MCP - Integración con asistentes - Ingestión - Análisis semántico
• Escalado: Espacios de trabajo y federación - Actualizaciones incrementales - Panel de PR
• Referencia: Configuración - Desarrollo

Desarrollo

cargo test --workspace --all-features              # all tests
cargo fmt --all --check                            # formatting (enforced in CI)
cargo clippy --workspace --all-targets --all-features -- -D warnings

El código base son 27 crates de biblioteca (crates/*) más el binario synaptic (bin/). CI compila cada gramática de idioma de forma aislada para que un aumento de gramática que elimine silenciosamente nodos/aristas falle por sí solo. Consulta Desarrollo y Arquitectura.

Historial de estrellas

Comunidad

¿Preguntas, ideas o quieres mostrar lo que construiste? Únete a nosotros en Discord.

Licencia

GNU Affero General Public License, versión 3 o posterior (AGPL-3.0-or-later), consulta LICENCIA y AVISO. Si modificas Synaptic y permites que los usuarios interactúen con él a través de una red, la licencia requiere que ofrezcas a esos usuarios el código fuente correspondiente. Las versiones históricas permanecen disponibles bajo las licencias bajo las cuales se recibieron. El sitio privado de Synaptic Platform mantenido por separado y el plano de control B2B son propietarios y no están cubiertos por la licencia de este repositorio.