A spatial context engineering practice selects the place, time, route, and business facts a model may use before it answers. A prompt can ask for the nearest charger. The useful answer still needs the route, the clock, and only the facts the host chose to share. A spatial service calculates the geography, and the model explains that result.
What Is Spatial Context Engineering?
A 2025 survey of more than 1,400 research papers treats context engineering as a discipline that goes beyond prompt design to the systematic optimization of the information a language model receives (Mei et al., 2025). The survey splits that work into context retrieval and generation, context processing, and context management. Spatial context engineering applies the same discipline to place. The payload has to say where the subject is, when the facts were true, which route or area matters, and which business records the caller may use.
More context is not automatically better. Liu and colleagues found that language models often performed best when the relevant information sat at the beginning or end of the input, and that performance degraded significantly when the model had to use information in the middle of a long context (Liu et al., 2024). A spatial packet should therefore stay small: the eligible places, the calculated distances or containment results, the freshness of those results, and the actions the caller may take. A dump of every layer in the current map view fails that test.
Practitioner guides already use the term. Vercel's developer guide names four patterns: retrieval, memory, compression, and tool context (Vercel, 2026). A map product uses all four, and none of them replaces a spatial calculation. Retrieval can bring a policy passage, memory a prior preference, and compression can drop the rest of the catalog. Tool context can hold the result of a route or a containment check, and the model should explain that result rather than invent a substitute number.
How Does a Prompt Differ From Context?
A prompt asks the question. Context is the evidence assembled before the answer. "Find the nearest chargers for a delivery route" is an instruction, and an instruction alone can produce a generic list of chargers that ignores the vehicle, the clock, and the roads that are actually open. The figure contrasts that thin reply with a packet that names a place, a time, a route, business state, permissions, and map state.
The left side shows a short instruction and a generic reply about nearby chargers. The right side adds place, time, route, business state, permissions, and map state before a location-aware reply. The place id, the June 2024 timestamp, the 5.2 km badge, and the charger pins are sample labels. The packet on the right is a reference sketch, not a Kaleidr request format.
The thin reply is not wrong as grammar. The thin reply is unusable as an operation, because "nearby" has no origin, no maximum detour, and no rule for which chargers the fleet may use. The richer side of the figure still uses sample identifiers, so those values are not a live query. A production packet would carry the host's own ids and the spatial service's own numbers.
Why Is Retrieval Only One Source?
Retrieval pulls passages from documents, policies, descriptions, and help articles. Those passages can explain a rule. Those passages cannot tell a dispatcher whether a stop is inside a service area, because a polygon test is a calculation rather than a paragraph. Spatial context keeps the retrieved text and adds structured facts, an authorization result, the current map state, and the spatial result.
The left column retrieves documents, policy text, descriptions, and knowledge into passages. The right column adds structured business facts, authorization, map state, and spatial calculations to that text. The result in the figure is a decision packet for a location-aware reply. The drawn route and the pin are sample artwork, not a measured trip.
A team that stops at retrieved text will sound informed and still be wrong about the map. The policy passage might say that late deliveries need a staffed site. Only the hours feed, the containment check, and the caller's permission can say whether this site qualifies now. The figure's decision packet is where those pieces meet.
Why Must Current Evidence Beat Stale Memory?
Memory is useful for a preference that does not expire, such as a saved depot or a language. Memory is a poor source for traffic, closures, stock, or who may see a private site today. A remembered "best stop" from last week can contradict the route the spatial service just returned. When the two disagree, the current calculation and the current authorization should win, and the memory should stay labeled as a preference rather than as a fact.
The same rule applies to a summary written earlier in the session. A compressed recap can drop a closure or a revoked permission. The next turn should re-read the fields that change, or the caller should refuse to act on a summary that has no timestamp. Freshness belongs in the packet as data, not as a hope that the earlier answer is still true.
Why Does Place Identity Come Before a Search?
Two records can share a name and still be different places. A search for "the downtown store" is not an id. The packet should carry a stable place id from the host's own system, plus the coordinates or geometry the spatial service will use, and the display name should stay a label rather than the key. Without that id, a later turn cannot tell a renamed shop from a second shop, and a citation cannot point at the record that was actually eligible.
Which Geometry Should the Packet Carry?
The geometry has to match the question. A nearest-charger question needs points and a route. A service-area question needs a polygon and a containment result. A corridor question needs a line and a distance from that line. GeoJSON defines a geometry object, and a Point is one of the geometry types in that format, so a packet can name the type instead of hiding the shape in prose (IETF, 2016). Sending a point when the decision depends on a polygon makes the later explanation look precise while the test never ran.
Why Is the Viewport Not a Permission?
A place can sit inside the camera and still be forbidden. The figure puts three sample sites in one view: two public stores the caller may use, and a private facility that stays out of the context even though the pin is visible. Visibility is a clue about what the user is looking at. Authorization is a separate check on what the request may include.
The dashed box is the current map view, and three sample places sit inside it. Public Store A and Public Store B are marked authorized. Private Facility C stays out of the model context even though the pin is on screen. A viewport supplies location context, and a separate permission check decides what may be used.
The same split applies on a host map. Kaleidr's developer docs say that Chat adds its own markers, moves the camera, and draws routes, and that Chat does not change the page's layers, sources, or markers or send those objects to Kaleidr (Kaleidr, 2026). A pin on screen is not a grant. The host decides which facts cross the boundary, and the packet should record that decision rather than assume the camera already made it.
What Should a Spatial Service Calculate First?
Put the numbers in a spatial service, then ask the model to explain them. The figure shows a route deviation, an inside-service-area result, and a travel time feeding an explanation of why one store fits. A separate box rejects a guessed travel time. The model is a poor source for a distance, a containment test, or an arrival estimate, because those values come from the road network, the polygon, and the clock.
A spatial service reports a six-minute route deviation, a true inside-service-area check, and a fourteen-minute travel time. The explanation then says why the figure's Store 104 is the selected stop. The rejected box shows a language model inventing a travel time instead of using the service result. The minutes, the store numbers, and the quoted guess are sample labels on the artwork.
The explanation can still be useful. After the service returns the eligible stop, the model can say which calculated fact made that stop the fit, in the caller's language. The explanation should quote the service result rather than replace it. Store numbers and minute badges in the figure are labels, not a Kaleidr benchmark.
What Makes a Context Packet Small Enough?
A packet should be small enough to read and complete enough that the decision does not depend on a hidden table. The figure starts from raw systems, including a store database, inventory, hours, routing, and permissions, and ends in a short object: a task, a handful of candidates, eligibility, a route deviation, a freshness timestamp, and the actions that are allowed. Anything that did not affect eligibility can stay in the source system.
Raw records from a store database, inventory, hours, routing, and permissions enter a context builder. The builder emits a short packet with a task, a few candidate stores, eligibility flags, a route deviation, a timestamp, and allowed actions. The packet is meant to be small enough to inspect and complete enough for one decision. Store ids, distances, and the June 2024 timestamp are sample labels, and the JSON is a reference sketch rather than a Kaleidr API.
The long-context result is the reason to omit. Candidate retrieval can start wide and then shrink: ineligible places drop out before the model sees them, and the packet keeps the reason, such as a closed hour or a failed containment check. Kaleidr's public chat request is a narrower contract than this sketch, and the next section states what that request actually carries. Teams should not POST the figure's JSON as if the platform documented that object.
What Does a Reference Pipeline Contain?
A practical pipeline names the stage that owns each risk. Parse the task, identify the caller, check authorization, set the geographic scope, retrieve candidates, attach business state, run the spatial computation, apply eligibility, assemble the packet, send that packet to the model, perform the map action, revalidate the volatile fields, and record what happened. The figure adds four controls across the top: the source, the freshness rule, the policy, and a trace id.
The strip runs from task parse through identity, authorization, geographic scope, candidate retrieval, business state, spatial computation, eligibility, a context packet, the model, a map action, revalidation, and observation. Source, freshness, policy, and a trace id sit above that strip as controls on every stage. The diagram is a reference pipeline for a team designing its own context builder. The route drawn underneath is sample artwork.
The order is a design aid, not a Kaleidr product sequence. Some teams will merge candidate retrieval with the spatial computation. The stages that should stay visible are authorization, the calculation, eligibility, and a revalidation immediately before an action such as assigning a stop. Grounded spatial AI for business data is the related Kaleidr guide for authorization, retrieval, and ranking.
Where Does Kaleidr Draw the Context Boundary?
On a host map, the boundary is explicit. The supported-maps guide covers attaching Kaleidr Chat to Mapbox GL JS, MapLibre GL JS, Google Maps, and Leaflet, among other libraries, and a Google Maps key stays between the page and Google because Kaleidr does not receive that key (Kaleidr, 2026). Pins, a move to a place, and a route line are drawings the panel adds. Those drawings are not a copy of the host's private tables.
The host application keeps users, private data, inventory, policies, custom layers, and business actions. Only an explicit slice, such as an authorized location, the map zoom, the session, and approved facts, crosses the boundary in the figure. Kaleidr Chat, on the right, resolves places, plans routes, and takes map actions from that shared slice. The footer is a figure label, the store and vehicle names are samples, and attaching chat does not by itself send the host's layers or business systems.
The Platform API documents a matching limit on the chat request. The messages field is the conversation, the location object is the map center used to interpret "near here," map_zoom is the zoom level, and lang is the reply language. The same page says there is no field for system instructions, a persona, tools, or the caller's own context, and that unknown fields are accepted and ignored. app_snapshot and auto_actions are accepted and not needed, so the page says to leave them out (Kaleidr, 2026).
Uploaded business data is a separate path from that request. Uploading an organization's own business data for AI answers is Enterprise only, and key-backed answers that draw on that uploaded data are Enterprise only, which How Kaleidr works states. A companion page, how to build a map-aware AI assistant, covers the assistant a team builds around the same boundary.
How Can the Same Page Be Found and Cited?
A page about this practice should be easy to quote. The figure splits that job into ordinary search, answer engines, and generative citation. Search wants the canonical phrase, a cluster of related methods, and links to the supporting guides. Answer engines want a direct definition, a few specific questions, and a comparison such as retrieval versus a spatial packet.
The center of the figure is spatial context engineering, with search, answer engines, and generative citation as three surfaces around it. Search covers a canonical keyword, a topic cluster, and internal links. Answer engines want direct definitions, frequently asked questions, and comparisons. Generative citation wants an original framework, a described schema, a failure list, and cited sources, and none of those boxes is a ranking promise.
The boxes in that figure are a writing checklist, not a traffic guarantee. Kaleidr does not rank the page, and the figure does not report a measurement. What the page can do is state the definition in one place, show the packet as a reference sketch rather than as a wire format, and cite the standards and docs the claims depend on. A reader can then see which sentence is a definition and which sentence is a product limit.
What Should a Team Do Next?
Write the packet for one real task before changing the prompt. Include the place id, the time, the geometry type, the spatial result, and the permission that allowed each fact. Then compare that list with the chat request a host can send today: the conversation, the map center, the zoom, and the language, with no field for the host's private context. When the answers must draw on uploaded business data, start with Kaleidr Enterprise.
Note: Kaleidr uses AI-assisted tools for image creation, content refinement, and research throughout its creative and development workflows.
FAQs
Is spatial context engineering the same as prompt engineering?
No. Prompt engineering changes the wording of the instruction. Spatial context engineering changes the evidence the instruction can use, including the place, the time, the route or area, and the business facts the caller may see. A better sentence cannot supply a containment result the spatial service never computed.
Does attaching Kaleidr Chat read the host map's layers?
No. On a page where Chat runs in the host document, Chat adds its own markers, moves the camera, and draws routes. Chat does not change the page's layers, sources, or markers, and Chat does not send those objects to Kaleidr. Private tables stay on the host side of the boundary unless a separate Enterprise path covers uploaded business data.
Can the public chat request carry a custom context packet?
The documented request carries the conversation, a location for the map center, an optional zoom, and a language. There is no field for system instructions, a persona, tools, or the caller's own context. app_snapshot and auto_actions are accepted and not needed, so a team should not treat them as the packet sketched in this guide. Unknown fields are accepted and ignored.
Why keep travel time in a spatial service?
A travel time depends on the road network and the clock, and a guessed minute value can contradict the route the service just calculated. The rejected box in the calculation figure is that failure mode, with a sample quote rather than a live result. Keep the number in the spatial service and let the model explain it.
References
- Mei, L., et al. A Survey of Context Engineering for Large Language Models. A review of more than 1,400 papers that treats context engineering as more than prompt design and splits it into retrieval and generation, processing, and management. arXiv:2507.13334. 2025. https://arxiv.org/abs/2507.13334
- Liu, N. F., et al. Lost in the Middle: How Language Models Use Long Contexts. Transactions of the Association for Computational Linguistics, 12, 157–173. Performance is often highest when relevant information is at the start or end of the input and degrades significantly in the middle of long contexts. 2024. https://doi.org/10.1162/tacl_a_00638
- Vercel. What is context engineering? A developer's guide. A practitioner guide naming four patterns: retrieval, memory, compression, and tool context. Accessed October 22, 2026. https://vercel.com/i/context-engineering
- IETF. RFC 7946: The GeoJSON Format. GeoJSON defines a geometry object, and a Point is one of the geometry types. 2016. https://www.rfc-editor.org/info/rfc7946
- Kaleidr Developer Docs. How Kaleidr works. Chat adds its own markers, moves the camera, and draws routes, and does not change the page's layers, sources, or markers or send them to Kaleidr. Uploaded business data for AI answers, and key-backed answers that draw on that data, are Enterprise only. Accessed October 22, 2026. https://docs.kaleidr.com/concepts/how-kaleidr-works
- Kaleidr. Grounded Spatial AI for Business Data. A related guide covering authorization, retrieval, ranking, evaluation, and a narrow pilot. Accessed October 22, 2026. https://kaleidr.com/blog/grounded-spatial-ai-business-data
- Kaleidr Developer Docs. Supported maps. Attach targets include Mapbox GL JS, MapLibre GL JS, Google Maps, and Leaflet. A Google Maps key stays between the page and Google; Kaleidr does not receive it. Accessed October 22, 2026. https://docs.kaleidr.com/chat/supported-maps
- Kaleidr Developer Docs. Platform API endpoints. The chat request carries the conversation, a map-center location, optional zoom, and a language. There is no field for system instructions, a persona, tools, or the caller's own context.
app_snapshotandauto_actionsare accepted and not needed. Accessed October 22, 2026. https://docs.kaleidr.com/platform-api/endpoints - Kaleidr. Map-Aware AI Assistant: How to Build One. A companion guide for building the assistant around a map. Accessed October 22, 2026. https://kaleidr.com/blog/how-to-build-a-map-aware-ai-assistant
- Kaleidr. Kaleidr Enterprise. The enterprise page for spatial AI integrated with a customer's own data. Accessed October 22, 2026. https://kaleidr.com/enterprise
References in BibTeX
@misc{mei_context_engineering_survey_2025,
title = {A Survey of Context Engineering for Large Language Models},
author = {Mei, Lingrui and others},
year = {2025},
eprint = {2507.13334},
archivePrefix = {arXiv},
url = {https://arxiv.org/abs/2507.13334}
}
@article{liu_lost_in_the_middle_2024,
title = {Lost in the Middle: How Language Models Use Long Contexts},
author = {Liu, Nelson F. and Lin, Kevin and Hewitt, John and Paranjape, Ashwin and Bevilacqua, Michele and Petroni, Fabio and Liang, Percy},
journal = {Transactions of the Association for Computational Linguistics},
volume = {12},
pages = {157--173},
year = {2024},
doi = {10.1162/tacl_a_00638}
}
@misc{vercel_context_engineering_2026,
title = {What is context engineering? A developer's guide},
author = {{Vercel}},
year = {2026},
url = {https://vercel.com/i/context-engineering}
}
@misc{ietf_rfc7946_2016,
title = {RFC 7946: The GeoJSON Format},
author = {{IETF}},
year = {2016},
url = {https://www.rfc-editor.org/info/rfc7946}
}
@misc{kaleidr_how_it_works_2026,
title = {How Kaleidr works},
author = {{Kaleidr Developer Docs}},
year = {2026},
url = {https://docs.kaleidr.com/concepts/how-kaleidr-works}
}
@misc{kaleidr_grounded_spatial_ai_2026,
title = {Grounded Spatial AI for Business Data},
author = {{Kaleidr}},
year = {2026},
url = {https://kaleidr.com/blog/grounded-spatial-ai-business-data}
}
@misc{kaleidr_supported_maps_2026,
title = {Supported maps},
author = {{Kaleidr Developer Docs}},
year = {2026},
url = {https://docs.kaleidr.com/chat/supported-maps}
}
@misc{kaleidr_platform_api_endpoints_2026,
title = {Platform API endpoints},
author = {{Kaleidr Developer Docs}},
year = {2026},
url = {https://docs.kaleidr.com/platform-api/endpoints}
}
@misc{kaleidr_map_aware_assistant_2026,
title = {Map-Aware AI Assistant: How to Build One},
author = {{Kaleidr}},
year = {2026},
url = {https://kaleidr.com/blog/how-to-build-a-map-aware-ai-assistant}
}
@misc{kaleidr_enterprise_2026,
title = {Kaleidr Enterprise},
author = {{Kaleidr}},
year = {2026},
url = {https://kaleidr.com/enterprise}
}