waypath

[!TIP] Neu hier? Der Schnellstart bringt Sie in etwa 60 Sekunden von npm install zu Ihrer ersten persistenten Agenten-Sitzung.

Was ist Waypath?

Waypath ist eine Local-First-Wissens-Engine für Coding-Agenten und Solo-Entwickler. Sie speichert Ihre Projektentscheidungen, Entitätsbeziehungen und Sitzungsartefakte in einer einzigen SQLite-Datei und stellt dann über eine schlanke CLI graph-basierten, wahrheitsorientierten Kontext für jeden Agenten-Host bereit — sei es Claude Code, Codex oder ein MCP-Client.

Im Gegensatz zu Cloud-Speicherdiensten:

• läuft Waypath vollständig auf Ihrem Rechner,

• besitzt ein kanonisches Wahrheitsschema anstelle eines Vektor-Blobs,

• behandelt jedes Gedächtnis als erstklassig mit expliziten Promotion- und Review-Gates,

• liefert ein 77 kB npm-Paket ohne erforderliche Laufzeitdienste.

Related MCP server: ClaudeX

Warum Waypath?

Installation

[!IMPORTANT] Erfordert Node.js ≥ 22. Node 22.5+ schaltet den nativen node:sqlite-Treiber frei; frühere 22.x-Versionen greifen automatisch auf better-sqlite3 zurück.

npm install -g waypath

Überprüfung:

waypath --help
waypath source-status --json

Schnellstart

1. Eine Sitzung bootstrappen (Codex-Beispiel):

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

2. Relevanten Kontext abrufen:

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

3. Eine destillierte Erkenntnis erfassen und durch ein Review befördern:

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

4. Als MCP-Server ausführen (für Claude Code, Cursor, jeden MCP-Client):

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

In Aktion sehen

$ 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"
    ]
  }
}

Befehlsumfang

Vollständige Hilfe: waypath --help.

Architektur

Waypath ist aus vier unabhängigen Kernen hinter einer schlanken Fassade aufgebaut:

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

• Wahrheitskern — kanonische Entscheidungen, Entitäten, Präferenzen, zeitliche Gültigkeit (Schema v3 mit Supersede + Historie).

• Archivkern — Rohdatenspeicher mit Content-Hash-Deduplizierung und FTS5-Volltextindex.

• Ontologie-Schicht — Graph-Traversierung für die Erweiterung des Entitäts-/Entscheidungskontexts (Muster: project_context, person_context, system_reasoning, contradiction_lookup).

• Promotion-Engine — Kandidaten-Review, Widerspruchserkennung, Supersede-Abläufe.

Ein einzelnes createFacade() macht 14 Verben verfügbar. Host-Shims passen diese an das Bootstrap-Protokoll jedes Agenten an.

Konfiguration

Waypath ist standardmäßig ohne Konfiguration einsatzbereit. Um Abrufgewichtungen, Adapter-Toggles oder Review-Schwellenwerte anzupassen, legen Sie eine config.toml in Ihrem Arbeitsverzeichnis ab (oder verweisen Sie WAYPATH_CONFIG_PATH darauf):

[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

Überschreiben Sie alles über Umgebungsvariablen:

export WAYPATH_RECALL_WEIGHT_SOURCE_SYSTEM_TRUTH_KERNEL=1.8
export WAYPATH_REVIEW_QUEUE_LIMIT=8

Priorität: env override > config.toml > built-in defaults.

MCP-Server

Waypath liefert einen nativen MCP-Server (Model Context Protocol) als zweite Binärdatei mit:

waypath-mcp-server

Oder über die Haupt-CLI:

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

Über MCP bereitgestellte Tools: recall, page, promote, review, graph-query, source-status.

Anforderungen

• Node.js ≥ 22.0 (erforderlich)

• Node.js ≥ 22.5 empfohlen — schaltet natives node:sqlite frei

• better-sqlite3 ist ein optionaler Fallback, der automatisch unter 22.0–22.4 oder bei Nichtverfügbarkeit von nativem SQLite verwendet wird

Status

• Version: 0.1.0 — erste öffentliche Veröffentlichung

• Tests: 131 bestanden (Unit + Integration + Benchmark)

• Stabile Oberfläche: CLI (26 Befehle), MCP-Server, Fassaden-API

• Zurückgestellt: gehostete Bereitstellung, Multi-User-Synchronisierung, adaptives Ranking-Feedback

Vergleich mit Alternativen

Mitwirken

Waypath freut sich über Host-Shims, Quell-Adapter und Fehlerbehebungen. Gute erste Issues sind entsprechend markiert.

Lesen Sie CONTRIBUTING.md für die Entwicklungseinrichtung, den Code-Stil und den PR-Ablauf.

Vor dem Einreichen eines PR:

npm run build
npm test

Lizenz

MIT © TheStack.ai — siehe LICENSE.