TheStack-ai/waypath

[!TIP] New here? The Quick start gets you from npm install to your first persistent agent session in about 60 seconds.

What is Waypath?

Waypath is a local-first knowledge engine for coding agents and solo developers. It stores your project decisions, entity relationships, and session artifacts in a single SQLite file, then serves graph-aware, truth-first context to any agent host — Claude Code, Codex, or an MCP client — through a thin CLI.

Unlike cloud memory services, Waypath:

• runs entirely on your machine,
• owns a canonical truth schema instead of a vector blob,
• treats every memory as first-class with explicit promotion + review gates,
• ships a 77 kB npm package with no required runtime services.

Why Waypath?

Install

[!IMPORTANT] Requires Node.js ≥ 22. Node 22.5+ unlocks the native node:sqlite driver; earlier 22.x versions auto-fall back to better-sqlite3.

npm install -g waypath

Verify:

waypath --help
waypath source-status --json

Quick start

1. Bootstrap a session (Codex example):

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

2. Recall relevant context:

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

3. Capture a distilled insight and promote it through review:

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

4. Run as an MCP server (for Claude Code, Cursor, any MCP client):

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

See it in action

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

Command surface

Full help: waypath --help.

Architecture

Waypath is built from four independent kernels behind a thin facade:

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

• Truth kernel — canonical decisions, entities, preferences, temporal validity (schema v3 with supersede + history).
• Archive kernel — raw evidence store with content-hash dedup and FTS5 full-text index.
• Ontology layer — graph traversal for entity/decision context expansion (patterns: project_context, person_context, system_reasoning, contradiction_lookup).
• Promotion engine — candidate review, contradiction detection, supersede flows.

A single createFacade() exposes 14 verbs. Host shims adapt it to each agent's bootstrap protocol.

Configuration

Waypath is zero-config by default. To tune retrieval weights, adapter toggles, or review thresholds, drop a config.toml in your working directory (or point WAYPATH_CONFIG_PATH at one):

[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

Override anything via env vars:

export WAYPATH_RECALL_WEIGHT_SOURCE_SYSTEM_TRUTH_KERNEL=1.8
export WAYPATH_REVIEW_QUEUE_LIMIT=8

Priority: env override > config.toml > built-in defaults.

MCP server

Waypath ships a native MCP (Model Context Protocol) server as a second binary:

waypath-mcp-server

Or via the main CLI:

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

Tools exposed via MCP: recall, page, promote, review, graph-query, source-status.

Requirements

• Node.js ≥ 22.0 (required)
• Node.js ≥ 22.5 recommended — unlocks native node:sqlite
• better-sqlite3 is an optional fallback auto-used on 22.0–22.4 or where native sqlite is unavailable

Status

• Version: 0.1.0 — first public release
• Tests: 131 passing (unit + integration + benchmark)
• Stable surface: CLI (26 commands), MCP server, facade API
• Deferred: hosted deployment, multi-user sync, adaptive ranking feedback

Compared to alternatives

Contributing

Waypath welcomes host shims, source adapters, and bug fixes. Good first issues are labeled accordingly.

Read CONTRIBUTING.md for dev setup, code style, and PR flow.

Before submitting a PR:

npm run build
npm test

License

MIT © TheStack.ai — see LICENSE.