# factq

**Your LLM's Local Source of Truth**

A local-first knowledge base and verification engine that sits between you and your AI tools. It answers from proven knowledge first, validates through executable code when needed, and gets smarter with every query.

## Install

```bash
pip install factq
```

## Quick Start

```python
import factq

# Initialize from project root — auto-indexes docs/ folder
fq = factq.init(".")

# Query checks project docs first, then KB, then Deepthink
result = fq.query("What version of Pydantic does our project use?")
# result.source: 'docs' | 'kb' | 'deepthink'

# Save a verified finding to the project's docs/ folder
fq.save("docs/research/pydantic_v2_migration.md", result)
```

Or from the CLI:

```bash
factq init                                    # index current project
factq query "What is our database schema?"    # docs-first resolution
factq save docs/research/schema_notes.md      # commit a finding
```

## How It Works

```
Query → KB Lookup (docs/ folder, milliseconds)
  → Deepthink (LLM writes Python to verify, sandbox execution)
    → Commit (verified fact saved back to docs/, git-versioned)
```

1. **Docs-First Resolution** — Your project's `docs/` folder is the first source of truth
2. **Executable Verification** — When docs can't answer, factq writes and runs Python code to verify facts in a secure sandbox
3. **Self-Growing Knowledge** — Verified facts are saved back as markdown files, version-controlled in git
4. **MCP Server** — Runs as a local MCP server for Claude Code, Cursor, and Windsurf

## Why factq?

| | Traditional RAG | Cloud Search | **factq** |
|---|---|---|---|
| **Verification** | Text similarity | Citation links | Executable code proof |
| **Infrastructure** | 3-6 GB VRAM | Cloud API | Zero VRAM, ~28 MB |
| **Knowledge Persistence** | Ephemeral chunks | None | Git-versioned docs/ |
| **Offline** | Partial | No | **Fully offline** |
| **Gets Smarter Over Time** | No | No | **Yes** |

## Development

```bash
git clone https://github.com/factq-dev/factq-cli.git
cd factq-cli
uv sync
uv run pytest tests/ -v
```

## License

Apache-2.0
