# pi-knowledge

Local-first RAG knowledge base for Pi and OMP coding agents.

Index your codebase, docs, PDFs, URLs, and notes into persistent knowledge bases that Pi and [OMP](https://omp.sh/) can search across sessions. `pi-knowledge` combines semantic embeddings, BM25 keyword search, code-aware chunking, reranking, diagnostics, and stable large-project indexing so agents can answer from your actual project knowledge instead of guessing.

Built as a native [Pi extension](https://pi.dev/docs/latest/extensions) with verified [OMP](https://omp.sh/) compatibility through the packaged extension entry. Designed for local-first project memory, agentic code search, and retrieval-augmented development workflows.

## Why It Matters

Agents lose project context between sessions and cannot fit large repositories into one prompt. `pi-knowledge` gives Pi and OMP durable, searchable project memory:

- Search code and documentation by meaning, exact symbols, or both. - Look up lightweight code symbols, Markdown headings, config keys, and environment variables before broader search. - Keep private source data local by default. - Re-index changed files incrementally. - Diagnose stale, stuck, or low-quality indexes. - Handle large repositories with persisted progress instead of silent hangs.

Unlike `pi-memory` (which manages the agent's own notes), `pi-knowledge` indexes **your existing files** and makes them semantically searchable by the agent.

## Highlights

- **Local-first project memory**: stores indexes under `~/.pi/knowledge/`; no project files are modified. - **Hybrid retrieval**: lexical-anchored BM25 + semantic vectors + normalized weighted score fusion, with semantic mode for vector-only conceptual recall. - **Code-aware indexing**: AST-aware chunking for TypeScript/JavaScript, Python, Go, Rust, and Java. - **Lightweight symbol lookup**: indexes functions, classes, interfaces, types, variables, route-like handlers, Markdown headings, config keys, and env vars for exact