How to use session semantic search
Find prior conversations, decisions, artifacts, and work by meaning when you remember the topic but not the session key, date, file name, or exact wording.
When to use it
Use session semantic search when you need to find an old discussion by concept, recover the session where a decision was made, locate previous work that used different terms, or compare several candidate sessions before resuming work.
If you already know the session key, exact file path, commit hash, or artifact name, start with exact session history search. Semantic search is strongest as a discovery layer, not as the final source of truth.
Quick answer
Buffaly has a documented Semantic Conversation Search surface backed by a read-only search agent profile, a dedicated UI page, semantic/exact/hybrid matching actions, and a scheduled reindex process that imports completed user/assistant turns from SQL session messages into semantic fragments.
Good first prompt
Use session semantic search to find earlier conversations about provider default confusion. Return the best session keys, matching snippets, why each result is relevant, and what I should inspect next before resuming work.
Then verify any important result by opening or summarizing the matching session history, checking artifacts and files, and confirming commits or final answers.
Semantic search versus exact search
| Search type | Best for | Limitation |
|---|---|---|
| Exact text search | Filenames, commit hashes, errors, session keys, action names, and unique phrases. | Misses conversations that used different words. |
| Semantic session search | Fuzzy topics, decisions, renamed concepts, and similar prior work. | Can return related-but-not-source conversations; verify before acting. |
| Hybrid search | Broad discovery when you have both a topic and a few concrete terms. | Still depends on indexed session content and ranking. |
| History paging/summarization | Known session key or date range. | Requires knowing which session to inspect. |
The verified pattern is to use semantic search to find candidate sessions, then use session history tools or direct artifact/file inspection to confirm the result.
What is searchable
Semantic conversation reindexing reads SQL-backed session messages and imports completed user/assistant turns into semantic fragments. That means semantic search is designed around conversation turns, not every low-level runtime row.
- User and assistant messages with non-empty content can be indexed.
- Completed turns are built from a pending user message and the next assistant answer.
- Tool output, lifecycle rows, reasoning rows, and transient UI state may not be indexed as semantic fragments.
- Artifacts, Plan, Scratch, task files, and changed repository files may need separate exact inspection.
Where users access it
The product exposes a Semantic Conversation Search page at semantic-conversation-search.html. The page creates or reuses a semantic-conversation-search session and sends the query to the Buffaly agent service.
Conversation indexing is handled by the scheduled reindex process. When the host exposes it, the read-only status endpoint is /api/semantic-conversation-search/reindex-status. You can also ask the Buffaly agent to use semantic conversation search from an ordinary session.
How to ask Buffaly
Include what you remember, how many candidates you want, and what evidence should be returned.
Find candidates: Use session semantic search to find conversations about watcher queued guidance. Return the top five candidate sessions, snippets, and why each candidate may be the source session.
Search by meaning: Search prior conversations by meaning for “how we decided provider defaults should be documented.” Include likely session keys, matching snippets, and whether any result points to committed wiki files.
Verify before resuming: Find old work about adding context prompts. Use semantic search first, then verify the top result by reading its session history and checking the target article file.
Interpret and verify results carefully
A good result includes
- Session key or session link.
- Matching snippets.
- Whether the match was semantic, exact, or hybrid.
- Why it appears relevant.
- Whether it is likely the source session or only a search/debug/supervisory session.
Before resuming
- Confirm the session is about the original work.
- Read final answers, Plan, Scratch, or task artifacts.
- Verify changed files, commits, and file paths still exist.
- Check that repository state has not changed in a conflicting way.
- Do not let compaction summaries hide missing details.
Prefer underlying source sessions over watcher, supervisory, search, or debug sessions when both appear in results.
Verify index freshness and availability
- Open the Semantic Conversation Search page and look for index or reindex status if available.
- Ask Buffaly to inspect
/api/semantic-conversation-search/reindex-statuswhen the host exposes it. - Compare the target session date with the latest indexed or processed time.
- If very recent work is missing, wait for scheduled reindex or use exact session history search instead.
Troubleshooting
No results or weak results. Try a broader concept query and a second query with exact terms, then inspect exact history, artifacts, repository files, or commits.
Results are about search itself. Deprioritize semantic-search, watcher, level-two, and debug sessions unless they point to the source session.
Recent work is missing. Check reindex status and fall back to exact session history or current session artifacts.
Tool outputs are not found. Search the known session history with tool rows included, or inspect artifacts/logs directly.
Wrong session. Compare candidates by matching snippets, session key, final answer, files changed, and why each is or is not the source session.