waypath

[!TIP] Впервые здесь? Быстрый старт позволит вам пройти путь от npm install до первой постоянной сессии агента примерно за 60 секунд.

Что такое Waypath?

Waypath — это локально-ориентированный движок знаний для агентов кодинга и индивидуальных разработчиков. Он хранит ваши проектные решения, связи между сущностями и артефакты сессий в одном файле SQLite, а затем предоставляет графовый, ориентированный на истину контекст любому хосту агентов — Claude Code, Codex или MCP-клиенту — через легкий CLI.

В отличие от облачных сервисов памяти, Waypath:

• работает полностью на вашем компьютере,

• использует каноническую схему истины вместо векторного блоба,

• считает каждое воспоминание первоклассным объектом с явными этапами продвижения и проверки,

• поставляется в виде npm-пакета размером 77 КБ без необходимости в фоновых сервисах.

Related MCP server: ClaudeX

Почему Waypath?

Установка

[!IMPORTANT] Требуется Node.js ≥ 22. Node 22.5+ открывает доступ к нативному драйверу node:sqlite; более ранние версии 22.x автоматически переключаются на better-sqlite3.

npm install -g waypath

Проверка:

waypath --help
waypath source-status --json

Быстрый старт

1. Инициализация сессии (пример для 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. Извлечение релевантного контекста:

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

3. Захват инсайта и его продвижение через проверку:

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

4. Запуск в качестве MCP-сервера (для Claude Code, Cursor, любого MCP-клиента):

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

Посмотрите в действии

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

Команды

Полная справка: waypath --help.

Архитектура

Waypath построен на четырех независимых ядрах за легким фасадом:

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

• Ядро истины — канонические решения, сущности, предпочтения, временная актуальность (схема v3 с замещением и историей).

• Ядро архива — хранилище необработанных данных с дедупликацией по контент-хешу и полнотекстовым индексом FTS5.

• Слой онтологии — обход графа для расширения контекста сущностей/решений (паттерны: project_context, person_context, system_reasoning, contradiction_lookup).

• Движок продвижения — проверка кандидатов, обнаружение противоречий, потоки замещения.

Один createFacade() предоставляет 14 глаголов. Прослойки хостов адаптируют его к протоколу загрузки каждого агента.

Конфигурация

Waypath не требует настройки по умолчанию. Чтобы настроить веса поиска, переключатели адаптеров или пороги проверки, создайте файл config.toml в рабочей директории (или укажите путь через WAYPATH_CONFIG_PATH):

[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

Переопределение через переменные окружения:

export WAYPATH_RECALL_WEIGHT_SOURCE_SYSTEM_TRUTH_KERNEL=1.8
export WAYPATH_REVIEW_QUEUE_LIMIT=8

Приоритет: переменные окружения > config.toml > встроенные значения по умолчанию.

MCP-сервер

Waypath поставляется с нативным сервером MCP (Model Context Protocol) в виде второго бинарного файла:

waypath-mcp-server

Или через основной CLI:

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

Инструменты, доступные через MCP: recall, page, promote, review, graph-query, source-status.

Требования

• Node.js ≥ 22.0 (обязательно)

• Node.js ≥ 22.5 рекомендуется — открывает доступ к нативному node:sqlite

• better-sqlite3 — опциональный запасной вариант, автоматически используемый в версиях 22.0–22.4 или там, где нативный sqlite недоступен

Статус

• Версия: 0.1.0 — первый публичный релиз

• Тесты: 131 пройдено (модульные + интеграционные + бенчмарки)

• Стабильный интерфейс: CLI (26 команд), MCP-сервер, API фасада

• Отложено: облачное развертывание, многопользовательская синхронизация, адаптивная обратная связь ранжирования

Сравнение с альтернативами

Участие в разработке

Waypath приветствует прослойки для хостов, адаптеры источников и исправления ошибок. Хорошие задачи для начала помечены соответствующим образом.

Прочитайте CONTRIBUTING.md для настройки среды разработки, стиля кода и процесса PR.

Перед отправкой PR:

npm run build
npm test

Лицензия

MIT © TheStack.ai — см. LICENSE.