Skip to content
Crucible

Your First Kiln

This guide walks you through creating a new kiln from scratch. By the end, you’ll have a working knowledge base ready for notes.

What is a Kiln?

A kiln is simply a directory containing markdown files. Crucible processes these files into a searchable knowledge graph. Think of it like an Obsidian vault or a folder of notes.

Creating Your Kiln

1. Choose a Location

Pick where your notes will live:

Terminal window
# Personal notes
mkdir -p ~/Documents/my-kiln


# Project documentation
mkdir -p ~/projects/my-project/docs


# Shared team knowledge
mkdir -p /shared/team-knowledge

2. Initialize the Directory

Create a basic structure:

Terminal window
cd ~/Documents/my-kiln


# Create some starter folders
mkdir -p Notes Projects Reference

3. Create Your First Note

Create Notes/Welcome.md:

---
description: My first note
tags:
  - meta
---


# Welcome to My Kiln


This is my knowledge base. Here I'll store notes, ideas, and references.


## Getting Started


- [[Notes/Ideas]] - Capture thoughts
- [[Projects/Current]] - Active work
- [[Reference/Index]] - Reference materials

4. Configure Crucible

Register the kiln in your global config under the [kilns] section:

Terminal window
mkdir -p ~/.config/crucible
cat > ~/.config/crucible/config.toml << 'EOF'
default_kiln = "my-kiln"


[kilns]
my-kiln = "/home/user/Documents/my-kiln"


[enrichment.provider]
type = "fastembed"
EOF

The simpler way is to let cru init do this for you from inside the kiln directory — it creates .crucible/kiln.toml, registers the kiln in your global config, and prompts for a data classification.

5. Process Your Notes

Terminal window
cru process

You should see:

Processing kiln via daemon...
Pipeline processing complete!
  Discovered: 1 indexable files
  Processed: 1 files
  Skipped (unchanged): 0 files

6. Verify Setup

Terminal window
cru stats

You should see your kiln statistics.

Building Your Structure

Start Simple

Don’t over-organize from the start:

my-kiln/
  Notes/          # Day-to-day notes
  Projects/       # Active work
  Reference/      # Stable reference material

Let Structure Emerge

As you add notes, patterns will emerge. Then you can:

  • Add more folders as needed
  • Create index notes (MOCs)
  • Adopt an organizational system like PARA

The power of a kiln is in connections:

This idea relates to [[Other Note]].


See also:
- [[Related Concept]]
- [[Another Idea#specific-section]]

Adding Metadata

Frontmatter

Every note benefits from frontmatter:

---
description: Main project documentation
tags:
  - project
  - active
created: 2024-01-15
---

Tags

Use tags for cross-cutting organization:

#status/active #priority/high #project/alpha

Processing Workflow

Initial Processing

First run processes everything:

Terminal window
cru process

Incremental Updates

Subsequent runs only process changes:

Terminal window
cru process

Watch Mode

Auto-process on file changes:

Terminal window
cru process --watch

Using Your Kiln

Find content directly:

Terminal window
cru search "project planning"

Or ask the agent:

Terminal window
cru chat "Find notes about project planning"

Chat

Explore with AI:

Terminal window
cru chat

Stats

Check kiln health:

Terminal window
cru stats

Next Steps

Now that you have a working kiln:

  1. Add more notes - Start capturing ideas
  2. Create connections - Link related notes with wikilinks
  3. Choose a structure - See Index
  4. Learn commands - Read Basic Commands
  5. Configure agents - Explore agents

Common Questions

Can I use existing notes?

Yes! Point Crucible at any folder with markdown files.

Do I need frontmatter?

It’s recommended but not required. Frontmatter enables property search and better metadata.

How do I backup?

Your kiln is just files. Use any backup method:

  • Git for version control
  • Cloud sync (Dropbox, iCloud)
  • Regular file backups

Can I use Obsidian too?

Yes! Crucible is compatible with Obsidian vaults. Just point to the same directory.

See Also