Add Knowledge

Add PDFs, markdown, spreadsheets, and more to give agents domain expertise. MUXI indexes your documents automatically and retrieves relevant context when users ask questions.

Overview

Knowledge sources let agents answer questions from your documents.

Step 1: Create Knowledge Directory

mkdir -p knowledge/docs

Add your documents:

knowledge/
└── docs/
    ├── getting-started.md
    ├── api-reference.md
    └── faq.md

Step 2: Configure Agent

Create agents/assistant.afs:

schema: "1.0.0"
id: assistant
name: Assistant
description: Helpful assistant with knowledge access

system_message: You are a helpful assistant.

knowledge:
  enabled: true
  sources:
    - path: knowledge/docs/
      description: Product documentation

Step 3: Test

muxi up

Ask about your docs:

You: How do I get started?
Assistant: Based on the documentation... [uses knowledge]

Multiple Sources

knowledge:
  sources:
    - path: knowledge/docs/
      description: Product documentation
    - path: knowledge/faq/
      description: Frequently asked questions
    - path: knowledge/policies/
      description: Company policies

Configuration Options

knowledge:
  enabled: true
  embed_batch_size: 50
  max_files_per_source: 10
  sources:
    - path: knowledge/docs/
      description: Documentation
      recursive: true              # Include subdirs
      allowed_extensions: [".md"]  # Only markdown
      file_limit: 20               # Max files
      max_file_size: 5242880       # 5MB limit

Supported Formats

Office documents convert with anydoc as the primary engine, with MarkItDown as a per-file fallback and as the converter for the formats anydoc does not claim. PDFs route to a dedicated pdf-inspector engine, with MarkItDown as fallback.

Conversion runs in a sandboxed subprocess with resource limits and a wall-clock timeout. Files that time out, exhaust memory, exceed size limits, are encrypted, or crash the parser are quarantined and skipped - indexing continues with the rest of your sources.

Agent-Specific Knowledge

Different agents, different knowledge:

agents:
  - id: support
    knowledge:
      sources:
        - path: knowledge/support/
          description: Support FAQs

  - id: sales
    knowledge:
      sources:
        - path: knowledge/pricing/
          description: Pricing info

Update Knowledge

When files change:

1. MUXI detects changes (MD5 hash)
2. Re-indexes updated files
3. Cache invalidates automatically

Or force reindex:

muxi knowledge rebuild

Troubleshooting

Knowledge Not Found

Check paths are relative to formation:

# Good
path: knowledge/docs/

# Bad
path: /absolute/path/to/docs/

Files Not Loading

Check file size limits:

knowledge:
  sources:
    - path: knowledge/
      max_file_size: 10485760  # 10MB

Next Steps

• Knowledge Reference - Full configuration
• Add Memory - Conversation memory