Configure SQL Server, SemDB, and sessions
A bunch of text files on a server is not an enterprise architecture. Buffaly requires true auditability and central management. Use this guide to configure SQL Server connection strings, choose your session storage mode, and map out your semantic data layers.
The Storage Philosophy (The End of Agent Amnesia)
Standard agents lose their minds when the server restarts or the context window clears. Buffaly solves this by storing state, timelines, and ontology data in a central database.
- True Auditability: If Buffaly executes a destructive action, the SQL timeline is the absolute, immutable proof of why it did it, what tools it called, and what the outcome was.
- Central Management: Database storage allows operators to centrally manage, monitor, and query a fleet of running agents across an organization from a single pane of glass.
Storage Roles
Do not collapse these concepts into one database setting. Buffaly can use SQL Server for sessions while still using project files for ontology definitions.
| Layer | Documented Role | Evidence to Verify |
|---|---|---|
| SQL Server / Sessions DB | Stores sessions, messages, artifacts, subscriptions, features, processes, and runtime/admin records. | buffaly_sessions.readwrite, Sessions.Web rows, SQL session-store behavior. |
| SemDB / SemanticDB | Stores semantic fragments, vector embeddings, and lookup data used for action/entity discovery. | buffaly_semanticdb.readwrite, SemanticDB initialization, semantic candidate search results. |
| File Session Store | Stores session snapshots and artifacts under the runtime sessions root. (Not recommended for enterprise). | Runtime Feature.SessionsRootPath, session.json, artifacts. |
| Session Store Mode | Chooses whether runtime session state is file, SQL, or hybrid. | Infrastructure Feature.SessionStoreMode |
| Ontology / Project Files | Define prototypes, action roots, prompt actions, and semantic names. | Active project path, project .pts files. |
SQL Server 2025 & SemDB
SQL Server 2025 is the officially recommended route for Buffaly. It features native Vector Storage, allowing Buffaly to store relational session data and perform high-speed SemDB semantic searches in the exact same database.
Legacy SQL Server
There is a configuration flag to use non-native vector storage so you can use older versions of SQL Server. However, it is much slower and not recommended.
Fleet Reporting
Because all agents share this central SemDB, you can spawn a "Reporting Agent" to run vector similarity searches across the entire organization's fleet to generate aggregate summaries.
Extensibility: Custom Storage Providers
If your organization uses a different enterprise backend (e.g., PostgreSQL with pgvector), Buffaly includes an extensible Storage Provider mechanism. You can write a custom provider to use alternate data storage, provided it supports both standard data storage and vector storage.
How to configure storage
Before starting, confirm the active repository or install root. Check whether Sessions.Web can open Dashboard, Sessions, and Features.
1. SQL connection strings
Verify named connection strings in the running installation configuration. buffaly_sessions.readwrite and buffaly_semanticdb.readwrite.
2. Session store mode
Set Infrastructure Feature.SessionStoreMode. Canonical values are file, hybrid, database-source, and hybrid-database. Exact casing is required.
3. Runtime Feature paths
Verify SessionsRootPath exists and the web/worker identity can read/write to it.
4. Configure SemDB
Provision and point SemDB before relying on semantic discovery. Verify SemanticDB data access initialization.
5. Session semantic search storage
Session semantic search uses Sessions DB rows, fragments, embeddings, and vectors. Verify the semantic reindex process, fragments/vectors for target sessions, and your configured Embedding Provider.
Security & Secrets Boundary
Do not store secrets in SemDB or standard Session Memory.
SQL Server timelines and SemDB embeddings are essentially plaintext to the system's memory-retrieval tools. If an agent commits an API key or database password to memory, it will be vectorized and could be retrieved later in an insecure context. Always configure Buffaly to use your infrastructure's proper Secrets Management system, and instruct agents to reference secrets by their logical keys only.
Verification & Prompts
How to verify it works, and how to ask Buffaly to help you diagnose it.
Audit configuration
"Inspect source first, then check buffaly_sessions.readwrite, buffaly_semanticdb.readwrite, session store mode, and Sessions.Web health. Do not reveal secrets."
Verify SemDB
"Search candidate actions and entities, report whether semanticdb or fallback was used, and identify stale prototype rows without changing data."
- SQL Server / Sessions DB: Dashboard, sessions, messages, and a new test session appear in the expected store.
- Runtime session store: file, SQL, or hybrid evidence matches the configured
SessionStoreMode. - SemDB search: Candidate search returns likely prototypes and reports whether SemDB or fallback was used.
- Semantic search: Semantic results match exact session history or committed-file evidence.
Troubleshooting Connectivity
| Symptom | Resolution |
|---|---|
| Connection string missing or wrong | Verify both named connection strings; sessions and SemDB serve different layers. Do not print secret values. |
| Wrong session-store mode token | Ensure exact casing: file, hybrid, database-source, or hybrid-database. |
| Sessions visible in files but not Web | Check store mode, sessions root, and Sessions.Web database connectivity. |
| Sessions visible in SQL but not on disk | This is expected in database-source mode. Verify your mode before treating it as data loss. |
| SemDB search is stale or noisy | Verify active project and source annotations before triggering a manual reindex of semantic data. |
| Exact search works but semantic does not | Verify Embedding Provider configuration, verify vectors are populating in SQL, check reindex status. |
| Permissions or Authentication failures | Start with read-only verification of process identity, SQL login, firewall, and DB name before broadening access. |