KnownPath

KnownPath es una red de conocimiento compartida de código abierto para agentes de codificación de IA. Su propósito a largo plazo es evitar que los agentes redescubran de forma repetida las mismas soluciones técnicas, haciendo que experiencias de ingeniería verificadas y reutilizables estén disponibles a través de interfaces nativas para agentes.

[!IMPORTANT] KnownPath se encuentra en desarrollo activo por fases. La Fase 13 añade el CLI de instalación portátil y adaptadores seguros para cinco agentes de codificación. Las herramientas de contribución/resultados, los paneles, el registro público y el acceso anónimo público aún no están implementados. El instalador se publica como knownpath.

Requisitos previos

• Node.js 24 LTS (.nvmrc registra la versión principal compatible; package.json fija el rango probado)

• Corepack, incluido en la distribución compatible de Node.js

• Docker Desktop u otro motor Docker compatible con Compose, para MongoDB local

Related MCP server: CodeGraph

Instalación

corepack enable
pnpm install
cp .env.example .env

Genera valores independientes para BETTER_AUTH_SECRET y API_KEY_PEPPER como se describe en .env.example. El ejemplo comprometido no contiene valores predeterminados de credenciales.

Iniciar el entorno de desarrollo actual

Inicia MongoDB:

pnpm dev:infra

Crea o reconcilia las colecciones, validadores e índices actuales:

pnpm db:init

Inspección opcional de persistencia y validación de ida y vuelta del repositorio:

pnpm db:inspect
pnpm db:verify

Crea el primer usuario o administrador local a través del CLI enmascarado (el registro está cerrado):

pnpm auth:user:create

Configura opcionalmente GITHUB_TOKEN en .env para el límite normal de REST autenticado de 5000 solicitudes y para el acceso a GitHub Discussions. Luego previsualiza o ejecuta una recopilación acotada:

pnpm ingest:github --source expo-core --types issues --limit 5 --dry-run
pnpm ingest:github --source expo-core --types issues --limit 5

Consulta la guía de ingesta de GitHub antes de ejecutar un backfill.

Descubre el conjunto actual de documentos oficiales curados sin escribir registros de origen y, a continuación, sincroniza una fuente acotada o una página indexada:

pnpm ingest:sources discover --source expo-documentation --limit 20
pnpm ingest:sources sync --source expo-documentation --limit 5 --dry-run
pnpm ingest:sources sync --source expo-documentation \
  --page https://docs.expo.dev/workflow/upgrading-expo-sdk-walkthrough --limit 1

Consulta la guía de ingesta de fuentes oficiales antes de cambiar la curación o solicitar una ejecución acotada del catálogo completo.

Con una clave de desarrollo de Gemini en el .env ignorado, procesa o inspecciona un candidato acotado de fuentes públicas:

pnpm extract one --source-item <uuid>
pnpm extract pending --limit 5
pnpm extract inspect --attempt <uuid>
pnpm extract inspect --candidate <uuid>

La ruta de Gemini gratuita rechaza directamente los registros de fuentes privadas/de equipo antes de cualquier llamada al proveedor. Consulta la guía de extracción con IA antes de configurar la clave o ampliar un lote.

Puntúa los candidatos extraídos sin llamar a un proveedor de IA y, después, inspecciona el desglose/historial completo:

pnpm score one --candidate <uuid>
pnpm score pending --limit 10
pnpm score inspect --assessment <uuid>
pnpm score history --candidate <uuid>

Las puntuaciones son señales de clasificación explicables, no probabilidades de verdad. Consulta la guía de puntuación antes de cambiar la política versionada.

Construye perfiles de similitud inmutables, descubre pares bloqueados, inspecciona las revisiones y aplica solo fusiones canónicas deterministas y seguras:

pnpm canonicalize profile --limit 10
pnpm canonicalize discover --limit 10
pnpm canonicalize review --limit 20
pnpm canonicalize auto-merge --limit 10       # dry-run
pnpm canonicalize auto-merge --limit 10 --apply
pnpm canonicalize history --known-path <uuid>

Los embeddings de Gemini solo se generan después de que tanto los candidatos como todas las fuentes referenciadas hayan sido verificados como públicos. Respaldan comparaciones bloqueadas plausibles, pero nunca deciden una fusión automática. Consulta la guía de canonicalización antes de aplicar fusiones u operaciones manuales.

Construye las proyecciones de búsqueda canónicas actuales y consúltalas localmente. Los registros en estado de revisión se excluyen a menos que se soliciten explícitamente:

pnpm run search project --pending --limit 10
pnpm run search query --text "EAS build cannot find an imported file" \
  --error "None of these files exist" --ecosystem expo --include-review
pnpm run search indexes print

MongoDB local utiliza recuperación exact/error y de texto ponderado e indica claramente que la recuperación semántica no está disponible. Atlas Search/Vector Search es una configuración opcional. El proveedor Gemini sin pago rechaza rotundamente los documentos de privados/de equipo y el texto de consulta. Consulta la guía de recuperación antes de habilitar Atlas o cambiar la configuración de clasificación/modelo.

Inicia todos los procesos de desarrollo de aplicaciones y paquetes:

pnpm dev

El shell web actual se sirve en http://127.0.0.1:3000. Los estados de liveness y readiness de la API están disponibles en http://127.0.0.1:3001/health/live y http://127.0.0.1:3001/health/ready. El JSON de OpenAPI está en http://127.0.0.1:3001/api/v1/openapi.json; la interfaz Swagger UI de desarrollo está disponible en http://127.0.0.1:3001/docs/.

La búsqueda de conocimiento autenticado, el detallado canónico lo, las alternativas, las reglas de acceso en representación y los ejemplos curl seguros se documentan en la guía de la API HTTP de conocimiento. Los clientes normales solo reciben registros públicos publicados; el acceso de revisión es explícito, solo con clave de administrador y auditado.

Después de compilar, conecta un cliente MCP directamente a http://127.0.0.1:3001/mcp, o ejecuta el puente stdio secundario con KNOWNPATH_API_URL y KNOWNPATH_API_KEY:

pnpm mcp:stdio
pnpm mcp:inspect --transport stdio

Los contratos de herramientas, la autenticación, el comportamiento de seguridad y las configuraciones actuales de Codex/Claude Code/Cursor/Gemini CLI se documentan en la guía de MCP.

El Agent Skill portátil enseña a los agentes de codificación compatibles cuándo y cómo consultar esas herramientas MCP para no aplicar, a ciegas, las soluciones recuperadas. La instalación manual de desarrollo y el contrato de comportamiento actual se documentan en la guía de Agent Skill.

Configura el origen de la API y la clave de API en el entorno que lanza cada agente y, después, inspecciona o aplica el plan del instalador de la Fase 13:

export KNOWNPATH_API_URL='https://your-knownpath-origin.example'
read -rsp 'KnownPath API key: ' KNOWNPATH_API_KEY && export KNOWNPATH_API_KEY && printf '\n'
pnpm knownpath -- install --dry-run --agent all
pnpm knownpath -- install --agent all
pnpm knownpath -- doctor --agent all

El CLI solo almacena referencias a esos nombres de variables y no tiene respaldo de URL. Es compatible con Codex CLI, Claude Code, Cursor, Gemini CLI y OpenCode en ámbito global o de proyecto. Los usuarios pueden ejecutar npx knownpath install; el desarrollo del repositorio puede usar pnpm knownpath --. Los cambios exactos, la configuración de Windows, las copias de seguridad, los conflictos, las actualizaciones y el comportamiento de desinstalación se documentan en la guía del instalador.

Desplegar la API

La raíz de render.yaml define un servicio web de Render para la API Fastify y mantiene MongoDB Atlas como base de datos. De forma deliberada no despliega el worker, el panel de control ni otro almacén de datos. Rotativos rotativos los cambios expuestos antes de la configuración y sigue la guía de despliegue de Render para el Blueprint, el acceso a Atlas, la verificación de estado y el flujo de claves de API posterior al despliegue.

Detén MongoDB y la API sin eliminar su volumen de desarrollo nominal:

pnpm dev:infra:down

Comandos del repositorio

Estructura

apps/
  api/             Fastify HTTP process
  cli/             Publishable installer CLI and stdio bridge entry point
  mcp-server/      Thin stdio MCP bridge to the authenticated HTTP API
  web/             Next.js application shell
  worker/          Source ingestion and future background processing runtime
packages/
  agent-adapters/  Safe detection/configuration adapters and ownership state
  ai/              Gemini provider, privacy gate, prompts, validation, and extraction lifecycle
  auth/            Sessions, API keys, principals, authorization, and audit
  config/          Typed environment parsing
  database/        MongoDB lifecycle, repositories, validators, and indexes
  domain/          Versioned domain schemas and canonicalization helpers
  canonicalization/ Deterministic blocking, optional embeddings, and canonical projections
  github-ingestion/ GitHub API collection and source normalization
  source-ingestion/ Official documentation/feed discovery and normalization
  verification/    Deterministic evidence verification and immutable seed scoring
  search/          Embeddings, search projections, hybrid retrieval, and explainable ranking
  mcp/             Shared MCP tool contracts, projections, server factory, and HTTP gateway
  typescript-config/ Shared strict compiler configurations
skills/
  knownpath/        Portable Agent Skill instructions and on-demand examples

Consulta la guía de arquitectura, el modelado de datos, la guía de recuperación, la guía de la API HTTP de Knowledge, la guía de MCP, la guía de Agent Skill, la guía de instalación, la guía de despliegue, el registro de decisiones y el progreso por fases para conocer los límites de funcionamiento y el estado de la entrega.

Licencia

KnownPath se licencia bajo la Apache License 2.0.