Knowledge-Befehle

Lokale Hybrid-Suche über Dateien und Web-Quellen, gebaut auf der @processcube-io/knowledge-sdk (FTS5 + bm25 über bun:sqlite). pc knowledge legt einen lokalen SQLite-Index an, indiziert Markdown-Dateien und URL-Listen und liefert Treffer per CLI oder REST-Server.

Empfohlenes Setup

Es gibt drei realistische Topologien — wählt nach Konsument:

Setup A: Lokaler Developer / AI-Agent per CLI (empfohlen für Einstieg)

Der Konsument (CLI-User oder Agent als Subprozess) ruft das pc-Binary auf. FTS5 + LLM-Reranking als Default-Pipeline:

# Einmalig
export VOYAGE_API_KEY=…
pc knowledge init
pc knowledge add-source filesystem ./docs
pc knowledge index
 
# Pro Suche (auch für Agent-Aufrufe)
pc knowledge search "<frage>" --rerank --limit 10 -o json

• ✅ funktioniert im Binary, kein Node-Setup
• ✅ Rerank deckt semantische Token-Mismatches ab
• ✅ ~0,5 ct pro Query bei voyage rerank-2
• ❌ Vektor-Hybrid steht nicht zur Verfügung

Für AI-Agents empfohlen, solange ihr im ersten Schritt direkt per CLI integriert und keinen Server zwischenhängt.

Setup B: Plugin-Cron schreibt, Binary liest

Plugins (docs-crawler, github-source, ingest-worker) laufen als Node-Cron und schreiben FTS-Body in die geteilte SQLite. Das Binary liest. Optional schreiben die Plugins zusätzlich Embeddings (*_EMBED=1), aber das Binary kann sie nicht nutzen — sinnvoll nur als Vorbereitung auf Setup C.

Setup C: Zentraler Node-Server, Agents/Browser hitten REST/MCP

Sobald ihr mehr als CLI-Konsumenten habt (Browser-UI, mehrere Agents, Cross-Org-Search), wechselt der Reader auf einen Node-Prozess:

# Server-Maschine, Node-Runtime
npm install sqlite-vec
node dist/pc.js knowledge serve --hybrid --rerank

Dann profitieren alle Clients — auch CLI-Aufrufe gegen den Server-Endpoint — von voller Hybrid-Suche.

Schnellstart

# Index initialisieren (legt knowledge.config.json + .knowledge/index.sqlite an)
pc knowledge init
 
# Quelle registrieren (Dateipfad oder URL)
pc knowledge add-source filesystem ./docs
pc knowledge add-source web https://example.com/handbook.html
 
# Indizieren
pc knowledge index           # alle Filesystem-Quellen
pc knowledge sync            # zusätzlich Web-Quellen
 
# Suchen
pc knowledge search "timer event"
pc knowledge search "deploy" --source docs --limit 5
pc knowledge search "userTask" -o json | jq '.result.hits[].title'

Index anlegen

# Config + leere SQLite anlegen
pc knowledge init
 
# Bestehende Config überschreiben
pc knowledge init --force

Erzeugt im aktuellen Verzeichnis:

• knowledge.config.json — Sources + Tokenizer-Wahl
• .knowledge/index.sqlite — leere FTS5-Datenbank, WAL-Modus aktiv

Der DB-Pfad ist über die Env-Variable KNOWLEDGE_DB_PATH überschreibbar.

Quellen verwalten

# Dateipfad als Quelle registrieren
pc knowledge add-source filesystem ./docs --name docs
 
# Web-URL als Quelle (für sync)
pc knowledge add-source web https://example.com/handbook.html
 
# Mit explizitem Namen (sonst wird ein Default abgeleitet)
pc knowledge add-source web https://example.com --name handbook

Indizieren

# Alle Filesystem-Quellen aus der Config indizieren
pc knowledge index
 
# Ad-hoc-Pfad (ohne Config-Eintrag)
pc knowledge index ./notes
 
# Nur eine bestimmte Quelle
pc knowledge index --source docs
 
# Mit Reconcile (Orphan-Removal, aktuell best-effort)
pc knowledge index --reconcile

Die Indizierung ist inkrementell: Unveränderter Inhalt (gleiche SHA-256 über den Body) wird übersprungen. Ein zweiter Lauf direkt nach dem ersten meldet upserted=0, unchanged=N.

# Filesystem + Web in einem Rutsch (inkl. fetch der Web-URLs)
pc knowledge sync
pc knowledge sync --source handbook

Suchen

# Volltext-Suche per FTS5 + bm25
pc knowledge search "timer event"
 
# Auf eine Quelle einschränken
pc knowledge search "deploy" --source docs --limit 5
 
# Präfix-Matching (Token wird zu Token*)
pc knowledge search "user" --prefix

Globales Flag -o text|json steuert die Ausgabe (siehe Erste Schritte). Für Pipes:

pc knowledge search "userTask" -o json | jq '.result.hits[].title'

Hybrid-Suche (FTS + Vektor)

--mode hybrid kombiniert die FTS-Suche mit Vektor-Ähnlichkeit über sqlite-vec . Die beiden Kandidatenlisten werden per Reciprocal Rank Fusion zusammengeführt (k=60). Sinnvoll für Anfragen, deren Schlüsselbegriffe nicht wörtlich in den Dokumenten stehen.

Voraussetzung: Der Index muss Embeddings enthalten. Einmalig mit --embed indizieren:

# sqlite-vec installieren (Node-only, einmalig im pc-Verzeichnis)
npm install sqlite-vec
 
# Index neu aufbauen, diesmal mit Embeddings
VOYAGE_API_KEY=… pc knowledge sync --embed
# oder gezielt:
VOYAGE_API_KEY=… pc knowledge index --embed
 
# Suche im Hybrid-Modus
VOYAGE_API_KEY=… pc knowledge search "scheduled job" --mode hybrid

Optionales LLM-Reranking

--rerank schickt die FTS-Top-N durch einen Cross-Encoder und sortiert die Treffer neu. Sinnvoll, wenn die Begriffe der Suchanfrage nicht wörtlich in den Dokumenten stehen.

# Voyage als Provider (Default)
VOYAGE_API_KEY=… pc knowledge search "BPMN scheduled workflow" --rerank
 
# Cohere alternativ
RERANK_PROVIDER=cohere COHERE_API_KEY=… pc knowledge search "BPMN scheduled workflow" --rerank

Die Standard-Pipeline: FTS holt 5 × Limit (mindestens 20) Kandidaten, der Reranker bewertet sie, der Server schneidet auf das gewünschte limit ab. Spalten in der Tabellen-Ausgabe sind dann rerank (höher = relevanter) und rank (bm25, kleiner = relevanter) parallel.

Treffer anzeigen

# Document-ID aus dem search-Output nehmen
pc knowledge show "docs:/abs/path/to/file.md"
 
# Im Redirect-Modus (Web-Quelle ohne Body) öffnet show die URL im Browser.
# Mit --no-open bleibt es nur Anzeige:
pc knowledge show "<id>" --no-open
 
# JSON-Output liefert das Dokument plus found-Flag
pc knowledge show "<id>" -o json

Markdown-Bodies werden über den eingebauten Terminal-Renderer ausgegeben.

Server-Modus

# REST-Server starten (Default: 127.0.0.1:51344)
pc knowledge serve
 
# Eigener Port und Interface
pc knowledge serve --port 8080 --host 0.0.0.0

REST-Endpoints:

Mit --rerank läuft die LLM-Pipeline auch hinter /api/search. --hybrid aktiviert die Vektor-Suche, sofern der Index Embeddings hat:

# Vollausstattung: FTS + Vektor + Rerank
VOYAGE_API_KEY=… pc knowledge serve --hybrid --rerank

Pro-Request-Overrides: ?rerank=1/?rerank=0 und ?mode=fts/?mode=hybrid. Im MCP-Tool knowledge_search greift dasselbe über die rerank- und mode-Argumente.

MCP-Endpoint für AI-Agents

Der Server exponiert die Suche zusätzlich als Model Context Protocol Endpoint, sodass Claude Code, Codex oder eigene Agents den Index ohne CLI-Aufruf abfragen können:

POST /mcp        Streamable HTTP (JSON-RPC 2.0)

Drei Tools:

Einbinden z.B. in Claude Code per claude mcp add pc-knowledge http://127.0.0.1:51344/mcp --transport http.

Der Server ist ein langlebiger Prozess und macht SIGINT/SIGTERM-Shutdown sauber. Reader und Writer können dieselbe SQLite-Datei parallel nutzen (WAL).

Plugins als Cron

Crawler und External-Task-Worker laufen als eigenständige Node-Prozesse und schreiben via WAL in dieselbe SQLite, die pc knowledge liest. Das macht sie cron-tauglich:

# docs-crawler nightly, 3 Uhr
0 3 * * *  cd /opt/docs-crawler && KNOWLEDGE_DB_PATH=/var/lib/knowledge/.knowledge/index.sqlite node dist/index.js >> /var/log/docs-crawler.log 2>&1

# github-source stündlich
0 * * * *  cd /opt/github-source && KNOWLEDGE_DB_PATH=/var/lib/knowledge/.knowledge/index.sqlite GITHUB_OWNER=5minds GITHUB_REPO=ProcessCube.App.SDK GITHUB_TOKEN=$(cat /etc/secrets/gh) node dist/index.js >> /var/log/github-source.log 2>&1

Robustheit:

• Single-Instance-Lock (.knowledge/crawl.lock) — überlappende Runs werden übersprungen.
• Idempotenz via contentHash — unveränderte Inhalte werden geskippt, pc knowledge search läuft daneben weiter.
• Sauberer Exit auch im Fehlerfall (Browser/Connections werden geschlossen).

Auf Kubernetes:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: docs-crawler
spec:
  schedule: "0 3 * * *"
  concurrencyPolicy: Forbid
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: crawler
              image: ghcr.io/example/docs-crawler:latest
              env:
                - { name: KNOWLEDGE_DB_PATH, value: /data/.knowledge/index.sqlite }
              volumeMounts:
                - { name: data, mountPath: /data }
          volumes:
            - name: data
              persistentVolumeClaim:
                claimName: knowledge-pvc

concurrencyPolicy: Forbid ist hier doppelte Sicherheit zum Lockfile.

Erweitern: eigene Plugins

pc knowledge ist Read-Pfad und liefert die Built-in-Sources filesystem und web (einfaches HTTP-fetch). Für eigene Quellen, JavaScript-gerenderte Seiten und Support-Loops liefert pc platform create-extension drei Templates:

# Eigene KnowledgeSource (z.B. Notion, Confluence, GitHub)
pc platform create-extension my-source -t knowledge-source
 
# Crawler-Plugin mit Playwright, cron-tauglich
pc platform create-extension docs-crawler -t knowledge-crawler
 
# Generischer Ingest-Worker — Default-Trigger HTTP-Webhook,
# BPMN/Agent/Mail-Varianten als Patterns im README
pc platform create-extension support-loop -t ingest-worker
 
# BPMN-spezifischer External-Task-Worker (engere Variante)
pc platform create-extension support-bpmn -t external-task

Der ingest-worker ist der empfohlene Einstieg, wenn Trigger und Pipeline getrennt sind: drei Bibliotheks-Funktionen (anonymize, curationGate, ingest) werden vom Default-HTTP-Webhook aufgerufen — eigene Trigger (BPMN External Task, AI-Agent, Mail-Poll) importieren processIngest() aus dist/pipeline.js und rufen es aus dem eigenen Loop auf.

Crawler und External-Task-Worker laufen als eigenständige Node-Prozesse und schreiben via WAL in dieselbe SQLite, die pc knowledge liest.

Plugins mit Embedding: Beide Referenz-Plugins akzeptieren ein optionales *_EMBED=1-Env, das parallel zum FTS-Eintrag ein Embedding schreibt — dann ist die Suche im Hybrid-Modus auch ohne zusätzlichen pc knowledge sync --embed-Schritt direkt einsatzbereit:

DOCS_EMBED=1 VOYAGE_API_KEY=… node examples/docs-crawler/dist/index.js
GITHUB_EMBED=1 VOYAGE_API_KEY=… GITHUB_OWNER=… GITHUB_REPO=… node examples/github-source/dist/index.js

Was pc knowledge nicht macht

• Kein Crawler. URL-Discovery (Sitemap, Frontier-Queue, robots.txt) gehört in ein Crawler-Plugin (knowledge-crawler-Template).
• Keine Hybrid-Suche. Vektor und LLM-Reranking laufen Server-seitig und werden mit der Indexer-Migration des SDK später aktiviert.
• Keine Anonymisierung beim Ingest. Wer aus Support-Tickets indiziert, nutzt das external-task-Template — dort ist die Pipeline anonymize → curation-gate → upsertDocument erzwungen.

Env-Variablen

Befehlsübersicht

Index & Quellen

Suchen & Anzeigen

Server