TheStack-ai/waypath

한국어 ·
中文
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.
Verify:
Quick start
**1. Bootstrap a session** (Codex example):
**2. Recall relevant context:**
**3. Capture a distilled insight and promote it through review:**
**4. Run as an MCP server** (for Claude Code, Cursor, any MCP client):
See it in action
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:
- **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.