I Built a Chatbot to Query My YAML Knowledge Base

Every business runs on scattered knowledge. Notion pages, Google Docs, Slack threads, someone’s memory. When you need to find something, you open three tabs and ask two people.

I spent a week pulling all of mine into a folder of YAML files. Every contact, every project, every service offering, every content idea, every daily work log. 60+ structured records in one Git repository. Then I built a chatbot that could answer any question about my business in seconds.

The numbers:

• 60+ structured YAML records
• 1 Git repository as the single source of truth
• 0 databases, SaaS subscriptions, or vendor lock-in
• 1 day to build the chatbot with Claude Code

What Is a Knowledge Operating System?

Knowledge Operating System. A structured, AI-readable knowledge base stored as YAML files in a Git repository. It is not a database. It is not a CRM. It is not a project management tool. But it does what all three do.

The core idea: consolidate scattered knowledge into one source of truth that both humans and AI agents can read.

The philosophy behind it is Systems Before Tools. Design the architecture first. Then pick the technology. Most people do it backwards. They buy Notion, then try to organize their business inside Notion’s constraints. A Knowledge Operating System starts with the structure. The tools that read it are interchangeable.

The pattern: Anyone running a business has the same categories of knowledge: people, projects, services, content, ideas, logs. The KOS gives each one a home.

The Folder Structure

Here is the generalized directory tree:

knowledge-base/
├── data/
│   ├── contacts/          # People you work with
│   ├── businesses/        # Your companies + clients
│   ├── services/          # What you offer
│   ├── projects/
│   │   ├── business/      # Client work
│   │   ├── research/      # Academic or R&D
│   │   └── personal/      # Side projects
│   ├── content-pipeline/  # Content through stages
│   │   ├── drafts/
│   │   ├── in-review/
│   │   ├── scheduled/
│   │   └── published/
│   ├── daily-logs/        # Work journals
│   ├── ideas/             # Raw ideas by domain
│   └── brand/             # Positioning, voice, assets
├── schemas/               # YAML schemas for every record type
├── config/                # Agent configuration
├── meta/                  # File registry + relationship graph
├── skills/                # AI agent instructions
└── CLAUDE.md              # Agent operating manual

Each layer has a specific job:

Why YAML and Git? Why Not a Database?

Three reasons:

Why not Notion, Airtable, or a CRM? Each stores your data inside a proprietary system. Exporting is painful. AI agent integration requires custom APIs. You are always one pricing change away from losing access to your own information.

Key takeaway: The Knowledge Operating System is a knowledge base designed to be operated by machines and read by humans. The entire system is a folder of text files. Clone it, fork it, move it anywhere. Zero vendor lock-in.

Why This Matters for You

Your knowledge is already scattered. Every tool you use stores a piece of the picture:

• Your CRM has contacts
• Your project manager has tasks
• Your Google Drive has documents
• Your head has the connections between them

The agent is only as powerful as the data behind it: deploy on scattered data, get scattered results.

The _meta block pattern works for any business:

_meta:
  id: contact.george-lewer
  created: 2026-01-15
  updated: 2026-02-20
  version: 3
  tags: [client, coaching, active]

• Freelancers — track clients, projects, invoices
• Agencies — centralize team knowledge, client briefs, campaign data
• Consultants — document engagements, frameworks, deliverables
• Coaches — maintain client progress, session notes, resources

Start small. Structure your contacts and your projects into YAML files. Even 10 records changes how you think about your business.

Structured knowledge is portable. Switch CRMs, switch project managers, switch providers. The data moves with you because it is just text files.

Building a Chatbot on Top of It

I had 60+ YAML records. I wanted a conversational way to explore them. Not a search bar. A conversation.

I built it in a day with Claude Code and Python. Here is the stack:

No embeddings. No vector database. Pure tool-calling. The LLM decides which files to read based on the question, reads them, and synthesizes an answer.

The 5 Core Features

Each feature in detail:

• Conversational knowledge search — ask a question in plain English, the AI reads your YAML files on demand using tool-calling. No embeddings, no vector database. It finds contacts, projects, services, and content across 60+ records in seconds.
• Persistent memory — a two-tier memory system that remembers across sessions. Core memory holds your preferences and corrections (always loaded). Episodic memory stores facts, decisions, and patterns (retrieved by semantic similarity). The chatbot gets smarter with every conversation.
• Multi-model AI switching — swap between GPT-4o, Claude Sonnet 4, and Gemini 2.5 from a dropdown. Same interface, same tools, different brain. Compare how each model handles your questions.
• File explorer and editor — an IDE-style document browser built into the UI. Browse the directory tree, view parsed YAML as formatted cards, edit files inline, see AI-generated diffs against backups, and view raw content.
• Mini apps — built-in tools beyond chat. The “M ou F?” tool checks the gender of any French word and returns articles, adjective agreements, example sentences with Farsi translations, and a mnemonic tip. A French Tutor mode turns the chatbot into a language learning assistant.

How the Chatbot Works

The architecture has four layers:

User Question
      ↓
Dynamic System Prompt (KOS context + memory)
      ↓
LLM (GPT-4o / Claude / Gemini)
      ↓
Tool Calls (up to 10 rounds)
      ↓
Synthesized Answer
      ↓
Auto-extract memories → Persistent storage

Layer 1: Dynamic system prompt. Every conversation starts with a system prompt built from the knowledge base itself. The directory map, file registry, and persistent memory are injected fresh each time. The LLM starts every conversation already knowing what files exist and where to find them.

Layer 2: Tool-calling. The LLM can call these tools to explore the knowledge base:

Layer 3: Tool loop. The LLM calls tools iteratively, up to 10 rounds per question. It reads a result, decides if it needs more information, and calls another tool or writes the final response. Most questions resolve in 1-2 rounds.

Layer 4: SSE streaming. Responses stream to the browser in real time using Server-Sent Events. You see tool calls happening live, then the answer streams in word by word.

Here is a typical flow:

User: “What projects involve my coaching client?”

LLM: calls search_content("coaching") → finds contact file + two project files

LLM: calls read_file on each match

LLM: synthesizes a structured answer with project names, statuses, and next steps

Path validation ensures the tools can only read inside the knowledge base directory. No accessing .env files. No escaping the root directory.

The Memory System

The chatbot remembers across sessions. A persistent memory file is loaded into every conversation’s system prompt.

Two Tiers

Memory Tools

How Memories Are Created

Three paths:

1. Explicit save — the chatbot calls save_memory during conversation. Preferences and corrections route to core. Facts, decisions, and patterns route to episodic.
2. Auto-extraction — after every conversation with 3+ turns, a background model reads the full conversation and pulls out key memories: preferences, facts, corrections, decisions, patterns.
3. Manual save — the memory panel in the UI lets you view, search, and delete individual memories. A “Tidy Up” button triggers manual consolidation.

Memory Categories

Auto-consolidation triggers when core memory exceeds 30 entries. The system merges duplicates, removes stale entries, and keeps the memory focused. This runs automatically.

Key takeaway: This is what makes the chatbot compound over time. It learns how you like information presented, what corrections you have made, what decisions you have reached. Next session, it already knows. The more you use it, the better it gets.

The Document Search UI

The first thing I needed beyond chat was a way to see my data. Not just ask about it. See it.

File Explorer. An IDE-style panel built into the chatbot UI. Click “File Explorer” in the sidebar and the interface shifts. The warm accent tones swap to a cooler blue palette. The layout splits into two panels.

┌─────────────────────────────────────────────────────┐
│  Sidebar  │  Tree Panel (260px)  │  Content Panel   │
│           │                      │                   │
│  KOS      │  data/               │  [View] [Edit]    │
│  French   │  ├── contacts/       │  [AI Changes]     │
│  M ou F?  │  ├── businesses/     │  [Raw]            │
│  Explorer │  ├── projects/       │                   │
│           │  ├── services/       │  Parsed YAML card │
│  ───────  │  meta/               │  or editor        │
│  Coming   │  config/             │  or diff view     │
│  Soon     │  schemas/            │  or raw content   │
│           │  00-inbox/           │                   │
│  [Model]  │                      │                   │
│  [Memory] │  [Filter: ______]    │                   │
└─────────────────────────────────────────────────────┘

The Tree Panel

Key features:

• Directory browsing — shows data/, meta/, config/, schemas/, and 00-inbox/ with expand/collapse
• Color-coded file types — yellow for YAML, green for Markdown, gray for everything else
• Count badges — each folder shows how many items it contains
• Real-time search filter — type “george” and only matching files remain visible
• Live refresh — tree rebuilds from the API on every load, always reflects current state

Four View Modes

Click any file and the content panel offers four modes:

How each mode works:

• View renders YAML records as cards. A contact file shows the person’s name, title, tags, and all fields laid out cleanly. The _meta block appears as badges: record type, version number, last modified date.
• Edit opens a full-height textarea with monospace font. When you save, the backend creates a timestamped backup before overwriting. Every edit is recoverable.
• AI Changes computes a diff between the current file and its most recent backup. This is how you see exactly what the chatbot changed when it wrote to a file through the chat interface.
• Raw displays the file content exactly as it exists on disk. No formatting, no cards.

Key takeaway: The file explorer turns the chatbot from a question-answering tool into a knowledge management interface. Ask the chatbot about a project, then flip to the explorer and read the full YAML file. Edit a record, save it, immediately ask questions about the updated data. Chat and explorer share the same backend, the same files, the same source of truth.

Mini Apps: M ou F?

Not every interaction with the knowledge base is a conversation. Some things are better as standalone tools.

“M ou F?” is a French gender reference tool built directly into the chatbot UI. I am learning French, and one of the most frustrating parts is memorizing whether a word is masculine or feminine. Every noun. Every time.

How It Works

User types "maison"
      ↓
Sends to current AI model (e.g. GPT-4o)
      ↓
Model returns structured JSON
      ↓
UI renders as formatted card

The card contains:

• Gender badge — masculine (blue) or feminine (pink)
• The word with its article — “la maison” or “le livre”
• Articles grid — all forms in a 2-column layout (definite, indefinite, partitive, contracted)
• Adjective chips — 3-4 adjectives agreeing with the word’s gender, each with the French adjective, English translation, and an example phrase
• Example sentences — 3-4 natural sentences in French, English, and Farsi (my native language, right-to-left)
• Mnemonic tip — a rule or trick for remembering the gender

Previous lookups appear as clickable pills below the input. Blue for masculine, pink for feminine. Click any pill to see that word’s card again.

Chat vs Mini App

The pattern: Chat for exploration, mini apps for utilities. The chatbot handles open-ended questions. Mini apps handle repetitive, structured lookups.

Beyond the gender tool, there is a full French Tutor mode: the same chat interface, the same AI models, the same tool-calling against my knowledge base, but a different system prompt that turns the chatbot into a conversational French teacher focused on grammar, vocabulary, practice conversations, and corrections.

Multi-Model AI Switching

The chatbot is not locked to one AI provider. A dropdown in the sidebar lets you switch at any time.

Available Models

How It Works

litellm handles the routing. The architecture is model-agnostic:

User selects model from dropdown
      ↓
Same tool schemas (read_file, search_content, etc.)
      ↓
Same system prompt (KOS context + memory)
      ↓
Same session state (conversation history preserved)
      ↓
Different LLM brain processes the request
      ↓
Same streaming UI renders the response

Key behaviors:

• Mid-conversation switching — change from GPT-4o to Claude and the chatbot keeps going. Session state stays the same. Only the brain changes.
• Mini apps use the same selector — check a French word with GPT-4o, then switch to Claude and check again. Different examples, different mnemonics, different adjective choices.
• No code changes needed — litellm normalizes all provider differences. Add a new model by adding one line to the config.

Key takeaway: Running multiple models against the same structured prompt and the same knowledge base is one of the fastest ways to learn where each model excels. When one model gives a weak answer, switch and ask again. Same data, same tools, different perspective.

Conversation Logging and Recall

Every conversation is saved to disk automatically.

Storage Structure

conversations/
├── 2026/
│   ├── 01/
│   │   ├── 2026-01-15_a3f8b2c1.json
│   │   └── 2026-01-15_d7e4c9a2.json
│   └── 02/
│       ├── 2026-02-20_b1c3d5e7.json
│       ├── 2026-02-22_f9a1b3c5.json
│       └── 2026-02-23_e2d4f6a8.json

Recall Tool

Ask “What did we talk about on February 20th?” and the chatbot pulls the conversation transcripts from that date.

How it pairs with memory:

• Memory captures the insights (preferences, facts, decisions)
• Conversation logs capture the full context (everything said, in order)
• Together they give the chatbot both quick-access knowledge and deep recall

What I’d Tell You to Build First

Here is the order:

1. Start with a CLAUDE.md file. It gives any AI agent persistent context about your project. Directory structure, naming conventions, business rules. One file that makes every future AI interaction smarter.
2. Structure your contacts and projects into YAML. Even 10 records changes how you think about your business. Use the _meta block: ID, created date, updated date, version, tags.
3. Add schemas. Define the structure for each record type so AI agents create consistent records.
4. Build a chatbot (optional). The chatbot itself is roughly 300 lines of Python. The real value is not in the chatbot. It is in the structured data underneath.

The YAML files are the system. Everything else is a tool. This is Systems Before Tools in practice.

This is what I do at ConnectMyTech. I help businesses structure their knowledge, connect their tools, and build the systems that replace manual work. If a non-coder can build a chatbot in a day, imagine what structured data and the right systems can do for your business.

Related Posts

• Stop Repeating Yourself to Claude. Use CLAUDE.md - The CLAUDE.md file is step one of building any AI-readable system. This post has the full template.
• I Can’t Code. I Made 4 Working Apps in 30 Days. - The KOS chatbot was one of them. Here’s the full build journey.
• How I Made My Website AI-Discoverable - The same structured data philosophy applied to web presence instead of internal knowledge.
• Systems Before Tools: Why Most Agents Fail at AI - The framework behind everything I build, including this knowledge base.

Want to Know Where Your Business Stands with AI?

I turned my AI discoverability audit process into a tool. The AI Visibility Audit scans your website and social profiles across six areas and gives you a score out of 100 with specific recommendations.

Try the AI Visibility Audit

If you want help structuring your business knowledge or building systems like this, reach out on LinkedIn or through my contact page.