RAG

RAG#

RAG (Retrieval-Augmented Generation) tool for context-aware assistance.

The RAG tool provides context-aware assistance by indexing and semantically searching text files.

Installation

The RAG tool requires the gptme-rag CLI to be installed:

pipx install gptme-rag

Configuration

Configure RAG in your gptme.toml:

[rag]
enabled = true
post_process = false # Whether to post-process the context with an LLM to extract the most relevant information
post_process_model = "openai/gpt-4o-mini" # Which model to use for post-processing
post_process_prompt = "" # Optional prompt to use for post-processing (overrides default prompt)
workspace_only = true # Whether to only search in the workspace directory, or the whole RAG index
paths = [] # List of paths to include in the RAG index. Has no effect if workspace_only is true.

Features

  1. Manual Search and Indexing

    • Index project documentation with rag_index

    • Search indexed documents with rag_search

    • Check index status with rag_status

  2. Conversation Indexing

    • Index past gptme conversations with rag_index_conversations

    • Only indexes user and assistant messages (skips system prompts)

    • Enables semantic search across your conversation history

Explicit project indexes use <gptme data dir>/rag/projects-v2/<SHA-256 of the exact UTF-8 project name>. Indexing, search and status share this identity; case, punctuation and whitespace are significant. Omitting project (or passing an empty string) still uses the CLI’s global index.

Legacy rag/<sanitized-name> directories are never selected or changed, even for ordinary names: sanitization did not record the original identity, so their contents may belong to another name. After upgrading, explicitly rebuild each project from its own source files with rag_index("/path/to/project", project="exact project name"). Search and status use the new index immediately, without falling back to old data. Keep legacy directories as backups; there is no automatic migration.

  1. Automatic Context Enhancement

    • Retrieves semantically similar documents

    • Preserves conversation flow with hidden context messages

Instructions

### When to use RAG

Use RAG for semantic search across indexed documents when you do not know the
exact file location or keyword. Prefer `shell` with grep/ripgrep for exact
string or pattern matching. Use `read` when you already know the file path.
Index first with `rag_index`, then search with `rag_search`.

Examples

User 
Index the current directory
Assistant 
Let me index the current directory with RAG.
ipython


rag_index()
System 
Indexed 1 paths
User 
Search for documentation about functions
Assistant 
I'll search for function-related documentation.
ipython


rag_search("function documentation")
System 
### docs/api.md
Functions are documented using docstrings...
User 
Show index status
Assistant 
I'll check the current status of the RAG index.
ipython


rag_status()
System 
Index contains 42 documents
User 
Index my past conversations so I can search them
Assistant 
I'll index your recent conversations with RAG.
ipython


rag_index_conversations()
System 
Indexed 47 conversations.
Indexed 47 paths
User 
Index only the last 10 conversations
Assistant 
I'll index just the 10 most recent conversations.
ipython


rag_index_conversations(n=10)
System 
Indexed 10 conversations.
Indexed 10 paths
gptme.tools.rag.get_rag_context(query: str, rag_config: RagConfig, workspace: Path | None = None) → Message

Get relevant context chunks from RAG for the user query.

gptme.tools.rag.init() → ToolSpec

Initialize the RAG tool.

gptme.tools.rag.rag_index(*paths: str, glob: str | None = None, project: str | None = None) → str

Index documents in specified paths.

Parameters:

  • paths – Paths to index (files or directories). Defaults to current directory.

  • glob – Glob pattern to filter files.

  • project – Project name to scope the index to. When set, documents are stored in a project-specific index isolated from all other projects and the global index. When omitted, uses the global index.

gptme.tools.rag.rag_index_conversations(n: int = 100, output_dir: str | None = None) → str

Index past gptme conversations for semantic search.

Exports user and assistant messages from conversation logs (skipping system prompts) into text files and indexes them with gptme-rag.

Parameters:

  • n – Maximum number of recent conversations to index (default: 100).

  • output_dir – Directory to write exported conversation files. Defaults to a temporary directory managed by gptme-rag.

Returns:

Status message from the indexing operation.

gptme.tools.rag.rag_search(query: str, return_full: bool = False, top_k: int | None = None, project: str | None = None) → str

Search indexed documents.

Parameters:

  • query – Search query.

  • return_full – Return full document content instead of excerpts.

  • top_k – Maximum number of results to return.

  • project – Project name to restrict the search to. Must match the project used when indexing. When omitted, searches the global index.

gptme.tools.rag.rag_status(project: str | None = None) → str

Show index status.

Parameters:

project – Project name to show status for. When set, shows information about the project-specific index directory. When omitted, shows the global index status.