CyClaw is a personal, offline-first RAG (Retrieval-Augmented Generation) backend built by Chris Grady. It runs as a FastAPI server bound exclusively to 127.0.0.1:8787 — never exposed to the internet. Every query is answered first from your local Markdown corpus using a hybrid ChromaDB + BM25 retrieval pipeline fused with Reciprocal Rank Fusion (RRF). Only if the corpus lacks a relevant answer does the system escalate — and even then only with triple explicit human confirmation.
The security model is topology-enforced, not prompt-enforced: a LangGraph 7-node state machine makes all routing decisions via hard graph edges, eliminating the possibility of LLM jailbreak bypassing safety policy. Version 1.8.0 (current) adds filesystem & SQL connectors, a NeMo Guardrails layer, and a comprehensive agentic layer — all opt-in and fully out-of-band from the core request path.
Key design principles: zero telemetry, all embeddings run locally (sentence-transformers), a SHA-256–signed soul/personality layer with drift detection, and a persistent audit log that stores only hashes — never raw query text.
retrieve is the unconditional graph entry — zero LLM calls can precede it. Not a config flag. Not a prompt rule. A hard graph edge.
mode=hybrid AND grok.enabled=true AND user_confirmed_online=true.
audit_logger. There is no shortcut path that skips audit. Zero exceptions.
| Module | Role |
|---|---|
| gate.py | FastAPI entry, soul endpoints, API key auth, rate limit, sanitizer |
| graph.py | 7-node LangGraph topology — all security policy lives here |
| retrieval/hybrid_search.py | RRF fusion (k=60) over ChromaDB + BM25Okapi |
| retrieval/indexer.py | Corpus ingestion with chunk sanitization |
| retrieval/embeddings.py | Local CPU embedding · SentenceTransformer · triple lru_cache |
| utils/sanitizer.py | 33-pattern prompt-injection filter; patterns in config.yaml |
| utils/personality.py | Soul versioning, SHA-256 drift detection, injection scan on write |
| utils/logger.py | Audit JSONL — SHA-256 query hashing, PII redaction |
| mcp_hybrid_server.py | MCP server (retrieval-only, no LLM, no sampling capability) |
| metrics.py | audit.jsonl analyzer — usage statistics and review |
pathsafe.py core using POSIX openat/O_NOFOLLOW. Closes CVE-2025-53110 (sibling-prefix) and CVE-2025-53109 (symlink escape). 5 MiB read cap. Writes default-OFF. Toggleable RAG-corpus indexing.
allow_write: false. Supports Postgres + MSSQL. DSN from env var only, never hardcoded. Disabled by default.
nemoguardrails; degrades to offline heuristic rails when absent. Hallucination grounding check (threshold 0.18). Separate hash-only metrics stream.
gh CLI + governed local skills registry. Writable scaffold exists but is non-executing. Full audit log on all reads, refusals, registry changes.max_delete, max_transfer. Scheduler integration for Linux/Windows. Optional reindex trigger.logs/audit.jsonl.