Skip to main content
know is a semantic search CLI that lets you query your local documents using natural language. This guide will get you indexing and searching in minutes.

​
Quick Start

1

Add a directory to watch

Tell know which directory to index:
know add ~/Documents/notes
You can add multiple directories:
know add ~/Projects/docs
know add ~/Downloads/papers
Use know dirs to see all watched directories at any time.
2

Index your files

Build the search index from your watched directories:
know index
This will:
  • Scan all watched directories for supported file types
  • Chunk documents into searchable segments
  • Generate and store embeddings locally in ./know_index
Indexing creates a know_index directory in your current working directory. Subsequent index runs only process new or changed files.
3

Search your documents

Query your indexed files using natural language:
know "retrieval augmented generation"
know returns ranked results with context:
Results for: retrieval augmented generation

#  File                          Score    Path
1  rag-notes.md                 0.234    ~/Documents/notes/ai/rag-notes.md
2  llm-architectures.md         0.456    ~/Documents/notes/ai/llm-architectures.md
3  semantic-search.txt          0.512    ~/Documents/research/semantic-search.txt

​
Common Workflows

​
Search with filters

Limit results to specific file types or recently modified files: 
know "API documentation" --glob "**/*.md"

​
Incremental indexing

Index only files modified in the last week: 
know index --since 7d
This is useful for large document collections where you want to quickly update the index.

​
Try different search modes

know supports multiple search strategies:
Semantic vector search using embeddings:
know "machine learning concepts"
Best for: Conceptual queries, finding similar topics

​
Preview changes without indexing

Use dry run mode to see what would be indexed: 
know index --dry
This shows you:
  • How many new documents would be added
  • How many unchanged documents would be skipped
  • No actual changes to the index

​
Understanding Results

​
Distance scores

For dense (vector) search, lower scores indicate better matches:
  • 0.0 - 0.3: Highly relevant
  • 0.3 - 0.5: Moderately relevant
  • 0.5+: Less relevant
Scores are cosine distances. A score of 0 means identical vectors, while higher values indicate greater dissimilarity.

​
Result limit

By default, know returns 5 results. Adjust with --limit: 
know "python testing" --limit 10

​
Managing Your Index

​
View watched directories

See all directories currently being tracked: 
know dirs

​
Remove old files from index

Clean up chunks from deleted files: 
know prune
Running prune permanently removes chunks for files that no longer exist on disk.

​
Start fresh

Clear the entire index and start over: 
know reset
Then re-index: 
know index

​
Next Steps

Commands Reference

Explore all available commands and options

Search Modes

Learn about dense, BM25, and hybrid search

Filtering Results

Master glob patterns and time-based filters

Output Formats

Export results as JSON or plain text

​
Tips for Better Results

Use natural language queries - know understands semantic meaning, so “how to handle errors in async functions” works better than just “error handling”
Combine search modes - Try --benchmark to compare dense vs BM25 results side-by-side and see which works better for your query
Organize by directory - Keep related documents in the same directory, then use --glob patterns to search within specific areas

Build docs developers (and LLMs) love

Get started for freeTalk to us