terraphim/local-knowledge

Local Knowledge Search

Use this skill when you need to search the developer's personal notes, documentation, or local knowledge base for context-specific information.

Overview

Terraphim enables AI coding agents to search local knowledge through role-based haystacks. Different roles have access to different knowledge domains:

| Role | Knowledge Domain | Haystacks | |------|------------------|-----------| | Terraphim Engineer | Architecture, system design | Local docs + Knowledge Graph | | Rust Engineer | Rust patterns, async, WASM | Local notes + Query.rs API | | Frontend Engineer | JavaScript, TypeScript, React | GrepApp (GitHub code search) |

When to Use This Skill

Search local knowledge when the user:

• Asks about topics in their personal notes ("in my notes", "my documentation")
• Needs domain-specific patterns they've documented before
• Asks "how do I usually do X" or "what's our pattern for Y"
• References previous solutions or bookmarked resources

Trigger Phrases:

• "check my notes about..."
• "search my documentation for..."
• "what do I have on..."
• "find my notes on..."
• Any domain-specific question (Rust async, frontend patterns, etc.)

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code Agent                         │
│  Uses /search and /role commands via terraphim-agent REPL   │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    terraphim-agent REPL                      │
│  /search "query" --role rust-engineer --limit 10            │
└───────────────────────────┬─────────────────────────────────┘
                            │
          ┌─────────────────┼─────────────────┐
          ▼                 ▼                 ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Terraphim Eng   │ │ Rust Engineer   │ │ Frontend Eng    │
│                 │ │                 │ │                 │
│ • Local docs    │ │ • Rust notes    │ │ • GrepApp JS    │
│ • expanded_docs │ │ • Query.rs      │ │ • GrepApp TS    │
│ • Knowledge KG  │ │ • Auto-gen KG   │ │                 │
└─────────────────┘ └─────────────────┘ └─────────────────┘

For Humans

Quick Start

# Build terraphim-agent with REPL features
cd /path/to/terraphim-ai
cargo build -p terraphim_agent --features repl-full --release

# Start the REPL
./target/release/terraphim-agent

# In REPL: List available roles
/role list

# Switch to Rust Engineer role
/role select rust-engineer

# Search your notes
/search "async iterator patterns" --limit 5

Role Configuration

Roles are defined in JSON config files at terraphim_server/default/:

{
  "roles": {
    "Rust Engineer": {
      "relevance_function": "title-scorer",
      "haystacks": [
        {
          "location": "/path/to/your/notes",
          "service": "Ripgrep",
          "extra_parameters": { "glob": "*rust*.md" }
        }
      ]
    }
  }
}

Adding Your Own Notes

1. Create a notes directory (e.g., ~/notes/rust/)
2. Add markdown files with your knowledge
3. Update role config to include the directory as a Ripgrep haystack
4. Optionally create a knowledge graph for semantic term expansion

For AI Agents

Detecting Terraphim Capabilities

Check if terraphim-agent is available:

# Find the agent binary
if command -v terraphim-agent >/dev/null 2>&1; then
    AGENT="terraphim-agent"
elif [ -x "./target/release/terraphim-agent" ]; then
    AGENT="./target/release/terraphim-agent"
elif [ -x "$HOME/projects/terraphim/terraphim-ai/target/release/terraphim-agent" ]; then
    AGENT="$HOME/projects/terraphim/terraphim-ai/target/release/terraphim-agent"
fi

REPL Command Reference

Search Commands:

# Basic search (uses current role)
/search "query string"

# Search with specific role
/search "async patterns" --role rust-engineer

# Limit results
/search "error handling" --limit 5

# Semantic search (uses knowledge graph)
/search "error handling" --semantic

# Concept-based search
/search "error handling" --concepts

Role Commands:

# List available roles
/role list

# Select a role
/role select rust-engineer

# Show current role
/role current

Graph Commands:

# Show knowledge graph terms
/graph

# Show top K terms
/graph --top-k 20

Search Patterns for AI Agents

Pattern 1: Domain-Specific Search

When the user asks about a specific domain, select the appropriate role first:

# User asks about Rust async
/role select rust-engineer
/search "async iterator" --limit 5

Pattern 2: Broad Knowledge Search

For general questions, use the Terraphim Engineer role with expanded_docs:

/role select terraphim-engineer
/search "atomic data server configuration"

Pattern 3: Code Examples

For frontend code examples, use GrepApp integration:

/role select frontend-engineer
/search "useState useEffect pattern"

Interpreting Results

Search results include:

• title: Document/note title
• url: File path or source URL
• body: Content excerpt
• description: Summary (if LLM summarization enabled)
• rank: Relevance score

Example output:

Results for "async iterator":

1. [rust-matching-iterators.md]
   Path: /Users/alex/notes/rust-matching-iterators.md
   Async iterator over AWS S3 pagination using State enum...

2. [rust-python-extension.md]
   Path: /Users/alex/notes/rust-python-extension.md
   PyO3/Maturin async patterns for Python extensions...

Error Handling

If terraphim-agent is not available or fails:

1. Graceful degradation: Continue without local search
2. Notify user: "Local knowledge search unavailable, using general knowledge"
3. Fallback: Use web search or built-in knowledge

# Check if search succeeded
if ! /search "query" 2>/dev/null; then
    echo "Local search unavailable, falling back to general knowledge"
fi

Knowledge Graph Format

Knowledge graph files enable semantic term expansion:

# term_name

Optional description of the term.

synonyms:: synonym1, synonym2, synonym3

Example - Rust async terms:

# async_iterator

Async iterators in Rust using Stream trait and async/await.

synonyms:: Stream, AsyncIterator, futures::Stream, tokio::stream

Configuration Examples

Rust Engineer with Local Notes

{
  "Rust Engineer": {
    "shortname": "rust-engineer",
    "relevance_function": "terraphim-graph",
    "kg": {
      "knowledge_graph_local": {
        "input_type": "markdown",
        "path": "docs/src/kg/rust_notes_kg"
      }
    },
    "haystacks": [
      {
        "location": "/Users/alex/synced/expanded_docs",
        "service": "Ripgrep",
        "extra_parameters": { "glob": "*rust*.md" }
      },
      {
        "location": "https://query.rs",
        "service": "QueryRs"
      }
    ]
  }
}

Frontend Engineer with GrepApp

{
  "Frontend Engineer": {
    "shortname": "frontend-engineer",
    "relevance_function": "title-scorer",
    "haystacks": [
      {
        "location": "https://grep.app",
        "service": "GrepApp",
        "extra_parameters": { "language": "JavaScript" }
      },
      {
        "location": "https://grep.app",
        "service": "GrepApp",
        "extra_parameters": { "language": "TypeScript" }
      }
    ]
  }
}

Troubleshooting

| Issue | Solution | |-------|----------| | No results returned | Check haystack path exists and contains .md files | | Wrong role active | Use /role select <name> to switch | | Search too slow | Reduce --limit or use more specific queries | | KG not loading | Verify path in config and markdown format | | Agent not found | Build with cargo build -p terraphim_agent --features repl-full --release |

Related Skills

• terraphim-hooks - For text replacement using knowledge graph
• session-search - For searching AI coding session history
• rust-development - For Rust-specific patterns