RAG Strategies for Maximo Data: Which Retrieval for Which Records

🎯 Who this is for: Maximo developers, integration leads and architects who have been asked to "put RAG on Maximo" and want to choose retrieval strategies deliberately instead of embedding the whole database and hoping.

Series: Part 3 of 8 — The Agentic AI Playbook for Maximo | Read time: 35 minutes

Concepts in this series are adapted from [Cole Medin's YouTube channel](https://www.youtube.com/@ColeMedin) and the Dynamous AI Mastery community (dynamous.ai), and applied to IBM Maximo by TheMaximoGuys.

🔥 The Question That Broke the Demo

The demo went well. A reliability engineer typed "why does pump P-2041 keep tripping on vibration?" and the agent came back with a tidy summary of three old work orders, a grout failure and a realignment. Everyone nodded.

Then the storeroom supervisor asked the second question: "Do we have seal kit 10045-778 at CENTRAL?" The agent answered confidently with a quantity of 12. The real balance was 0. The number came from a worklog written eight months earlier ("pulled 2 of 14 seal kits"), which the embedding search had judged the most similar text. Somebody then asked "what sits below V-118 in the raw water system?" and got a paragraph about a different valve with a similar description.

None of these failures was a model problem. The same agent, the same LLM, the same prompt. They were retrieval choice problems:

  • A balance is a number in INVBALANCES. It should have been a live query, never a similarity search.
  • 10045-778 is an identifier. Embedding models are bad at identifiers.
  • "Below V-118 in the raw water system" is a hierarchy question. It lives in LOCHIERARCHY and asset parent links, not in any paragraph of text.

Cole Medin makes the point that there is no single correct RAG strategy. The right system usually combines "three to five" strategies chosen for the data ("Every RAG Strategy Explained in 13 Minutes", 0:00:54). Maximo is a good test of that idea, because a single Manage database holds almost every kind of data a retrieval system can meet: strict relational tables, deep hierarchies, short codes, long free text, rich-text HTML, and binary attachments.

This part is about choosing. The deep build (a pgvector schema, incremental OSLC sync, Kafka publish channels, agent memory) is already in agm-05: Giving Maximo Agents a Memory. Here we take the step before that: for each kind of Maximo data, which retrieval strategy should you use, and why?

📌 The Short Version

If the question is about...UseNot
The present (status, stock, who is assigned, open POs)A live OSLC or SQL query toolVector search
A specific identifier (part, asset, WO, failure code)Exact filter or keyword searchPure semantic search
"Has this happened before?" / "what fixed it?"Hybrid search over narrative text, filtered and rerankedTop-k semantic with no filters
A procedure in an OEM manual or SOPHierarchical RAG over a separate document corpusOne flat index mixed with work orders
Parents, children, systems, failure-code treesRecursive SQL or OSLC; a graph for cross-entity questionsText retrieval
Counts, averages, trendsSQL or analytics toolAny RAG at all

And three rules that apply everywhere: every chunk carries SITEID and ORGID and is filtered before ranking; every chunk carries a stable record identity so edits are re-ingested with delete-before-insert; and the agent, not a fixed pipeline, chooses which of these tools to call.

🧭 First Decision: Is This Even a RAG Problem?

Cole's answer to the recurring "is RAG dead?" debate is a domain answer, not a yes or no: "For coding, yes. For literally everything else, definitely not." ("Why the Best AI Coding Tools Abandoned RAG", 0:14:33). His reasoning is the useful part. Coding agents dropped vector indexes because codebases are highly structured: file trees, symbol names and imports already form an index, so an agent can navigate with grep and file reads instead of guessing by similarity. In the same video he frames the real question as "how structured is it?" (0:01:57).

Apply that test to Maximo and you get a split down the middle of the database.

Structured Maximo data is like code. It has a schema, keys, domains and relationships that are already indexed. WORKORDER.STATUS, INVBALANCES.CURBAL, ASSET.PARENT, LOCHIERARCHY, FAILURELIST, MATUSETRANS, WOSTATUS history. The schema is the index, and the object structures (mxapiwo, mxapiwodetail, mxapiasset, mxapiinventory and many more) are a navigation API. An agent should "navigate" this data the way a coding agent navigates files: with exact queries.

Cole is blunt about what happens when you chunk tables: RAG "usually does absolutely terribly with tables" because it pulls chunks that "might only be a part of the table" ("The ULTIMATE n8n RAG AI Agent Template - Local AI Edition", 0:08:13). His fix is to give the agent a tool that writes SQL for sums, averages and maximums. In Maximo terms: "mean time between failures for BEDFORD pumps" is not something you can retrieve. It is something you compute, from failure-reported work orders, with a query.

Unstructured Maximo data is where retrieval belongs. The long description of a corrective work order. The worklog where a technician wrote what actually happened. The remarks on a failure report. Job plan task text. The 300-page OEM manual attached to the asset record. The SOP PDF attached to a location. The scanned inspection form from 2014. None of this has a schema beyond "some text owned by some record", and people describe the same problem in a dozen different ways ("tripping on vib", "high vibration alarm", "shaking at startup"). That ambiguity is what semantic search was built for.

Here is the inventory most Manage databases actually contain:

Maximo dataWhere it livesShapeDefault access
WO status, priority, dates, assignmentsWORKORDER, ASSIGNMENT, WOSTATUSStructured, changes hourlyLive OSLC query
Inventory balances, reservations, open PO linesINVBALANCES, INVRESERVE, POLINEStructured, numericLive OSLC or SQL
Meter readings, measurementsMETERREADING, MEASUREMENTTime seriesAnalytics or SQL, not RAG
Asset, location and system hierarchiesASSET.PARENT, LOCHIERARCHY, ancestor tablesGraph-shaped relationalRecursive query; graph if cross-entity
Failure class, problem, cause, remedyFAILURELIST, FAILURECODE, FAILUREREPORTTree of short codesExact lookup; codes as metadata filters
WO and SR long descriptionsLONGDESCRIPTIONRich-text proseRetrieval
WorklogsWORKLOG + long descriptionProse, child of WORetrieval, grouped under parent
Job plan and PM task textJOBPLAN, JOBTASK + long descriptionsProcedural proseRetrieval, plus exact lookup by job plan number
OEM manuals, SOPs, drawings, photosDOCLINKS / DOCINFO attachmentsFiles of mixed typeExtraction, then hierarchical retrieval
Item and asset specificationsITEMSPEC, ASSETSPEC, classificationsAttribute-value pairsFilters and exact queries; text for similarity

The table is the same idea agm-05 applies to memory, which is the right place for the "what do I embed" list in depth. The point here is the next step: once you know which rows are retrieval problems, there are a dozen ways to retrieve, and each Maximo corpus wants a different mix.

💡 Same record, two representations. A work order is both. Its status and dates are structured and live; its long description and worklogs are narrative. Cole notes that the same data can be stored more than one way so the agent can reason over each representation ("Introducing RAG 2.0", 0:09:36). For Maximo, copy a few structured fields into chunk metadata for filtering, and fetch the live record when the agent needs a current value.

🗂️ The Retrieval Toolbox, Translated for Maximo

Cole's "Every RAG Strategy Explained in 13 Minutes" walks through eleven strategies across two phases, data preparation and retrieval. His tactical advice if you only pick three: reranking, agentic RAG and context-aware chunking (0:12:24). Below is the toolbox with a Maximo reading of each. Use it as a menu, not a checklist.

StrategyWhat it fixesCostWhere it fits in Maximo
Semantic searchFinds meaning across different wordingLow"Similar problems" over long descriptions and worklogs
Keyword searchGuarantees exact-term matchesLowPart numbers, asset tags, WO numbers, failure codes, error codes in PLC text
Hybrid search + RRFCombines both without score-scale fightsLow to mediumAny corpus mixing prose and identifiers (most of Maximo)
RerankingNarrows a wide candidate set to the truly relevant fewMedium (extra model call)After hybrid search on work order history and manuals
Query expansionRewrites terse questions into the corpus vocabularyLow (one LLM call)"pump shaking" → vibration, VIBR, misalignment, cavitation
Multi-query RAGSeveral phrasings searched in parallel for coverageMediumRoot-cause research across years of history
Context-aware chunkingSplits on structure, not character countsLowManuals by section, WOs by long description and worklog
Contextual retrievalAdds document context to each chunk before embeddingMedium to high (LLM per chunk)Manuals where a chunk says "tighten to spec" with no equipment named
Late chunkingEmbeds the whole document before splittingNeeds long-context embedderLong SOPs with heavy cross-referencing
Hierarchical RAGSearch small, return the parent sectionLow to mediumOEM manuals, multi-task job plans, asset → WO → worklog
Knowledge graphsRelationships and multi-hop questionsHigh (LLM extraction)Cross-entity questions that SQL hierarchies cannot answer
Temporal knowledge graphsFacts that change over time, kept with validity datesHighAsset moves, changing vendor or spec facts, superseded procedures
Self-reflective RAGGrades retrieved chunks and retries if weakMedium (extra LLM calls)High-stakes answers: safety procedures, isolation steps
Agentic RAG / agentic searchThe agent picks the tool, the filter, and whether to retryVariesThe router over everything above, plus live OSLC tools

Two observations before we go strategy by strategy. First, most of the high-value moves for Maximo sit in the cheap rows: metadata filters, keyword search for identifiers, structure-aware chunking. Second, Maximo gives you something most RAG corpora lack: structured context for free. A worklog chunk does not need an LLM to tell it which asset, site and failure class it belongs to. The work order already knows. We will use that repeatedly.

🔎 Identifiers Break Semantic Search: Keyword and Hybrid for Maximo

Semantic search is a conceptual search. Cole puts the trade-off plainly: "we're able to find concepts and related ideas, but we aren't guaranteed to find exact terms" ("The Simplest RAG Stack That Actually Works", 0:05:52). In the same video he gives the failure mode that maps exactly onto Maximo: classic RAG with several years of data "might find 2023 revenue instead of 2025" (0:08:33). Substitute "WO 10431 instead of WO 10481" or "seal kit 10045-778 instead of 10045-788" and you have the most common Maximo RAG bug.

Maximo is dense with identifiers that carry no meaning for an embedding model:

  • Item numbers and manufacturer part numbers (10045-778, SKF 6205-2RS)
  • Asset numbers and tags (P-2041, 11430), often reused patterns across sites
  • Location codes (PS-07, BEDFORD-BLDG2-MCC3)
  • Work order, PM and job plan numbers (WO 10431, PM-PUMP-Q, JP-PUMP-07)
  • Failure codes (VIBR, GROUT, REALIGN) and classification ids
  • Alarm and fault codes pasted from SCADA or PLC screens

Rule one: identifiers go to exact tools first. If the question contains something that looks like an identifier, the agent should resolve it with a live, exact lookup before any similarity search. In Maximo that is an oslc.where equality on the object structure, or the REST API's text search. The Maximo JSON API supports oslc.searchTerms together with searchAttributes, which names the fields to search and combines with oslc.where. It does wildcard (LIKE-style) matching, not relevance ranking, which is exactly what you want for identifiers:

# Illustrative: exact identifier resolution, run as the requesting user
GET /maximo/api/os/mxapiinventory?lean=1
    &oslc.where=itemnum="10045-778" and location="CENTRAL" and siteid="BEDFORD"
    &oslc.select=itemnum,location,curbaltotal,binnum

# Illustrative: free-text lookup on a few fields, combined with a filter
GET /maximo/api/os/mxapiasset?lean=1
    &oslc.where=siteid="BEDFORD"
    &oslc.searchTerms="P-2041"
    &searchAttributes=assetnum,description,serialnum

Rule two: any text index you build should be hybrid. Worklogs and long descriptions mix prose with identifiers ("replaced 10045-778, pump P-2041 now 2.1 mm/s"). A pure vector index will match the prose and blur the identifiers. Keyword search fixes the second half: if the exact term "appears in my knowledge base, I am guaranteed to find that chunk" ("The Simplest RAG Stack", 0:05:26). Cole's memorable example is that searching "AAPL" finds the stock and not the fruit. In Maximo, searching VIBR finds the vibration failures and not every paragraph that mentions noise.

Hybrid search runs both legs and merges them. The merge is the subtle bit. Cole explains why you cannot just average scores: "the similarity scores from our two pipelines have a completely different scale" ("The Simplest RAG Stack", 0:20:56). Vector similarity sits between zero and one; a BM25 score might be 13. Reciprocal rank fusion throws the raw scores away and uses rank positions only, so an item near the top of both lists rises.

-- Illustrative: hybrid search with reciprocal rank fusion in Postgres.
-- Site filter applied INSIDE both legs, before ranking (see the security section).
WITH sem AS (
  SELECT chunk_id, ROW_NUMBER() OVER (ORDER BY embedding <=> :query_vec) AS r
  FROM maximo_chunk
  WHERE siteid = ANY(:allowed_sites) AND corpus = 'wo_history'
  ORDER BY embedding <=> :query_vec
  LIMIT 50
),
kw AS (
  SELECT chunk_id, ROW_NUMBER() OVER (ORDER BY ts_rank(tsv, q) DESC) AS r
  FROM maximo_chunk, websearch_to_tsquery('simple', :query_text) q
  WHERE siteid = ANY(:allowed_sites) AND corpus = 'wo_history' AND tsv @@ q
  ORDER BY ts_rank(tsv, q) DESC
  LIMIT 50
)
SELECT chunk_id,
       COALESCE(1.0 / (60 + sem.r), 0) + COALESCE(1.0 / (60 + kw.r), 0) AS rrf
FROM sem FULL OUTER JOIN kw USING (chunk_id)
ORDER BY rrf DESC
LIMIT 30;   -- hand these 30 to a reranker, keep the best 5-8

Two Maximo details matter in the keyword leg. Use a text-search configuration that does not stem or split your identifiers (the simple configuration above keeps 10045-778 closer to intact than an English stemmer would), and consider indexing normalised variants of part numbers (with and without dashes) because technicians type them both ways. A simple way to do that is a separate normalised identifier column (for example ident_norm, holding 10045778 for 10045-778: upper-cased, punctuation stripped) populated at ingestion, with the same normalisation applied to the query before an exact or prefix match on that column runs alongside the full-text leg.

Then rerank. Hybrid search is a recall tool: cast a wide net. Reranking is the precision step. Cole's warning about skipping it: handing the LLM "25 chunks leads to a very high risk of hallucinating" ("Your ULTIMATE n8n RAG AI Agent Template just got a Massive Upgrade", 0:16:14). A cross-encoder reranker reads the question and each candidate together and orders them by real relevance, cheaply, because it is a narrow model rather than a general LLM. For Maximo history, retrieving 30 to 50 candidates and keeping 5 to 8 after reranking is a sensible starting point to tune with evals (agm-06).

Query expansion helps the semantic leg, not the identifier. "Pump shaking" will never match a worklog that says "VIBR alarm, soft foot found". A single LLM call that rewrites the question into Maximo vocabulary (vibration, VIBR, misalignment, soft foot, bearing) improves recall substantially. Feed it your failure-code descriptions for the relevant failure class as context and the expansion stops guessing. Multi-query RAG, several variants in parallel, is worth it for root-cause research where coverage matters more than latency. It is wasted on "what is the torque for this flange?"

📚 Manuals, SOPs and Doclinks: Hierarchical RAG and Document Extraction

Work order history and OEM manuals are different corpora and should be different indexes, or at least different corpus values that the agent filters on. History is thousands of short, similar, site-specific stories. A manual is one long, structured, authoritative document that applies to every asset of a model. Mix them in one flat index and the short work order chunks crowd out the manual, or the manual's general text crowds out the specific history.

Getting the text out is the hard part

Cole is direct that extraction, not embedding, is where pipelines break: the hardest part "is really just actually extracting the text from the documents" ("Effortless RAG in n8n - Use ALL Your Files", 0:00:00). His fix is to branch on file type rather than push every file through one extractor.

Maximo attachments live in DOCLINKS (which record owns the attachment) and DOCINFO (the document itself). Through the REST API you list them from the owning resource's doclinks collection and fetch each one by its link; the IBM REST guide shows GET .../mxapiasset/{id}/doclinks to list and GET .../doclinks/{id} for content, and a doclinks/meta/{id} link for metadata. MAS 9.2 also lets users add attachments directly in the Work Orders application (IBM's MAS 9.2 What's New for Manage), so expect the volume of WO-level attachments to grow.

What you find there is a mess, and the extraction plan should say so out loud:

Attachment typeTypical contentExtraction approach
Digital PDF manualsOEM operation and maintenance manualsLayout-aware PDF extraction to markdown; keep headings and tables
Scanned PDFs and imagesOld inspection forms, signed permits, nameplate photosOCR; flag low-confidence pages; often better as metadata than as chunks
Word and text SOPsSite procedures, LOTO stepsConvert to markdown; headings become section boundaries
SpreadsheetsSpare parts lists, torque tables, test resultsKeep as rows the agent can query; do not chunk as prose
Drawings (DWG, large PDFs)P&IDs, wiring diagramsTitle block and revision as metadata; usually do not embed
Email (.msg, .eml)Vendor correspondenceStrip quoted chains and signatures; low priority

Cole's preferred tool for this is Docling, which handles many formats and offers hybrid chunking that keeps paragraphs and lists intact ("The Simplest RAG Stack", 0:04:02). Whatever you use, test it on your worst attachment, not your best one.

Search small, return big

A manual chunk that says "torque bolts to 85 Nm in a star pattern" is a perfect search hit and a dangerous answer on its own, because the steps before and after it (isolation, cleaning, gasket replacement) are what make it safe. Hierarchical RAG solves this with parent-child links stored as chunk metadata: the search runs over small, precise chunks, and the agent receives the parent section. Cole's summary is "searching small with context, returning big" ("Every RAG Strategy Explained", 0:09:25).

Maximo hierarchies to use:

  • Manual: document → chapter → section/procedure → step chunk. Return the whole procedure.
  • Job plan: job plan → task → task long description. Return all tasks, in sequence, when any task matches.
  • History: asset → work order → long description and worklogs. Return the assembled work order when a worklog matches. (agm-05 shows the assembled-document format, so we will not repeat it here.)

Context for free, and when to pay for it

Contextual retrieval, published by Anthropic and covered by Cole, prepends a short description of where a chunk sits in its document before embedding. Cole notes that even "one or two sentences" added at the start of each chunk improves results significantly. Anthropic's own write-up reports that contextual embeddings cut top-20 retrieval failures by 35%, combining them with contextual BM25 by 49%, and adding reranking by 67%, on their internal benchmarks. Treat those as directional, not as a promise for your data.

For Maximo there are two tiers:

  1. Free context from Maximo fields. Every chunk from a work order or worklog can start with a header built from structured fields: site, asset, location, failure class and problem code, work type, date. That is contextual retrieval without an LLM call, and it is the default for history.
  2. Paid context for manuals. A manual chunk has no Maximo fields beyond its owner. "Replace the seal as shown in Figure 12" means nothing without knowing it is section 7.3 of the Flowserve model X maintenance manual, for the mechanical seal. That is where an LLM-generated context line per chunk earns its cost, with prompt caching of the full manual to keep the bill down. Cheaper middle ground: prepend the chapter and section headings, which Cole also describes as a light form of contextualisation.

Late chunking (embed the whole document with a long-context embedding model, then split the token embeddings) is an alternative for long SOPs with lots of "as above" references. It is newer and depends on the embedding model, so try contextual headings first.

# Illustrative: metadata stamped on every manual chunk
corpus: oem_manual
doclinks_id: 28417          # stable identity for re-ingestion
owner_table: ASSET          # or ITEM, LOCATIONS, JOBPLAN
owner_key: "P-2041"         # assetnum; or itemnum for item-level manuals (site is the separate siteid field)
applies_to_model: "Flowserve-X"   # from asset or item spec, enables reuse across sites
doc_type: MANUAL            # MANUAL | SOP | DRAWING | PHOTO | FORM
revision: "Rev C 2021-04"
section_path: "7 Maintenance > 7.3 Mechanical seal > Step 4"
parent_section_id: "28417:7.3"
siteid: BEDFORD
orgid: EAGLENA

🕸️ Hierarchies Are Graphs: Asset, Location and Failure Codes

Vector databases, Cole points out, "don't do a good job storing relationships between the different entities that we have in our data" ("Knowledge Graphs in n8n are FINALLY Here!", 0:01:33). His rule for when to reach for a graph is a good one: a question about a single entity goes to the vector store; a question about how two entities relate goes to the graph (same video, 0:03:11).

Maximo is full of relational questions:

  • "Which locations and assets sit below V-118 in the RAWWATER system hierarchy?"
  • "What else is fed from MCC-3?"
  • "For failure class PUMPS, which causes have we recorded under problem VIBR, and what remedies?"
  • "Which child assets of this conveyor have open corrective work?"

Here is the part most AI vendors skip: Maximo already stores these as graphs. Location systems live in LOCHIERARCHY (location, parent, system). Asset parent-child relationships live on ASSET.PARENT, with ancestor tables for fast lookups. The failure hierarchy lives in FAILURELIST, where each row has a TYPE of problem, cause or remedy and a PARENT pointing to the row above, rooted at the failure class. These are relational graphs with exact edges, maintained by the people who own the data.

One caution about what those edges mean. LOCHIERARCHY is containment ("this location is part of that system position"), not flow. A parent-child link does not tell you which way water runs or what is fed from what, and a valve is usually an asset installed at a location rather than a location itself. Feed and flow connectivity is usually not in LOCHIERARCHY at all: it needs asset or location relationships configured for it, linear asset data, or a network model in GIS or a hydraulic tool. The hierarchy tool below answers "what is below this position in the system", which is a useful first cut, not an isolation or impact analysis.

So the first answer for hierarchy questions is a tool, not an index:

-- Illustrative: everything below a location in one system hierarchy, exact and cheap
-- (containment, not hydraulic flow; V-118 here is the location position the valve occupies)
WITH RECURSIVE below AS (
  SELECT location, parent, 1 AS depth
  FROM lochierarchy
  WHERE parent = 'V-118' AND systemid = 'RAWWATER' AND siteid = 'BEDFORD'
  UNION ALL
  SELECT h.location, h.parent, d.depth + 1
  FROM lochierarchy h JOIN below d ON h.parent = d.location
  WHERE h.systemid = 'RAWWATER' AND h.siteid = 'BEDFORD'
)
SELECT * FROM below;

Expose that as a read-only tool (or the OSLC equivalent, or an MCP tool, which is the subject of Part 4) and the agent answers hierarchy questions exactly, with no extraction cost and no drift from Maximo.

The failure hierarchy deserves a special mention because it doubles as a retrieval vocabulary. Before searching history for "shaking", the agent can call a tool that lists the problem codes under the asset's failure class, map "shaking" to VIBR, and then filter the history search on problemcode = 'VIBR'. Exact codes as filters, descriptions as query expansion. That one move fixes more Maximo RAG accuracy problems than any embedding model upgrade.

When a knowledge graph does earn its cost

A graph built with an LLM extractor (Cole uses Graphiti over Neo4j) is worth it when the relationships you need are not in Maximo's tables, but in the text:

  • "Assets that share the seal kit the vendor recalled": the link between seal kit and assets may live only in worklogs and vendor emails.
  • "Which contractors worked on assets that later failed with the same cause?": a multi-hop across labour, work orders and failure reports that is painful in SQL and natural in a graph.
  • Relationships between sites that Maximo does not model, such as a shared spares pool agreed informally.

Cole is candid about the trade-off: graphs are "fantastic for interconnected data" but "a lot slower and more expensive" because an LLM does the extraction ("Every RAG Strategy Explained", 0:05:14). Start with SQL hierarchies, write down the cross-entity questions SQL cannot answer, and build a graph for those only.

Temporal graphs and Maximo history

Temporal knowledge graphs store a changed fact as a new fact with valid_at and invalidated_at, so an agent knows what is true now and what used to be true ("Make RAG 100x Better with Real-Time Knowledge Graphs", 0:00:51). This maps onto real Maximo questions: an asset that moved between locations, a job plan revision that superseded the old procedure, a vendor that changed a recommended interval.

Before building one, check what Maximo already records. Asset moves have their own transaction history; status changes are in status history tables; job plans have revisions. Often the "temporal" layer is a query against history tables plus metadata on chunks (revision, valid_from) so that superseded manual revisions are filtered out by default. A temporal graph is the right tool when the changing facts are buried in narrative text, not when Maximo already stamps them.

🔐 Metadata Filtering Is Your Security Model

Metadata filtering is usually taught as a precision tool. Cole's examples are about scoping a search to one documentation source, or to records ingested in the last day, and about carrying file id and title so the model can cite its source ("The Future of RAG is Agentic", 0:17:23 and 0:17:39). In Maximo, it is also the security model, because your ingestion job almost certainly ran as an integration user who can see every site.

Maximo enforces access through security groups, site authorisation and data restrictions. A REST call made with a user's API key runs in that user's security context. Your vector store knows none of that. If the BEDFORD technician's question can retrieve a NASHUA chunk, the index has leaked a record Maximo would never have shown them.

The minimum metadata on every chunk, and what each field is for:

FieldPurposeFilter type
orgid, siteidSite authorisationMandatory pre-filter, from the user's authorised sites
corpusSeparate history, manuals, SOPs, job plansAgent-chosen
owner_table, owner_keyStable identity, citation, re-ingestionExact
assetnum, location, itemnumNarrow to the equipment in questionAgent-chosen, exact
failurecode, problemcode, causecodeNarrow history by failure modeAgent-chosen, exact
worktype, reportdateCM vs PM, recencyAgent-chosen, range
doc_type, revision, valid_fromExclude superseded proceduresDefault filter
security_tagData restrictions you mirror (confidential locations, HR-sensitive WOs)Mandatory pre-filter

Three rules make it work:

  1. The site filter is not the agent's choice. The agent may choose assetnum and failurecode. It must never choose siteid. Inject the allowed sites from the authenticated user into the retrieval tool in code, the way agm-05 does with row-level security in Postgres. Prompt instructions are not access control; Part 5 covers why.
  2. Filter before ranking, not after. Filtering after a top-k search can return zero results for a user at a small site, because the top 50 were all from the big site. Apply the filter inside each search leg (as in the SQL above), and check that your vector index honours filters during the scan.
  3. Re-check what you cite. Before quoting a work order, the agent fetches it live through the API as the requesting user. If the fetch fails, the citation is dropped. This catches data restrictions you did not mirror into metadata.

🔄 When a Work Order Changes: Re-ingestion Without Ghosts

Maximo records are edited constantly. A planner fixes the long description after a call with the technician. A worklog is added a week after completion. A failure code is corrected during review. An attachment gets a new revision. A demo ingests once; a production system ingests forever. Cole names freshness as one of the three axes on which toy RAG fails, alongside scale and unexpected questions ("This RAG AI Agent with n8n + Supabase is the Real Deal", 0:00:15).

The trap is in the write step. Most vector-store inserts are not upserts. Cole: "it is not an upsert it is just an insert" ("Run ALL Your AI Locally in Minutes", 0:14:18). Re-ingest a changed work order and you now have both the old and the new long description in the index, and the agent may quote the version the planner deliberately corrected.

The fix is delete-before-insert keyed on a stable identity in metadata:

Change in MaximoIdentity to delete byRe-ingest
WO long description editedowner_table=WORKORDER, siteid, wonumAll chunks for that WO, header rebuilt
Worklog added or editedParent WO identity (not the worklog alone)Parent WO's assembled chunks
Failure codes correctedParent WO identityHeader and metadata change, so re-chunk
WO status onlyNoneNothing to re-embed; status is live data
Attachment replaced or new revisiondoclinks_id, plus revisionThat document's chunks; mark old revision invalid or delete
WO or attachment deletedIdentity from reconciliationDelete only
Job plan revisedJob plan number + revisionNew revision chunks; old ones filtered by valid_from

Two Maximo specifics. Worklogs are children, so a changedate on the work order may not move when only a worklog changes; agm-05's freshness section covers watermarks, Kafka publish channels and the reconciliation job in detail, so this part only states the rule. And status changes should not trigger re-embedding at all. If status-only changes are churning your embedding bill, you have put live data in the index.

# Illustrative: delete-before-insert for one work order, in one transaction
def reingest_work_order(db, wo):           # wo fetched live from mxapiwodetail
    key = {"owner_table": "WORKORDER", "siteid": wo["siteid"], "owner_key": wo["wonum"]}
    chunks = build_chunks(wo)               # header from Maximo fields + long description + worklogs
    with db.transaction():
        db.delete_chunks(where=key)         # remove every old version first
        db.insert_chunks(chunks, metadata=key | {"content_hash": hash_of(chunks)})

🧮 The Decision Table: Which Retrieval for Which Maximo Data

This is the table to print. It assumes metadata filtering (site, org, security tag) on every row with a text index, and an agentic router that chooses between rows.

Maximo dataTypical questionPrimary retrievalAdd when neededAvoid
WO / SR status, dates, assignments"Is WO 10431 approved?"Live OSLC query (mxapiwo)MCP tool for the sameAny embedding
Inventory balances, reservations"Seal kits at CENTRAL?"Live OSLC or SQL (mxapiinventory)Alternate-item lookupSimilarity on worklogs mentioning quantities
Counts, MTBF, costs, trends"Average repair time on BEDFORD pumps?"SQL or analytics toolRead-only reporting viewsRAG of any kind
Part numbers, asset tags, WO numbers"What is 10045-778?"Exact filter or oslc.searchTermsKeyword leg of hybridPure semantic search
WO long descriptions + worklogs"Has P-2041 seized before? What fixed it?"Hybrid (BM25 + vector) with RRF, Maximo-field headersRerank; query expansion via failure codes; multi-query for RCAUnfiltered top-k
Failure reports"Common causes of VIBR on PUMPS?"Exact codes via FAILURELIST + SQL countsRemarks text in hybrid searchEmbedding the codes as prose
Job plans and PM tasks"Which job plan covers seal replacement?"Exact lookup by number; hybrid search on task textHierarchical return of all tasksReturning one task out of sequence
OEM manuals (doclinks)"Torque spec for the seal gland?"Hierarchical RAG on a separate corpus, structure-aware chunksContextual headers or LLM context; rerank; self-reflective gradingMixing into the WO history index
SOPs, LOTO procedures"Isolation steps for PS-07?"Hierarchical RAG, revision-filteredSelf-reflective grading; human confirmationAnswering from a superseded revision
Scanned forms, photos, drawings"Last nameplate photo of P-2041?"Metadata search on doclinks (owner, type, date)OCR text when quality allowsEmbedding low-quality OCR
Asset / location hierarchies"What sits below V-118 in RAWWATER?"Recursive SQL or OSLC toolKnowledge graph for cross-entity, text-derived linksText retrieval
Facts that change over time in text"What interval does the vendor recommend now?"Revision and validity metadataTemporal knowledge graphOverwriting without history
Specifications and classifications"150 HP vertical turbine pumps at BEDFORD"Attribute filters (classification search)Spec text in hybrid for similaritySemantic search on numeric specs

🤖 Putting It Together: An Agentic Retrieval Router

Everything above becomes useful only when the agent can choose. Cole's definition of agentic RAG is short: "giving agents the ability to reason about how they explore the knowledge base instead of just giving it a single tool" ("I Built the ULTIMATE n8n RAG AI Agent Template", 0:03:14). One common pattern he describes is several stores serving different purposes, each behind its own tool ("All the BEST RAG Strategies in ONE MCP", 0:13:30). He is also clear about the price: flexibility comes with less predictability ("Every RAG Strategy Explained", 0:04:22).

IBM's own direction points the same way. In its Think article "Working smarter with agentic workflows in Maximo Assistant", IBM describes an agentic Maximo Assistant built around a Supervisor ALM agent that orchestrates tools including knowledge search, product-guidance RAG, data retrieval and condition insights, with write actions going through the Maximo MCP server. Treat that as IBM's announced direction (parts of the article are in the future tense), not as a documented, shipped feature set; what IBM does document for 9.2 is the MCP server itself and automation scripts as custom MCP tools. Either way, the shape is a retrieval router: some tools search text, some query live data, and the agent decides. If you build your own agent, or extend IBM's through custom MCP tools, the same design applies.

A playbook-level tool set (agm-05 has a memory-oriented version; this one is organised by retrieval strategy):

# Illustrative tool catalogue for a Maximo retrieval router

resolve_identifier(text)            -> exact OSLC lookups for items, assets, locations, WOs, job plans
query_live(object, where, select)   -> read-only OSLC query as the user (status, balances, assignments)
run_report(name, params)            -> approved SQL views for counts, MTBF, costs (no free-form SQL)
list_failure_codes(failureclass)    -> FAILURELIST problems/causes/remedies with descriptions
get_hierarchy(location|asset, dir)  -> recursive parents/children within a system
search_history(query, filters)      -> hybrid + RRF + rerank over WO long descriptions and worklogs
search_documents(query, filters)    -> hierarchical RAG over manuals/SOPs, returns whole sections
get_record(owner_table, key)        -> live fetch for citation checks

And a decision policy in the system prompt, short enough to follow:

- If the question contains an identifier, call resolve_identifier first.
- Questions about now (status, stock, assignments): query_live. Never answer from search tools.
- Questions with numbers over many records (averages, counts, trends): run_report.
- "Has this happened before / what fixed it": list_failure_codes to get codes, then search_history filtered by asset and codes.
- Procedures, specs, torque values, isolation steps: search_documents, then quote the whole section with document and revision.
- Before citing any work order, call get_record. Drop citations that fail.
- If retrieved text does not answer the question, say so, refine once, then stop.

The last line is a lightweight version of self-reflective RAG: grade what came back, retry with a better query if it is weak, and stop rather than loop. Cole describes the full form as an LLM grading the chunks on a 1 to 5 scale and re-searching when the grade is low ("Every RAG Strategy Explained", 0:10:14). For Maximo, spend that extra call where wrong answers are dangerous (isolation steps, torque values, confined space procedures) and skip it for "similar work orders" panels, where a fixed filter-search-rerank pipeline is faster and easier to test.

💡 Agentic search over Maximo is real, but bounded. Coding agents navigate codebases without an index because the structure is the index. An agent with query_live and get_hierarchy can navigate structured Maximo data the same way. It cannot navigate 40,000 worklogs one record at a time; that is what the text index is for. Cole's own caveat: for large knowledge bases with thousands of documents, semantic search is still "more accurate and way way cheaper" ("Everything You Thought About Building AI Agents is Wrong", 0:14:15).

🔬 Worked Scenarios

1. The storeroom question. "Do we have seal kit 10045-778 at CENTRAL, and what can substitute?" The router sees an identifier and calls resolve_identifier, which returns the item and its alternates. It then calls query_live on inventory for the item and its alternates at CENTRAL, as the user. Balance 0 for the item, 3 for an alternate. No vector search runs at all. The demo failure from the opening is gone because the answer was never a retrieval problem.

2. Repeat vibration on P-2041. "Why does P-2041 keep tripping on vibration?" list_failure_codes(PUMPS) maps "vibration" to VIBR. search_history runs hybrid search filtered to site BEDFORD, asset P-2041 and its siblings of the same model, problem code VIBR, last five years. Fifty candidates, reranked to six. Two hits mention cracked baseplate grout; one mentions soft foot. The agent calls get_record on each before quoting, then calls query_live to confirm today's work order is in WAPPR. The answer cites three work orders by number and site, and recommends checking grout and soft foot, with "needs planner review" set.

3. The torque value. A technician on mobile asks for the seal gland torque on P-2041. resolve_identifier returns the asset's item and manufacturer model. search_documents filters to corpus=oem_manual, the model, doc_type=MANUAL, current revision. The best small chunk is step 4 of section 7.3; hierarchical retrieval returns all of section 7.3, including isolation and gasket steps. A self-reflective grade confirms the section names the right seal type. The answer quotes the procedure with manual title, revision and page, and says plainly that the value is from the OEM manual, not site practice.

4. Below V-118. "If we close V-118 for the PM, what might be affected?" get_hierarchy(V-118, down) in the RAWWATER system hierarchy returns eleven locations below that position; query_live lists the operating assets at those locations and their open work orders. No text index touched. Treat the list as a candidate set for operations to confirm, not as the answer to "what loses supply": the hierarchy is containment, and true feed impact needs relationship or network data (see the hierarchies section). If the operations team later asks "which of those had complaints from the plant about low pressure last winter?", that is a history search filtered to those eleven locations: structured narrowing first, retrieval second.

5. The corrected long description. A planner rewrites WO 10431's long description after learning the root cause was cavitation, not bearing wear. The publish event (or the next changedate pull) triggers reingest_work_order: delete every chunk keyed to BEDFORD/10431, rebuild the header with the corrected cause code, insert. An hour later the agent's answer about P-2041 cites cavitation. Without the delete step it would have cited both causes from the same work order and hedged between them.

6. Choosing a job plan for a new PM. A reliability engineer asks which existing job plan best fits quarterly inspection of a new pump model. search_documents with corpus=job_plan runs hybrid search over task text and returns whole job plans, not single tasks, ranked. The agent lists the top three by number and revision, notes which tasks reference the old model's manual, and suggests the engineer review task 30 against section 6 of the new model's manual. It proposes; the engineer decides, and any creation of the PM goes through approved write tools covered in Parts 4 and 5.

⚠️ Pitfalls

SymptomLikely causeFix
Agent quotes stock quantities or statuses from old worklogsLive data answered by similarity searchRoute present-tense questions to live query tools; say so in tool descriptions
Right topic, wrong part or asset numberPure semantic search on identifiersExact resolution first; hybrid search with a non-stemming keyword leg
Answers mix sites or show records the user cannot openIndex built by an all-sites integration user, no pre-filterMandatory siteid/orgid filter injected in code; re-fetch citations as the user
Small sites get no resultsFiltering after top-kFilter inside each search leg, before ranking
Manual answers miss the safety steps around a valueFlat chunks, no parent returnHierarchical RAG; return whole procedure sections
Agent quotes a superseded SOPNo revision or validity metadataStamp revision and valid_from; filter current by default
Contradictory answers about one work orderRe-ingestion inserted without deletingDelete-before-insert keyed on site and WO number
Embedding bill spikes dailyStatus-only changes trigger re-embeddingRe-embed on text or code changes only; status is live
"Average" or "how many" answers are wrongAggregates computed from retrieved chunksApproved SQL or report tool for anything aggregate
Scanned attachments return garbageOne extractor for every file typeBranch extraction by type; keep low-quality OCR as metadata only
Knowledge graph project stallsGraph built for questions SQL already answersUse LOCHIERARCHY, asset parents and FAILURELIST first; graph only for named cross-entity questions
Agent loops on retriesSelf-reflection without a stop ruleOne refinement, then report "not found"

Key Takeaways

  • Split before you embed. Structured Maximo data (status, balances, costs, meters, hierarchies) is a query. Narrative text (long descriptions, worklogs, job plans, manuals, SOPs) is a retrieval. Most failed Maximo RAG projects blurred that line.
  • Identifiers need exact tools. Part numbers, asset tags, WO numbers and failure codes go to oslc.where, oslc.searchTerms or a keyword leg. Hybrid search with reciprocal rank fusion, then reranking, is the default for Maximo text.
  • Manuals are their own corpus. Type-aware extraction from doclinks, structure-aware chunks, hierarchical return of whole procedures, revision filters, and LLM context only where Maximo fields cannot supply it.
  • Maximo already has graphs. Use LOCHIERARCHY, asset parents and FAILURELIST through tools first; build a knowledge graph for cross-entity relationships that only exist in text.
  • Metadata is security and precision. Site and org filters injected in code, applied before ranking, and citations re-checked live as the user.
  • Edits are normal. Delete-before-insert keyed on record identity, worklogs re-ingest the parent, status never re-embeds.
  • Let the agent choose. Put each strategy behind a tool, give the agent a short decision policy, and spend self-reflection only where a wrong answer is dangerous.

References

🧰 From TheMaximoGuys toolbox: Max_Interfaces (open source, MIT) catalogues 2,439+ Maximo endpoints, useful when you are deciding which object structure backs each live-query tool in your router. Max_mcp (@themaximoguys/maximo-mcp on npm, 175 tools, proprietary) gives any MCP-capable agent the live, structured side of retrieval across Maximo versions, alongside IBM's native MAS 9.2 MCP server.

Series Navigation

The Agentic AI Playbook for Maximo

Previous:Part 2 — Prompts, Tools and Context for Maximo Agents
Next:Part 4 — MCP and Tool Design for Maximo: Fewer, Sharper Tools Beat a 175-Tool Buffet
Deep dive:agm-05 — Giving Maximo Agents a Memory (pgvector build, sync, agent memory)