Search and retrieval

Usable provides several ways to find knowledge. The right method depends on whether you already know the metadata you want or need help discovering which fragments are relevant.

The central distinction is between selection and reading. Search helps you select candidate fragments. The full fragment content remains the source you should read before acting on the information.

Structured listing and filtering

Use structured listing when you know exact properties of the fragments you need. Depending on the interface, you can filter by values such as:

• workspace;
• fragment type;
• lifecycle status;
• tags;
• title or dates;
• collection membership;
• supported frontmatter fields.

This is the best approach for deterministic tasks: list all active fragments with a given tag, find documents updated after a date, or enumerate the members of a collection.

Exact filters do not understand synonyms or intent. Filtering for authentication will not reliably find every fragment about sign-in if that metadata was never applied.

Semantic search

Semantic search looks for similarity in meaning rather than only exact words. It can find a fragment whose language differs from the query—for example, a question about “sign-in failures” may retrieve material that uses “authentication errors”.

Semantic search is useful for exploratory questions and natural-language lookup. Results are still candidates, not proof. Similar meaning does not guarantee that a fragment is current, authoritative, or applicable to the exact situation.

Agentic search

Agentic search is the primary discovery tool for AI-assisted research in Usable. It can interpret a goal, search relevant workspace knowledge, and expand the search when the first candidates are insufficient.

Use it when the question is broad, the terminology is uncertain, or the answer may be distributed across several fragments. Give it a clear query and the correct workspace scope. Add tags or other hints only when they improve precision without excluding useful sources.

An agentic search result normally includes candidate IDs, titles, and reasons for relevance. Those snippets help choose what to read next; they should not be treated as the complete source.

Retrieve the full content

After discovery, fetch the full fragment before relying on it. This two-step pattern is important:

1. Search returns likely sources.
2. Full-content retrieval provides the actual text, metadata, and context.

Search summaries may omit prerequisites, exceptions, dates, or residual risks. Reading the full fragment prevents an agent from turning a plausible match into an unsupported answer.

A practical decision guide

Use listing/filtering when you can state exact criteria:

Show active Recipe fragments tagged deployment in this workspace.

Use semantic search when you know the meaning but not the wording:

How do we recover when a production rollout stops halfway?

Use agentic search when discovery may require refinement or several sources:

Research the supported production deployment workflow and its rollback guidance.

Then retrieve every fragment you intend to use.

Workspace scope matters

Search only the workspaces appropriate to the question. Broadening scope can add useful context, but it can also mix public documentation, internal operations, and project-specific decisions.

If a search returns nothing, first confirm that your account or token can see the workspace. Then check the workspace ID, query wording, filters, and tags before concluding that no knowledge exists.

Write fragments that retrieve well

Retrieval quality starts with authoring quality. A fragment is easier to find when it has:

• a specific title using the words people naturally use;
• a summary that states its purpose and boundaries;
• focused, coherent body content;
• a small set of consistent tags;
• an appropriate fragment type;
• current status and dates where time matters.

Do not add unrelated keywords to manipulate results. Search should return a fragment because it is genuinely useful for the question.

Example: researching a webhook failure

An effective workflow might be:

1. Scope the search to the product’s documentation and operational workspaces.
2. Use agentic search for “webhook delivery fails with authorization errors”.
3. Review candidate titles and relevance reasons.
4. Fetch the full troubleshooting and authentication fragments.
5. Check their dates, applicability, and verification notes.
6. Answer from the retrieved sources and improve the knowledge if a gap is confirmed.

This produces a grounded answer and leaves a clear path for maintaining the source.

Good practices

• Start with the narrowest correct workspace scope.
• Use exact filters for deterministic inventory tasks.
• Use semantic or agentic search for meaning-based discovery.
• Fetch full content for every source you rely on.
• Check status, dates, and applicability before acting.
• Refine the query when results are broad or thin.
• Improve titles, summaries, and tags when useful knowledge is consistently hard to find.

Related concepts

• Tags and summaries explains two important retrieval signals.
• Collections provide curated search scopes.
• Frontmatter and metadata covers exact structured fields.
• Memory fragments explains the full sources returned by retrieval.