Initial commit: Multi-repository role-based knowledge graphs

2026-02-19 04:11:57 +08:00
commit 3720b9e325
19 changed files with 1218 additions and 0 deletions
@@ -0,0 +1,136 @@
+# 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
+```json
+{
+  "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
+```json
+{
+  "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
+```json
+{
+  "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
+
+```bash
+# 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