The Philosophy: Perpetual SMEs
Do not create one "Super Agent" to run your entire infrastructure. No matter how large an LLM's context window is, loading every tool and every ontology item into a single session will cause the model to degrade and lose focus.
The Chatbot Trap
Starting a new chat for every task. The agent constantly forgets your environment, and institutional knowledge gets lost the moment you close the browser tab.
The Buffaly Way
Create dedicated, long-running agents per domain. Use one agent for "Website Project" and another for "Client B". They live forever, dynamically querying only the ontology and tools they need.
By keeping agents running perpetually, institutional knowledge accumulates in the agent's memory and files drawer. It becomes a specialized team member you can query at any time.
Parent & Child Agents
Many platforms use "child agents" as a dirty hack to get around LLM context limits. Buffaly uses them for architectural organization.
1. Parallelism
If an overarching task has 5 independent steps, a parent agent can spawn child agents to execute them simultaneously. This is purely to get work done faster.
2. Sub-Domain SMEs
As a domain agent (e.g., "Website Project") handles complex tasks, it can spawn permanent child agents to handle specialized sub-domains (e.g., "Database Migrations"). This prevents tool-loading bloat.
Storage, History, and Semantic Search
Buffaly never truly loses information because it does not rely on volatile frontend chat sessions.
- SQL Server BackendEvery historical message, tool call, state change, and artifact is saved permanently in SQL Server.
- Automatic Semantic Database (SemDB)Sessions utilize a semantic database plugin for vector similarity search. As agents work, their knowledge is automatically indexed.
- Agent Self-RetrievalIf an agent forgets a detail due to context compaction, you can simply tell it to: "Search your session history to remember how we configured this." The agent natively queries its own SQL and Semantic history.
- Cross-Agent AggregationBecause all sessions share the SemDB, you can create a "Reporting Agent" to query the vector database across dozens of other agents. (e.g., "Generate an end-of-day report summarizing what all Client agents accomplished today.")
Managing State: Plan, Scratch, & Tasks
Standard agents overwrite their own plans when they get distracted, causing them to abandon long-running tasks. Buffaly prevents this by isolating state into specialized concepts. The goal is to keep enough state durable that work can continue without guessing.
| Layer | Purpose | Do not use for |
|---|---|---|
| Plan | The immediate route and next steps. | Permanent requirements or long evidence dumps. |
| Scratch | Working notes, hypotheses, and temporary investigation breadcrumbs. | Final acceptance criteria or source of truth. |
| Task artifacts | Durable task scope, decisions, evidence, and done criteria. Defines what success looks like when returning from sub-tasks. | Noisy per-turn transcript copies. |
| Timeline | Ordered, immutable evidence of turns, tools, actions, and results. | A polished deliverable by itself. |
| Files Drawer | Operational documents (checklists, specifications) that guide the agent long-term. | Unverified conclusions or hidden state. |
User and Buffaly responsibilities
Despite marketing hype, LLMs are not fully autonomous. They require human-provided guardrails (checklists, goals, test cases). Here is how you interact with a long-running session.
| User action | What Buffaly should do | How to verify |
|---|---|---|
| Start long-running work | Create a route, define deliverables, identify evidence, and keep progress in Plan or a durable task. | Plan names the next step, target path, validation, and stop condition. |
| Continue | Find the prior session, summarize the last completed step, then continue from current state. | Buffaly cites the session or task and shows what changed since the last step. |
| Preserve evidence | Save important outputs as artifacts or committed files instead of leaving them only in chat. | Artifact path, file path, commit hash, or timeline entry is named. |
| Delegate | Create bounded child work with target, source, working directory, and expected output. | Child key, status, deliverable, and parent integration step are visible. |
| Finish | Validate deliverables, report files or artifacts, name gaps, and commit only intended work. | Final includes validation evidence, scoped status, and commit hash. |
Compaction & The System 2 Watcher
Compaction
Context windows fill up. Buffaly handles this via Compaction—timeline housekeeping that reduces conversation weight while preserving typed snapshots. It uses methods like CodexApi (best performing) or ResponsesApi. If an agent forgets a detail after compaction, instruct it to search its own session history.
The System 2 Watcher
LLMs drift. Buffaly solves this with a secondary, parallel watching agent. It acts as an over-the-shoulder supervisor. It cannot use standard tools; its only job is to validate plans and send feedback to correct the primary agent if it gets off track or forgets a step during compaction.
Recovery patterns
When a session stalls, compacts, recycles, or loses visible progress, recover in evidence order. The point is to anchor the next action before editing.
- Exact target path and session key.
- Plan.
- Scratch.
- Durable task artifact.
- Target files and saved artifacts.
- Timeline and tool evidence.
- C:\logs\Buffaly logs.
- Scoped git status and latest relevant commits.
"Recover this session before editing. Show the session key, Plan, Scratch, durable task artifact, target path, timeline evidence, relevant Buffaly logs, scoped git status, and latest commit that touched the target. Then tell me the next safe step."
Troubleshooting quick reference
| Symptom | First checks | Good next prompt |
|---|---|---|
| Stuck work | Session status, queued count, latest timeline turn, worker logs. | "Check status and queued turns before adding follow-up input." |
| Missing child result | Child key, source session, status, error, artifact path. | "Find the child session result and show its deliverable or error." |
| Watcher confusion | Source key, Level2 key, turn.completed event, handler action. | "Verify the watcher source and whether it handled the latest turn." |
| Stale context | Plan, Scratch, target file mtime, git status, latest commits. | "Revalidate state and continue without repeating valid discovery." |
| Too-long session | Compaction thresholds, epoch, archive snapshot, active turn. | "Summarize route and evidence, compact if needed, then resume." |
| File or commit missing | Absolute target path, artifact path, scoped git status. | "Show where the deliverable exists and whether it was committed." |