Candor AI — Lawful Good Rust Agentic Operating System

A production-grade personal AI agent with voice, memory, PDA capabilities, and a pluggable skill ecosystem.

# One-shot task
candor task "build a CLI tool"

# Interactive conversation
candor chat

# Voice-activated (whisper-cpp + piper-tts)
candor voice                        # One-shot
candor voice-interactive            # Listen → think → speak loop

# Personal Digital Assistant
candor pda init                     # Initialize ~/.candor/ identity & memory
candor pda digest                   # Morning briefing via TTS
candor pda monitor                  # Scan for stale work sessions

# Diagnostics
candor health                       # Subsystem health
candor doctor                       # Full diagnostic scan
candor serve --port 31337           # REST API daemon

Quick Install

# Via Cargo (Rust toolchain required)
cargo install candor-ai

# Via install script (auto-downloads pre-built binary)
curl -sfL https://raw.githubusercontent.com/iknowkungfubar/candor-ai/main/install.sh | sh

# Verify
candor doctor

Portfolio CLI note: This installs as candor. Turintech portfolio convention uses turintech-candor-ai — create a symlink if desired: ln -s $(which candor) ~/.local/bin/turintech-candor-ai

Examples

The examples/ directory contains usage demos:

examples/quick_start.sh — Health check, one-shot tasks, interactive chat, PDA init, and REST API server examples

bash examples/quick_start.sh

Why Rust?

Most AI agent frameworks are written in Python (AutoGPT, LangChain, CrewAI). candor-ai is built in Rust for three reasons:

Concern	Python frameworks	candor-ai (Rust)
Memory safety	GC pauses, buffer overflows possible	Compile-time guarantees, no GC
Distribution	Requires Python runtime + 500MB+ deps	Single 57MB binary, no runtime needed
Performance	GIL-bound, interpreted	Native speed, true parallelism
Sandboxing	Subprocess isolation (porous)	WASM runtime (wasmtime) — real capability-based security
Concurrency	asyncio (cooperative)	Tokio (preemptive, multi-threaded)

Bottom line: candor-ai gives you an AutoGPT-class agent that installs with cargo install and runs as a single binary — no Python, no virtualenvs, no dependency hell.

How it compares

Feature	candor-ai	AutoGPT	LangChain Agents	Rig (Rust)
Language	Rust	Python	Python	Rust
Install	`cargo install`	`git clone + pip`	`pip install`	`cargo install`
Sandboxing	WASM + bubblewrap	Subprocess only	None built-in	None
Memory	SurrealDB (kv-mem)	JSON files	Vector store plugin	Plugin-based
Voice	STT/TTS built-in	Plugin only	None	None
PDA	Identity + git-backed memory	None	None	None
7-phase loop	Observe→Think→Plan→Build→Execute→Verify→Learn	Think→Act→Observe	Prompt→Tool→Observe	Configurable
Guardrails	6 rules + 10 doctrines	None	None	None
Binary size	57MB	500MB+ (Python + deps)	200MB+	~15MB

Features

📦 Memory Persistence

Memory is ephemeral in the default build (in-memory SurrealDB). All data is lost on process exit. Enable the persistent-memory feature flag for on-disk RocksDB storage at ~/.candor/data/.

cargo build --release --features persistent-memory

🧠 7-Phase Agent Loop

Observe → Think → Plan → Build → Execute → Verify → Learn

LLM-driven software engineering agent with the Ideal State Artifact (ISA) — a 12-section markdown document defining goals, criteria, and constraints for every task.

🎤 Voice Interface

STT: Record mic via arecord, transcribe via whisper-cpp
TTS: Speak responses via piper-tts (neural) or espeak-ng (fallback)
Interactive mode: Listen → think → speak — conversational loop with exit words

🧑 Personal Digital Assistant

IDENTITY.md — who you are (name, goals, preferences, values)
DA_IDENTITY.md — your DA's personality (name, voice, tone, directives)
Git-backed memory — every write auto-commits, full history available
Memory triage: WORK/slugs (ISA tasks), LEARNING/ (meta-patterns), KNOWLEDGE/ (entities)
Morning Digest — daily briefing from identity + work state + TTS
Monitor Agent — scans for stale sessions and knowledge gaps

🔒 Security

WASM sandbox (wasmtime) + bubblewrap process isolation
Sentinel guardrails: 6 deterministic rules, 10 doctrine principles
Force-push blocked, secrets never logged, deny-by-default posture
17 security advisories fixed (wasmtime 30→36; lock now at 47.0.3)
Zero CVEs — automated cargo audit in CI

🔧 Tools (12 built-in)

Tool	Description
`read_file` / `write_file`	File I/O with line limits
`list_dir`	Directory listing
`search_code`	ripgrep search
`search_files`	File name search
`shell`	Sandboxed command execution
`run_tests`	Cargo test runner
`git_branch` / `git_commit` / `git_push` / `git_status`	Git operations (sentinel-gated)

🔌 Integrations

LLM backends: Anthropic, OpenAI, DeepSeek, Gemini, LM Studio, Ollama — auto-detected from env vars
MCP servers: stdio + HTTP transports, auto tool discovery
MCP skills: 400+ bioinformatics skills, browser automation
REST API: axum server on port 31337

Architecture

┌──────────────────────────────────────────────────────────┐
│                     OrchestratorEngine                      │
│  Observe → Think → Plan → Build → Execute → Verify → Learn  │
├─────────┬─────────┬─────────┬─────────┬─────────┬──────────┤
│  Graph   │ Sandbox │Cognitive│ Memory  │ Sentinel│   PDA    │
│  Runner  │(WASM +  │ Engine  │(Surreal │ Inter-  │ Identity │
│(petgraph)│  bwrap) │         │  DB)    │ ceptor  │ + Memory │
├─────────┼─────────┼─────────┼─────────┼─────────┼──────────┤
│  Tools   │   MCP   │  Local  │  Skills │ Recovery│ Voice    │
│ (12 tools)│ Client  │ Backend¹│ System  │  Nodes  │ STT/TTS  │
└─────────┴─────────┴─────────┴─────────┴─────────┴──────────┘

11 Crate Workspace

Crate	Purpose	Tests
`candor-core`	Shared types, AgentState, ISA, errors	14
`candor-graph`	Petgraph runner, lifecycle hooks, recovery	17
`candor-sandbox`	wasmtime + bubblewrap, circuit breaker	12
`candor-cognitive`	LLM inference, embeddings (hash-based), 4 backends	29
`candor-memory`	SurrealDB with HNSW vector index	12
`candor-sentinel`	Guardrails: rules + doctrine	25
`candor-orchestrator`	7-phase agent, ISA climbing, skills	58
`candor-tools`	12 tools: fs, search, shell, test, git	27
`candor-mcp`	MCP client, JSON-RPC 2.0, auto-discovery	8
`candor-ai`	CLI + REST API + PDA + Voice	27
`candor-telemetry`	OpenTelemetry tracing	1

Total: ~250+ tests, 0 clippy warnings, 0 compiler warnings, 0 CVEs.

¹ Local Backend: Requires --features local-inference at build time. The default build uses mock responses for local inference. See Feature Flags below.

Built with Rust edition 2024. See crates.io for the published package.

Feature Flags

Candor uses Cargo feature flags to gate optional functionality. The default build gives you a fully functional agent with cloud LLM backends, all 12 tools, WASM sandboxing, PDA, and voice.

Feature	Default	Description
`local-inference`	off	Enables mistral.rs for on-device GGUF model inference
`persistent-memory`	off	Switches SurrealDB from in-memory (ephemeral) to on-disk RocksDB storage at `~/.candor/data/`

# Build with local inference
cargo build --release --features local-inference

# Build with persistent memory
cargo build --release --features persistent-memory

# Build with both
cargo build --release --features "local-inference,persistent-memory"

Memory note: The default build stores all memory in-memory only — data is lost when the process exits. For persistent storage, enable persistent-memory.

Configuration

# LLM backends (auto-detected, checked in this order)
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export DEEPSEEK_API_KEY="sk-..."
export GEMINI_API_KEY="..."
export LM_STUDIO_URL="http://localhost:1234/v1"
export OLLAMA_URL="http://localhost:11434/v1"

# Model override
export CANDOR_MODEL="gpt-4o"

# MCP servers
export MCP_SERVERS="http://localhost:3000"

# Audio (voice features)
export CANDOR_AUDIO_DEVICE="default"
export CANDOR_RECORD_SECONDS="5"
export CANDOR_TTS_MODEL="/path/to/piper-model.onnx"
export CANDOR_TTS_VOICE="en-us"

# TOML config file (loaded by Figment, overridden by env vars):
#   ./candor.toml          (project-local)
#   ~/.candor/config.toml  (user-global)

Performance

Metric	Value
Clean dev build	~36s
Release build	~3m15s
Binary size	57MB stripped
State append (100 msgs)	3.2 µs
Context compaction	6.4 µs
Token limit check	94 ps
ISA validation (10 criteria)	41 ns
Test suite	~250+ all passing

Development

git clone https://github.com/iknowkungfubar/candor-ai
cd candor-ai

# Dependencies for voice features (optional)
sudo pacman -S whisper-cpp espeak-ng alsa-utils  # Arch
# brew install whisper-cpp espeak-ng portaudio     # macOS
# apt install whisper-cpp espeak-ng alsa-utils     # Debian/Ubuntu

# Build and test
cargo build --release
cargo test --workspace

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for detailed guidelines on our development process, coding standards, PR workflow, and code of conduct.

License

MIT — see LICENSE