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 an agent on scattered data, you get scattered results. Deploy an agent on structured data, you get structured answers.

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.

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.

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

This is what I do at ConnectMyTech. I help businesses structure their knowledge, connect their tools, and build the systems that replace manual work. My name is Shahab Papoon, and I believe the wall between idea and product is crumbling. 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.