waypath

English · <a href="./README.ko.md">한국어</a> · <a href="./README.zh.md">中文</a>

Local-first external brain for coding agents. A SQLite-backed CLI that gives Claude Code, Codex, and any MCP client persistent context, graph-aware recall, and governed memory — with zero cloud dependencies.

[!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?

| Problem | Waypath's answer | |---|---| | Agents forget across sessions | Persistent SQLite truth kernel | | RAG returns irrelevant chunks | FTS5 + RRF hybrid ranking with graph expansion | | Memory services hallucinate silently | Explicit page → promote → review governance | | Cloud lock-in, data exfiltration | Everything is one local .db file you own | | Tool per host (Claude, Codex, Cursor) | Single facade, thin host shims, native MCP server |

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

| Area | Commands | |------|----------| | Session bootstrap | codex, claude-code, mcp-server | | Recall | recall, explain, graph-query, history | | Pages (distilled knowledge) | page, promote, refresh-page, inspect-page | | Review governance | review, review-queue, inspect-candidate, resolve-contradiction | | Import / scan | import-seed, import-local, scan | | Health | source-status, health, db-stats, rebuild-fts | | Maintenance | backup, benchmark, export |

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

| | Waypath | Cloud memory (mem0, zep) | Vector-only RAG | |---|:---:|:---:|:---:| | Local-first | ✓ | ✗ | depends | | Canonical truth schema | ✓ | ✗ | ✗ | | Graph-aware recall | ✓ | partial | ✗ | | Explicit review gate | ✓ | ✗ | ✗ | | MCP server built-in | ✓ | ✗ | ✗ | | One-file install | ✓ | needs service | varies |

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