Reference
CLI Reference
All waystone commands, flags, and options.
Global flags
| Flag | Description |
|---|---|
--help |
Show help for any command |
--version |
Print the installed version of Waystone |
--config <path> |
Use a config file other than ~/.waystone/config.yaml |
waystone init
waystone init <project-name>Create a new project. Creates ~/.waystone/projects/<project-name>/ with an empty knowledge graph, a transcripts/ directory, and an exports/ directory. If the project already exists, reports the existing path without overwriting.
waystone extract
waystone extract <project> <file>Extract structured facts from a transcript or text file and merge them into the project graph. The file can be a plain-text conversation, a Claude Code .jsonl session, or any markdown document.
| Flag | Description |
|---|---|
--verify |
Run a second LLM pass hunting for missed secondary details, buried numerics, transition statements, and rationale |
--decisions |
Targeted pass: decision nodes and their rationale |
--lessons |
Targeted pass: failed approaches and rejected alternatives |
--questions |
Targeted pass: open questions and unresolved items |
--constraints |
Targeted pass: hard constraints and requirements |
--numerics |
Targeted pass: numeric values, measurements, and quantified facts |
--preferences |
Targeted pass: personal preferences, habits, tastes, and dislikes |
--synthesize |
Run a synthesis pass after extraction: create cross-cutting summary nodes |
--chunk-size <chars> |
Max characters per LLM call. Auto-applied when file exceeds 20,000 characters. |
--timeout <seconds> |
LLM timeout per call in seconds (overrides config) |
waystone query
waystone query <project> "<task description>"Retrieve the facts most relevant to a task description or question. Waystone scores nodes by semantic similarity, graph traversal, and recency, then returns the highest-signal facts as formatted markdown.
| Flag | Description |
|---|---|
--top-k <n> |
Max nodes to return (default: from config, typically 25) |
--hops <n> |
Graph traversal depth (default: 3) |
--enable <strategy> |
Enable a retrieval strategy (repeatable). Options: superseded_pruning, recency_decay, relevance_scoring, confidence_threshold, token_budget |
--disable <strategy> |
Disable a retrieval strategy (repeatable) |
--confidence <float> |
Minimum confidence threshold (e.g. 0.6) |
--token-budget <n> |
Max tokens in output (greedy packing) |
--source <prefix> |
Restrict results to nodes from a source path prefix (repeatable) |
--at-time <ISO8601> |
Bi-temporal point-in-time query: only return nodes valid at this timestamp |
--stats |
Show retrieval statistics (node counts, strategy pipeline output) |
waystone show
waystone show <project>Display graph statistics and recent nodes for a project — node counts by type, most recently added nodes, edge counts. Useful for verifying extraction results.
| Flag | Description |
|---|---|
--failures |
Show recent extraction failures instead of nodes (useful for debugging model errors) |
waystone onboard
waystone onboard [project]One-click import of recent Claude Code sessions into a project graph. Discovers .jsonl session files from ~/.claude/projects/, presents an interactive menu, and extracts facts from selected sessions. Most users see their graph populated in under two minutes.
| Flag | Description |
|---|---|
--limit <n> |
Max sessions to show in the menu (default: 10) |
--verify |
Run a verification pass on each imported session |
--chunk-size <chars> |
Auto-split sessions larger than this many characters (default: 30000) |
waystone reflect
waystone reflect <project> <transcript>Extract process patterns and workflows from a transcript. Where extract looks for facts and decisions, reflect looks for procedural patterns that emerged through iteration — multi-step workflows, repeatable protocols, debugging strategies.
| Flag | Description |
|---|---|
--since-turn <n> |
Start from conversation turn N (0-indexed) |
--domain <label> |
Domain label for extracted process nodes (default: software_dev) |
--chunk-size <n> |
Max utterances per LLM call (default: 200). Long sessions are chunked automatically. |
waystone survey
waystone survey <project>Create cross-cutting summary nodes from existing graph nodes. Scans for clusters of parallel facts (3+ nodes sharing the same metric or attribute across different subjects) and creates one summary node per cluster — making broad queries like "compare all models" or "rank all options" retrievable in a single hop.
| Flag | Description |
|---|---|
--dry-run |
Print survey nodes without storing them |
--max-nodes <n> |
Max nodes to send to LLM, sorted by confidence (default: 1000; 0 = no limit) |
--tags <tag> |
Only include nodes with at least one of these tags (repeatable) |
waystone dedup
waystone dedup <project>Find and merge semantically duplicate nodes. Runs in preview mode by default — prints which nodes would be merged. Two nodes are considered duplicates when their embedding cosine similarity exceeds --threshold. The lower-confidence node is merged into the higher-confidence one.
| Flag | Description |
|---|---|
--threshold <float> |
Cosine similarity threshold (default: 0.92) |
--top-k <n> |
Neighbors to check per node (default: 5) |
--limit <n> |
Max nodes to scan per run (0 = all). Use to batch large graphs. |
--execute |
Actually merge duplicate nodes (default: preview only) |
waystone prune
waystone prune <project>Preview or remove graph nodes matching the given criteria. Runs in preview mode by default. All criteria are ANDed — a node must match all specified filters to be removed.
| Flag | Description |
|---|---|
--older-than <days> |
Remove nodes older than N days |
--confidence-below <float> |
Remove nodes with confidence below this value |
--source <pattern> |
Remove nodes whose source contains this substring |
--execute |
Actually delete matched nodes (default: preview only) |
waystone vacuum
waystone vacuum <project>Remove stale nodes that have never been retrieved by any query. Deletes nodes satisfying all of: hit count = 0, older than --min-age-days, and confidence below --max-confidence. Keeps the graph lean without touching recently extracted or actively retrieved nodes.
| Flag | Default | Description |
|---|---|---|
--min-age-days <n> |
90 | Only prune nodes older than N days |
--max-confidence <float> |
0.75 | Only prune nodes with confidence below this value |
--dry-run |
false | Preview what would be removed without deleting |
waystone export
waystone export <project> [-o output.md]Export the full graph as markdown, with optional strategy filtering. If no output file is given, prints to stdout.
waystone export my-project -o full-context.md
waystone export my-project | pbcopywaystone pin / unpin / pinned
waystone pin <project> <node-id>
waystone unpin <project> <node-id>
waystone pinned <project>Pin a node to make it always appear in query results, regardless of relevance score. Useful for project-wide constraints, personas, or standing context that should never be filtered out. waystone pinned lists all pinned nodes in a project.
waystone sources
waystone sources <project>List all source transcripts or files that have contributed nodes to the project graph, with node counts per source.
waystone history
waystone history <project> <node-id>Show the full edit history of a single node — all versions, supersession events, and confidence changes over time.
waystone hook-init
waystone hook-init <project> [--dir <path>]Mark a directory so the Claude Code hook auto-detects the correct project. Creates a .context-broker marker file containing the project name. The hook reads this file when determining which graph to query at session start.
# Mark current directory
waystone hook-init my-project
# Mark a specific directory
waystone hook-init my-project --dir ~/code/my-appwaystone watch
waystone watch <project> [--paths <dir>]Watch a directory for new or modified files and automatically extract them into the project graph. Useful for continuously keeping memory in sync with a notes folder or writing workspace.
waystone mcp-serve
waystone mcp-serve [--project <name>] [--transport stdio|sse]Start the MCP server. See the MCP Server docs for editor configuration.
| Flag | Description |
|---|---|
--project <name> |
Scope all tool calls to one project by default |
--transport <mode> |
stdio (default, for Claude Code / Cursor / Windsurf) or sse (for HTTP clients) |
waystone serve
waystone serve [--host <addr>] [--port <n>]Start the REST API server. Requires the api extra: pip install 'waystone[api]'. Defaults to 0.0.0.0:8000. See the REST API docs for endpoint reference.
| Flag | Description |
|---|---|
--host <addr> |
Bind address (default: 0.0.0.0) |
--port <n> |
Port to listen on (default: 8000) |
--reload |
Auto-reload on code changes (dev mode only) |
waystone doctor
waystone doctorRun a preflight check: config validity, LLM reachability, project marker detection, and MCP server status. Prints a checklist of what's working and what needs attention. Run this first when diagnosing setup issues.
waystone feedback
waystone feedback <project> <node-id> [--rating up|down]Record feedback on a retrieved node. Thumbs-up/down ratings feed into future confidence scoring. Use --export-path to export a feedback report for fine-tuning or analysis.