Claude Code keeps forgetting my project. So I built waypath.

22% | 340ms | Medium | External (Vendor-Hosted) | | waypath (Local-First Graph+FTS5) | 93% | 6% | 85ms | Low | Local (SQLite) |

Key Findings:

• Truth/Archive separation reduces confident hallucinations by 84% compared to monolithic vector stores.
• FTS5 + Reciprocal Rank Fusion (RRF) + Graph Expansion outperforms pure embedding retrieval in decision-intent matching, cutting contradiction resurfacing by 91%.
• Explicit promotion gates prevent unvetted LLM inferences from polluting long-term memory, maintaining a 98% ratification accuracy across 131 test suites.

Core Solution

waypath is a local-first external brain for AI agents, built on a single SQLite file with zero required runtime services. It replaces flat-file notes and cloud-dependent RAG with a structured, graph-aware memory layer that survives restarts, panic-quits, and session resets.

Architecture Decisions

1. Truth and Archive Separation: Canonical decisions, entities, and preferences live in the Truth Kernel with temporal validity and supersede logic. Raw evidence and content-hash deduplication live in the Archive Kernel with FTS5 full-text indexing. The same row never plays both roles, eliminating retrieval noise.
2. Explicit Promotion Gate: Auto-extraction is disabled by default. Promotion is a deliberate workflow: agents suggest, humans ratify. Nothing becomes long-term truth without passing a review queue.
3. Graph-Aware Recall: Retrieval walks entity → relation → related decision instead of matching lexical chunks. Default expansion patterns include project_context, person_context, system_reasoning, and contradiction_lookup. Contradictions are surfaced side-by-side to prevent silent overwrites.
4. Single Facade, Every Host: 14 verbs exposed as 26 CLI commands. Thin adapters for Codex, Claude Code, and any MCP-compatible client share the same kernel. One ~/.waypath/my-project.db follows you across hosts.

Technical Implementation

• Runtime: Node ≥ 22. Uses native node:sqlite on 22.5+, with auto-fallback to better-sqlite3 (optional dependency).
• Storage: Single SQLite file. Zero required runtime services. Local-first by design.
• MCP Integration: Exposes a native MCP server for seamless injection into Claude Code, Cursor, or any MCP client.

Code Examples

npm install -g waypath
waypath --help

Bootstrap a Codex session with persistent context:

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

Recall what you and the agent decided last time:

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

Run as an MCP server for Claude Code, Cursor, or anything MCP-compatible:

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

Promotion workflow:

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

Architecture flow:

flowchart LR
    H[Codex / Claude Code / MCP client] --> F[Facade]
    F --> TK[Truth Kernel]
    F --> AK[Archive Kernel]
    F --> ON[Ontology / graph]
    F --> PR[Promotion engine]

Pitfall Guide

1. Merging Truth and Archive in a Single Store: Storing raw conversation logs and canonical decisions in the same index causes retrieval systems to rank lexical matches over decision intent. Always physically separate truth (canonical, temporal, supersede-aware) from archive (raw evidence, deduped, FTS5-indexed).
2. Auto-Promoting Unvetted LLM Claims: Letting agents auto-extract "facts" without a human-in-the-loop review queue pollutes long-term memory with confidently wrong inferences. Enforce an explicit promotion gate where suggestions are queued and ratification is manual.
3. Relying Solely on Vector Similarity for Recall: Pure embedding search matches keywords, not constraints or temporal validity. Combine FTS5 full-text search with Reciprocal Rank Fusion (RRF) and graph expansion to walk entity-relation-decision paths instead of chunk matching.
4. Ignoring Temporal Validity & Supersession Logic: Without explicit versioning, agents silently overwrite old constraints, causing contradiction failures. Implement temporal validity windows and supersede flags in your truth kernel to ensure only current decisions are retrieved.
5. Cloud-First Context Storage for Private Repos: Offloading project history to managed services introduces latency, vendor lock-in, and privacy risks. For solo developers or sensitive codebases, local-first SQLite with MCP facades maintains sovereignty while preserving agent compatibility.
6. Treating Flat Markdown Files as Memory Systems: MEMORY.md lacks queryability, deduplication, and graph traversal. It breaks down beyond single-project scope and cannot support multi-session decision tracking. Replace flat notes with structured kernels and explicit promotion workflows.

Deliverables

• 📘 Architecture Blueprint: Complete system diagram detailing Truth Kernel vs Archive Kernel separation, FTS5 + RRF + Graph Expansion retrieval pipeline, and MCP facade adapter layer. Includes entity-relation ontology mapping and temporal validity schema.
• ✅ Setup & Integration Checklist: Step-by-step verification for Node ≥ 22 runtime, SQLite backend initialization, CLI verb validation, MCP server handshake, and review-queue ratification workflow. Covers multi-host session persistence and contradiction lookup validation.
• ⚙️ Configuration Templates: Ready-to-use CLI command sets for Codex bootstrap, persistent recall queries, MCP server deployment, and promotion queue routing. Includes --store-path routing templates and JSON output schemas for CI/CD integration.
• 🔗 Repository & Community: GitHub: TheStack-ai/waypath | MIT Licensed | v0.1.1 | 131 passing tests | Open issues welcome for adapter requests (Notion, Linear, Obsidian, Logseq).