terraphim-kg-config/KG_ROLES.md

Multi-Repository Role-Based Knowledge Graphs

Overview

Terraphim supports role-specific knowledge graphs for different repositories/projects.

Role Configuration

Each role can have:

• Unique thesaurus - Domain-specific synonyms
• Custom haystacks - Repository-specific search paths
• Different embeddings - Controlled embedding strategies
• Access control - Public/private settings

Example Roles

1. Terraphim AI Developer

{
  "name": "Terraphim AI Developer",
  "kg": {
    "knowledge_graph_local": {
      "path": "terraphim-ai/kg"
    }
  },
  "haystacks": [
    { "location": "terraphim-ai/crates", "service": "Ripgrep" },
    { "location": "terraphim-ai/docs", "service": "Ripgrep" }
  ],
  "extra": {
    "embeddings_model": "local",
    "synonym_depth": "deep"
  }
}

Thesaurus Concepts:

• Rust (rust, cargo, tokio, async)
• Knowledge Graph (kg, thesaurus, ontology)
• Agent (ai, assistant, claude, llm)
• Search (retrieval, query, find)
• Role (persona, expert, engineer)

2. OpenClaw Developer

{
  "name": "OpenClaw Developer",
  "kg": {
    "knowledge_graph_local": {
      "path": "openclaw/kg"
    }
  },
  "haystacks": [
    { "location": "openclaw/src", "service": "Ripgrep" },
    { "location": "openclaw/docs", "service": "Ripgrep" }
  ],
  "extra": {
    "embeddings_model": "local",
    "synonym_depth": "standard"
  }
}

Thesaurus Concepts:

• TypeScript (ts, js, node, npm)
• Gateway (server, api, websocket)
• Channel (telegram, discord, slack)
• Skill (tool, capability, extension)
• Config (configuration, settings, json)

3. Learning Capture

{
  "name": "Learning Capture System",
  "kg": {
    "knowledge_graph_local": {
      "path": "~/.config/terraphim/docs/src/kg"
    }
  },
  "haystacks": [
    { "location": "~/.local/share/terraphim/learnings", "service": "Ripgrep" },
    { "location": "~/.openclaw/workspace/memory", "service": "Ripgrep" }
  ],
  "extra": {
    "embeddings_model": "local",
    "synonym_depth": "deep",
    "synonym_expansion": true
  }
}

Thesaurus Concepts: (20 groups)

• Knowledge, Configuration, Git, AI Assistant
• Tool, Storage, Context Management, Retrieval
• Failure, Documentation, Programming Languages
• Testing, Security, Performance, Build
• Execution, Debugging, Repair

Embeddings Control

Role	Model	Depth	Use Case
Terraphim AI	local	deep	Complex reasoning
OpenClaw	local	standard	Balanced
Last30Days	none	basic	Simple lookup
System Operator	none	minimal	Log analysis
Learning Capture	local	deep	Semantic memory

Switching Roles

# List available roles
terraphim-agent roles list

# Switch to specific role
terraphim-agent roles select "LearningCapture"

# Search within current role
terraphim-agent learn query "setup"

Benefits

1. Isolation - Each repo has its own KG
2. Specialization - Domain-specific synonyms
3. Performance - Controlled embedding scope
4. Privacy - Public/private KG settings
5. Flexibility - Different search strategies per role

Files Created

• ~/.config/terraphim/multi_repo_roles.json - Role definitions
• ~/.config/terraphim/kg/terraphim-ai/ - Terraphim AI KG
• ~/.config/terraphim/kg/openclaw/ - OpenClaw KG
• ~/.config/terraphim/kg/last30days/ - Last30Days KG
• ~/.config/terraphim/kg/system/ - System Operator KG