Skip to main content
Knowledge search returns a typed result you can loop over and score.

​
Quick Start

1

Loop over results

Call knowledge.search() and iterate the results list.
from praisonaiagents import Agent
from praisonaiagents.knowledge import Knowledge

knowledge = Knowledge()
knowledge.store("Paris is the capital of France.")

results = knowledge.search("capital of France", user_id="alice")

for item in results.results:
    print(f"[{item.score:.2f}] {item.text}  ({item.source or '-'})")
2

Convert to a plain dict

Use to_legacy_format() or to_dict() when you need raw data.
results = knowledge.search("capital of France", user_id="alice")

legacy = results.to_legacy_format()   # {"results": [{"memory": ..., "text": ...}, ...]}
plain = results.to_dict()             # {"results": [...], "metadata": {}, "query": ..., "total_count": N}

​
How It Works

Knowledge.search() normalises every backend into one typed SearchResult.

​
The SearchResult shape

The container holds the ranked items plus search-level metadata.
FieldTypeDescription
resultslist[SearchResultItem]Ranked items
metadatadictSearch-level metadata (always dict, never None)
querystrOriginal query string
total_countint | NoneTotal available (may exceed len(results) if paginated)

​
The SearchResultItem shape

Each item carries the content, its score, and optional source hints.
FieldTypeDescription
idstrBackend identifier
textstrContent (normalised from memory / text / metadata.data)
scorefloatRelevance score (0.0 default)
metadatadictItem metadata (always dict, never None)
sourcestr | NoneOptional source hint
filenamestr | NoneOptional filename
created_atstr | NoneTimestamp
updated_atstr | NoneTimestamp

​
Common Patterns

​
Show top-N with scores

results = knowledge.search("machine learning", user_id="alice")

for rank, item in enumerate(results.results, start=1):
    print(f"{rank}. [{item.score:.2f}] {item.text}")

​
Convert to legacy dict format

results = knowledge.search("machine learning", user_id="alice")

legacy = results.to_legacy_format()
for row in legacy["results"]:
    print(row["memory"])  # legacy consumers expect the "memory" key

​
Handle any backend shape

Custom backends can return a typed SearchResult, a legacy dict, or a plain list. Normalise them with one call. 
from praisonaiagents.knowledge.models import normalize_search_result

raw = my_custom_backend.query("machine learning")   # dict, list, or SearchResult
results = normalize_search_result(raw)               # always a SearchResult

for item in results.results:
    print(item.text)

​
Best Practices

An empty SearchResult is still a dataclass instance, so it is always truthy.
# ❌ Wrong — SearchResult is a dataclass, always truthy
if not results:
    print("No results")

# ✅ Right — check .results (or .total_count)
if not results.results:
    print("No results")
metadata is never None on SearchResult or SearchResultItem — it defaults to an empty dict, so you never need to guard against None.
for item in results.results:
    page = item.metadata.get("page")  # safe, metadata is always a dict
Older code that expects mem0-shaped {"results": [...]} dicts stays compatible.
legacy = results.to_legacy_format()
send_to_older_pipeline(legacy)
Typed attributes are clearer and safer than dict lookups.
# ✅ Preferred
print(item.text)

# ❌ Avoid
print(item.get("memory"))

Knowledge Overview

Give agents access to your documents

Knowledge CLI

Search from the command line