In-Task Knowledge Retrieval¶
Inside a managed agent task execution environment, use the task-runtime semantic-model subcommands to search bound knowledge sources, paginate full evidence passages, locate text inside parsed Markdown documents, and submit answer citations. For the underlying HTTP API contracts and authorization rules, see Search and cite knowledge within a task.
Use the injected task connection bundle¶
When an agent execution sandbox spawns child processes, it injects MOI_RUNTIME_AUTHORIZATION (Bearer <token>), MOI_ENDPOINT, MOI_API_KEY, and MOI_WORKSPACE_ID as an atomic bundle. When MOI_RUNTIME_AUTHORIZATION is present, moi-cli binds that short-lived task proof automatically and disables interactive prompts:
Run the
moi-cli semantic-model ...commands below directly while preserving the injected environment variables.Passing an explicit
-endpointor-api-keythat differs from the injected bundle fails immediately withCLI_RUNTIME_CONNECTION_CONFLICTso task proofs are never sent to another endpoint.Standalone workspace management PATs do not carry task execution context and cannot replace short-lived task authorization.
Search, paginate evidence, and submit citations¶
Task-scoped knowledge retrieval follows a three-step loop: search candidate passages, paginate full evidence text, and submit verified citations.
1. Search candidate passages and save the result file¶
Set your query keywords and pass a non-existent local file path to --output:
export KNOWLEDGE_QUERY="retention policy"
moi-cli semantic-model search --keywords "$KNOWLEDGE_QUERY" --output ./search.json
Standard output prints a summary containing path (full JSON result) and reading_path (formatted passage text indexed by PASSAGE numbers). Inspect reading_path to choose the passage indices that answer the user question.
2. Paginate full evidence by passage index¶
Point --from at the saved search file and specify the selected passage --index (0 in the example below):
moi-cli semantic-model read-evidence --from ./search.json --index 0 --output ./evidence-0.json
moi-cli extracts artifact, file, and segment identifiers directly from --from. Inspect output.content and output.has_more; while output.has_more is true, pass the newly written evidence file to --from and save each subsequent page to a new output path until has_more is false:
moi-cli semantic-model read-evidence --from ./evidence-0.json --index 0 --output ./evidence-1.json
If search.json already contains an untruncated full passage that you have read completely, you can pass --local-read to register that full local read.
3. Submit citations and verify accepted¶
After reading the full supporting passages, submit the selected indices before composing the final answer:
# Submit passage index 0 from a single result file (repeat --from <file> --indices <list> across multiple files)
moi-cli semantic-model cite --from ./search.json --indices 0
# Submit an explicit empty citation set when no retrieved evidence supports the factual claim
moi-cli semantic-model cite --json '{"sources":[]}'
Verify output.accepted (and inspect the full JSON at path if the summary reports unaccepted items):
When
acceptedistrue, the server has verified the required evidence reads and recorded your citations.When
acceptedisfalse, fulfill any missingread-evidencerequirements reported in the response and re-submitcite.
Discover source files, search parsed Markdown, and query tables¶
Beyond keyword passage search, runtime commands support source discovery, parsed Markdown navigation, image search, and authorized structured table queries:
Subcommand and key flags |
Description |
|---|---|
|
Search bound source filenames; pass matching entries via |
|
Sequentially read a uniquely named source and inspect coverage metadata. |
|
Paginate passages within a single source using returned source cursors. |
|
Search inside a parsed Markdown document using Markdown locator metadata attached to the evidence item. |
|
Read pages of a parsed Markdown document and follow continuation cursors. |
|
Retrieve image evidence items and page bounding/location metadata. |
|
Inspect structured tables authorized for the current task, then execute a table query and check row counts, truncation flags, and provenance. |
Search inside a parsed Markdown document from an earlier search hit:
moi-cli semantic-model search-document \
--from ./search.json \
--index 0 \
--query "$KNOWLEDGE_QUERY" \
--output ./matches.json
Limitations and notes¶
Every
--outputflag requires a destination path that does not exist yet; choose a new filename for each pagination step or follow-up query.search-documentandread-documentrequire parsed Markdown locator metadata on the referenced evidence item; when absent, continue reading passages withread-evidenceorlist-passages.Local file creation alone does not confirm accepted citations; always check the process exit status, API error fields, and
acceptedin theciteoutput JSON.