Personal RAG

# personal-rag

Tiny writable personal knowledge base exposed through MCP.

## Features

- Single Go process
- SQLite database (`knowledge.db`)
- SQLite FTS5 full-text search
- MCP over stdio
- Separate raw text and structured facts
- No embeddings, vector DB, Docker, Redis or external services

## MCP tools

- `knowledge_add_text`
- `knowledge_add_fact`
- `knowledge_search`
- `knowledge_update` (Titel, Inhalt und Tags eines Texteintrags per ID ändern)
- `knowledge_delete`
- `knowledge_stats`

The write tools explicitly say they should only be used when the user asks to persist knowledge.

## Build

```powershell
.\build.ps1
```

Das Skript führt die Tests aus und erzeugt ZIP-Archive für Windows, Linux und
macOS auf amd64 und arm64 unter `dist/`.

## Project structure

```text
cmd/personal-rag/  Application source and tests
go.mod             Go module definition
README.md          Usage documentation
LICENSE            MIT license
```

## Run

```powershell
Expand-Archive .\dist\personal-rag-windows-amd64.zip -DestinationPath .\dist\windows-amd64
.\dist\windows-amd64\personal-rag-windows-amd64.exe
```

The server talks MCP on stdin/stdout. Do not type into it manually; configure it as a local MCP command in your client.

Optional kann MCP über Streamable HTTP bereitgestellt werden:

```sh
./personal-rag --http 0.0.0.0:8080 --db-path /data --auth-token 'change-me'
```

Alternativ kann das Token über die Umgebung gesetzt werden:

```sh
export PERSONAL_RAG_AUTH_TOKEN='change-me'
./personal-rag --http 0.0.0.0:8080 --db-path /data
```

HTTP-Anfragen müssen `Authorization: Bearer <token>` mitsenden. Ohne Token startet
der HTTP-Modus nicht. Ohne `--http` verwendet der Server weiterhin stdio und
benötigt kein Token. TLS und Reverse Proxy werden bei Bedarf extern bereitgestellt.

Für Clients, die keine eigenen Header setzen können, wird alternativ ein exakt
passender Token-Pfad akzeptiert:

```text
https://rag.example.com/token=<token>
```

Der Header ist vorzuziehen, weil URLs von Reverse Proxies und anderen Systemen
protokolliert werden können.

By default the DB is `knowledge.db` in the process working directory. Override it with:

```powershell
.\dist\windows-amd64\personal-rag-windows-amd64.exe --db-path C:\Users\you\Knowledge
```

`--db-path` bezeichnet das Verzeichnis, das `knowledge.db` enthält. Ein fehlendes
Verzeichnis wird automatisch angelegt. Die bisherige Umgebungsvariable
`PERSONAL_RAG_DB` (vollständiger Dateipfad) bleibt als Fallback kompatibel.

Beim Hinzufügen wird ein Eintrag mit exakt gleichem Inhalt nicht dupliziert;
stattdessen liefert das Tool die vorhandene ID und `already_exists: true` zurück.

## Suggested MCP policy

- Search freely when personal context could help.
- Write only after an explicit user request such as “merken”, “speichern”, or “ins RAG”.
- Prefer `knowledge_add_fact` for stable atomic facts.
- Prefer `knowledge_add_text` for notes, project summaries and longer context.

## License

MIT