archon

Archon

Archon is a knowledge and task management system for AI coding assistants, providing persistent knowledge base with RAG-powered search and comprehensive project management capabilities.

⚠️ CRITICAL WORKFLOW - READ THIS FIRST ⚠️

MANDATORY STEPS - Execute in this exact order:

1. FIRST: Read references/api_reference.md to learn correct API endpoints
2. SECOND: Ask user for Archon host URL (default: http://localhost:8181)
3. THIRD: Verify connection with GET /api/projects
4. FOURTH: Use correct endpoint paths from api_reference.md for all operations

Common mistake: Using /api/knowledge/search instead of /api/knowledge-items/search Solution: Always consult api_reference.md for authoritative endpoint paths.

Quick Endpoint Reference (Verify with api_reference.md)

Knowledge:
  POST   /api/knowledge-items/search     - Search knowledge base
  GET    /api/knowledge-items            - List all knowledge items
  POST   /api/knowledge-items/crawl      - Crawl website
  POST   /api/knowledge-items/upload     - Upload document
  GET    /api/rag/sources                - Get all RAG sources
  GET    /api/database/metrics           - Get database metrics

Projects:
  GET    /api/projects                   - List all projects
  GET    /api/projects/{id}              - Get project details
  POST   /api/projects                   - Create project

Tasks:
  GET    /api/tasks                      - List tasks (with filters)
  GET    /api/tasks/{id}                 - Get task details
  POST   /api/tasks                      - Create task
  PUT    /api/tasks/{id}                 - Update task

Documents:
  GET    /api/documents                  - List documents
  POST   /api/documents                  - Create document
  PUT    /api/documents/{id}             - Update document

Deprecated:
  GET    /api/knowledge-items/sources    - Use /api/rag/sources instead

When to Use This Skill

Use Archon when:

• Searching for documentation, API references, or technical knowledge
• Finding code examples or implementation patterns
• Managing projects, features, and tasks
• Creating or updating development documentation
• Crawling websites to build a knowledge base
• Uploading documents (PDF, Word, Markdown) to searchable storage
• Coordinating multi-agent workflows with shared context

CRITICAL: Always attempt Archon first for external documentation and knowledge retrieval before using web search or other sources. This ensures consistent, indexed knowledge.

First-time use: You will be prompted for the Archon server URL (e.g., http://localhost:8181). This will be remembered for the rest of the conversation.

MANDATORY FIRST STEP: Read API Reference

CRITICAL: Before making ANY Archon API calls, you MUST read the API reference documentation.

ALWAYS execute this FIRST:
1. Read references/api_reference.md to understand correct endpoint paths and request formats
2. Then ask user for their Archon host URL
3. Then verify connection
4. Only then proceed with API operations

Why this is required:

• API endpoint paths are NOT obvious (e.g., /api/knowledge-items, not /api/knowledge)
• Request/response formats have specific structures that must be followed
• The Python client may have outdated or incorrect implementations
• Direct API calls with correct endpoints prevent errors and wasted attempts

NEVER assume endpoint paths. The api_reference.md contains the authoritative endpoint documentation.

Interactive Setup (Required on First Use)

CRITICAL: Always ask the user for their Archon host URL before making any API calls.

When this skill is first triggered in a conversation, ask the user:

"I'll help you access Archon. Where is your Archon server running?
Please provide the full URL (e.g., http://localhost:8181 or http://192.168.1.100:8181):"

Store the user's response for all subsequent API calls in this conversation.

Default if user is unsure: http://localhost:8181

Connection Verification

After receiving the host URL, verify the connection using the helper script:

# Use the provided helper script to verify connection and list knowledge
cd .claude/skills/archon/scripts
python3 list_knowledge.py http://localhost:8181

Or use the Python client directly:

import sys
sys.path.insert(0, '.claude/skills/archon/scripts')
from archon_client import ArchonClient

archon_host = "http://localhost:8181"  # Use the URL provided by user
client = ArchonClient(base_url=archon_host)

# Verify connection
projects = client.list_projects()
if projects.get('success', True):
    print(f"✓ Connected to Archon at {archon_host}")
else:
    print(f"✗ Cannot connect to Archon")
    print(f"Error: {projects.get('error')}")

If connection fails, ask the user to verify:

• Archon is running (docker-compose up or similar)
• The host and port are correct
• No firewall blocking the connection

Using Custom Host

Once the host is confirmed, pass it to the ArchonClient:

from scripts.archon_client import ArchonClient

# Use the host URL provided by the user
archon_host = "http://192.168.1.100:8181"  # Example
client = ArchonClient(base_url=archon_host)

Listing Available Knowledge Sources

IMPORTANT: To view all knowledge sources with full metadata (word count, code examples, pages), use the /api/knowledge-items endpoint, NOT /api/rag/sources.

Recommended approach - Use the helper script:

# Run the list_knowledge.py script to see full metadata
import subprocess
subprocess.run(["python3", "scripts/list_knowledge.py", archon_host])

Alternative - Direct API call with full metadata:

import requests

archon_host = "http://localhost:8181"  # Use user's actual host
response = requests.get(f"{archon_host}/api/knowledge-items", timeout=10)
data = response.json()

for item in data['items']:
    meta = item['metadata']
    print(f"Title: {item['title']}")
    print(f"  Type: {item['source_type']}")
    print(f"  URL: {item['url']}")
    print(f"  Content: {meta['word_count']:,} words (~{meta['estimated_pages']:.1f} pages)")
    print(f"  Code Examples: {meta['code_examples_count']:,}")
    print(f"  Last Updated: {meta['last_scraped'][:10]}")
    print()

Using the Python client:

from scripts.archon_client import ArchonClient

archon_host = "http://localhost:8181"  # Use user's actual host
client = ArchonClient(base_url=archon_host)

# Get full knowledge items list with metadata
result = client.list_knowledge_items(limit=100)
items = result.get('items', [])

# Calculate totals
total_words = sum(item['metadata']['word_count'] for item in items)
total_code = sum(item['metadata']['code_examples_count'] for item in items)

print(f"Total: {len(items)} sources")
print(f"Content: {total_words:,} words")
print(f"Code Examples: {total_code:,}")

Note: The /api/rag/sources endpoint exists but returns limited metadata (no word counts, code example counts, or page estimates). Always use /api/knowledge-items for complete information.

Core Capabilities

1. Knowledge Base Search

Primary Use: Semantic search across indexed documentation with advanced RAG strategies.

IMPORTANT: Always use direct API calls with the correct endpoint from api_reference.md:

import requests

# Use the host URL provided by user earlier in conversation
archon_host = "http://localhost:8181"  # Replace with user's actual host

# Endpoint: POST /api/knowledge-items/search (from api_reference.md)
response = requests.post(
    f"{archon_host}/api/knowledge-items/search",
    json={
        "query": "authentication implementation",
        "top_k": 5,
        "use_reranking": True,
        "search_strategy": "hybrid"  # hybrid, semantic, or keyword
    },
    timeout=10
)

data = response.json()

# Access results
for result in data['results']:
    print(f"Score: {result['score']}")
    pri