Ontology is Buffaly's structured runtime graph of typed objects and relationships. ProtoScript is one checked-in authoring and loading path for putting objects, capabilities, services, skills, prompt actions, and remembered entities into that graph.
Use this page as a practical bridge for technical users. For focused semantic-discovery behavior, see Semantic data and ontology. For extension-boundary choices, see Adding skills, services, and tools.
Short version
Ontology
A graph of known objects and relationships: systems, accounts, skills, actions, prompt actions, services, and remembered entities.
Prototypes
Runtime graph nodes that can act as types, instances, or both.
ProtoScript
A C#-like declaration language for prototypes, partials, typed properties, functions, services, prompt metadata, imports, and includes.
Semantic discovery
Entity names help Buffaly find objects. Infinitive phrases help Buffaly find actions.
Practical rule: reusable facts, systems, accounts, actions, and workflows should become typed ontology objects, remembered entities, workflow memory, skills, actions, or service boundaries instead of living only in prompt text.
How users experience ontology
Most users experience ontology when a normal request binds to the right concrete target instead of an ambiguous word.
Repository target
"Use the local Buffaly repo" should bind to a known repository or implementation path.
Remembered database rule
"Remember the staging reporting database is read-only" should create durable structured memory, not just chat text.
Discoverable action
"Run the browser task" should resolve to an installed Browser skill action when available.
Configured account
"Use the Google Workspace account for finance" should bind to the configured account entity.
Prototypes versus ProtoScript
The runtime graph is the product. ProtoScript is source. A prototype is a typed node in a property-labeled graph, while a .pts file is one way to declare, extend, and manipulate those nodes.
| Concept | Meaning |
|---|---|
| Prototype | Runtime type, instance, or both; can hold stored facts and computed behavior. |
| ProtoScript | Checked-in declaration language for source-controlled ontology and actions. |
| Runtime graph | Loaded ontology the Buffaly agent searches, binds, and executes against. |
Project load shape
Checked-in implementation paths may still use legacy OpsAgent naming. User-facing prose should still say Buffaly agent unless it is pointing at a path.
include Imports.pts;
include "Annotations.pts";
include "Core/index.pts";
include "Skills/index.pts";
include "Nodes/index.pts";If a file is not included through the active project or skill index, it is not part of the loaded graph and discovery will not see it.
Core ontology pieces
BaseObject
Common object base for notes and definition prompts.
SemanticEntityBase
Entity name and description fields for discoverable entities.
ProtoScriptAction
Action metadata such as infinitive phrase, description, response format, and authoring guidance.
PromptAction and ContextPrompt
Trusted prompt-backed actions and situational behavior prompts.
OpsAction, CoreAction, CoreSkill, CoreEntity
Base families used by the project to organize actions, skills, and entities.
SkillEntity and ActionRoot
A skill points at the action root where related actions live.
Semantic annotations
Semantic annotations are the bridge from approximate language to concrete prototypes.
Entity names
[SemanticEntity("finance Google Workspace account")]Used by entity search for accounts, systems, repositories, databases, and remembered objects.
Infinitive phrases
[SemanticProgram.InfinitivePhrase("to load a protoscript action tool")]Used by action search when the user asks the Buffaly agent to do something.
Core discovery tools include ToSearchCandidateActions, ToSearchCandidateEntities, ToLoadProtoScriptActionTool, ToListSkills, and ToListSkillActions.
Actions and entities: two discovery paths
Action by phrase
Search candidate actions by infinitive-style phrases, then load only the selected action.
Entity by semantic name
Search candidate entities by meaningful names and descriptions, then bind to the most specific prototype.
Good verification request
"Verify why the new workspace action is not discoverable. Inspect active project includes, show prototype details, search candidate actions with two phrases, and check whether the action tool is loaded before suggesting a fix."
What a .pts file usually contains
[SemanticProgram.InfinitivePhrase("to build the buffaly solution")]
prototype ToBuildBuffalySolution : OpsAction
{
Description = @"Uses the default build profile unless overridden.";
function Execute() : string
{
return "Build result text.";
}
}Why the graph matters
Relationships connect skills to action roots, actions to semantic phrases, entities to names, service instances to configuration, prompt actions to trusted prompt files, and remembered environment details to the entity they describe.
When to care about ProtoScript
| Need | Use |
|---|---|
| Durable fact, account, system, or preference | Memory or a remembered typed entity. |
| Repeatable workflow | Workflow memory, then promote to a skill if needed. |
| Stable callable behavior | Prompt action or ProtoScript action. |
| Lifecycle, identity, configuration, state, or multiple methods | Service boundary. |
Services and MCP
ProtoScript can define service types and concrete service instances, while C# owns protocol implementation when needed. MCP should be represented as per-binding service instances: one service type, one concrete service instance per configured server.
Reading and verification checklist
- Start with the project file and confirm include order.
- Find the base prototype: action, entity, skill, service, prompt action, or context prompt.
- Inspect semantic annotations, typed properties, descriptions, and
Execute(...). - Search candidate actions and entities with two clear phrasings and compare prototype names.
- List loaded tools before assuming an action is callable.
- Use compile and startup diagnostics after source changes.
Troubleshooting ontology problems
File not included
Trace from the active project and skill index.
Vague semantic phrase
Add a specific entity name or infinitive phrase and test search.
Wrong base type
Use the right action, skill, entity, service, prompt action, or context prompt base.
Secret modeled as ontology
Move passwords, bearer tokens, OAuth secrets, and API keys to protected secret storage.
Service boundary missing
Use a service when identity, lifecycle, state, configuration, or multiple methods matter.
Compile or startup race
Check compile output, startup diagnostics, and the loaded runtime graph.
Common mistakes to avoid
- Treating ProtoScript as prompt text instead of runtime-shaping source.
- Adding vague or misleading semantic phrases.
- Storing secrets in
.ptssource or normal memory. - Creating a flat action when a configured service instance is safer.
- Using legacy implementation names such as OpsAgent as the user-facing name.