Agent skill

local-knowledge

Leverage personal notes and documentation through Terraphim's role-based search. AI agents can search developer's local knowledge organized by domain (Rust, frontend, architecture) using the terraphim-agent REPL commands.

View SKILL.md on GitHub Repository
Stars 2
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/terraphim/codex-skills/tree/main/skills/local-knowledge

SKILL.md

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

bash
# 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/:

json
{
  "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:

bash
# 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:

bash
# 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:

bash
# List available roles
/role list

# Select a role
/role select rust-engineer

# Show current role
/role current

Graph Commands:

bash
# 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:

bash
# 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:

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

Pattern 3: Code Examples

For frontend code examples, use GrepApp integration:

bash
/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
bash
# 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:

markdown
# term_name

Optional description of the term.

synonyms:: synonym1, synonym2, synonym3

Example - Rust async terms:

markdown
# 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

json
{
  "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

json
{
  "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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

terraphim/codex-skills

ubs-scanner

Run Ultimate Bug Scanner for automated bug detection across multiple languages. Detects 1000+ bug patterns including null pointers, security vulnerabilities, async/await issues, and resource leaks. Integrates with quality-gate workflow.

2 0
Explore
terraphim/codex-skills

1password-secrets

Secure secret management using 1Password CLI. Detect plaintext secrets in files and codebases, convert environment files to 1Password templates, inject secrets securely using op inject, and audit codebases for security compliance.

2 0
Explore
terraphim/codex-skills

debugging

Systematic debugging for Rust applications. Root cause analysis, logging strategies, profiling, and issue reproduction. All debug changes removed before final report.

2 0
Explore
terraphim/codex-skills

open-source-contribution

Open source contribution best practices. Creating quality pull requests, writing good issues, following project conventions, and collaborating effectively with maintainers.

2 0
Explore
terraphim/codex-skills

git-safety-guard

Blocks destructive git and filesystem commands before execution. Prevents accidental loss of uncommitted work from git checkout --, git reset --hard, rm -rf, and similar destructive operations. Works as a Claude Code PreToolUse hook with fail-open semantics.

2 0
Explore
terraphim/codex-skills

community-engagement

Open source community building and engagement. Welcoming contributors, managing discussions, writing release notes, and fostering a healthy project ecosystem.

2 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results