Retrieval

Retrieval

kb.retrieve() is the RAG entry point. It returns the facts relevant to a question, as notation, within a token budget.

context = kb.retrieve(
    "Who is Google's CEO?",
    top_k=5,
    hops=1,
    max_tokens=200,
    format="notation",
)

How it works

1. Vector search. The question is embedded and compared with the embedded facts. The top_k closest facts are the seeds.
2. Graph expansion. Starting from the entities in those facts, Noema walks outward up to hops relation edges. Each entity records its distance from the nearest seed.
3. Assembly. Facts are packed greedily until max_tokens is reached, in priority order: facts that directly matched the question first, then other facts closest to a seed.

The fact index is built on the first retrieve() and rebuilt after each ingest(). A loaded bundle reuses its saved index.

Options

Option	Default	Meaning
top_k	5	Number of vector-search hits used as seeds
hops	1	How far to expand from each seed through the graph
max_tokens	200	Token budget for the returned text
format	"notation"	"notation" for compact text, "natural_language" for decoded sentences
token_model	cl100k_base	tiktoken encoding used to count the budget

Any other format value raises ValueError.

The result

retrieve() returns a RetrievalResult:

Field	Meaning
text	The context, in the requested format. Empty when nothing was found
notation	The raw notation, whatever format was
entity_ids, relation_ids	Which graph items made it into the text
token_count	Tokens used
truncated	True when the budget cut facts off
fact_matches	The vector-search hits, each with a relation_id and similarity score

Tuning

• Answers missing from the context. Raise top_k, then max_tokens. Check truncated: if it is True, the budget is cutting facts.
• Multi-hop questions. A question like "Who founded the company that acquired X?" needs a fact from one document and a fact from another. Use hops=2 so expansion reaches the second fact. This is where graph retrieval differs from chunk retrieval.
• Noisy context. Lower hops and top_k, or lower max_tokens.
• Cost. Larger max_tokens and hops send more tokens. Fewer tokens per query is the point of Noema, so raise them only as far as accuracy needs.

Assembly stops at the first fact that would exceed the budget instead of searching for a smaller one that fits, so a budget slightly below a fact's size can end the context early.

Notation or natural language

format="notation" is the most token-efficient. format="natural_language" decodes the same facts into sentences. The decoder is template-based, so the sentences can be grammatically rough, but some models and downstream steps handle prose more reliably. Try both on your task.

In a prompt

context = kb.retrieve(question, max_tokens=200)
prompt = f"Use these facts:\n{context.text}\n\nQuestion: {question}"

Check context.text for emptiness before calling your model, so you can answer "no information" instead of prompting with nothing.

From the command line

noema query company_kb.noema "Who is Google's CEO?" --top-k 5 --hops 1 --max-tokens 200

Related

Knowledge Bases, Notation Format, Integrations