Logo Terraphim AI documentation

Guide

  • Bun Package Manager Replacement - Implementation Summary
  • CI Status for PR #179 - OpenRouter and Axum Fix
  • Cloudflare Pages Deployment for Terraphim AI Documentation
  • Comprehensive Test Report: terraphim-agent and terraphim-cli
  • Conare AI vs Terraphim: Implementation Summary
  • LLM Markdown Linter Design for Terraphim KG Schemas
  • LLM Markdown Linter Implementation Plan
  • OpenRouter Integration Testing Plan - Implementation Complete
  • Terraphim AI Performance Benchmarking Framework
  • Right-Side-of-V Report: PR 492 (CLI Onboarding Wizard)
  • Right-Side-of-V Report: PR 494 (agent and CLI test failures)
  • Right-Side-of-V Report: PR 495 (clippy warnings and rocksdb tests)
  • Right-Side-of-V Report: PR 496 (CI timeouts and redundant workflows)
  • Release Process Documentation
  • Ripgrep Tag Filtering Documentation
  • Tauri Signing Keys - 1Password Integration
  • Test Environment Improvements - Implementation Complete
  • Comprehensive Test Report: terraphim-agent and terraphim-cli
  • TinyClaw (CLAW) Component - Test Report
  • Untitled
  • Phase 5: Validation Report - Issue #421
  • Zipsign Signature Verification Fix - Handover Document
  • Terraphim Architecture Improvement Plan
  • Terraphim Architecture Review Report
  • Atomic Client Feature Flag Documentation
  • Terraphim Agent Auto-Update System
  • CI/CD Pipeline Migration
  • Code Assistant Requirements vs Current Implementation Analysis
  • Terraphim AI Component Architecture
  • Composio Agent Orchestrator vs Terraphim ADF -- Comparison Analysis
  • Conare AI vs Terraphim: Context Engineering Comparison
  • Context Collections Management
  • Context Engineering with Terraphim: Quick Start
  • Terraphim AI Deployment Guide
  • Duplicate Handling in Terraphim AI
  • GitHub Actions Issues and Proposed Fixes
  • GitHub Actions Release Workflow Fix Implementation Plan
  • Terraphim GitHub Runner - Architecture Documentation
  • GitHub Runner Integration - Commit Summary
  • Terraphim GitHub Runner - Setup Guide
  • GitHub Runner Webhook Integration - Implementation Complete
  • GitHub Secrets Setup Guide
  • Terraphim AI Installation and Deployment Guide
  • knowledge-graph
  • LLM Proxy Configuration Guide
  • MCP File Context Tools
  • Perplexity Integration for Terraphim AI
  • Architecture Comparison: pi-mono vs terraphim-ai
  • Implementation Plan: Telegram Bot Integration for TinyClaw
  • Platform-Specific Installation Guide
  • Quickwit Integration Guide
  • Sentrux Quality Gates
  • Setting Up Telegram Bot with TinyClaw
  • Terraphim TUI Features
  • Terraphim Terminal User Interface (TUI)
  • Vendor API Drift Report - Echo/Twin Maintainer

adf

  • ADF model selection and agent spawn — reference
  • ADF Operations Guide

archive

  • Release v1.2.3
  • Terraphim AI v1.0.0 Release Notes
  • Terraphim AI v1.0.2 - Multi-Platform Release

archive/blog-posts

  • Building a GitHub Actions-Style Runner with Firecracker VMs and Knowledge Graph Learning

archive/desktop

  • 🚀 Terraphim Autocomplete in Novel Editor - Demonstration
  • ✅ Cache-First Architecture with Streaming - IMPLEMENTED
  • Chat Layout Responsive Design Test Plan
  • Novel Editor Autocomplete Integration - Implementation Status
  • ✅ OpenDAL Warnings Fixed
  • ✅ Performance Optimization Complete
  • ✅ Performance Validation Complete - All Issues Resolved
  • ✅ PROOF: All Issues Are Resolved
  • Desktop App for Terraphim AI Assistant
  • Terraphim AI Frontend Testing Guide
  • Test Status Summary
  • bulmaswatch-README
  • Manual Test: Graph Tags in Tauri App
  • Comprehensive Test: Tauri Parameter Naming Fixes
  • Novel Editor Autocomplete Tests
  • Atomic Server Haystack Integration Tests
  • CI-Friendly Playwright Tests
  • Rolegraph End-to-End Test Framework
  • Unit Tests
  • Tauri WebDriver Tests for KG Graph Functionality

archive/marketing

  • Blog Post: Building Privacy-First AI Tools with X Integration
  • Hacker News Submission
  • Reddit Posts for Terraphim AI
  • X (Twitter) Marketing Thread

archive/root

  • Auto-Update Feature - Implementation Plan Summary
  • TerraphimAgent Performance Benchmarks
  • Bigbox Deployment Plan: Firecracker-Rust + Terraphim Multi-Agent System
  • Branch Protection and Naming Conventions
  • Multi-Platform Build Guide for Terraphim AI
  • CI/CD Optimization Implementation Complete
  • CI/CD Troubleshooting Guide
  • CI_FIX_STATUS
  • CI/CD Migration from Earthly to GitHub Actions - COMPLETE
  • CI/CD Migration Guide
  • CI/CD Migration Plan: Earthly to Dagger
  • 🎉 CI/CD Workflows Successfully Fixed and Optimized
  • CI/Testing Infrastructure Enhancement Plan
  • Cloudflare Infrastructure Proof Analysis
  • 🎉 Terraphim TUI Implementation - Comprehensive Test Results
  • Context Management Fixes Summary
  • Terraphim-Agent Crash Analysis Report
  • Terraphim v1.0.0 Cross-Platform Installation Status
  • Database Backend Features
  • Dependency Minimization & Release Hardening - Summary Report
  • Firecracker-Rust Deployment Status
  • Implementation Plan: Automatic Updates Feature
  • Implementation Plan: Auto-Update Signature Verification
  • Terraphim Desktop App Test Checklist
  • Terraphim AI Development Session Summary
  • Disciplined Design Plan: Remaining Quality Issues
  • DNS Migration Guide: Terraphim.ai from Netlify to Cloudflare
  • Documentation Enhancement Implementation Complete
  • Terraphim v1.0.0 - Final Status Report
  • Terraphim Build & Interactive Mode Fix Plan
  • terraphim-agent Fix Verification Report
  • Terraphim AI v1.0.1 - Complete Functional Proof
  • Terraphim AI - Complete Functional Testing Plan
  • GitHub Actions Failure Analysis - PR #186
  • GitHub Actions Status - PR #186
  • Handover Document: Terraphim GitHub Runner Server Integration
  • Handover Document - LLM Router Feature Integration
  • Handover: 2026-03-10 - Agent Workflows E2E Implementation Complete
  • Auto-Update Feature Implementation Handover
  • Handover: GitHub Runner LLM Parser Fix
  • 🎉 Terraphim Implementation Summary - Complete Success!
  • Integration Test Fixes Summary
  • Linting Fixes Implemented
  • Linting Fixes Plan
  • LLM Markdown Linter for Terraphim KG Schemas - Summary
  • LLM Proxy Implementation Summary
  • Matrix Release Build Implementation Summary
  • GitHub Actions Matrix Configuration Fixes
  • Terraphim v1.0.0 Memory Usage Report
  • Phase 2 Complete: Cloudflare Migration - FULL SUCCESS ✅
  • docs.terraphim.ai Migration Plan: Zola → md-book
  • ✅ Terraphim v1.0.0 Minimal Release - COMPLETE!
  • Minimal Release Plan: Lib, REPL, and CLI
  • Disciplined Design Plan: OpenDAL WARN Message Reduction
  • OpenDAL Warning Messages - Research Summary
  • Terraphim AI - Outstanding Items Analysis
  • 🚀 Terraphim Performance Analysis & Optimization Guide
  • Terraphim AI Performance Improvement Plan
  • Phase 2: Core Functionality Validation - IMPLEMENTATION COMPLETE
  • Phase 5 Integration Summary
  • Phase 5 Verification: Complete ✅
  • Phase 1 Complete: Cloudflare Pages Project & 1Password Setup ✅
  • Terraphim AI - Outstanding Tasks and Development Plan
  • Platform Verification Report - v1.0.0
  • Pre-commit Hook Integration - API Key Detection
  • PR #186 - Complete Summary
  • PR #277 - Code Assistant Implementation Summary
  • 🎉 Terraphim v1.0.0 Minimal Release - PUBLISHED!
  • Quality Improvement Summary
  • Query.rs and Reddit Content Fetching Fix Plan
  • Atomic Server Roles for Terraphim
  • Dual Haystack Validation Framework
  • QueryRs Haystack Integration
  • Rebase Integration Test Fix Status
  • Terraphim AI v1.4.7 - Linux Release Build Report
  • ✅ Terraphim AI v1.0.0 Release - COMPLETED
  • Release Branch Consolidation Implementation Plan
  • Terraphim AI v1.0.0 Release Plan
  • 🎉 COMPLETE RELEASE PUBLISHED
  • Terraphim AI Release Readiness Validation Report
  • RELEASE_STATUS
  • Terraphim AI v1.0.0 Release Build Summary
  • Terraphim AI v0.2.4 Release Summary
  • RELEASE_V1.2.3_SUMMARY
  • Research Document: Automatic Updates Feature
  • Research Document: Auto-Update Signature Verification
  • Proof: Search Results Change Based on Role Selection
  • Self-Update Feature Analysis & Implementation Plan
  • Signature Verification Implementation Progress
  • 🚀 Terraphim Novel Autocomplete Testing Scripts
  • Test Implementation Report - Terraphim AI Role Coverage
  • Comprehensive Scoring Function x Haystack Test Matrix
  • 🎯 Terraphim Test Matrix - Comprehensive Results
  • Terraphim AI v1.0.1 Test Report
  • Test Report for v1.1.0 Release
  • Testing & Linting Results Summary - 2025-10-08
  • Test Results for v1.1.0 Release
  • Minimal Release Testing Summary
  • TruthForge Data Leak Response - FINAL STATUS
  • TruthForge Debug Mode - Complete Implementation & Deployment
  • TUI Validation Summary - November 11, 2025
  • TUI REPL Complete Functionality Verification Report
  • Phase 5 Validation Report: Automatic Updates Feature
  • Phase 4 Verification Report: Auto-Update Feature
  • Phase 2.1 Complete: Video Optimization ✅
  • Cloudflare Pages File Size Limitation
  • Terraphim Agent to VM Execution Integration - PROOF
  • Phase 5 Verification Report: VM Allocation Behavior
  • VM Allocation Verification - Executive Summary
  • VM Execution API Design - Comprehensive Architecture
  • VM Execution System Guide
  • VM Execution Testing Plan
  • VM Execution Integration - Implementation Summary
  • Warning Analysis and Implementation Plan - COMPLETED ✅
  • Terraphim.ai Migration: Netlify to Cloudflare Pages
  • Terraphim.ai Website Migration Complete
  • AI Agent CLI Functionality Proof Report
  • CI/CD Critical Issues - Immediate Action Required
  • CI/CD Issues Analysis and Fix Proposal
  • Cross-Reference Validation Report
  • Droid Configuration - Lessons Learned
  • Terraphim AI Security Testing Implementation - Plan Update
  • Terraphim Firecracker Project - Implementation Plan Update
  • Security Testing Lessons Learned (2025-10-07)
  • Lessons Learned - Terraphim AI Development
  • Memories - Terraphim AI Development
  • Phase 5: Final CI/CD Optimizations Implementation
  • Configuration for GitHub Labeler Action
  • Scratchpad - Active Development Tasks
  • TUI Remediation Session Summary
  • test-timeout-investigation
  • CI/CD Timeout Test - Mon 22 Dec 2025 02:30:38 PM CET
  • Terraphim AI Test and Benchmark Report
  • Testing Infrastructure Implementation Status Report
  • Terraphim TUI Implementation Completion Summary
  • Terraphim TUI Validation Report
  • Version Update Report

artifacts

  • Release v1.0.0 - Accomplishments Summary
  • GitHub Actions Fix Applied
  • Dead Code Investigation: query_rs.rs
  • Terraphim AI v1.0.0 - Final Comprehensive Status
  • Terraphim AI v1.0.0 - Final Validation Status
  • Terraphim AI v1.0.0 - Functional Validation Report
  • GitHub Actions Fix Plan for v1.0.0 Release
  • GitHub Secret Setup for Signed Tauri Releases
  • Release v1.0.0 - Status Update
  • Terraphim AI v1.0.0 Release Notes
  • Terraphim AI v1.0.0 - Step-by-Step Functional Validation

blog

  • Dynamic Ontology Launch Announcement
  • Introducing Dynamic Ontology: Schema-First Knowledge Graphs
  • FFF Search Integration: Knowledge-Graph-Augmented File Search for AI Agents

capabilities

  • FFF Search Integration -- Capability Statement

context-library

  • Context Library

designs

  • Design & Implementation Plan: DangerousPatternHook Unification
  • turbopuffer `ContainsAnyToken` vs Terraphim graph/embedding search

development

  • GrepApp Feature

domain-models

  • Terraphim AI Domain and Data Models
  • terraphim_automata - Text Matching and Autocomplete Engine
  • terraphim_config - Configuration Management
  • terraphim_middleware - Haystack Indexing and Orchestration
  • terraphim_persistence - Multi-Backend Storage Abstraction
  • terraphim_rolegraph - Knowledge Graph Implementation
  • terraphim_service - Main Service Layer
  • terraphim_types - Core Type Definitions

examples

  • Terraphim AI Examples & Integration Guide

handovers

  • Handover Document: Dynamic Ontology Feature

plans

  • Implementation Plan: Fix Search Output/Result Regressions (#578, #579)
  • Research Document: Fix `terraphim-agent`/`terraphim-cli` Search Regressions (#578, #579)
  • Research: Fix LegacyTerm deserialization in terraphim_automata
  • Research: Fix LegacyTerm deserialisation in parse_thesaurus_json
  • Implementation Plan: Make Offline Mode Default for terraphim-agent TUI
  • Research Document: Make Offline Mode Default for terraphim-agent
  • Implementation Plan: PR/Issue Execution with PR #527 Merged First
  • Implementation Plan: Post-#527 Portfolio Execution (Overall)
  • Disciplined Research: Current PR and Issue Portfolio
  • Research Document: PR #529 Gap Analysis
  • Implementation Plan: PR #529 Gap Coverage
  • Implementation Plan: Clarify `terraphim-agent` TUI Offline/Server Requirement (`terraphim-ai-cbm`)
  • Research Document: Clarify `terraphim-agent` TUI Offline/Server Requirement (`terraphim-ai-cbm`)
  • Implementation Plan: TinyClaw OpenClaw Parity via Terraphim Extensions
  • Research Document: TinyClaw OpenClaw Parity via Terraphim Extensions
  • Phase 2 Implementation Plan: TinyClaw Enhancements
  • Phase 2 Research Document: TinyClaw Enhancements
  • Implementation Plan: TinyClaw Slack Channel Adapter
  • Research Document: TinyClaw Slack Channel Adapter
  • Implementation Plan: TinyClaw Slack Test Leverage (12 Tests + 3 Bug Fixes)
  • Research Document: Leveraging OpenClaw and NanoClaw Slack Tests for TinyClaw
  • Implementation Plan: TinyClaw on Terraphim (terraphim_tinyclaw)
  • Rebuilding TinyClaw with Terraphim AI
  • Research Document: Rebuilding TinyClaw on Terraphim AI
  • Design & Implementation Plan: Revert NormalizedTerm.id and Concept.id from String to u64
  • Research Document: Revert NormalizedTerm.id and Concept.id from String to u64

reports

  • Desktop Extraction + Crate Dependency Minimization Review (2026-02-25)
  • Traceability Matrix: Issues #578 and #579
  • Validation Report: Issues #578 and #579
  • Verification Report: Issues #578 and #579

research

  • Research Document: Next PR Selection -- Post 5-PR Merge Sprint
  • Terraphim Agent and CLI Multi-Agent Orchestration Status
  • Major Version Updates Test Results
  • PR #502 Changes Summary
  • Terraphim AI -- Full Codebase Exploration Report
  • Terraphim AI Release Constraints Analysis
  • Terraphim AI Release Validation System - Architecture Design
  • Implementation Plan: Fix Cross-Mode Consistency Test Failures
  • Implementation Plan: terraphim_orchestrator -- AI Dark Factory
  • Implementation Plan: Dependabot PR Triage and Dependency Optimization
  • Terraphim AI Release Validation System - File/Module Change Plan
  • Design & Implementation Plan: Fix SearchResultDoc Compilation Errors in Integration Tests
  • Implementation Plan: Issue #589 - Wire WebToolsConfig to Web Search/Fetch Tools
  • Implementation Plan: Issue #611 - Sessions Files and By-File Subcommands
  • Implementation Plan: Issue #623 - Exclude Unused Haystack Providers
  • Implementation Plan: Issue #624 - Remove terraphim_repl, Consolidate CLIs
  • Implementation Plan: Replace atty with std::io::IsTerminal
  • Implementation Plan: OpenDAL Upgrade Decision
  • Terraphim AI Server API Testing Framework Design
  • Design & Implementation Plan Review: PR #502
  • Implementation Plan: PR #652 Merge Conflict Resolution
  • Terraphim AI Release Validation - Risk Review and Mitigation
  • Terraphim AI Release Validation System - Design Phase Summary
  • Terraphim AI Release Validation System - Design Document
  • Implementation Plan: Validation Framework for terraphim-ai
  • Research Document: Dynamic Ontology Feature Gates
  • Implementation Plan: Dynamic Ontology Feature Gates
  • Terraphim AI Functional Validation Requirements
  • Handover: terraphim_orchestrator -- AI Dark Factory
  • Terraphim AI Phase 2 Implementation Summary
  • Document Quality Evaluation Report
  • Document Quality Evaluation Report
  • Document Quality Evaluation Report
  • Research Document: Cross-Mode Consistency Test Failures
  • Research Document: AI Dark Factory -- End-to-End Multi-Agent Orchestration
  • Research Document: Dependency Optimization and Dependabot Merge Planning
  • Terraphim AI Release Validation Research Document
  • Research Document: Fix SearchResultDoc Compilation Errors in Integration Tests
  • Research Document: Issue #589 - Wire WebToolsConfig to Web Search/Fetch Tools
  • Research Document: Issue #611 - Sessions Files and By-File Subcommands
  • Research Document: Issue #623 - Exclude Unused Haystack Providers
  • Research Document: Issue #624 - Remove terraphim_repl, Consolidate CLIs
  • Research Document: Replace atty and fxhash Dependencies
  • Research Document: Replace instant with web-time
  • Research Document: OpenDAL Upgrade Analysis
  • Research Document: pi-mono vs terraphim-ai Architecture Analysis
  • Research Document: PR #502 - plan/kg dynamic routing
  • Research Document: PR #652 Agent Workflows E2E Implementation
  • Terraphim AI Release Validation Research Questions
  • Research Document: Validation Framework for terraphim-ai
  • Terraphim AI Release Risk Assessment
  • Runtime Validation Hooks Documentation## OverviewTerraphim AI implements a **two-stage runtime validation system** that provides safety and knowledge-graph enhancement for AI-assisted development workflows. This system operates through pre/post hooks around LLM generation and tool execution.## Two-Stage Hook Flow### Stage 1: Guard Stage (Security & Bypass Protection)**Purpose**: Prevent dangerous operations and enforce safety invariants before any processing occurs.**Location**: `~/.claude/hooks/pre_tool_use.sh`**Implementation**:```bash#!/bin/bash# Extract command from JSON inputCOMMAND=$(echo "$1" | jq -r '.tool_input.command // empty')# Strip quoted strings to avoid false positivesCLEAN_COMMAND=$(echo "$COMMAND" | sed 's/"[^"]*"//g')# Check for dangerous bypass flagsif [[ "$CLEAN_COMMAND" =~ (--no-verify|-n)(?=.*\bgit\s+(commit|push)) ]]; then # Return deny decision echo '{"decision": "deny", "reason": "Git bypass flags detected"}' exit 0fi# Continue to replacement stagecd ~/.config/terraphimterraphim-agent hook "$1"```**Guard Actions**:- **Block**: `--no-verify` or `-n` flags in `git commit/push` commands- **Allow**: All other commands proceed to replacement stage- **Log**: All guard decisions with reasons### Stage 2: Replacement Stage (Knowledge Graph Enhancement)**Purpose**: Replace text using knowledge graph patterns and connectivity validation.**Location**: `terraphim-agent hook` command in Terraphim agent**Implementation**:```rust// terraphim_agent/src/commands/hook.rspub async fn execute_hook( input: HookInput, agent: &TerraphimAgent,) -> Result { // Apply knowledge graph replacements let enhanced_text = agent .rolegraph .apply_replacements(&input.text)?; // Validate connectivity agent .automata .validate_connectivity(&enhanced_text)?; Ok(HookOutput { modified_text: enhanced_text, was_modified: enhanced_text != input.text, })}```**Replacement Actions**:- **Enhance**: Apply role-based knowledge graph patterns- **Validate**: Ensure semantic connectivity and coherence- **Transform**: Use thesaurus and autocomplete for consistency## Runtime LLM/Tool Hooks### Pre-LLM Hooks**Purpose**: Validate LLM inputs before generation.**Context**:```rustPreLlmContext { prompt: String, // Command type + description agent_id: String, // Agent identifier conversation_history: Vec, // Previous messages token_count: usize, // Estimated tokens}```**Hook Decisions**:- **Allow**: Proceed with LLM generation- **Block**: Stop with reason (security, policy, etc.)- **Modify**: Transform prompt (not recommended for LLM)- **AskUser**: Require human confirmation### Post-LLM Hooks**Purpose**: Validate and potentially modify LLM outputs.**Context**:```rustPostLlmContext { prompt: String, // Original prompt response: String, // Generated response agent_id: String, // Agent identifier token_count: usize, // Total tokens used model: String, // LLM model used}```**Hook Decisions**:- **Allow**: Return original response unchanged- **Block**: Prevent response delivery (harmful content, policy violations)- **Modify**: Transform response (formatting, style, safety fixes)- **AskUser**: Require human review before delivery### Pre-Tool Hooks**Purpose**: Validate code and commands before execution.**Context**:```rustPreToolContext { code: String, // Code to execute language: String, // Programming language agent_id: String, // Agent identifier vm_id: String, // VM execution environment metadata: HashMap, // Additional context}```**Security Validations**:- **Dangerous Patterns**: `rm -rf /`, `sudo`, `chmod 777`, etc.- **Language Restrictions**: Block execution in disallowed languages- **Resource Limits**: Validate memory, CPU, and file access- **Injection Prevention**: Command injection and shell escape detection### Post-Tool Hooks**Purpose**: Monitor and analyze execution results.**Context**:```rustPostToolContext { original_code: String, // Original code executed output: String, // Execution output exit_code: i32, // Process exit code duration_ms: u64, // Execution time agent_id: String, // Agent identifier vm_id: String, // VM identifier}```**Monitoring Actions**:- **Success/Failure Tracking**: Learn patterns of successful executions- **Performance Analysis**: Track execution times and resource usage- **Security Logging**: Record blocked or suspicious activities- **Knowledge Graph Learning**: Update successful patterns for future reference## Configuration### Runtime Validation Config**Location**: `~/.config/terraphim/runtime-validation.toml````toml[hooks]enabled = truefail_open = true # Allow execution if hooks fail (development mode)[guard]strict_mode = false # Block on any suspicion vs. specific patternslog_all_decisions = true # Log allow/block decisions[llm_hooks]enabled = truerequire_human_review = false # Only for high-stakes operations[tool_hooks]enabled = truevm_isolation = trueresource_limits = true[replacement]knowledge_graph_enhancement = trueconnectivity_validation = true```### Environment Variables```bash# Enable/disable specific hook categoriesTERRAPHIM_RUNTIME_VALIDATION_HOOKS=trueTERRAPHIM_GUARD_STAGE=trueTERRAPHIM_REPLACEMENT_STAGE=true# Hook behavior overridesTERRAPHIM_FAIL_OPEN=false # Production mode: fail closedTERRAPHIM_HOOK_TIMEOUT_MS=5000 # Hook execution timeout```## Hook Development### Creating Custom Hooks```rustuse crate::vm_execution::{hooks::*, VmExecutionError};#[derive(Debug)]pub struct SecurityHook { blocked_patterns: Vec,}#[async_trait]impl Hook for SecurityHook { fn name(&self) -> &str { "security-hook" } async fn pre_tool(&self, context: &PreToolContext) -> Result { for pattern in &self.blocked_patterns { if pattern.is_match(&context.code) { return Ok(HookDecision::Block { reason: format!("Blocked pattern: {}", pattern.as_str()), }); } } Ok(HookDecision::Allow) } async fn post_tool(&self, context: &PostToolContext) -> Result { // Log execution for learning if context.exit_code != 0 { log::warn!("Tool execution failed: {:?}", context); } Ok(HookDecision::Allow) }}```### Registering Hooks```rust// In agent initializationlet mut agent = TerraphimAgent::new(config).await?;// Add custom hooksagent.hook_manager.add_hook(Arc::new(SecurityHook::new()));agent.hook_manager.add_hook(Arc::new(PerformanceHook::new()));agent.hook_manager.add_hook(Arc::new(LearningHook::new()));```## Troubleshooting### Hook Not Invoked**Symptoms**: LLM/tool execution without hook validation**Causes**:- HookManager not initialized in agent- Hooks not registered with manager- Hook execution disabled in config**Resolution**:```bash# Check configcat ~/.config/terraphim/runtime-validation.toml# Verify agent initializationgrep -r "hook_manager" src/agent.rs# Check registrationgrep -r "add_hook" src/```### Hook Blocking Too Much**Symptoms**: Many operations blocked as "dangerous"**Causes**: Overly strict regex patterns, false positives**Resolution**:- Review `blocked_patterns` in security hooks- Enable debug logging to see exact matches- Adjust patterns to be more specific### Performance Issues**Symptoms**: Slow LLM/tool response times**Causes**: Hook timeout, expensive operations, network calls**Resolution**:- Increase `TERRAPHIM_HOOK_TIMEOUT_MS`- Profile hook execution with `tokio-console`- Move expensive operations to background threads## Best Practices1. **Fail-Open Development**: Use `fail_open = true` during development to avoid blocking2. **Specific Patterns**: Use targeted regex patterns instead of broad blocks3. **Async Operations**: Keep hook implementations fast and non-blocking4. **Comprehensive Logging**: Log all decisions for debugging and learning5. **Knowledge Graph Integration**: Leverage existing rolegraph and automata for intelligence6. **Security First**: Always implement security validation before functionality7. **Testing**: Test both success and failure scenarios for all hooks## Integration Points- **Claude Code**: `pre_tool_use.sh` → Guard → Replacement → Tool execution- **Terraphim Agent**: CommandExecutor with HookManager integration- **VM Execution**: Pre/post tool hooks around Firecracker execution- **LLM Generation**: Pre/post LLM hooks in all agent types- **Knowledge Graph**: Replacement service using rolegraph connectivityThis two-stage validation system ensures both security (guard stage) and intelligence enhancement (replacement stage) while maintaining clear separation of concerns and comprehensive audit trails.
  • Terraphim AI Release System Map
  • Terraphim AI Test Scenarios
  • Validation Report: terraphim_orchestrator -- AI Dark Factory
  • Terraphim AI Release Validation Implementation Roadmap
  • Validation Report: Issue #589 - Wire WebToolsConfig to Web Search/Fetch Tools
  • Validation Report: Issue #624 - terraphim_repl Removal
  • Validation Report: Validation Framework Implementation
  • Verification Report: Issue #589 - Wire WebToolsConfig to Web Search/Fetch Tools
  • Verification Report: Validation Framework Implementation
  • Verification and Validation Report: Issue #538
  • Verification and Validation Report: Issue #589
  • Verification and Validation Report: Issue #8
  • Verification and Validation Report: Issues #10, #56, #91, #96
  • Verification and Validation Report: Performance Issues #189-#203
  • Verification and Validation Report: Issues #207-#248
  • Verification and Validation Report: Issues #261-#382
  • Verification and Validation Report: Issues #539, #540, #541
  • Verification and Validation Report: KG Ranking Integration Tests
  • V-Model Final Report: Validation Framework Implementation

runbooks

  • ROC v1 Staged Rollout Runbook

sessions

  • Design & Implementation Plan: Terraphim Knowledge Graph Workflows
  • Implementation Summary: Knowledge Graph Validation Workflows
  • Research Document: Underutilized Terraphim Features for Pre/Post-LLM Knowledge Graph Workflows
  • Session 20251228-201509
  • Development Session - 2025-12-29 10:49:27
  • Session Log: Build Scripts Investigation
  • Session: Merge PR 440
  • Fetching main, creating branch, drafting detailed specification

specifications

  • Chat & Session History - Quick Reference
  • Chat and Session History Specification
  • Specification Interview Findings: Enhanced Learning Capture System
  • Terraphim Agent Session Search - Architecture Document
  • Terraphim Agent Session Search - Feature Specification
  • Terraphim Agent Session Search - Implementation Tasks
  • Terraphim-Based Codebase Evaluation Check
  • Terraphim Desktop Application - Technical Specification

src

  • Terraphim AI Architecture
  • Code of Conduct
  • Contributing to Terraphim AI
  • Using Terraphim Desktop with Claude via MCP
  • Design Decisions
  • Introduction
  • Terraphim documentation
  • Summary
  • Use cases for Terraphim AI
  • Terraphim AI Agent Evolution System Architecture
  • 5 AI Agent Workflows for Consistent Results (with Code) | Data Science Collective
  • Terraphim AI Agent Evolution System - API Reference
  • Atomic Server Integration
  • Automata Paragraph Extraction
  • Branch Protection and Security
  • Changelog
  • Claude Code Skills Integration
  • Code Assistant Implementation (PR #277)
  • How-To: Learning-Driven Command Rewriting
  • Crate Reference
  • Development Setup Guide
  • Dynamic Ontology
  • Automata Evaluation Framework
  • Graph Connectivity Check for Matched Terms
  • Haystack Configuration with Extra Parameters
  • Homebrew Formula for Terraphim AI
  • Knowledge Graph Bug Reporting Enhancement
  • Learning Compile
  • Listener Shell Dispatch
  • MCP Integration
  • OpenRouter AI-Powered Article Summarization
  • Release Process for Terraphim AI
  • Terraphim vs OpenClaw: Search Architecture Comparison
  • Terraphim Search Architecture
  • Test KG Auto-linking Demo
  • Relationship between Aircraft and Crew
  • Terraphim AI Agent Evolution System - Testing Matrix
  • TypeScript Bindings with tsify
  • Terraphim TUI
  • Terraphim AI Agent Workflow Patterns Guide

src/artifacts

  • Artifacts

src/artifacts/reports/ci

  • Artifact: GitHub Actions Fix Plan for v1.0.0 Release

src/artifacts/reports/release

  • Artifact: v1.0.0 Final Validation Status
  • Artifact: Release Status Final

src/blog

  • Your AI Agent Has Amnesia. We Fixed That.
  • Reddit Announcements
  • X/Twitter Thread

src/case-studies

  • Case Studies
  • Case Study: Symphony Builds a Web Application

src/components

  • Terraphim Atomic Client
  • Terraphim Automata
  • Terraphim Service

src/desktop

  • Desktop App

src/domains/ci

  • CI/CD Domain

src/domains/ci/case-studies

  • Deployment Lessons: Vanilla JS UI + Caddy + 1Password

src/domains/ci/reports

  • GitHub Actions Fix Plan (v1.0.0)

src/domains/desktop

  • Desktop Domain

src/domains/release

  • Release Domain

src/domains/release/reports

  • Final Validation Status (v1.0.0)

src/domains/security

  • Security Domain

src/domains/security/case-studies

  • Security Testing Lessons Learned

src/domains/vm

  • VM Domain

src/guides/setup

  • 1Password Integration for Terraphim AI\n\n## Overview\n\nThis document describes the comprehensive 1Password integration for Terraphim AI, providing enterprise-grade secret management across all components including backend services, desktop applications, and CI/CD pipelines.\n\n## Architecture\n\n### Three-Vault Strategy\n\n- **`Terraphim-Dev`**: Development environment secrets\n- **`Terraphim-Prod`**: Production environment secrets \n- **`Terraphim-Shared`**: Shared secrets across environments (signing keys, monitoring)\n\n### Integration Methods\n\n#### Method 1: Process Memory Injection (Recommended)\n```bash\n# Secrets are injected directly into process memory\nop run --env-file=\".env.terraphim\" -- cargo run\n```\n\n#### Method 2: Secure File Injection\n```bash\n# Secrets are written to secure temporary files\nop inject -i templates/settings.toml.template -o settings.toml\ncargo run\n```\n\n## Setup Instructions\n\n### 1. Install 1Password CLI\n\n**macOS:**\n```bash\nbrew install 1password-cli\n```\n\n**Linux:**\n```bash\ncurl -sS https://downloads.1password.com/linux/keys/1password.asc | gpg --import\nwget https://downloads.1password.com/linux/debian/amd64/stable/1password-cli-amd64-latest.deb\nsudo dpkg -i 1password-cli-amd64-latest.deb\n```\n\n### 2. Initialize 1Password Integration\n\n```bash\n# Run the setup script to create vaults and secret structure\n./scripts/setup-1password-terraphim.sh dev\n\n# For production setup\n./scripts/setup-1password-terraphim.sh prod\n\n# For complete setup\n./scripts/setup-1password-terraphim.sh all\n```\n\n### 3. Populate Secrets\n\nAfter running the setup script, you'll need to update the placeholder values in 1Password with actual secrets:\n\n1. Open 1Password and navigate to the appropriate vault\n2. Update each secret item with real values\n3. Ensure all `op://` references in templates are valid\n\n## Usage\n\n### Backend Services\n\n#### Option 1: Direct 1Password Integration\n```rust\nuse terraphim_settings::DeviceSettings;\n\n#[tokio::main]\nasync fn main() -> Result<(), Box> {\n // Load settings with 1Password integration\n let settings = DeviceSettings::load_with_onepassword(None).await?;\n println!(\"Loaded settings with resolved secrets\");\n Ok(())\n}\n```\n\n#### Option 2: Template-based Configuration\n```bash\n# Generate configuration from template\nop inject -i templates/settings.toml.template -o settings.toml\n\n# Run application with resolved configuration\ncargo run\n```\n\n### Desktop Application\n\nThe Tauri desktop application includes built-in 1Password commands:\n\n```typescript\nimport { invoke } from '@tauri-apps/api/tauri';\n\n// Check 1Password status\nconst status = await invoke('onepassword_status');\nconsole.log('1Password available:', status.available);\nconsole.log('1Password authenticated:', status.authenticated);\n\n// Resolve a secret reference\nconst secret = await invoke('onepassword_resolve_secret', {\n request: { reference: 'op://Terraphim-Dev/OpenRouter/API_KEY' }\n});\n\n// Process configuration with 1Password\nconst config = await invoke('onepassword_process_config', {\n request: { config: 'api_key = \"op://Terraphim-Dev/OpenRouter/API_KEY\"' }\n});\n```\n\n### CI/CD Integration\n\nUse the enhanced GitHub Actions workflow with 1Password service accounts:\n\n```yaml\n# .github/workflows/ci-1password.yml\nname: CI with 1Password\n\nenv:\n OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}\n\njobs:\n build:\n steps:\n - name: Install 1Password CLI\n uses: 1password/install-cli-action@v1\n \n - name: Generate configuration\n run: |\n op inject -i templates/env.terraphim.template -o .env.terraphim\n \n - name: Build with secrets\n run: |\n source .env.terraphim\n cargo build --release\n```\n\n## Configuration Templates\n\n### Environment Variables Template\n```bash\n# templates/env.terraphim.template\nOPENROUTER_API_KEY=\"op://Terraphim-Dev/OpenRouter/API_KEY\"\nANTHROPIC_API_KEY=\"op://Terraphim-Dev/Anthropic/API_KEY\"\nATOMIC_SERVER_SECRET=\"op://Terraphim-Dev/AtomicServer/SECRET\"\n```\n\n### Settings Configuration Template\n```toml\n# templates/settings.toml.template\n[profiles.s3]\nbucket = \"op://Terraphim-Dev/AWS_S3/BUCKET_NAME\"\naccess_key_id = \"op://Terraphim-Dev/AWS_S3/ACCESS_KEY_ID\"\nsecret_access_key = \"op://Terraphim-Dev/AWS_S3/SECRET_ACCESS_KEY\"\n```\n\n### Application Configuration Template\n```json\n{\n \"llm\": {\n \"openrouter\": {\n \"api_key\": \"op://Terraphim-Dev/OpenRouter/API_KEY\"\n }\n }\n}\n```\n\n## Secret Categories\n\n### LLM API Keys\n- **OpenRouter**: `API_KEY`, `ORGANIZATION_ID`\n- **Anthropic**: `API_KEY`, `MODEL_NAME`\n- **Ollama**: `BASE_URL`, `MODEL_NAME`\n\n### Search Services\n- **Perplexity**: `API_KEY`\n- **Atomic Server**: `URL`, `SECRET`\n- **ClickUp**: `API_TOKEN`, `TEAM_ID`, `LIST_ID`\n\n### Cloud Storage\n- **AWS S3**: `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`, `BUCKET_NAME`, `REGION`\n- **Cloudflare R2**: `ACCOUNT_ID`, `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`\n\n### External APIs\n- **GitHub**: `TOKEN`, `ORGANIZATION`, `REPOSITORY`\n- **Discord**: `BOT_TOKEN`, `GUILD_ID`, `CHANNEL_ID`\n\n### Database Connections\n- **PostgreSQL**: `CONNECTION_STRING`, `USERNAME`, `PASSWORD`\n- **Redis**: `URL`, `PASSWORD`, `HOST`, `PORT`\n\n### Shared Secrets\n- **Tauri Signing**: `PRIVATE_KEY`, `PUBLIC_KEY`, `PASSPHRASE`\n- **Code Signing**: `CERTIFICATE_PATH`, `CERTIFICATE_PASSWORD`\n- **Monitoring**: `SENTRY_DSN`, `DATADOG_API_KEY`\n\n## Security Best Practices\n\n### 1. Vault Access Control\n- Use separate vaults for different environments\n- Implement least-privilege access policies\n- Regularly audit vault permissions\n\n### 2. Secret Rotation\n- Rotate API keys regularly\n- Update 1Password references when secrets change\n- Monitor for deprecated or expired secrets\n\n### 3. Template Security\n- Never include hardcoded secrets in templates\n- Use only `op://` references in configuration templates\n- Validate template format before deployment\n\n### 4. CI/CD Security\n- Use 1Password service accounts for automation\n- Limit service account permissions to specific vaults\n- Clean up generated configuration files after use\n\n## Troubleshooting\n\n### Common Issues\n\n#### 1Password CLI Not Authenticated\n```bash\n# Sign in to 1Password\nop signin\n\n# Verify authentication\nop vault list\n```\n\n#### Secret Reference Not Found\n```bash\n# Check vault contents\nop item list --vault=\"Terraphim-Dev\"\n\n# Verify specific item\nop item get \"OpenRouter\" --vault=\"Terraphim-Dev\"\n```\n\n#### Template Processing Failed\n```bash\n# Validate template syntax\nop inject -i templates/env.terraphim.template --dry-run\n\n# Check for malformed references\ngrep -n \"op://\" templates/env.terraphim.template\n```\n\n### Debug Commands\n\n```bash\n# Test 1Password integration\ncargo run --bin debug-onepassword\n\n# Validate configuration templates\n./scripts/validate-templates.sh\n\n# Check secret resolution\nop run --env-file=\".env.terraphim\" -- env | grep -E '^(OPENROUTER|ANTHROPIC)'\n```\n\n## Development Workflow\n\n### Local Development\n1. Install 1Password CLI and authenticate\n2. Run vault setup script: `./scripts/setup-1password-terraphim.sh dev`\n3. Populate development secrets in 1Password\n4. Generate configuration: `op inject -i templates/env.terraphim.template -o .env.terraphim`\n5. Run application: `source .env.terraphim && cargo run`\n\n### Testing\n1. Use separate test vault or test-specific items\n2. Generate test configuration with mock values\n3. Run tests with isolated secrets: `op run --env-file=\".env.test\" -- cargo test`\n\n### Production Deployment\n1. Use production vault and service accounts\n2. Validate all secret references before deployment\n3. Deploy using CI/CD pipeline with 1Password integration\n4. Monitor for secret-related errors and alerts\n\n## Migration Guide\n\n### From Environment Variables\n1. Identify current environment variables\n2. Create corresponding 1Password items\n3. Update configuration templates with `op://` references\n4. Test secret resolution in development\n5. Deploy with 1Password integration\n\n### From Configuration Files\n1. Extract sensitive values from configuration files\n2. Store values in 1Password vaults\n3. Replace sensitive values with `op://` references\n4. Use `op inject` to generate final configuration\n5. Update deployment scripts to use template injection\n\n## Support\n\nFor issues with 1Password integration:\n1. Check this documentation for common solutions\n2. Validate 1Password CLI installation and authentication\n3. Review secret references and vault permissions\n4. Test with minimal configuration first\n5. Contact the Terraphim team for additional support\n\n---\n\n**Next Steps:**\n- Set up your 1Password vaults using the setup script\n- Populate secrets with real values\n- Test integration in development environment\n- Deploy with 1Password-enhanced CI/CD pipeline

src/history

  • Lessons Learned
  • Progress Memories
  • Terraphim AI Project Memory
  • Current Work: Terraphim Multi-Role Agent System Testing & Production 🚀
  • Security Testing Lessons Learned (2025-10-07)

src/history/lessons-learned

  • Comprehensive Lessons Learned - Terraphim AI Development
  • Security Testing Patterns - Terraphim AI

src/history/plans

  • Terraphim Firecracker Project - Implementation Plan
  • Terraphim AI Security Testing Implementation - Complete
  • Terraphim AI Testing Infrastructure Improvement Plan

src/howto

  • Howto: Learning Capture for Claude Code
  • Howto: Learning Capture for opencode
  • Plug Terraphim Search into Claude Code and opencode
  • Personal Assistant Role: Search Email and Notes Together

src/kg

  • Package Manager Replacement with Bun
  • API
  • Bug Reporting
  • bun install
  • bun
  • Configuration
  • Database
  • docker compose
  • Exit Classes
  • Generated with Terraphim AI
  • Terraphim Graph Embeddings: Learning Agent Guide
  • Graph
  • Haystack
  • https://terraphim.ai
  • Issue Tracking
  • Terraphim Knowledge Graph System
  • Knowledge Graph
  • Learning Capture System
  • Middleware
  • [email protected]
  • Terraphim KG Schema Linter
  • Search
  • Service
  • System
  • Terraphim-graph
  • Terraphim AI
  • Thesaurus
  • uv
  • uv add

src/kg/case-studies

  • Case Study: Knowledge Graph Validation Workflows for Pre/Post-LLM

src/kg/checklists

  • code_review_checklist
  • security_checklist

src/research

  • Design: PageRank Bug Fixes for Gitea Robot API
  • Research: PageRank Computation Bug in Gitea Robot API
  • Research Document: TypeScript Bindings for TLA+
  • Design Document: TypeScript Bindings for TLA+

src/scorers

  • Title-Scorer
  • BM25 Scorers
  • Terraphim Graph Embeddings vs Cleora
  • Terraphim Graph scorer

src/symphony

  • Symphony Orchestrator

src/testing

  • Comprehensive Testing Strategies for Terraphim
  • Knowledge Graph Ranking Expansion Testing
  • MCP Integration Testing
  • Testing Overview

src/testing/desktop

  • Desktop Testing
  • Chat Layout Responsive Design Test Plan
  • Desktop Frontend Testing Guide

taxonomy/routing_scenarios/adf

  • Implementation Tier
  • Planning Tier
  • Review Tier

updates

  • Terraphim AI Update Signing Keys

user-guide

  • Getting Started with Terraphim AI
  • Installation Guide
  • Quick Start Guide
  • Quickwit Log Exploration Guide
  • Troubleshooting Guide

validation

  • Documentation Validation Plan
  • Validation Report: Learning Capture System

verification

  • Phase 5 Verification Documentation Index
  • Verification Report: Learning Capture System
  • Verification Report: Word Boundary Matching (#395)
  • VM Allocation Architecture - Visual Verification

vibe-rules

  • Vibe-Rules

vibe-rules/global

  • Documentation Standards
  • Global Naming Conventions

vibe-rules/rust

  • Rust Async Programming Patterns
  • Rust Error Handling Patterns

walkthroughs

  • Creating a Front-End Developer Agent with Terraphim

CI/CD Domain

This section covers CI pipelines, GitHub Actions, and deployment automation.

What belongs here

  • Workflow design and debugging
  • CI reliability and performance
  • Documentation deployment

Reports

  • GitHub Actions Fix Plan (v1.0.0)

Case studies

  • Deployment Lessons: Vanilla JS UI + Caddy + 1Password
  • v1.0.0 CI + Validation Case Study
  • Case Studies Index
Development Setup Guide Deployment Lessons: Vanilla JS UI + Caddy + 1Password

© 2026 Terraphim AI documentation. Built with md-book.

GitHub