Documentation | Terraphim AI documentation

Guide

Cloudflare Pages Deployment for Terraphim AI Documentation

Terraphim AI Performance Benchmarking Framework

Release Process Documentation

Terraphim Agent Auto-Update System

Terraphim AI Component Architecture

Conare AI vs Terraphim: Context Engineering Comparison

Context Collections Management

Context Engineering with Terraphim: Quick Start

Contributing to Terraphim-AI

Terraphim AI Deployment Guide

Terraphim GitHub Runner - Architecture Documentation

Terraphim GitHub Runner - Setup Guide

Terraphim AI Installation and Deployment Guide

LLM Proxy Configuration Guide

MCP File Context Tools

Perplexity Integration for Terraphim AI

Platform-Specific Installation Guide

Quickwit Integration Guide

Sentrux Quality Gates

Terraphim TUI Features

Terraphim Terminal User Interface (TUI)

Released VS Code extension with a real Terraphim server

architecture

Architecture

Polyrepo topology (Gitea #1910)

Architecture: terraphimagent

architecture/adr

ADR-0002: Polyrepo GitHub Publish Pipeline

architecture/dsm

Phase 1 §1 — Tooling Inventory

Aggregator decoupling sketch (Stage B, Gitea #1910)

Phase 1 §10 — Experimental Crate Register

Phase 1 §4 — Hub Fan-In Summary

architecture/dsm/timings

Cold-build timing baseline -- Stage A (Gitea #1910)

capabilities

FFF Search Integration -- Capability Statement

context-library

Context Library

domain-models

Terraphim AI Domain and Data Models

terraphimautomata - Text Matching and Autocomplete Engine

terraphimconfig - Configuration Management

terraphimmiddleware - Haystack Indexing and Orchestration

terraphimpersistence - Multi-Backend Storage Abstraction

terraphimrolegraph - Knowledge Graph Implementation

terraphimservice - Main Service Layer

terraphimtypes - Core Type Definitions

examples

Terraphim AI Examples & Integration Guide

Example: terraphimagent shared learning end-to-end

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

specifications/adf

ADF Behaviour Specifications

Specification: Local Project Skill Path Resolution

Specification: Provider Probe Timeout and Health Classification

Specification: Redacted Output Capture and Timeout Reporting

Specification: Webhook Group Alias Dispatch and Expansion Limits

Specification: Worktree Fail-Closed Behaviour

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

Installing Terraphim AI

Knowledge Graph Bug Reporting Enhancement

Learning Compile

Listener Shell Dispatch

MCP Integration

OpenRouter AI-Powered Article Summarization

Release Channels

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

Dynamic Ontology Launch Announcement

Introducing Dynamic Ontology: Schema-First Knowledge Graphs

FFF Search Integration: Knowledge-Graph-Augmented File Search for AI Agents

Your AI Agent Has Amnesia. We Fixed That.

Reddit Announcements

Reddit Announcements -- Terraphim Grep

Hybrid Code Search That Knows When to Ask an LLM

Grep That Knows When to Ask an LLM

X/Twitter Thread

X/Twitter Thread -- Terraphim Grep

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)\nbash\n# Secrets are injected directly into process memory\nop run --env-file=\".env.terraphim\" -- cargo run\n\n\n#### Method 2: Secure File Injection\nbash\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\nmacOS:\nbash\nbrew install 1password-cli\n\n\nLinux:\nbash\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\nbash\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\nrust\nuse terraphimsettings::DeviceSettings;\n\n#tokio::main\nasync fn main() - Result {\n // Load settings with 1Password integration\n let settings = DeviceSettings::loadwithonepassword(None).await?;\n println!(\"Loaded settings with resolved secrets\");\n Ok(())\n}\n\n\n#### Option 2: Template-based Configuration\nbash\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\ntypescript\nimport { invoke } from '@tauri-apps/api/tauri';\n\n// Check 1Password status\nconst status = await invoke('onepasswordstatus');\nconsole.log('1Password available:', status.available);\nconsole.log('1Password authenticated:', status.authenticated);\n\n// Resolve a secret reference\nconst secret = await invoke('onepasswordresolvesecret', {\n request: { reference: 'op://Terraphim-Dev/OpenRouter/APIKEY' }\n});\n\n// Process configuration with 1Password\nconst config = await invoke('onepasswordprocessconfig', {\n request: { config: 'apikey = \"op://Terraphim-Dev/OpenRouter/APIKEY\"' }\n});\n\n\n### CI/CD Integration\n\nUse the enhanced GitHub Actions workflow with 1Password service accounts:\n\nyaml\n# .github/workflows/ci-1password.yml\nname: CI with 1Password\n\nenv:\n OPSERVICEACCOUNTTOKEN: ${{ secrets.OPSERVICEACCOUNTTOKEN }}\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\nbash\n# templates/env.terraphim.template\nOPENROUTERAPIKEY=\"op://Terraphim-Dev/OpenRouter/APIKEY\"\nANTHROPICAPIKEY=\"op://Terraphim-Dev/Anthropic/APIKEY\"\nATOMICSERVERSECRET=\"op://Terraphim-Dev/AtomicServer/SECRET\"\n\n\n### Settings Configuration Template\ntoml\n# templates/settings.toml.template\nprofiles.s3\nbucket = \"op://Terraphim-Dev/AWSS3/BUCKETNAME\"\naccesskeyid = \"op://Terraphim-Dev/AWSS3/ACCESSKEYID\"\nsecretaccesskey = \"op://Terraphim-Dev/AWSS3/SECRETACCESSKEY\"\n\n\n### Application Configuration Template\njson\n{\n \"llm\": {\n \"openrouter\": {\n \"apikey\": \"op://Terraphim-Dev/OpenRouter/APIKEY\"\n }\n }\n}\n\n\n## Secret Categories\n\n### LLM API Keys\n- OpenRouter: APIKEY, ORGANIZATIONID\n- Anthropic: APIKEY, MODELNAME\n- Ollama: BASEURL, MODELNAME\n\n### Search Services\n- Perplexity: APIKEY\n- Atomic Server: URL, SECRET\n- ClickUp: APITOKEN, TEAMID, LISTID\n\n### Cloud Storage\n- AWS S3: ACCESSKEYID, SECRETACCESSKEY, BUCKETNAME, REGION\n- Cloudflare R2: ACCOUNTID, ACCESSKEYID, SECRETACCESSKEY\n\n### External APIs\n- GitHub: TOKEN, ORGANIZATION, REPOSITORY\n- Discord: BOTTOKEN, GUILDID, CHANNELID\n\n### Database Connections\n- PostgreSQL: CONNECTIONSTRING, USERNAME, PASSWORD\n- Redis: URL, PASSWORD, HOST, PORT\n\n### Shared Secrets\n- Tauri Signing: PRIVATEKEY, PUBLICKEY, PASSPHRASE\n- Code Signing: CERTIFICATEPATH, CERTIFICATEPASSWORD\n- Monitoring: SENTRYDSN, DATADOGAPIKEY\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\nbash\n# Sign in to 1Password\nop signin\n\n# Verify authentication\nop vault list\n\n\n#### Secret Reference Not Found\nbash\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\nbash\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\nbash\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\nNext 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

AI Agent Onboarding Quickstart

Graph Embeddings for Checklists

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

3 Ways to Save Money on Tokens for Your AI Agents

Zero-Token LLM Routing: Deterministic Decisions Before the Call

src/kg

Package Manager Replacement with Bun

Example Knowledge Graph

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

codereviewchecklist

securitychecklist

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

Decision Tier

Implementation Tier

Planning Tier

Review Tier

taxonomy/runner

Runner Command Policy

updates

Terraphim AI Update Signing Keys

user-guide

Getting Started with Terraphim AI

Installation Guide

Quick Start Guide

Quickwit Log Exploration Guide

Setting Up Telegram Bot with TinyClaw

Enabling terraphim-grep Offline (lessons learned)

Troubleshooting Guide

walkthroughs

Creating a Front-End Developer Agent with Terraphim