Knowledge Bases

Built-in Knowledge

HQ ships with 10 knowledge bases in core/knowledge/public/:

Knowledge Base	Path	Contents
Ralph	`core/knowledge/public/Ralph/`	Coding methodology — overview, core concepts, back-pressure, specifications, implementation
Workers	`core/knowledge/public/workers/`	Worker framework — Ralph loop pattern, skill schema, state machines, templates
HQ Core	`core/knowledge/public/hq-core/`	HQ system docs — agent session contract, thread and checkpoint schemas
AI Security Framework	`core/knowledge/public/ai-security-framework/`	Security framework — principles, checklists, templates
Agent Browser	`core/knowledge/public/agent-browser/`	Browser automation — auth profiles, social posting, Tauri testing
Brand Voice	`core/knowledge/public/brand-voice/`	Brand-voice packs and their schema
Getting Started	`core/knowledge/public/getting-started/`	HQ cheatsheet, quick-start guide, learning path
Dev Team	`core/knowledge/public/dev-team/`	Development patterns, troubleshooting, workflows
Loom	`core/knowledge/public/loom/`	Agent patterns reference — architecture, state machines, thread system
Projects	`core/knowledge/public/projects/`	Project templates — README template for new projects

core/ is replaced when you run /update-hq, so don’t edit these files. Put your own knowledge in personal/knowledge/ or companies/{co}/knowledge/.

Personal and Company Knowledge

After running /setup, you’ll have personal knowledge:

personal/knowledge/
├── profile.md           # Your identity, role, goals
└── voice-style.md       # Writing voice and style preferences

Each company has its own knowledge folder at companies/{co}/knowledge/. For a cloud-backed company, that folder syncs to the company vault, so teammates get the same files.

Real Directories, Not Symlinks

Knowledge bases are plain directories inside HQ. Don’t symlink knowledge into repos/: cloud sync records a symlink as a marker and teammates receive no content.

Company knowledge stays a plain directory with no Git metadata. It syncs through the company vault.
Personal knowledge may use an embedded Git repo when you want separate version history.

If you have older knowledge bases that are symlinks into repos/, hq reindex converts them into real directories.

Adding New Knowledge

Create a directory:

mkdir -p personal/knowledge/my-topic

For company knowledge, use companies/{co}/knowledge/my-topic instead.

Add content (markdown files)
Optional, personal knowledge only: give it its own version history:

cd personal/knowledge/my-topic
git init
git add . && git commit -m "init knowledge repo"

Update the search index:

hq index sync

Using Knowledge in Workers

Workers reference knowledge bases in their worker.yaml:

context:
  base:
    - core/knowledge/public/Ralph/
    - core/knowledge/public/workers/
    - companies/my-company/knowledge/

When a worker runs, your AI tool loads these paths as context, giving the worker access to all relevant knowledge.

Search Across Knowledge

All knowledge bases are indexed by qmd:

/search "deployment best practices"

This searches across HQ content and indexed repos.