GrokDocs
minhhh/grokdocs
Indexador local com busca semântica e full-text para código e documentação
Ver no GitHubMotor de busca local-first que indexa Markdown e código com busca híbrida (full-text + semantic). Funciona como MCP server para LLMs, reduzindo drasticamente o consumo de tokens de contexto através de recuperação inteligente de chunks semanticamente relevantes.
Instalação
npx convez-ai minhhh/grokdocs1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Recuperar chunks relevantes de código/docs sem sobrecarregar contexto do LLM
- Implementar RAG local com embeddings on-device (ONNX)
- Indexar e consultar grandes bases de documentação técnica incrementalmente
Veredito

Ferramenta sólida e bem-arquitetada para RAG local eficiente. Ideal para desenvolvedores que precisam integrar busca semântica em workflows com Claude sem depender de APIs externas, mantendo privacidade dos dados.
README
A tradução para o português deste README ainda está na fila.
grokdocs
Overview
grokdocs is a local-first search engine that indexes your Markdown and code files for semantic and full-text search. It splits your documentation and code files into semantically meaningful chunks, generates local embeddings, and indexes them using SQLite (FTS5) and FAISS for fast similarity and keyword search.
Core Features
1. Document Ingestion & Chunking
- Multi-format Support: Parse Markdown, plain text, and Go source files.
- Intelligent Chunking: Use
gomantics/chunkxto break down large documents into semantically meaningful chunks rather than arbitrary character counts. - Incremental Indexing: Track file modification times (mtime) and content hashes. Only re-chunk and re-embed files that have actually changed to save compute time.
2. Hybrid Search Engine
- Generate embeddings for each chunk using a local ONNX model on-device.
- Store embeddings in a local FAISS index for semantic search, and insert chunk text into SQLite for Full-Text Search.
- Combine vector similarity and lexical search to retrieve the most relevant chunks using an adjustable hybrid weighting scheme (
--alpha).
Build & Installation
Prerequisites
- Go 1.21 or later.
- C/C++ compiler (e.g.,
gccorclang) if building with CGO dependencies (such as FAISS viago-faiss).
Building from Source
Clone the repository and build the binary:
go build -tags fts5 ./cmd/grokdocs
This produces a grokdocs executable in the root directory.
Running Tests
go test ./...
Note: Tests requiring SQLite FTS5 (go test -tags fts5) will be skipped if your system SQLite build lacks the FTS5 module. Run them explicitly with:
go test -tags fts5 ./...
Quick Start
To view all available commands and flags, run:
./grokdocs --help
Project Structure & Workspace Configuration
grokdocs organizes index data and configuration inside a .grokdocs folder located at the root of your project:
my-project/
├── .grokdocs/
│ ├── config.yaml # Project configuration
│ ├── grokdocs.db # FTS database (SQLite schema and FTS5 keyword index)
│ └── grokdocs.index # Vector database (FAISS index file for semantic search)
├── docs/
│ └── readme.md
└── src/
└── main.go
Configuration File (config.yaml)
A default config.yaml is generated inside .grokdocs/ upon calling grokdocs init:
collections:
default:
path: "."
parsers:
- markdown
Root Directory Lookup Algorithm
All CLI commands support a global -p, --project <path> flag to specify the workspace root. If the flag is omitted:
grokdocsstarts searching at the current working directory (.).- It walks up the parent directories recursively looking for a
.grokdocsfolder. - If no
.grokdocsdirectory is found up to the filesystem root, it falls back to the current directory (.) as the project root.
CLI Interface
All commands support the global -p, --project <path> flag. If -p is omitted, the CLI uses the lookup algorithm above to discover the project workspace.
grokdocs init: Initialize the workspace and generate a default configuration file (config.yaml) inside the.grokdocsdirectory.grokdocs sync: Scan directories and synchronize files into the SQLite database and FAISS index.--all: Sync all configured collections.--collection <name>: Sync only the specified collection.
grokdocs search "<query>": Perform a hybrid search and return matching chunks.--collection <name>: Limit search query to the specified collection.--mode <hybrid|vector|fts>: Specify the search strategy (default:hybrid).--alpha <float>: Weight multiplier between FTS and vector results (0.0 = pure FTS, 1.0 = pure Vector, default: 0.5).--limit <int>: Number of results to return (default: 5).