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

Configuration

Configuration management and settings for the application.

synonyms:: application configuration, runtime configuration

security_checklist

Database

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