Knowledge-Befehle

Lokale und entfernte KnowledgeSDK-Suche über Dateien, Web-Quellen sowie REST-/MCP-Endpunkte, 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. Entfernte Quellen werden bei jeder Suche live abgefragt und nicht in den lokalen Index importiert.

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

Entfernte KnowledgeSDK-Quellen (add-source api)

Neben lokalen Dateien und Web-Seiten kann pc knowledge auch entfernte KnowledgeSDK-Endpunkte durchsuchen — per REST oder MCP. Diese Quellen werden nicht in den lokalen Index importiert, sondern bei jeder Suche live abgefragt.

# Öffentliche ProcessCube®-Dokumentation per MCP (Abonnenten-Endpoint)
pc knowledge add-source api https://docs.processcube.io/api/mcp-public \
  --name processcube-docs --protocol mcp --token-env PROCESSCUBE_API_KEY
 
# Suchen — der Token kommt aus der Umgebungsvariablen
PROCESSCUBE_API_KEY=… pc knowledge search "timer event" \
  --source processcube-docs -o json
 
# Alternativ per REST
pc knowledge add-source api https://docs.processcube.io/api/search \
  --name processcube-rest --protocol rest
 
pc knowledge search "deploy" --source processcube-rest --limit 5

Index und Collection

Eine entfernte Quelle kann serverseitig mehrere Collections bereitstellen. Deshalb wird sie nicht als einzelne CLI-Collection angelegt:

• --source wählt den konfigurierten Endpunkt und damit den dahinterliegenden Suchindex.
• --collection filtert optional innerhalb dieses Indexes.
• Ohne --collection werden alle Collections der Quelle durchsucht.

Einen separaten --index-Parameter gibt es nicht.

# Endpunkt registrieren und eine Standard-Collection setzen
pc knowledge add-source api https://docs.processcube.io/api/search \
  --name processcube-index --protocol rest --collection engine
 
# Standard-Collection der Quelle verwenden
pc knowledge search "deployment" --source processcube-index
 
# Collection für eine einzelne Suche überschreiben
pc knowledge search "deployment" --source processcube-index --collection studio
 
# Ohne Collection-Filter: alle Collections der Quelle
pc knowledge search "deployment" --source processcube-rest

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
 
# Bei Dateiänderungen inkrementell nachziehen (Ctrl+C beendet)
pc knowledge index --watch

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

Lokale und entfernte Treffer kombinieren

Ohne --source fragt eine Suche den lokalen Index und alle konfigurierten REST-/MCP-Quellen ab und führt die Treffer quellenübergreifend zusammen:

# Lokal + alle entfernten Quellen
pc knowledge search "timer event"
 
# Nur eine bestimmte Quelle
pc knowledge search "timer event" --source processcube-docs
 
# Zeitlimit pro entfernter Anfrage (Default: 15000 ms)
pc knowledge search "timer event" --timeout 5000

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.

Dokumente aus entfernten Quellen nachladen

Treffer aus REST-/MCP-Quellen liegen nicht im lokalen Index. Mit --source lädt show das vollständige Dokument direkt bei der Quelle nach — ohne es zu importieren:

# Vollständigen Body eines Remote-Treffers holen
pc knowledge show "qmd://engine/deployment/page.mdx" --source processcube-rest
 
# Größere Dokumente zulassen (Default 100.000 Zeichen)
pc knowledge show "<id>" --source processcube-rest --max-bytes 200000

• Immer die id aus dem Suchtreffer verwenden — sie ist die stabile Dokument-ID der Quelle.
• Die Authentifizierung ist dieselbe wie bei der Suche (--token-env der Quelle).
• Ältere MCP-Server ohne structuredContent werden über den Text-Inhalt der Antwort unterstützt.

Grenzen von --max-bytes

Der Parametername folgt dem API-Vertrag; gemessen wird in der aktuellen SDK-Implementierung die JavaScript-String-Länge, nicht die exakte UTF-8-Bytezahl. Im JSON-Output nennt body_length die Länge des vollständigen Bodys, truncated zeigt an, ob body gekürzt wurde. Dokumente unterhalb des Limits kommen vollständig.

Einen unbegrenzten oder paginierten Abruf gibt es derzeit nicht — Dokumente über 500.000 Zeichen werden nur bis zur Obergrenze geliefert; für deren vollständigen Abruf wäre eine Erweiterung um Chunking oder Paging nötig. Die Grenze schützt den Remote-Endpunkt, den MCP-Client und das Kontextfenster eines Agenten vor einzelnen übergroßen Antworten.

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.

Auth in drei Stufen: ohne (Default, Bindung an 127.0.0.1) · fixer API-Key (--api-key <key> oder KNOWLEDGE_API_KEY; Agenten via Authorization: Bearer/X-API-Key, Browser einmalig via ?key=<key> — der Server setzt ein HttpOnly-Cookie; /health bleibt offen) · eigenes Auth-Plugin (--auth-plugin <modul.mjs> mit createServeAuth(): ServeAuthPlugin — über redirect/setCookie ist ein kompletter OIDC-Flow, z.B. gegen die ProcessCube Authority, abbildbar).

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:

Bei konfiguriertem Wiki kommen vier Pflege-Tools dazu — damit können auch remote laufende Agenten das Wiki pflegen:

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).

Wiki-Layer

Destillierte, LLM-gepflegte Wissensbasis über dem Index — nach Karpathys „LLM Wiki”-Muster, im OKF-v0.1-Format (Open Knowledge Format , Google). Die Arbeitsteilung: die CLI macht die deterministische Buchhaltung, ein AI-Agent macht die Destillation (Workflows im Skill: pc skill install knowledge).

# Wiki anlegen: KNOWLEDGE.md (Schema), index.md (TOC, okf_version), log.md (Chronik)
# — wird zugleich als Filesystem-Source im Index registriert
pc knowledge wiki init
 
# Ingest-Queue: welche Index-Dokumente sind neu/geändert und warten auf Destillation?
pc knowledge wiki status -o json
 
# Qualitätswache gegen Drift (Exit 1 bei Befunden → CI/Cron-tauglich)
pc knowledge wiki lint
 
# Chronik (OKF-Datums-Gruppen) und Seitenliste mit Markern
pc knowledge wiki log "ingest: timer-events destilliert"
pc knowledge wiki pages --stale --orphaned -o json

Provenienz = Drift-Erkennung: Jede Wiki-Seite referenziert im Frontmatter die verarbeiteten Index-Dokumente samt contentHash. Ändert sich eine Rohquelle, melden wiki status (als changed) und wiki lint (als stale-source) die betroffenen Seiten — deterministisch, ohne LLM.

---
type: Concept
title: Timer-Events
description: Zeitgesteuerte Prozess-Starts in der Engine
timestamp: 2026-07-17T12:00:00Z
sources:
  - id: "docs:/abs/pfad/timer.md"
    contentHash: <hash aus `pc knowledge show <id> -o json`>
---
 
# Timer-Events
 
Destillat. Querverweise als [[engine/deployment]] oder OKF-Markdown-Link: [Deployment](/engine/deployment.md).

Lint prüft kaputte Links (beide Konventionen), verwaiste Seiten (nicht in index.md), fehlendes Frontmatter, das OKF-Pflichtfeld type und veraltete Quellen.

Suchen mit Layer-Filter: --layer wiki liefert nur destillierte Seiten (höchste Antwortdichte), --layer raw nur Rohquellen:

pc knowledge search "timer" --layer wiki
pc knowledge search "timer" --layer raw

Browsen: Der wiki/-Ordner ist Obsidian-kompatibel. pc knowledge serve --ui liefert einen eingebauten Wiki-Browser unter /wiki (Sidebar, Provenienz-Fußzeile mit aktuell/veraltet-Badges, Suche, Log). Für eigene Apps gibt es die React-Komponente WikiBrowser aus @processcube-io/knowledge-sdk-ui, die die JSON-API konsumiert.

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).
• Kein Vektor-Hybrid im Binary. FTS5 + bm25 und optionales LLM-Reranking laufen im pc-Binary; die Vektor-Hybrid-Suche braucht sqlite-vec und damit eine Node-Runtime. Sie gilt nur für lokale Quellen.
• 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

Wiki