Dein KI-Agent kennt dein Projekt nicht. Alcove ändert das.
English ·
한국어 ·
日本語 ·
简体中文 ·
Español ·
हिन्दी ·
Português ·
Deutsch ·
Français ·
Русский
Alcove ist ein HTTP-API-Server, der KI-Codierungs-Agenten bedarfsgesteuerten Zugriff auf deine private Projektdokumentation gibt — **BM25 + Vektor-Hybridsuche** für präzise Abrufe, **tree-sitter Code-Indexierung** damit Agenten deine Codebasis-Struktur verstehen, und **Policy-Durchsetzung** für Dokumentkonsistenz. Kein Context-Bloat, keine Doc-Leaks in öffentliche Repos, keine Projekt-für-Projekt-Konfiguration für jeden Agenten.
Speichere PRDs, Architekturentscheidungen, Secret-Maps und interne Runbooks an einem Ort. Alle KI-Agenten erhalten dieselben Tools, über alle Projekte hinweg, ohne Konfiguration pro Projekt.
## Demo
> *Claude, Codex — Suche · Projektwechsel · globale Suche · Validierung & Generierung. Ein Setup.*
CLI-Demo
> *`alcove search` · Projektwechsel · `--scope global` · `alcove validate`*
## Das Problem
Dein KI-Agent startet jede Session von null.
Er kennt deine Architektur nicht. Ignoriert Einschränkungen aus bereits getroffenen Entscheidungen. Bittet dich jede Session, dieselben Dinge zu erklären.
Das Kontextfenster ist der Flaschenhals. Jeder Token kostet Geld und Aufmerksamkeit. 10 Architektur-Dokumente in den Kontext zu laden verschwendet 50K+ Tokens bei jeder Ausführung — und Anthropic's eigene Docs warnen, dass aufgeblähte Config-Dateien Agenten dazu bringen, *deine tatsächlichen Anweisungen zu ignorieren*.
Du hast also drei schlechte Optionen:
**Alles in die Agent-Konfiguration stopfen** — jede Datei wird bei jeder Ausführung in den Kontext geladen. 10 Docs = Kontext-Aufblähung = langsamere, teurere, ungenauere Antworten.
**In jeden Chat kopieren** — funktioniert einmal, skaliert nicht über eine Session hinaus.
**Einfach lassen** — dein Agent erfindet Anforderungen, die du bereits dokumentiert hast, ignoriert Einschränkungen aus bereits getroffenen Entscheidungen, und du erklärst dieselbe Architektur jeden Montagmorgen neu.
Multipliziere das mit 5 Projekten und 3 Agenten. Jedes Mal wenn du wechselst, verlierst du den Kontext.
## Wie Alcove das löst
Alcove speichert alle deine privaten Dokumente in **einem gemeinsamen Repository**, organisiert nach Projekt. Alle Agenten greifen über HTTP API auf dieselbe Weise darauf zu — egal ob du Claude Code, Cursor, Antigravity oder Codex verwendest.
```
~/projects/my-app $ claude "/alcove Wie ist die Authentifizierung implementiert?"
→ Alcove erkennt Projekt: my-app
→ Liest ~/documents/my-app/ARCHITECTURE.md
→ Agent antwortet mit echtem Projektkontext
```
```
~/projects/my-api $ codex "/alcove Überprüfe das API-Design"
→ Alcove erkennt Projekt: my-api
→ Gleiche Dokumentstruktur, gleiches Zugriffsmuster
→ Anderes Projekt, gleicher Workflow
```
**Wechsle den Agenten jederzeit. Wechsle das Projekt jederzeit. Die Dokumentschicht bleibt standardisiert.**
## Hauptfunktionen
- **Ein Docs-Repository, mehrere Projekte** — private Dokumente nach Projekt organisiert, an einem Ort verwaltet
- **Einmal einrichten, jeder Agent** — einmal konfigurieren, jeder KI-Agent erhält dieselben Tools
- **Automatische Projekterkennung** vom CWD — keine Konfiguration pro Projekt nötig
- **Bereichsbezogener Zugriff** — jedes Projekt sieht nur seine eigenen Dokumente
- **Intelligente Suche** — BM25-Ranking-Suche mit automatischer Indexierung; findet die relevantesten Dokumente zuerst, fällt bei Bedarf auf grep zurück
- **Projektübergreifende Suche** — suche in allen Projekten gleichzeitig mit `scope: "global"` — nutze es als persönliche Wissensdatenbank
- **Private Dokumente bleiben privat** — sensible Dokumente (Secret-Map, interne Entscheidungen, technische Schulden) berühren nie dein öffentliches Repository
- **Standardisierte Dokumentstruktur** — `policy.toml` erzwingt konsistente Dokumente über alle Projekte und Teams
- **Cross-Repo-Audit** — findet fehlplatzierte interne Dokumente im Projektrepository und schlägt Korrekturen vor
- **Dokumentvalidierung** — prüft auf fehlende Dateien, unausgefüllte Templates, erforderliche Abschnitte
- **Semantisches Lint** — erkennt automatisch defekte Wikilinks, verwaiste Dateien, veraltete WIP/DRAFT-Markierungen und Datumsangaben älter als 2 Jahre
- **Import aus externen Vaults** — bringt eine Notiz aus Obsidian (oder einem anderen Vault) mit einem Befehl ins doc-repo; automatisches Routing zum richtigen Projekt
- **Funktioniert mit 9+ Agenten** — Claude Code, Cursor, Claude Desktop, Cline, OpenCode, Codex, Copilot, Antigravity
## Warum Alcove
| Ohne Alcove | Mit Alcove |
|-------------|------------|
| Interne Dokumente verstreut über Notion, Google Docs, lokale Dateien | Ein Docs-Repository, nach Projekt strukturiert |
| Jeder KI-Agent separat für Dokumentzugriff konfiguriert | Einmal einrichten, alle Agenten teilen dieselben Tools |
| Projektwechsel bedeutet Verlust des Dokumentkontexts | CWD-Autoerkennung, sofortiger Projektwechsel |
| Agentensuche liefert zufällige Treffer | Hybridsuche (BM25 + RAG) — Agenten rufen nur ab, was sie brauchen, nach Relevanz sortiert |
| Agent sieht nur Textdokumente, nicht die Codestruktur | tree-sitter Code-Indexierung — Agenten verstehen Module, Funktionen und Typen in 12 Sprachen |
| "Alle meine Notizen zur Authentifizierung durchsuchen" — unmöglich | Globale Suche über alle Projekte in einer Abfrage |
| Sensible Dokumente riskieren Leak in öffentliche Repos | Private Dokumente physisch von Projekt-Repos getrennt |
| Dokumentstruktur variiert pro Projekt und Teammitglied | `policy.toml` erzwingt Standards über alle Projekte |
| Keine Möglichkeit zu prüfen, ob Dokumente vollständig sind | `validate` erkennt fehlende Dateien, leere Templates, fehlende Abschnitte |
| Defekte Links oder WIP-Markierungen bleiben unbemerkt | `lint` erkennt automatisch defekte Links, verwaiste Dateien und veraltete Markierungen |
| Notizen aus Obsidian oder anderen Tools bleiben isoliert | `promote` integriert externe Notizen mit einem Befehl ins doc-repo |
## Schnellstart
> **Erforderlich**: Führen Sie einmal `alcove setup` nach der Installation aus, um Ihr Dokumentenverzeichnis zu konfigurieren und die volle Funktionalität zu aktivieren. Plugins starten den API-Server automatisch, aber Alcove kann Dokumente erst durchsuchen und indizieren, wenn `setup` ausgeführt wurde.
>
> **Obsidian-Nutzer?** Informationen zur empfohlenen Dokumentstruktur und Vault-Konfiguration finden Sie im Abschnitt [Ökosystem](#ecosystem).
### Claude Code
```
/plugin marketplace add epicsagas/plugins
/plugin install alcove@epicsagas
```
Installiert automatisch das Binary und startet den API-Server beim nächsten Sitzungsstart.
> **Erforderlich**: Führe `alcove setup` einmal nach der Installation aus, um dein Dokumenten-Root zu konfigurieren und die volle Funktionalität zu aktivieren. Das Plugin startet den API-Server automatisch, aber Alcove kann erst nach Ausführung von `setup` Dokumente suchen oder indexieren.
```bash
alcove setup # einmal nach der Plugin-Installation ausführen
```
Aktualisierungen mit `claude plugin update epicsagas/alcove`.
### Codex CLI
```bash
codex plugin install alcove@epicsagas
```
Installiert automatisch das Skill und startet den API-Server. Sofort verfügbar — keine weiteren Schritte erforderlich.
Aktualisierungen mit `codex plugin update alcove@epicsagas`.
### macOS (nur Apple Silicon)
```bash
brew install epicsagas/tap/alcove
```
Kein Homebrew? Verwende das Installationsskript:
```bash
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/epicsagas/alcove/releases/latest/download/alcove-installer.sh | sh
```
### Linux (x86_64 / ARM64)
```bash
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/epicsagas/alcove/releases/latest/download/install.sh | sh
```
### Windows (x86_64 / ARM64)
```powershell
irm https://github.com/epicsagas/alcove/releases/latest/download/install.ps1 | iex
```
### Antigravity (Gemini CLI)
```bash
agy plugins install https://github.com/epicsagas/alcove
```
Installiert automatisch das Plugin (API-Server, Skill, Hooks) und startet es beim nächsten Sitzungsstart.
```bash
alcove setup # run once after plugin install
```
### Über die Rust-Werkzeugkette
```bash
cargo binstall alcove # vorgefertigtes Binary, Hybrid-Suche inklusive
cargo install alcove --features full-macos # aus Quellcode bauen (macOS)
cargo install alcove --features full-cross # aus Quellcode bauen (Linux/Windows)
```
> **Hinweis**: `cargo binstall` lädt ein vorgefertigtes Binary mit Hybrid-Suche (Vektor + BM25) herunter. Beim Bauen aus dem Quellcode ist `--features full-macos` oder `--features full-cross` für Hybrid-Suche erforderlich. Ohne Features ist nur BM25-Suche (Schlüsselwort) verfügbar.
### Ersteinrichtung (erforderlich)
Nach der Installation mit einer der obigen Methoden, führe aus:
```bash
alcove setup
alcove --version
alcove doctor
```
`setup` führt dich interaktiv durch alles:
1. Wo deine Dokumente liegen
2. Welche Dokumentkategorien verfolgt werden sollen
3. Bevorzugtes Diagrammformat
4. Embedding-Modell für hybride Suche
5. **Hintergrund-Server** — Kaltstart bei jeder Sitzung eliminieren (macOS-Login-Objekt)
6. Welche KI-Agenten konfiguriert werden sollen (Skill-Dateien — Claude Code und Codex werden über ihre Plugin-Systeme verwaltet)
Führe `alcove setup` jederzeit erneut aus, um Einstellungen zu ändern. Es merkt sich deine vorherigen Auswahlen.
**Optionale Abhängigkeiten**
| Tool | Zweck | Installation |
|---|---|---|
| `pdftotext` (poppler) | Vollständige PDF-Textextraktion — erforderlich für PDF-Suche | macOS: `brew install poppler` · Debian/Ubuntu: `apt install poppler-utils` · Fedora: `dnf install poppler-utils` · Windows: [poppler for Windows](https://github.com/oschwartz10612/poppler-windows/releases) |
Ohne `pdftotext` fällt Alcove auf einen integrierten PDF-Parser zurück, der bei einigen Dateien fehlschlagen kann. Führe `alcove doctor` aus, um deine Installation zu überprüfen.
### Problembehebung
**Agent findet Alcove-Tools nicht**
Führen Sie `alcove setup` erneut aus — es rekonfiguriert den API-Server für alle konfigurierten Agenten. Starten Sie dann eine neue Agentensitzung (die Registrierung wird beim nächsten Sitzungsstart wirksam).
**Suche liefert keine Ergebnisse**
Der Index wurde möglicherweise noch nicht erstellt. Führen Sie `alcove index` aus und versuchen Sie es erneut.
**403 Unauthorized vom Hintergrundserver**
`ALCOVE_TOKEN` ist in Ihrer Shell nicht gesetzt. Führen Sie `alcove token` aus, um es anzuzeigen, fügen Sie dann `export ALCOVE_TOKEN="..."` zu Ihrem Shell-Profil hinzu und laden Sie es neu.
**`alcove doctor` meldet Probleme**
Befolgen Sie die von `doctor` ausgegebenen Vorschläge — es prüft Binärdatei-Speicherort, API-Server-Status, Index-Status und optionale Abhängigkeiten wie `pdftotext`.
## Verwendung
### CLI-Suche
Durchsuchen Sie Ihre Dokumente direkt vom Terminal aus. Standardmäßig wird über **alle Projekte** hinweg gesucht (globaler Bereich).
```bash
# Einfache Suche (globaler Bereich)
alcove search "authentication"
# Suche auf das aktuelle Projekt beschränken (automatisch erkannt via CWD)
alcove search "auth flow" --scope project
# Grep-Modus erzwingen (exakte Teilstring-Suche)
alcove search "TODO" --mode grep
# Ranking-Modus erzwingen (BM25/Hybrid)
alcove search "data model" --mode ranked
# Ergebnislimit anpassen
alcove search "deployment" --limit 5
```
### Codierungs-Agenten (HTTP API)
KI-Codierungs-Agenten nutzen Alcove über eine **lokale HTTP API** auf Port 58301. Skills rufen intern `curl http://localhost:58301/...` auf. Normalerweise müssen Sie diese nicht selbst aufrufen; der Agent ruft sie auf, wenn Sie Fragen zu Ihrem Projekt stellen.
| Endpunkt | Methode | Beschreibung |
|----------|---------|--------------|
| `/health` | GET | Health-Check — prüfen ob der API-Server läuft |
| `/search?q=...` | GET | Dokumentensuche (Query-Parameter) |
| `/v1/search` | POST | Suche mit JSON-Body (scope, limit, mode) |
| `/projects` | GET | Alle Projekte im Doc-Repository auflisten |
| `/projects` | POST | Neues Projekt aus Vorlagen initialisieren |
| `/projects/{name}/docs` | GET | Dokumente eines Projekts mit Größen und Klassifizierung auflisten |
| `/projects/{name}/audit` | GET | Dokumentengesundheit prüfen (fehlend, veraltet, fehlplatziert) |
| `/projects/{name}/validate` | GET | Dokumente gegen policy.toml validieren |
| `/projects/{name}/config` | PUT | Projekteinstellungen in alcove.toml aktualisieren |
| `/docs/{path}` | GET | Bestimmte Dokumentdatei lesen (Query: `project`, `offset`, `limit`) |
| `/rebuild` | POST | Suchindex neu aufbauen |
| `/changes` | GET | Geänderte Dateien seit letzter Indexierung prüfen (Query: `auto_rebuild`) |
| `/lint` | GET | Docs linten — defekte Links, verwaiste Dateien, veraltete Markierungen (Query: `project`) |
| `/vaults` | GET | Alle Wissensdatenbank-Vaults auflisten |
| `/vaults/search?q=...` | GET | Vaults durchsuchen (Query: `vault`, `limit`) |
| `/vaults/backup` | POST | Git-Snapshot des Vault-Zustands |
| `/promote` | POST | Datei ins Doc-Repository importieren |
| `/index-code` | POST | Quellcode über tree-sitter indexieren |
| `/mcp` | POST | JSON-RPC-Proxy (Legacy MCP) |
> **Hinweis**: MCP ist weiterhin für manuelles Setup verfügbar — siehe `registry/mcp.json` für stdio-basierten Zugriff.
**Beispiel für die Interaktion mit dem Agenten:**
> **Benutzer:** "/alcove Wie füge ich einen neuen API-Endpunkt hinzu?"
> **Agent:** (ruft `POST /v1/search` mit `query="add api endpoint"` auf)
> **Agent:** (liest das relevanteste Dokument über `GET /docs/{path}?project=...`)
> **Agent:** "Laut `ARCHITECTURE.md` müssen Sie..."
---
## Funktionsweise
```mermaid
flowchart LR
subgraph Projects["Deine Projekte"]
A1["my-app/\n src/ ..."]
A2["my-api/\n src/ ..."]
end
subgraph Docs["Deine privaten Dokumente (ein Repository)"]
D1["my-app/\n PRD.md\n ARCH.md"]
D2["my-api/\n PRD.md\n ..."]
P1["policy.toml"]
end
subgraph Agents["Jeder KI-Agent"]
AG["Claude Code · Cursor\nCodex · Copilot\n+4 more"]
end
subgraph API["Alcove HTTP-API-Server"]
T["search · get_file\noverview · audit\ninit · validate"]
end
A1 -- "CWD erkannt" --> D1
A2 -- "CWD erkannt" --> D2
Agents -- "HTTP :58301" --> API
API -- "bereichsbezogener Zugriff" --> Docs
```
Deine Dokumente sind in einem separaten Verzeichnis (`DOCS_ROOT`) organisiert, ein Ordner pro Projekt. Alcove verwaltet Dokumente dort und stellt sie über HTTP auf Port 58301 jedem KI-Agenten bereit.
## Dokumentklassifizierung
Alcove klassifiziert Dokumente in folgende Stufen:
| Klassifizierung | Ort | Beispiele |
|----------------|-----|-----------|
| **doc-repo-required** | Alcove (privat) | PRD, Architecture, Decisions, Conventions |
| **doc-repo-supplementary** | Alcove (privat) | Deployment, Onboarding, Testing, Runbook |
| **reference** | Alcove `reports/` Ordner | Audit-Berichte, Benchmarks, Analysen |
| **project-repo** | GitHub-Repository (öffentlich) | README, CHANGELOG, CONTRIBUTING |
Das `audit`-Tool scannt sowohl das Docs-Repository als auch das lokale Projektverzeichnis und schlägt Aktionen vor — wie das Generieren einer öffentlichen README aus deinem privaten PRD oder das Zurückholen fehlplatzierter Berichte nach Alcove.
## API-Endpunkte
| Endpunkt | Methode | Funktion |
|----------|---------|----------|
| `/health` | GET | Health-Check — prüfen ob der API-Server läuft |
| `/search?q=...` | GET | Dokumentensuche (Query-Parameter) |
| `/v1/search` | POST | Suche mit JSON-Body (scope, limit, mode) |
| `/projects` | GET | Alle Projekte auflisten |
| `/projects` | POST | Neues Projekt initialisieren |
| `/projects/{name}/docs` | GET | Dokumente eines Projekts auflisten |
| `/projects/{name}/audit` | GET | Dokumentengesundheit prüfen |
| `/projects/{name}/validate` | GET | Dokumente gegen Policy validieren |
| `/projects/{name}/config` | PUT | Projekteinstellungen aktualisieren |
| `/docs/{path}` | GET | Dokumentdatei lesen |
| `/rebuild` | POST | Suchindex neu aufbauen |
| `/changes` | GET | Geänderte Dateien prüfen |
| `/lint` | GET | Docs linten |
| `/vaults` | GET | Vaults auflisten |
| `/vaults/search?q=...` | GET | Vaults durchsuchen |
| `/vaults/backup` | POST | Vault sichern |
| `/promote` | POST | Datei ins Doc-Repository importieren |
| `/index-code` | POST | Code-Struktur indexieren |
| `/mcp` | POST | JSON-RPC-Proxy (Legacy MCP) |
> **Hinweis**: MCP ist weiterhin für manuelles Setup verfügbar — siehe `registry/mcp.json` für stdio-basierten Zugriff.
## CLI
```
alcove API-Server starten (Agenten rufen das auf)
alcove setup Interaktives Setup — jederzeit erneut ausführen
alcove doctor Gesundheit der Alcove-Installation prüfen
alcove validate Dokumente gegen Policy validieren (--format json, --exit-code)
alcove lint Semantisches Lint — defekte Links, verwaiste Dateien, veraltete Markierungen (--format json)
alcove promote Notizen aus einem externen Vault ins doc-repo importieren
alcove index Suchindex inkrementell aktualisieren (nur geänderte Dateien)
alcove rebuild Suchindex von Grund auf neu aufbauen (nach Schema-Änderungen)
alcove search Dokumente vom Terminal aus suchen
alcove bench Suchqualitäts-Benchmark (Präzision, Latenz, Regressionserkennung) [--corpus]
alcove index-code Code-Struktur-Index aus Quellcode generieren [--language LANG] [--source PATH]
alcove token Bearer-Token ausgeben (für Hintergrund-Server-Authentifizierung)
alcove uninstall Skills, Konfiguration und Legacy-Dateien entfernen
alcove mcp Lebenszyklus des API-Servers im Hintergrund verwalten (start, stop, status, enable, disable)
alcove vault link Externes Verzeichnis als Vault verknüpfen (z. B. Obsidian)
alcove vault list Alle Vaults mit Dokumentanzahl auflisten
alcove vault index Suchindex für Vaults aufbauen
```
### Code-Indexierung
Analysiert Quelldateien mit tree-sitter und generiert `CODE_INDEX.md`—eine modulebene Markdown-Zusammenfassung Ihrer Codebasis, die in die Tantivy-Suchpipeline integriert ist.
```bash
# Aktuelles Projekt indexieren (alle Sprachen automatisch erkennen)
alcove index-code --source ./src
# Monorepo: Verzeichnis mit mehreren Sprachen auf einmal indexieren
alcove index-code --source ./
# Auf eine einzelne Sprache beschränken
alcove index-code --source ./src --language typescript
alcove index-code --source ./src --language rust
```
**Unterstützte Sprachen:**
| Sprache | Feature-Flag | Dateierweiterungen |
|---------|-------------|-------------------|
| Rust | `lang-rust` | `.rs` |
| Python | `lang-python` | `.py`, `.pyi` |
| TypeScript | `lang-typescript` | `.ts`, `.tsx` |
| JavaScript | `lang-javascript` | `.js`, `.jsx`, `.mjs` |
| Go | `lang-go` | `.go` |
| Java | `lang-java` | `.java` |
| Kotlin | `lang-kotlin` | `.kt`, `.kts` |
| C | `lang-c` | `.c`, `.h` |
| C++ | `lang-cpp` | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx`, `.h` |
| Swift | `lang-swift` | `.swift` |
| Ruby | `lang-ruby` | `.rb` |
| C# | `lang-csharp` | `.cs` |
Offizielle Binärdateien aktivieren alle 12 Parser (`lang-all`). Ohne `--language` werden **alle erkannten Erweiterungen automatisch indexiert**—sicher für Monorepos.
`--language` akzeptiert Abkürzungen: `ts` → TypeScript, `cpp` → C++, `csharp` → C#, `py` → Python, `js` → JavaScript, `kt` → Kotlin, `rb` → Ruby.
### Lint
```bash
# Lint des aktuellen Projekts (automatisch aus CWD erkannt)
alcove lint
# Projekt angeben
alcove lint --project my-app
# Maschinenlesbare Ausgabe für CI
alcove lint --format json
```
Lint prüft vier Dinge:
| Prüfung | Was erkannt wird |
|---------|-----------------|
| `broken-link` | `[[Wikilinks]]` oder `[Text](Pfad)` die auf fehlende Dateien zeigen |
| `orphan` | Dateien, auf die kein anderes Dokument verlinkt |
| `stale-marker` | WIP / TODO / FIXME / DRAFT / DEPRECATED Markierungen |
| `stale-date` | Datumsangaben älter als 2 Jahre (z. B. "as of 2022") |
### Promote
```bash
# Obsidian-Notiz ins doc-repo kopieren (automatisches Routing zum Projekt)
alcove promote ~/my-brain/Projects/auth-notes.md
# Bestimmtes Projekt angeben
alcove promote ~/my-brain/Projects/auth-notes.md --project my-app
# Verschieben statt kopieren
alcove promote ~/my-brain/Projects/auth-notes.md --mv
```
Dateien ohne passendes Projekt werden in `inbox/` zur manuellen Überprüfung gespeichert.
### Benchmark
**Isolierter Corpus-Modus** (`--corpus`) verwendet einen eigenständigen Testdatensatz (19 synthetische Dokumente, 25 Abfragen) für schnelle, reproduzierbare CI-Benchmarks — keine echten Dokumente nötig, fertig in unter 60 Sekunden.
```bash
# Gegen das integrierte Eval-Corpus ausführen (empfohlen für CI)
alcove bench --corpus --baseline benches/corpus/baseline.json
# Corpus-Baseline nach bewussten Änderungen aktualisieren
alcove bench --corpus --save-baseline benches/corpus/baseline.json
# Gegen echte Dokumente ausführen (50 Abfragen in 10 Kategorien)
alcove bench --metrics precision
# Als Baseline für zukünftigen Vergleich speichern
alcove bench --output json --save-baseline benches/baseline.json
# Mit Baseline vergleichen — Regressionen in CI erkennen
alcove bench --baseline benches/baseline.json
# Markdown-Bericht
alcove bench --output markdown --output-file bench-report.md
```
| Metrik | Was sie misst |
|--------|---------------|
| Precision@K | Anteil relevanter Dokumente in den Top-K Ergebnissen |
| Recall@K | Anteil gefundener relevanter Dokumente in Top-K |
| NDCG@K | Ranking-Qualität mit Positionsabschlag |
| MAP@K | Durchschnittliche Präzision über alle Abfragen |
| MRR | Reziproker Rang des ersten relevanten Ergebnisses |
| Chunk-Genauigkeit | Ob abgerufene Chunks in den richtigen Abschnitten liegen |
**Regressionsschwellen**: Präzision >5%, Latenz >20%, Durchsatz >15%. Warnung bei der Hälfte des Schwellenwerts.
## Hintergrund-Server
Das Ausführen eines dauerhaften Hintergrund-Servers eliminiert die Kaltstart-Latenz bei jeder neuen Agenten-Sitzung. **`alcove setup` aktiviert dies standardmäßig** (macOS-Login-Objekt).
```bash
alcove mcp enable --now # Aktivieren und starten (bleibt nach Neustarts bestehen)
alcove mcp stop / start / restart / status
alcove mcp disable # Deaktivieren und Login-Objekt entfernen
```
Wenn der Hintergrund-Server läuft, fungiert der stdio-Prozess als leichter Proxy — anstatt bei jeder Sitzung die Such-Engine zu laden, leitet er Anfragen an den aktiven Server weiter. Beim Start prüft der stdio-Prozess `GET /health` und wechselt automatisch in den Proxy-Modus.
## Suche
Alcove wählt automatisch die beste Suchstrategie. Wenn der Suchindex existiert, verwendet es **BM25-Ranking-Suche** (basierend auf [tantivy](https://github.com/quickwit-oss/tantivy)) für relevanzbasierte Ergebnisse. Ohne Index fällt es auf grep zurück. Du musst nie darüber nachdenken.
```bash
# Aktuelles Projekt durchsuchen (automatisch vom CWD erkannt)
alcove search "authentication flow"
# Alle Projekte durchsuchen — deine persönliche Wissensdatenbank
alcove search "OAuth token refresh" --scope global
# Grep-Modus erzwingen für exakte Teilstring-Suche
alcove search "FR-023" --mode grep
```
Der Index wird automatisch im Hintergrund erstellt, wenn der API-Server startet, und wird bei Dateiänderungen automatisch neu aufgebaut. Keine Cron-Jobs, keine manuellen Schritte.
**Wie es für Agenten funktioniert:** Agenten rufen einfach `search_project_docs` mit einer Abfrage auf. Alcove kümmert sich um den Rest — Ranking, Deduplizierung (ein Ergebnis pro Datei), projektübergreifende Suche und Fallback. Der Agent muss nie einen Suchmodus wählen.
### Embedding-Modell wählen
| Modell | Festplatte | Dim | Kontext | Sprachen | Am besten für | Peak-RAM |
|--------|------------|-----|---------|----------|---------------|----------|
| **`ArcticEmbedXS`** (Standard) | **90 MB** | **384** | **512** | **Mehrsprachig** | **Standard — bestes Preis-Leistungs-Verhältnis** | **~400 MB** |
| `ArcticEmbedXSQ` | 90 MB | 384 | 512 | Mehrsprachig | Quantisiert, kleinerer Download | ~400 MB |
| `MultilingualE5Small` | 470 MB | 384 | 512 | 100+ Sprachen | Beste Korean/CJK-Unterstützung | ~1.2 GB |
| `BGEM3` | 600 MB | 1024 | 8192 | 100+ Sprachen | Premium — Dense+Sparse+ColBERT | ~2 GB |
| `ArcticEmbedMLong` | 430 MB | 768 | 8192 | Mehrsprachig | Lange Dokumente | ~1.5 GB |
| `JinaEmbeddingsV2BaseCode` | 550 MB | 768 | 8192 | Code+Englisch | Code-optimiert | ~1.5 GB |
Das Standardmodell ist **ArcticEmbedXS** (90 MB, mehrsprachig). Es bietet die beste Balance aus Größe und Qualität für die meisten Projekte.
Einbettungsmodelle basieren auf [fastembed-rs](https://github.com/Anush008/fastembed-rs) (ONNX Runtime) und laufen vollständig lokal. Um ein anderes Modell zu verwenden, setzen Sie es in `config.toml`:
```toml
[embedding]
model = "BGEM3" # Variable-Name aus der Modelldokumentation
```
Die vollständige Liste der 40+ unterstützten Modelle (Dimensionen, Kontextlänge, Sprachunterstützung) finden Sie in **[EMBEDDING_MODELS.md](../docs/EMBEDDING_MODELS.md)**.
**Speicherbedarf beim Rebuild:**
Die Peak-RAM variiert je nach Modell — siehe die Spalte "Peak-RAM" in der Tabelle oben. Große Modelle (BGEM3, ArcticEmbedMLong) können während des Rebuilds 1.5-2 GB verwenden. Nach Abschluss des Rebuilds sinkt der Ruhezustand auf ~50-200 MB je nach Ihrer `[memory]`-Konfiguration. Sie können den Ruhezustand weiter reduzieren mit niedrigerem `max_hnsw_cache` und kürzerem `model_unload_secs`.
## Projekterkennung
Standardmäßig erkennt Alcove das aktuelle Projekt aus dem Arbeitsverzeichnis deines Terminals (CWD). Du kannst dies mit der Umgebungsvariable `MCP_PROJECT_NAME` überschreiben:
```bash
MCP_PROJECT_NAME=my-api alcove
```
Nützlich, wenn dein CWD nicht mit einem Projektnamen in deinem Docs-Repository übereinstimmt.
## Dokumentrichtlinie
Definiere teamweite Dokumentationsstandards mit `policy.toml` in deinem Docs-Repository:
```toml
[policy]
enforce = "strict" # strict | warn
[[policy.required]]
name = "PRD.md"
aliases = ["prd.md", "product-requirements.md"]
[[policy.required]]
name = "ARCHITECTURE.md"
[[policy.required.sections]]
heading = "## Overview"
required = true
[[policy.required.sections]]
heading = "## Components"
required = true
min_items = 2
```
Policy-Dateien werden mit Priorität aufgelöst: **Projekt** (`/.alcove/policy.toml`) > **Team** (`DOCS_ROOT/.alcove/policy.toml`) > **eingebauter Standard** (core-Dateiliste aus config.toml). Dies stellt konsistente Dokumentqualität über alle Projekte sicher und erlaubt projektspezifische Überschreibungen.
## Konfiguration
Die Konfiguration liegt unter `~/.config/alcove/config.toml`:
```toml
docs_root = "/Users/you/documents"
[core]
files = ["PRD.md", "ARCHITECTURE.md", "PROGRESS.md", "DECISIONS.md", "CONVENTIONS.md", "SECRETS_MAP.md", "DEBT.md"]
[team]
files = ["ENV_SETUP.md", "ONBOARDING.md", "DEPLOYMENT.md", "TESTING.md", ...]
[public]
files = ["README.md", "CHANGELOG.md", "CONTRIBUTING.md", "SECURITY.md", ...]
[diagram]
format = "mermaid"
```
Alles wird interaktiv über `alcove setup` eingestellt. Du kannst die Datei auch direkt bearbeiten.
## Unterstützte Agenten
| Agent | Zugriff | Skill |
|-------|-----|-------|
| Claude Code | `~/.claude.json` | `~/.claude/skills/alcove/` |
| Cursor | `~/.cursor/mcp.json` | `~/.cursor/skills/alcove/` |
| Claude Desktop | Plattformkonfiguration | — |
| Cline (VS Code) | VS Code globalStorage | `~/.cline/skills/alcove/` |
| OpenCode | `~/.config/opencode/opencode.json` | `~/.opencode/skills/alcove/` |
| Codex CLI | `~/.codex/config.toml` | `~/.codex/skills/alcove/` |
| Copilot CLI | `~/.copilot/mcp-config.json` | `~/.copilot/skills/alcove/` |
| Antigravity | `agy plugins install` | — |
## Unterstützte Sprachen
Das CLI erkennt automatisch deine Systemsprache. Du kannst sie auch mit der Umgebungsvariable `ALCOVE_LANG` überschreiben.
| Sprache | Code |
|---------|------|
| English | `en` |
| 한국어 | `ko` |
| 简体中文 | `zh-CN` |
| 日本語 | `ja` |
| Español | `es` |
| हिन्दी | `hi` |
| Português (Brasil) | `pt-BR` |
| Deutsch | `de` |
| Français | `fr` |
| Русский | `ru` |
```bash
# Sprache überschreiben
ALCOVE_LANG=de alcove setup
```
## Aktualisieren
| Methode | Befehl |
|---------|-------|
| Homebrew | `brew upgrade alcove` |
| curl Installer | Das obige Installationsskript erneut ausführen |
| cargo binstall | `cargo binstall alcove@latest` |
| cargo install | `cargo install alcove@latest --features full-macos` |
| Claude Code Plugin | `claude plugin update epicsagas/alcove` |
```bash
alcove --version
```
## Deinstallieren
```bash
alcove uninstall # Skills & Konfiguration entfernen
cargo uninstall alcove # Binary entfernen
```
## Wissensdatenbank-Vaults
Über die Projektdokumentation hinaus unterstützt Alcove **unabhängige Wissensdatenbank-Vaults** für Forschungsnotizen, Referenzmaterialien und kuratiertes Wissen, das LLMs durchsuchen können.
```bash
# Einen Vault für KI-Forschungsnotizen erstellen
alcove vault create ai-research
# Einen bestehenden Obsidian-Vault verknüpfen (kein Kopieren — Indexierung vor Ort)
alcove vault link my-obsidian ~/Obsidian/research
# Ein Dokument hinzufügen
alcove vault add ai-research ~/Downloads/transformer-survey.md
# Suchindex für Vaults aufbauen
alcove vault index
# Alle Vaults auflisten
alcove vault list
# areas (8 docs) → (linked)
# resources (71 docs) → (linked)
# zettelkasten (17 docs) → (linked)
# Über CLI suchen
alcove search "attention mechanism" --vault ai-research
# Agenten suchen über API
search_vault(query="attention mechanism", vault="ai-research")
# Alle Vaults gleichzeitig durchsuchen
search_vault(query="transformer", vault="*")
```
Vaults sind **vollständig isoliert** von Projektdokumenten — separate Indizes, separate Caches, separate Suche. Die Suche Ihres Codierungs-Agenten nach Projektdokumenten wird niemals durch Vault-Aktivitäten beeinflusst.
| Funktion | Projektdokumente | Vaults |
|---------|-------------|--------|
| Zweck | Dokumentation pro Projekt | Allgemeine Wissensdatenbank |
| Speicherung | `~/.alcove/docs/` | `~/.alcove/vaults/` |
| Index | Gemeinsamer Projektindex | Unabhängiger Index pro Vault |
| Cache | `PROJECT_READER_CACHE` | `VAULT_READER_CACHE` |
| Suche | `search_project_docs` | `search_vault` |
| Symlink | Nein | Ja (externe Verzeichnisse verknüpfen) |
### Vault-Konfiguration
Standardmäßig werden Vaults in `~/.alcove/vaults/` gespeichert. Sie können dies in Ihrer `config.toml` ändern:
```toml
[vaults]
root = "/pfad/zu/deinen/vaults"
```
Weitere Details zur `config.toml` finden Sie im Abschnitt [Konfiguration](#konfiguration).
## Ökosystem
### [obsidian-forge](https://github.com/epicsagas/obsidian-forge)
Alcove lässt sich nahtlos mit **obsidian-forge** kombinieren, einem Obsidian-Vault-Generator und Automatisierungs-Daemon. Für die beste Integration sollte dein Alcove **`docs_root`** auf die obsidian-forge Projektarchive zeigen.
**1. Dokumenten-Root festlegen**
Verweise mit deinen primären Dokumenten auf das obsidian-forge Projektverzeichnis (direkt oder über einen Symlink):
```bash
# Setze während des Alcove-Setups docs_root auf:
~/Obsidian/SecondBrain/99-Archives/projects
```
**2. Wissensbereiche als Vaults verknüpfen**
Verknüpfe die anderen drei obsidian-forge Kategorien als unabhängige Alcove-Vaults. Dies erstellt Symlinks in `~/.alcove/vaults/`:
```bash
# obsidian-forge Kategorien verknüpfen
alcove vault link areas ~/Obsidian/SecondBrain/02-Areas
alcove vault link resources ~/Obsidian/SecondBrain/03-Resources
alcove vault link zettelkasten ~/Obsidian/SecondBrain/10-Zettelkasten
```
Jetzt haben deine Agenten strukturierten Zugriff:
- **`search_project_docs`**: Durchsucht archiviertes Projektwissen (PRDs usw.)
- **`search_vault`**: Durchsucht deine breiteren Wissensbereiche und Forschungsnotizen.
Du kannst das physische Speicher-Mapping überprüfen, indem du die Symlinks in `~/.alcove/vaults/` kontrollierst.
## FAQ
### Warum nicht einfach ripgrep als Tool verwenden?
Ripgrep liefert gesamte Dateien zurück. Wenn dein Agent nach „auth" sucht und 5 Dateien mit jeweils durchschnittlich 200 Zeilen trifft, werden ~10K Tokens in den Kontext injiziert — davon ist das meiste irrelevant. Alcove zerteilt Dokumente in Abschnitte, bewertet diese nach Relevanz und gibt nur die passendsten Passagen zurück. Zudem bietet Alcove eine semantische Suche (Vektor-Embeddings), die ripgrep nicht beherrscht — eine Anfrage wie „wie ist die Deployment-Pipeline strukturiert" wird keinen einzigen Begriff in deiner DEPLOYMENT.md treffen, aber Alcoves Vektorsuche findet es trotzdem.
### Ersetzt dies CLAUDE.md / AGENTS.md?
Nein — sie dienen unterschiedlichen Zwecken. Agent-Konfigurationsdateien (CLAUDE.md, AGENTS.md) definieren **Verhaltensregeln**: Commit-Stil, Spracheinstellungen, Sicherheitsrichtlinien. Alcove verwaltet **organisatorisches Wissen**: Architekturentscheidungen, Fortschrittsverfolgung, Coding-Konventionen, Code-Struktur. Die Agent-Konfiguration bestimmt, *wie der Agent handeln soll*. Alcove bestimmt, *was der Agent wissen soll*.
### Warum Rust?
Einzelnes Binary, keine Laufzeitabhängigkeiten. Tantivy ist die Referenzimplementierung für BM25. fastembed (ONNX Runtime) ermöglicht lokale Vektor-Embeddings ohne Python. Ein einfaches `cargo install` oder curl — kein Docker, kein Node.js, kein virtualenv.
### Was ist mit immer größer werdenden Kontextfenstern?
Größere Fenster lösen nicht das Relevanzproblem. Selbst ein 200K-Token-Fenster, das mit irrelevanten Dokumenten gefüllt ist, verschlechtert die Qualität der Agent-Ausgabe — Anthropic warnt in der eigenen Dokumentation davor, dass aufgeblähte Konfigurationsdateien dazu führen, dass Agenten tatsächliche Anweisungen ignorieren. Das Ziel ist nicht mehr Kontext, sondern der richtige Kontext zum richtigen Zeitpunkt.
## Fahrplan
- **Multi-User-Fernzugriff** — REST-API für Team-Dokumentenfreigabe über LAN/VPN (Bearer-Token-Authentifizierung, Rate-Limiting bereits implementiert). Erforderlich: Schreib-API, gleichzeitige Index-Koordination, Projekt-Lebenszyklusverwaltung.
## Mitwirken
Fehlerberichte, Funktionsanfragen und Pull Requests sind willkommen. Bitte öffne ein Issue auf [GitHub](https://github.com/epicsagas/alcove/issues), um eine Diskussion zu beginnen.
## Lizenz
Apache-2.0