waypath

[!TIP] ¿Eres nuevo aquí? El Inicio rápido te lleva desde npm install hasta tu primera sesión de agente persistente en unos 60 segundos.

¿Qué es Waypath?

Waypath es un motor de conocimiento local-first para agentes de programación y desarrolladores individuales. Almacena las decisiones de tu proyecto, las relaciones entre entidades y los artefactos de sesión en un único archivo SQLite, y luego sirve contexto basado en grafos y orientado a la verdad a cualquier host de agente —Claude Code, Codex o un cliente MCP— a través de una CLI ligera.

A diferencia de los servicios de memoria en la nube, Waypath:

• se ejecuta completamente en tu máquina,

• posee un esquema de verdad canónica en lugar de un blob vectorial,

• trata cada memoria como de primera clase con puertas de promoción y revisión explícitas,

• distribuye un paquete npm de 77 kB sin servicios de tiempo de ejecución requeridos.

Related MCP server: ClaudeX

¿Por qué Waypath?

Instalación

[!IMPORTANT] Requiere Node.js ≥ 22. Node 22.5+ desbloquea el controlador nativo node:sqlite; las versiones 22.x anteriores recurren automáticamente a better-sqlite3.

npm install -g waypath

Verificar:

waypath --help
waypath source-status --json

Inicio rápido

1. Iniciar una sesión (ejemplo de Codex):

waypath codex --json \
  --project my-project \
  --objective "ship v2 of the retrieval pipeline" \
  --task  "refactor hybrid ranker" \
  --store-path ~/.waypath/my-project.db

2. Recuperar contexto relevante:

waypath recall --query "hybrid ranker decisions" --json

3. Capturar una idea destilada y promoverla a través de una revisión:

waypath page    --subject "hybrid ranker v2 design"
waypath promote --subject "hybrid ranker v2 design"
waypath review-queue --json

4. Ejecutar como servidor MCP (para Claude Code, Cursor, cualquier cliente MCP):

waypath mcp-server --store-path ~/.waypath/my-project.db

Véalo en acción

$ waypath codex --json --project auth-service \
    --objective "migrate to passkeys" --task "design flow"
{
  "host": "codex",
  "session_id": "auth-service:passkey-flow",
  "context_pack": {
    "truth_highlights": {
      "decisions": [
        "Use WebAuthn level 2 with user verification required",
        "Argon2id for password fallback hashing"
      ],
      "entities": ["UserSession", "AuthGateway", "RefreshToken"],
      "contradictions": []
    },
    "recent_pages": [
      "Session storage design — promoted 2026-04-12"
    ]
  }
}

Superficie de comandos

Ayuda completa: waypath --help.

Arquitectura

Waypath está construido a partir de cuatro núcleos independientes detrás de una fachada ligera:

flowchart TD
    subgraph HOST[" Host Shims "]
        direction LR
        CX["codex"]
        CC["claude-code"]
        MC["mcp-server"]
    end

    Facade["<b>Facade</b><br/><code>createFacade()</code>"]

    TK["<b>Truth Kernel</b><br/>decisions · entities · preferences<br/>temporal validity · supersede"]
    AK["<b>Archive Kernel</b><br/>evidence · content-hash dedup<br/>FTS5 index"]
    ON["<b>Ontology</b><br/>graph traversal<br/>pattern expansion"]
    PR["<b>Promotion Engine</b><br/>candidate review<br/>contradiction detection"]

    HOST --> Facade
    Facade --> TK
    Facade --> AK
    Facade --> ON
    Facade --> PR

    classDef kernel fill:#21262d,color:#c9d1d9,stroke:#30363d,stroke-width:1px
    classDef facade fill:#1f6feb,color:#ffffff,stroke:#58a6ff,stroke-width:2px
    classDef host fill:#161b22,color:#c9d1d9,stroke:#30363d,stroke-width:1px
    class TK,AK,ON,PR kernel
    class Facade facade
    class CX,CC,MC host

• Núcleo de verdad — decisiones canónicas, entidades, preferencias, validez temporal (esquema v3 con reemplazo + historial).

• Núcleo de archivo — almacén de evidencia cruda con deduplicación por hash de contenido e índice de texto completo FTS5.

• Capa de ontología — recorrido de grafos para la expansión del contexto de entidad/decisión (patrones: project_context, person_context, system_reasoning, contradiction_lookup).

• Motor de promoción — revisión de candidatos, detección de contradicciones, flujos de reemplazo.

Un único createFacade() expone 14 verbos. Los shims de host lo adaptan al protocolo de arranque de cada agente.

Configuración

Waypath es zero-config por defecto. Para ajustar los pesos de recuperación, los interruptores de adaptador o los umbrales de revisión, coloca un config.toml en tu directorio de trabajo (o apunta WAYPATH_CONFIG_PATH a uno):

[source_adapters]
jarvis-memory-db = true
jarvis-brain-db  = false

[retrieval.source_system_weights]
truth-kernel = 1.2

[retrieval.source_kind_weights]
decision = 0.9
memory   = 0.5

[review_queue]
limit = 12

Sobrescribe cualquier cosa mediante variables de entorno:

export WAYPATH_RECALL_WEIGHT_SOURCE_SYSTEM_TRUTH_KERNEL=1.8
export WAYPATH_REVIEW_QUEUE_LIMIT=8

Prioridad: env override > config.toml > valores predeterminados integrados.

Servidor MCP

Waypath incluye un servidor MCP (Model Context Protocol) nativo como segundo binario:

waypath-mcp-server

O a través de la CLI principal:

waypath mcp-server --store-path ~/.waypath/project.db

Herramientas expuestas a través de MCP: recall, page, promote, review, graph-query, source-status.

Requisitos

• Node.js ≥ 22.0 (requerido)

• Node.js ≥ 22.5 recomendado — desbloquea node:sqlite nativo

• better-sqlite3 es una alternativa opcional utilizada automáticamente en 22.0–22.4 o donde sqlite nativo no esté disponible

Estado

• Versión: 0.1.0 — primer lanzamiento público

• Pruebas: 131 pasando (unidad + integración + benchmark)

• Superficie estable: CLI (26 comandos), servidor MCP, API de fachada

• Diferido: despliegue alojado, sincronización multiusuario, retroalimentación de clasificación adaptativa

Comparado con alternativas

Contribución

Waypath agradece shims de host, adaptadores de fuente y correcciones de errores. Los buenos primeros problemas están etiquetados en consecuencia.

Lee CONTRIBUTING.md para la configuración de desarrollo, estilo de código y flujo de PR.

Antes de enviar un PR:

npm run build
npm test

Licencia

MIT © TheStack.ai — ver LICENSE.