Skip to content

Chat Interface

The Compendium chat interface lets you interact with the system agent to query, search, and curate your knowledge catalog. Available through both the web UI and CLI.

Starting a Chat Session

Via Web UI

  1. Start the web server: 

    ./bin/web/Compendium.Web          # Linux/macOS
.\bin\web\Compendium.Web.exe      # Windows

  2. Navigate to http://localhost:5050

  3. Load your bundle:

  4. Click "Load Bundle"
  5. Select your bundle directory

  6. Or configure default bundle in appsettings.json

  7. Configure LLM (if not already set):

  8. Go to "Settings"

  9. Enter API endpoint, key, and model

  10. Go to "Chat" tab and start asking questions

Via CLI

# Read-only session (default)
compendium chat --bundle my-catalog

# With write permissions
compendium chat --bundle my-catalog --allow-write

Agent Capabilities

Read-Only Mode (Default)

Available tools:

  • ListConcepts — Browse concepts, optionally filtered by type
  • ListConceptTypes — List the concept types this bundle's spec recognizes (from .compendium/config.json, if present)
  • ReadConcept — View a specific concept's raw content
  • SearchConcepts — Full-text search across titles, descriptions, and bodies
  • ReadFile / ListFiles / ReadDirectoryStructure — Inspect files outside the bundle (e.g. source code or docs) for grounding

Example queries:

List all systems
Show me the Order Management System concept
Search for "payment processing"
What integrations are documented?
Which systems are tagged as critical?

Write Mode (--allow-write)

Additional curation tools:

  • CreateConcept — Mint new concepts
  • UpdateConceptBody — Edit concept content
  • AddLink — Link concepts together
  • FlagForReview — Mark concepts for human review

Agent-created content stays draft

The agent can never promote concepts to stable or set verified metadata. Only humans can approve concepts.

Example queries:

Create a concept for the new Analytics API
Update the Payment Gateway concept with recent changes
Link the Order Management System to the Payment Gateway
Flag the Inventory System concept as potentially stale

Common Query Patterns

Discovery

List all concepts
What concept types exist?
Show me all systems
List data maps

Search for "authentication"
Find concepts about payments
Which integrations mention the CoreDB database?
Show concepts tagged as security-sensitive

Relationships

What systems does the Order Management System depend on?
Show me all integrations that read from the Warehouse database
What processes involve the Payment Gateway?
Trace the data lineage for customer email addresses

Metadata Queries

Which concepts are marked as draft?
Show me concepts without verification
List concepts that are stale
What concepts were generated by the agent?

Data Map Queries

For bundles containing data maps:

Which integrations read from the CoreDB database?
Show me all data flows that output to files
What integrations transform data to uppercase?
List all source systems in the data maps
Which integrations send emails?

The agent can leverage structured metadata (source_systems, destination_types, field_count) for precise answers.

Agent Curation Workflow

With --allow-write, the agent can maintain your catalog:

1. Ingest New Content

User: I have new documentation about the Analytics API
Agent: I'll create a concept for it. [creates draft concept]

2. Update Existing Concepts

User: The Payment Gateway now uses Stripe v2 API
Agent: I'll update the Payment Gateway concept [updates concept body]

User: The Order Management System depends on the Payment Gateway
Agent: I'll add that relationship [links concepts]

4. Flag for Review

User: Is the Inventory System concept still accurate?
Agent: The concept mentions an old database server. I'll flag it for review. [adds to log.md]

Response Format

Agent responses include:

  • Direct answers — Natural language responses
  • Citations — Links to specific concepts
  • Metadata — Structured data from frontmatter
  • Tool results — Output from catalog operations

Example:

User: What does the Order Management System do?

Agent: The Order Management System (OMS) handles customer orders from 
placement through fulfillment. It integrates with:
- Payment Gateway (Stripe) for payment processing
- Inventory System for stock checks
- Warehouse Management System for fulfillment

Source: systems/order-management.md
Status: stable (verified 2026-08-10)

Settings and Configuration

CLI Options

compendium chat --bundle my-catalog     # Read-only
compendium chat --bundle my-catalog --allow-write  # With curation tools

The model isn't a per-session flag — it's configured once via compendium init or the Web UI's Settings page.

Web UI Default Bundle

The bundle the Web UI loads at startup is set in Compendium:BundlePath in src/Compendium.Web/appsettings.json:

{
  "Compendium": {
    "BundlePath": "catalog/sample"
  }
}

LLM Provider

Configure via compendium init or the Web UI's Settings page — either one configures both surfaces, with no config file to hand-edit. For CI or scripting, environment variables are also honored as a fallback:

export LITELLM_BASE_URL="https://api.openai.com/v1"
export LITELLM_API_KEY="sk-..."
export LITELLM_MODEL="gpt-4"

See Configuration Guide for details.

Tips and Best Practices

1. Be Specific

❌ "Tell me about systems" ✅ "List all systems tagged as critical"

2. Provide Context

❌ "What's the integration?" ✅ "Show me the integration that connects Order Management to Warehouse"

3. Ask for Citations

"Show me the concept where that's documented" "What's the source of that information?"

4. Review Agent Changes

Always review concepts created or updated by the agent before promoting to stable:

# Check recent agent changes
git log --author="agent:compendium" --oneline

# Review a specific concept
cat systems/new-concept.md

5. Use Write Mode Sparingly

Enable --allow-write only when actively curating. For queries, read-only mode is safer.

Session Management

CLI Sessions

  • Exit: Type exit (case-insensitive), press Enter on an empty line, or Ctrl+C
  • Each line you type is one query — there's no in-session command history or multi-line input today

Web UI Sessions

  • Persistent: Sessions persist across page refreshes
  • History: Full conversation history displayed
  • Export: Copy conversation to clipboard

Troubleshooting

Agent Can't Find Concepts

Problem: "I couldn't find any concepts about..."

Solutions: - Check bundle path is correct - Verify concepts exist: ls my-bundle/systems/ - Try broader search: "List all concepts" - Check concept status: agent might only see stable concepts in some configurations

Agent Won't Create/Update

Problem: "I don't have permission to create concepts"

Solution: Enable write mode: compendium chat --bundle my-catalog --allow-write

Slow Responses

Problem: Queries take a long time

Solutions: - Use a faster model (e.g., gpt-3.5-turbo instead of gpt-4) - Reduce bundle size by archiving old concepts - Be more specific in queries to reduce search space

Connection Errors

Problem: "Failed to connect to LLM provider"

Solutions: - Check configuration: re-run compendium init, or view current settings on the Web UI's Settings page (the API key itself is never displayed) - Verify base URL is correct - Test connectivity: curl -I https://api.openai.com/v1/models - Check firewall/proxy settings

Next Steps