[!TIP] 처음 오셨나요? 빠른 시작을 통해
npm install부터 첫 번째 지속적 에이전트 세션까지 약 60초 만에 완료할 수 있습니다.
Waypath는 코딩 에이전트와 1인 개발자를 위한 로컬 우선 지식 엔진입니다. 프로젝트 결정 사항, 엔티티 관계 및 세션 아티팩트를 단일 SQLite 파일에 저장하고, 가벼운 CLI를 통해 Claude Code, Codex 또는 MCP 클라이언트와 같은 모든 에이전트 호스트에 그래프 인식형, 진실 우선 컨텍스트를 제공합니다.
클라우드 메모리 서비스와 달리 Waypath는 다음과 같은 특징이 있습니다:
완전히 로컬 환경에서 실행됩니다.
벡터 블롭 대신 **표준 진실 스키마(canonical truth schema)**를 소유합니다.
명시적 승격 + 검토 게이트를 통해 모든 메모리를 일급 객체로 취급합니다.
필수 런타임 서비스 없이 77kB의 npm 패키지로 제공됩니다.
Related MCP server: GoodMemory
문제 | Waypath의 해결책 |
에이전트가 세션 간 기억을 잊음 | 지속적인 SQLite 진실 커널 |
RAG가 관련 없는 청크를 반환함 | 그래프 확장을 포함한 FTS5 + RRF 하이브리드 랭킹 |
메모리 서비스가 조용히 환각을 일으킴 | 명시적 |
클라우드 종속성, 데이터 유출 | 모든 것이 사용자가 소유한 하나의 로컬 |
호스트별 도구 (Claude, Codex, Cursor) | 단일 파사드, 가벼운 호스트 심(shim), 네이티브 MCP 서버 |
[!IMPORTANT] Node.js ≥ 22가 필요합니다. Node 22.5+는 네이티브
node:sqlite드라이버를 활성화하며, 이전 22.x 버전은 자동으로better-sqlite3로 대체됩니다.
npm install -g waypath확인:
waypath --help
waypath source-status --json1. 세션 부트스트랩 (Codex 예시):
waypath codex --json \
--project my-project \
--objective "ship v2 of the retrieval pipeline" \
--task "refactor hybrid ranker" \
--store-path ~/.waypath/my-project.db2. 관련 컨텍스트 회상:
waypath recall --query "hybrid ranker decisions" --json3. 추출된 통찰력을 캡처하고 검토를 통해 승격:
waypath page --subject "hybrid ranker v2 design"
waypath promote --subject "hybrid ranker v2 design"
waypath review-queue --json4. MCP 서버로 실행 (Claude Code, Cursor, 모든 MCP 클라이언트용):
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"
]
}
}영역 | 명령어 |
세션 부트스트랩 |
|
회상 |
|
페이지 (추출된 지식) |
|
검토 거버넌스 |
|
가져오기 / 스캔 |
|
상태 |
|
유지보수 |
|
전체 도움말: waypath --help.
Waypath는 가벼운 파사드 뒤에 4개의 독립적인 커널로 구축되었습니다:
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) — 표준 결정, 엔티티, 선호도, 시간적 유효성 (supersede + history를 포함한 스키마 v3).
아카이브 커널(Archive kernel) — 콘텐츠 해시 중복 제거 및 FTS5 전문 검색 인덱스를 갖춘 원시 증거 저장소.
온톨로지 계층(Ontology layer) — 엔티티/결정 컨텍스트 확장을 위한 그래프 탐색 (패턴: project_context, person_context, system_reasoning, contradiction_lookup).
승격 엔진(Promotion engine) — 후보 검토, 모순 탐지, 대체 흐름.
단일 createFacade()가 14개의 동사를 노출합니다. 호스트 심(shim)은 이를 각 에이전트의 부트스트랩 프로토콜에 맞게 조정합니다.
Waypath는 기본적으로 설정이 필요 없습니다. 검색 가중치, 어댑터 토글 또는 검토 임계값을 조정하려면 작업 디렉토리에 config.toml을 배치하거나 WAYPATH_CONFIG_PATH를 해당 파일로 지정하세요:
[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환경 변수를 통해 무엇이든 재정의할 수 있습니다:
export WAYPATH_RECALL_WEIGHT_SOURCE_SYSTEM_TRUTH_KERNEL=1.8
export WAYPATH_REVIEW_QUEUE_LIMIT=8우선순위: 환경 변수 재정의 > config.toml > 내장 기본값.
Waypath는 두 번째 바이너리로 네이티브 MCP(Model Context Protocol) 서버를 제공합니다:
waypath-mcp-server또는 메인 CLI를 통해 실행:
waypath mcp-server --store-path ~/.waypath/project.dbMCP를 통해 노출되는 도구: recall, page, promote, review, graph-query, source-status.
Node.js ≥ 22.0 (필수)
Node.js ≥ 22.5 권장 — 네이티브 node:sqlite 활성화
better-sqlite3는 22.0–22.4 버전 또는 네이티브 sqlite를 사용할 수 없는 경우 자동으로 사용되는 선택적 대체 라이브러리입니다.
버전: 0.1.0 — 첫 번째 공개 릴리스
테스트: 131개 통과 (단위 + 통합 + 벤치마크)
안정적인 인터페이스: CLI (26개 명령어), MCP 서버, 파사드 API
보류 중: 호스팅 배포, 다중 사용자 동기화, 적응형 랭킹 피드백
Waypath | 클라우드 메모리 (mem0, zep) | 벡터 전용 RAG | |
로컬 우선 | ✓ | ✗ | 상황에 따라 다름 |
표준 진실 스키마 | ✓ | ✗ | ✗ |
그래프 인식 회상 | ✓ | 부분적 | ✗ |
명시적 검토 게이트 | ✓ | ✗ | ✗ |
MCP 서버 내장 | ✓ | ✗ | ✗ |
원파일 설치 | ✓ | 서비스 필요 | 다양함 |
Waypath는 호스트 심(shim), 소스 어댑터 및 버그 수정을 환영합니다. 좋은 첫 번째 이슈는 해당 라벨이 지정되어 있습니다.
개발 환경 설정, 코드 스타일 및 PR 흐름은 **CONTRIBUTING.md**를 읽어보세요.
PR을 제출하기 전:
npm run build
npm testMIT © TheStack.ai — 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.
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_statusScored across 11 tools
Each 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.
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.
