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 -endpoint or -api-key that differs from the injected bundle fails immediately with CLI_RUNTIME_CONNECTION_CONFLICT so 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 accepted is true, the server has verified the required evidence reads and recorded your citations.

  • When accepted is false, fulfill any missing read-evidence requirements reported in the response and re-submit cite.

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

semantic-model find-files --query <kw> --output <path>

Search bound source filenames; pass matching entries via --from and --index into subsequent search or passage calls (file listings themselves are not citable evidence).

semantic-model read-source --source-name <exact-name> --output <path>

Sequentially read a uniquely named source and inspect coverage metadata.

semantic-model list-passages --from <file> --index <n> --output <path>

Paginate passages within a single source using returned source cursors.

semantic-model search-document --from <file> --index <n> --query <kw> --output <path>

Search inside a parsed Markdown document using Markdown locator metadata attached to the evidence item.

semantic-model read-document --from <file> --index <n> --output <path>

Read pages of a parsed Markdown document and follow continuation cursors.

semantic-model search-images --query <kw> --output <path>

Retrieve image evidence items and page bounding/location metadata.

semantic-model describe-tables / semantic-model query --json-file <query.json> --output <path>

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 --output flag requires a destination path that does not exist yet; choose a new filename for each pagination step or follow-up query.

  • search-document and read-document require parsed Markdown locator metadata on the referenced evidence item; when absent, continue reading passages with read-evidence or list-passages.

  • Local file creation alone does not confirm accepted citations; always check the process exit status, API error fields, and accepted in the cite output JSON.

Last updated on