Waypath is a local-first, SQLite-backed MCP server that acts as an external brain for coding agents, providing persistent, graph-aware, and governed memory with zero cloud dependencies.
Hybrid Recall (waypath_recall): Free-text hybrid search using FTS5 + graph-aware RRF across stored decisions, preferences, and project facts.
Session Bootstrap (waypath_session_start): Builds a prioritized context pack of recent decisions, preferences, and seed entities — optionally scoped by project, objective, or task.
Graph Traversal (waypath_graph_query): Walks the knowledge graph from a known entity ID using patterns like project_context, person_context, system_reasoning, or contradiction_lookup.
Knowledge Page Synthesis (waypath_page): Generates a structured, human-readable summary by aggregating truth-kernel and archive entries about a subject.
Memory Promotion (waypath_promote): Submits facts, decisions, or preferences as candidates to a governed review queue before entering the truth-kernel.
Review & Governance (waypath_review): Accept, reject, or supersede promotion candidates — the gate before facts become queryable.
Review Queue Inspection (waypath_review_queue): Lists pending candidates, stale knowledge pages, and detected contradictions.
Contradiction Resolution (waypath_resolve_contradiction): Resolves conflicting preferences sharing the same key by designating one as authoritative.
Page Refresh (waypath_refresh_page): Rebuilds a stale knowledge page against the current store state.
Health & Diagnostics (waypath_health, waypath_source_status): End-to-end health checks covering SQLite connectivity, FTS5 index sync, source adapter availability, and truth-kernel row counts.
All data is stored locally in a single SQLite file, ensuring full data ownership and privacy.
New here? TheQuick start gets you from npm install to your first persistent agent session in about 60 seconds.
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.
Related MCP server: noggin
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 |
Cloud lock-in, data exfiltration | Everything is one local |
Tool per host (Claude, Codex, Cursor) | Single facade, thin host shims, native MCP server |
RequiresNode.js ≥ 22. Node 22.5+ unlocks the native node:sqlite driver; earlier 22.x versions auto-fall back to better-sqlite3.
npm install -g waypathVerify:
waypath --help
waypath source-status --json1. 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.db2. Recall relevant context:
waypath recall --query "hybrid ranker decisions" --json3. 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 --json4. Run as an MCP server (for Claude Code, Cursor, any MCP client):
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"
]
}
}Area | Commands |
Session bootstrap |
|
Recall |
|
Pages (distilled knowledge) |
|
Review governance |
|
Import / scan |
|
Health |
|
Maintenance |
|
Full help: waypath --help.
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 hostTruth 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.
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 = 12Override anything via env vars:
export WAYPATH_RECALL_WEIGHT_SOURCE_SYSTEM_TRUTH_KERNEL=1.8
export WAYPATH_REVIEW_QUEUE_LIMIT=8Priority: env override > config.toml > built-in defaults.
Waypath ships a native MCP (Model Context Protocol) server as a second binary:
waypath-mcp-serverOr via the main CLI:
waypath mcp-server --store-path ~/.waypath/project.dbTools exposed via MCP: recall, page, promote, review, graph-query, source-status.
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
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
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 |
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 testMIT © TheStack.ai — see LICENSE.
Read-only traversal of the Waypath knowledge graph from a specific entity id. Returns neighbors, edges, and related facts using one of four traversal patterns. Use this when you already have a resolved entity id (from waypath_recall results or from prior context); for free-text lookup use waypath_recall instead. Does not write to the database.
| Name | Required | Description | Default |
|---|---|---|---|
| entityId | Yes | Entity id to expand from, as returned by waypath_recall or waypath_session_start (e.g. "person:alice", "system:auth-svc"). Required. | |
| pattern | No | Traversal pattern selector. "project_context" surfaces projects/tasks/decisions around the entity. "person_context" surfaces ownership, preferences, and collaborations. "system_reasoning" walks system → dependency → decision chains. "contradiction_lookup" finds conflicting preferences/facts attached to the entity. Optional; defaults to a balanced traversal when omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description explicitly states it is read-only and does not write to the database, which is key behavioral information. However, it could mention any rate limits or permissions, but given the read-only nature, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a usage note. Every sentence adds value, no redundancy. Highly concise and front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description mentions return types (neighbors, edges, related facts) and traversal patterns. Without an output schema, it could benefit from more details about the result structure or limits, but it covers the essential aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already provides detailed descriptions for both parameters (100% coverage). The tool description adds value by summarizing the traversal patterns and their purposes, enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb (read-only traversal), resource (Waypath knowledge graph), and output (neighbors, edges, related facts). It also distinguishes from the sibling waypath_recall by specifying it requires a resolved entity id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (when you have a resolved entity id from waypath_recall or prior context) and when not to (use waypath_recall for free-text lookup). Provides clear alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only end-to-end health check: SQLite connectivity and migration version, FTS5 index sync status, source adapter probe results, and truth-kernel row counts. Safe to call any time and from any context. Use as a single diagnostic entrypoint before opening a support issue; for adapter-specific detail call waypath_source_status. Takes no parameters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares read-only nature and safety to call any time, listing checks performed. Without annotations, description carries full burden; missing specification of return format (e.g., JSON status object) is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, safety, and sibling distinction. However, given no output schema, description could specify what the tool returns (e.g., a status object). Still adequate for a simple health check.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so schema coverage is 100%. Baseline set at 4. Description confirms zero parameters but adds no extra value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it is a read-only health check listing specific components (SQLite, FTS5 sync, source adapters, truth-kernel row counts). Distinguishes from sibling waypath_source_status by noting it's a single diagnostic entrypoint vs adapter-specific detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Safe to call any time and from any context' and 'Use as a single diagnostic entrypoint before opening a support issue; for adapter-specific detail call waypath_source_status.' Provides clear when and when-not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Synthesize a human-readable knowledge page about a subject by aggregating and summarizing matching truth-kernel and archive entries. Returns a structured page object plus a markdown summary. The synthesis is deterministic for a given store state and does not call out to any LLM or network service. Read-only with respect to promoted memory; may cache synthesis artifacts in the local store. Use for briefings or handoffs when a recall result would be too fragmented; for targeted lookup use waypath_recall instead.
| Name | Required | Description | Default |
|---|---|---|---|
| subject | Yes | Subject to synthesize a page about. Can be an entity id ("project:acme-api") or a natural-language subject ("Q2 billing migration"). Required; 1-300 chars. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: deterministic, no LLM/network call, read-only regarding promoted memory, may cache artifacts. This is comprehensive for a tool of this complexity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no filler. First sentence captures main action and output. Second sentence adds key traits. Third sentence gives usage guidance. Information density is optimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with clear output description and behavior, the description covers everything an agent needs. No missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and schema already describes the parameter with min/max length. Description adds value by giving concrete examples (entity id format, natural-language subject) and emphasizing it is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Synthesize', 'aggregating', 'summarizing') and clearly identifies the resource ('knowledge page about a subject'). It also distinguishes from the sibling tool 'waypath_recall' by contrasting use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Use for briefings or handoffs when a recall result would be too fragmented; for targeted lookup use waypath_recall instead.' Clearly states when and when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: submit a candidate for promotion into the Waypath truth-kernel. Creates a new candidate row in the local SQLite review queue — it does NOT promote immediately. A human (or agent with explicit authority) must call waypath_review to accept or reject the candidate before it becomes queryable by waypath_recall. Use when you want to persist a decision, preference, or fact; use waypath_review_queue to list pending candidates and waypath_review to act on them.
| Name | Required | Description | Default |
|---|---|---|---|
| subject | Yes | The proposed truth statement or fact to promote, as free text. Will be stored verbatim on the candidate record and shown to the reviewer. 1-1000 chars. Required. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly states the tool is a write operation ('WRITE:'), creates a candidate in a local SQLite queue, and requires human or authorized agent review. It does not mention edge cases like duplicate detection, but the core behavior is transparent. A minor gap for a score of 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding distinct value. Starts with an action label ('WRITE:'), then explains the asynchronous nature, then provides usage guidance. No unnecessary words, highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (one parameter, no output schema) and the availability of sibling tools, the description is nearly complete. It covers purpose, usage, and behavior. A minor omission is what the tool returns (e.g., candidate ID), but the context suggests the agent can infer it from the schema or review queue. Highly adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds that the subject is stored verbatim and shown to the reviewer, which adds some value beyond the schema's constraints but is not essential. No additional parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a candidate row in a review queue for promotion, not an immediate promotion. It uses a specific verb ('submit') and resource ('candidate for promotion'), and distinguishes from siblings like waypath_review and waypath_review_queue by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool ('persist a decision, preference, or fact') and when not ('does NOT promote immediately'), and directs to sibling tools (waypath_review_queue to list, waypath_review to act). This provides excellent guidance for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only hybrid search over the local Waypath SQLite memory store. Runs FTS5 lexical search fused with graph-aware Reciprocal Rank Fusion (RRF) across truth-kernel and archive tables and returns ranked entries with source, score, and snippet. Use before answering any question that may depend on prior decisions, preferences, or project facts; call this instead of waypath_graph_query when you have a free-text query rather than a known entity id. Does not write to the database and does not hit the network.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Free-text recall query (1-500 chars). Supports natural language; tokens are FTS5-escaped automatically. Prefer specific nouns and project names over vague phrases ("auth service rollout plan" beats "that thing"). Required. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It clearly states read-only behavior ('Does not write to the database') and no network access. Also mentions automatic FTS5 escaping. Could add more detail on concurrency limits or performance expectations, but sufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each serving a distinct purpose: functional definition, usage guidance, and behavioral clarification. No redundant or extraneous text. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description covers purpose, usage, behavior, and parameter hints. It mentions output format ('ranked entries with source, score, and snippet') which is adequate. Could specify result limit or ordering, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter 'query' with constraints and description. The description adds value by noting automatic token escaping and advising use of specific nouns/project names ('auth service rollout plan' beats 'that thing'), which helps the agent formulate better queries.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a 'Read-only hybrid search' over a SQLite memory store using FTS5 and RRF, specifying outputs (ranked entries with source, score, snippet). It distinguishes from sibling waypath_graph_query by noting it is for free-text queries rather than known entity IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'before answering any question that may depend on prior decisions, preferences, or project facts'. Also provides a direct alternative: 'call this instead of waypath_graph_query when you have a free-text query rather than a known entity id'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: rebuild an existing knowledge page against the current store state and update its cached summary/markdown. Use on pages flagged "stale" by waypath_review_queue, or after a large batch of promotions that should be reflected in a briefing page. Idempotent — calling twice with no intervening writes produces the same output. Does not call any external service.
| Name | Required | Description | Default |
|---|---|---|---|
| pageId | Yes | The knowledge page id to refresh, as returned by waypath_page or waypath_review_queue. Required; 1-200 chars. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the WRITE nature, idempotency, and that it does not call external services. This is clear behavioral transparency, though additional details like error handling or required permissions could improve it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with purpose and usage, and contains no unnecessary words. Every sentence adds value, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, no output schema, no annotations), the description is complete. It covers purpose, when to use, idempotency, and external service behavior, leaving no obvious gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter (pageId) already described. The description adds context about the parameter's source ('as returned by waypath_page or waypath_review_queue'), which is helpful but not extensive. Since schema already provides most semantics, the description adds moderate value, earning a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'rebuild an existing knowledge page against the current store state and update its cached summary/markdown.' It specifies the action (rebuild and update) and the resource (knowledge page), distinguishing it from sibling tools by mentioning when to use it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage scenarios: 'Use on pages flagged "stale" by waypath_review_queue, or after a large batch of promotions that should be reflected in a briefing page.' It also mentions idempotency, but lacks explicit when-not to use or alternatives, so not a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: resolve a detected contradiction between two or more preferences sharing the same key by keeping exactly one preference and marking the others as superseded. Intended for user-scoped or project-scoped preference collisions surfaced by waypath_review_queue. Use waypath_review_queue first to see active contradictions and their preference ids. This call persists to the local store and is the destructive side of contradiction handling — the non-kept preferences are no longer returned by waypath_recall.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The preference key with the contradiction (e.g. "editor.tab_width", "deploy.region"). Must match the key reported by waypath_review_queue. Required. | |
| keepPreferenceId | Yes | The preference id to keep as authoritative. All other preferences with the same key (and matching scope) are marked superseded. Required. | |
| scopeRef | No | Optional scope reference ("user:dd", "project:acme-api") when the contradiction is scoped rather than global. Omit to resolve across all scopes of the key. | |
| notes | No | Optional free-text rationale for the resolution (stored in audit trail). Recommended for non-obvious decisions. 0-2000 chars. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It clearly labels the operation as 'WRITE' and 'destructive', and states that non-kept preferences are no longer returned by waypath_recall. However, it does not mention return value or error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (4 sentences), front-loaded with the action, and structured logically: purpose, usage, consequences, optional notes. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description adequately explains purpose, usage, and destructive nature, but does not specify return value or error conditions, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds workflow context (e.g., key must match review_queue output) but does not significantly enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'resolve' and the resource 'contradiction between preferences', and explicitly distinguishes its role from siblings like waypath_review_queue and waypath_recall.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use the tool (after reviewing queue), provides the prerequisite step (use waypath_review_queue first), and describes the intended scope (user/project-scoped collisions).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: decide the fate of a pending promotion candidate. Setting status to "accepted" promotes the candidate into the truth-kernel so it becomes visible to waypath_recall; "rejected" discards it; "superseded" marks it as replaced by a newer candidate; the other states are non-terminal holding states. This call is the governance gate between waypath_promote and durable memory — do not accept without evidence. Call waypath_review_queue first to list candidates and their ids.
| Name | Required | Description | Default |
|---|---|---|---|
| candidateId | Yes | Candidate id from waypath_review_queue or the response of waypath_promote. Required. | |
| status | Yes | Decision to record. "accepted" = promote into truth-kernel (visible to waypath_recall). "rejected" = discard permanently. "needs_more_evidence" = keep pending, signal reviewer needs support. "pending_review" = reset to inbox. "superseded" = replaced by a newer candidate. Required. | |
| notes | No | Optional free-text rationale for the decision (shown in audit trail). Recommended for "rejected" and "needs_more_evidence". 0-2000 chars. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It discloses the effects of each status (e.g., 'accepted promotes into truth-kernel so it becomes visible to waypath_recall', 'rejected discards permanently', 'superseded marks as replaced'). It also warns that this is a governance gate. However, it does not mention potential side effects like idempotency or whether the action is reversible, but the key consequences are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured paragraph with no wasted words. It front-loads the purpose and provides essential details efficiently. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with 3 parameters, no output schema), the description covers the prerequisites (call review_queue first), all status effects, and the source of candidateId. It is sufficiently complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the meaning of each status beyond the enum values, recommending notes for certain statuses, and specifying the origin of candidateId. This enriches the schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'WRITE: decide the fate of a pending promotion candidate' and distinguishes its role from siblings by explicitly mentioning 'governance gate between waypath_promote and durable memory.' It uses specific verbs and resources, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Call waypath_review_queue first to list candidates and their ids' and 'do not accept without evidence.' It also explains when each status is appropriate, including terminal vs. non-terminal states, which helps the agent decide when to use this tool vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only snapshot of everything awaiting human attention: pending promotion candidates, stale knowledge pages past their refresh threshold, and detected preference contradictions. Use at the start of a review or maintenance session to see outstanding work; then call waypath_review, waypath_refresh_page, or waypath_resolve_contradiction as appropriate. Takes no parameters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature ('Read-only snapshot') and no-parameter requirement. Without annotations, description carries burden; it sufficiently conveys safety but could add details about data freshness or access permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: function, usage guidance, parameters. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema), the description fully covers purpose, contents, usage context, and follow-up actions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0 parameters, description correctly states 'Takes no parameters.' Baseline 4 for no-param tools; no additional semantics needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it's a read-only snapshot of pending items (promotion candidates, stale pages, contradictions), and distinguishes from sibling tools by naming them as follow-up actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises use at start of review/maintenance sessions and names specific alternatives (waypath_review, waypath_refresh_page, waypath_resolve_contradiction).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only context pack builder for the beginning of a coding or planning session. Assembles a prioritized brief from recent decisions, active preferences, seed entities, and related graph context. Does not write to the database. Call once per session before substantive work; for mid-session lookups use waypath_recall or waypath_graph_query instead. All parameters are optional — pass what is known; omitted fields fall back to project defaults.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project identifier or slug (e.g. "acme-api"). Optional; when omitted the store is queried across all projects. | |
| objective | No | One-sentence goal for this session ("land the stripe webhook refactor"). Optional; biases ranking toward relevant truth-kernel entries. | |
| activeTask | No | Current task identifier or short label (e.g. "PROJ-412" or "fix flake in payments_test"). Optional; scopes the pack toward this task's neighborhood. | |
| seedEntities | No | Optional list of known entity ids (people, files, systems) to expand from. Useful when you already know the starting points; omit to let Waypath infer seeds from project/objective/activeTask. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature ('Does not write to the database') and overall optionality of parameters, but lacks detail on output structure since no output schema is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences efficiently cover purpose, function, behavioral note, and parameter guidance with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately covers usage, read-only nature, parameter optionality, and sibling distinctions; minor gap in output format description but mitigated by low complexity and schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds value beyond schema by explaining fallback behavior ('omitted fields fall back to project defaults') and usage context for seedEntities, despite 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'assembles' and resource 'context pack builder', and explicitly distinguishes from siblings by naming alternatives (waypath_recall, waypath_graph_query) for different use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call ('once per session before substantive work'), provides alternatives for mid-session lookups, and clarifies read-only behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only probe of the local source adapters Waypath can ingest from (filesystem snapshots, git repos, JCP live reader, etc.). Returns each adapter's availability, last-scan timestamp, and any configuration errors. Use to diagnose "why is my recall empty" or before running a large ingest. Does not write and does not hit the network. Takes no parameters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explicitly states 'Read-only probe', 'Does not write', 'Does not hit the network', and 'Takes no parameters'. Missing error handling details, but sufficient for intended use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded, with no wasted words. Every sentence adds value: first explains purpose and output, second gives usage and safety info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description covers return values ('availability, last-scan timestamp, configuration errors'). Complete for a diagnostic probe tool given its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters and schema coverage is 100%. Description adds 'Takes no parameters' to confirm, which is clear and sufficient for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'read-only probe of the local source adapters' and specifies it returns 'availability, last-scan timestamp, and any configuration errors'. It is distinct from sibling tools like waypath_recall or waypath_graph_query, and explicitly links to diagnosing recall issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Use to diagnose why is my recall empty or before running a large ingest.' It does not explicitly state when not to use, but implies safe and lightweight behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.2waypath_graph_query4 fields changedInput schema / properties / entityId / descriptionAdded value: +"Entity id to expand from, as returned by waypath_recall or waypath_session_start (e.g. \"person:alice\", \"system:auth-svc\"). Required."Input schema / properties / entityId / maxLengthAdded value: +200Input schema / properties / entityId / minLengthAdded value: +1Input schema / properties / pattern / descriptionAdded value: +"Traversal pattern selector. \"project_context\" surfaces projects/tasks/decisions around the entity. \"person_context\" surfaces ownership, preferences, and collaborations. \"system_reasoning\" walks system → dependency → decision chains. \"contradiction_lookup\" finds conflicting preferences/facts attached to the entity. Optional; defaults to a balanced traversal when omitted."waypath_page3 fields changedInput schema / properties / subject / descriptionAdded value: +"Subject to synthesize a page about. Can be an entity id (\"project:acme-api\") or a natural-language subject (\"Q2 billing migration\"). Required; 1-300 chars."Input schema / properties / subject / maxLengthAdded value: +300Input schema / properties / subject / minLengthAdded value: +1waypath_promote3 fields changedInput schema / properties / subject / descriptionAdded value: +"The proposed truth statement or fact to promote, as free text. Will be stored verbatim on the candidate record and shown to the reviewer. 1-1000 chars. Required."Input schema / properties / subject / maxLengthAdded value: +1000Input schema / properties / subject / minLengthAdded value: +1waypath_recall3 fields changedInput schema / properties / query / descriptionPrevious value: -"Recall query text."New value: +"Free-text recall query (1-500 chars). Supports natural language; tokens are FTS5-escaped automatically. Prefer specific nouns and project names over vague phrases (\"auth service rollout plan\" beats \"that thing\"). Required."Input schema / properties / query / maxLengthAdded value: +500Input schema / properties / query / minLengthAdded value: +1waypath_refresh_page3 fields changedInput schema / properties / pageId / descriptionPrevious value: -"The knowledge page ID to refresh."New value: +"The knowledge page id to refresh, as returned by waypath_page or waypath_review_queue. Required; 1-200 chars."Input schema / properties / pageId / maxLengthAdded value: +200Input schema / properties / pageId / minLengthAdded value: +1waypath_resolve_contradiction10 fields changedInput schema / properties / keepPreferenceId / descriptionPrevious value: -"The preference ID to keep."New value: +"The preference id to keep as authoritative. All other preferences with the same key (and matching scope) are marked superseded. Required."Input schema / properties / keepPreferenceId / maxLengthAdded value: +200Input schema / properties / keepPreferenceId / minLengthAdded value: +1Input schema / properties / key / descriptionPrevious value: -"The preference key with the contradiction."New value: +"The preference key with the contradiction (e.g. \"editor.tab_width\", \"deploy.region\"). Must match the key reported by waypath_review_queue. Required."Input schema / properties / key / maxLengthAdded value: +200Input schema / properties / key / minLengthAdded value: +1Input schema / properties / notes / descriptionPrevious value: -"Optional resolution notes."New value: +"Optional free-text rationale for the resolution (stored in audit trail). Recommended for non-obvious decisions. 0-2000 chars."Input schema / properties / notes / maxLengthAdded value: +2000Input schema / properties / scopeRef / descriptionPrevious value: -"Optional scope reference."New value: +"Optional scope reference (\"user:dd\", \"project:acme-api\") when the contradiction is scoped rather than global. Omit to resolve across all scopes of the key."Input schema / properties / scopeRef / maxLengthAdded value: +200waypath_review6 fields changedInput schema / properties / candidateId / descriptionAdded value: +"Candidate id from waypath_review_queue or the response of waypath_promote. Required."Input schema / properties / candidateId / maxLengthAdded value: +200Input schema / properties / candidateId / minLengthAdded value: +1Input schema / properties / notes / descriptionAdded value: +"Optional free-text rationale for the decision (shown in audit trail). Recommended for \"rejected\" and \"needs_more_evidence\". 0-2000 chars."Input schema / properties / notes / maxLengthAdded value: +2000Input schema / properties / status / descriptionAdded value: +"Decision to record. \"accepted\" = promote into truth-kernel (visible to waypath_recall). \"rejected\" = discard permanently. \"needs_more_evidence\" = keep pending, signal reviewer needs support. \"pending_review\" = reset to inbox. \"superseded\" = replaced by a newer candidate. Required."waypath_session_start9 fields changedInput schema / properties / activeTask / descriptionAdded value: +"Current task identifier or short label (e.g. \"PROJ-412\" or \"fix flake in payments_test\"). Optional; scopes the pack toward this task's neighborhood."Input schema / properties / activeTask / maxLengthAdded value: +500Input schema / properties / objective / descriptionAdded value: +"One-sentence goal for this session (\"land the stripe webhook refactor\"). Optional; biases ranking toward relevant truth-kernel entries."Input schema / properties / objective / maxLengthAdded value: +500Input schema / properties / project / descriptionAdded value: +"Project identifier or slug (e.g. \"acme-api\"). Optional; when omitted the store is queried across all projects."Input schema / properties / project / maxLengthAdded value: +200Input schema / properties / seedEntities / descriptionAdded value: +"Optional list of known entity ids (people, files, systems) to expand from. Useful when you already know the starting points; omit to let Waypath infer seeds from project/objective/activeTask."Input schema / properties / seedEntities / items / maxLengthAdded value: +200Input schema / properties / seedEntities / maxItemsAdded value: +32waypath_graph_querywaypath_healthwaypath_pagewaypath_promotewaypath_recallwaypath_refresh_pagewaypath_resolve_contradictionwaypath_reviewwaypath_review_queuewaypath_session_startwaypath_source_statusEach tool has a clearly distinct purpose. For example, waypath_recall is for free-text search while waypath_graph_query is for entity-based traversal; waypath_promote, waypath_review, and waypath_review_queue form a distinct workflow. Descriptions clearly differentiate overlapping tools.
All tools start with 'waypath_' and use snake_case. Most follow a verb_noun pattern (e.g., refresh_page, resolve_contradiction), but a few like session_start and source_status are noun_verb or noun_noun. Overall consistent enough for predictable navigation.
With 11 tools, the set is well-scoped for a knowledge management system. It covers query, search, page generation, promotion workflow, health checks, and session context without being bloated or too sparse.
Major workflows are covered: submit candidates (waypath_promote), review (waypath_review, waypath_review_queue), retrieve (waypath_recall, waypath_graph_query), and page synthesis (waypath_page, waypath_refresh_page). Minor gaps include no explicit delete tool, but rejection and superseding serve similar purposes.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/TheStack-ai/waypath'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
