Hi everyone!
I just posted the first video in this series about building AI assistance with memory and agency. In this video, we built a simple customer support assistant using Spring Boot, Spring AI, and Oracle Database. It answers policy questions, but the key idea is that those answers are grounded in data stored in Oracle rather than coming from the model itself.
In this post I want to walk through how the application is actually put together, focusing on the pieces that make that retrieval flow work.
The full project is here: https://github.com/markxnelson/shopassist
If you clone the repo and open it up, it looks like a normal Spring Boot application. The difference is how Oracle is used underneath, and how that gets wired into the chat flow.
A good place to start is with how the database is brought up locally.
In compose.yaml, the application relies on Spring Boot’s Docker Compose support to start Oracle automatically:
services: oracle: image: gvenzl/oracle-free:23.26.1-slim ports: - "1521" environment: ORACLE_PASSWORD: oracle APP_USER: shopassist APP_USER_PASSWORD: shopassist
There’s nothing unusual here, but it’s worth noting that this is just a standard Oracle instance. There’s no separate “vector database” running anywhere. The same database is going to store both relational data and vector embeddings.
Once that container is running, the next piece is how the application connects to it.
In application.yml, you can see both the datasource configuration and the vector store configuration side by side:
spring: datasource: url: jdbc:oracle:thin:@localhost:${oracle.port}/FREEPDB1 username: shopassist password: shopassist ai: vectorstore: oracle: initialize-schema: true index-type: NONE distance-type: COSINE
This is where Oracle AI Vector Search becomes visible in the application.
The initialize-schema flag tells Spring AI to create the underlying tables needed to store embeddings. Once that happens, the database is no longer just storing rows – it’s storing vectors that can be searched using similarity.
The distance-type: COSINE setting controls how similarity is calculated, which is what allows us to retrieve “related” documents even when the wording is different.
With that in place, the next question is how data actually gets into the vector store.
That happens in DataSeeder.java, and this is one of the more important pieces of the application because it defines what the system actually knows.
If you look at the seeder, you’ll see the policy documents being added like this:
vectorStore.add(List.of( new Document(""" POL-RETURN-01: Returns are accepted within 30 days of purchase with a valid receipt. Refunds are issued to the original payment method. """), new Document(""" POL-DAMAGE-01: Damaged items must be reported within 48 hours of delivery. Customers may request a replacement or refund. """), new Document(""" POL-SHIPPING-01: Shipping delays may occur due to weather or carrier issues. Customers will be notified of significant delays. """), new Document(""" POL-REFUND-01: Refunds are typically processed within 5-7 business days after approval. Processing times may vary by payment provider. """)));
Each of these documents is embedded and stored in Oracle. That’s what allows us to later take a user’s question, convert it into a vector, and find the most similar documents using Oracle AI Vector Search.
The same class also seeds some relational order data, which we expose through /api/v1/orders. That isn’t used by the chatbot yet, but it becomes important later when we start combining retrieval with structured queries.
Once the data is in place, the next piece is how a request flows through the system.
If you open AgentController.java, the endpoint itself is intentionally simple:
@RestController@RequestMapping("/api/v1/agent")public class AgentController { private final ChatClient chatClient; public AgentController(ChatClient chatClient) { this.chatClient = chatClient; } @PostMapping("/chat") public String chat(@RequestBody ChatRequest request) { return chatClient.prompt(request.message()).call().content(); }}
On its own, this just looks like a thin wrapper around an LLM call. There’s no obvious retrieval happening here.
That’s because the retrieval is introduced through how the ChatClient is configured:
QuestionAnswerAdvisor.builder(vectorStore) .searchRequest(SearchRequest.builder().topK(3).build()) .build();
When chatClient.prompt(...).call() is invoked, this advisor intercepts the request, runs a similarity search against Oracle, and retrieves the top three matching documents.
Those documents are then injected into the prompt that gets sent to the model.
So when a user asks something like “How long do refunds take?”, the system first retrieves the refund policy from Oracle and then asks the model to generate an answer based on that context.
One small addition that makes this much easier to see is the debug endpoint. Instead of going through the full chat flow, this endpoint lets you query the vector store directly and inspect what Oracle returns.
The controller for that looks like this:
@RestController@RequestMapping("/api/v1/debug/policies")public class PolicyDebugController { private final VectorStore vectorStore; public PolicyDebugController(VectorStore vectorStore) { this.vectorStore = vectorStore; } @GetMapping("/search") public List<Document> search(@RequestParam String q) { return vectorStore.similaritySearch( SearchRequest.builder() .query(q) .topK(3) .build() ); }}
There’s nothing complicated here, but it’s doing something important. Instead of calling the model, it calls vectorStore.similaritySearch(...) directly using the same search configuration.
So when you hit:
GET /api/v1/debug/policies/search?q=refund
you’re seeing exactly what Oracle returns for that query. The same embeddings, the same cosine similarity, the same top-K logic—just without the LLM step.
This makes it much easier to reason about the system. If the wrong documents show up here, the model never had a chance to produce the right answer. If the right documents show up here but the answer is still off, then you know to look at prompt construction instead.
At this point, the application is doing something useful, but it’s also very clearly limited because it is completely stateless.
If you try something like:
My name is Maya.
and then follow it with:
What’s my name?
the system won’t be able to answer. Each request is handled independently, and the only context available is the current message plus whatever documents were retrieved from Oracle.
There is no conversation history, and nothing is stored between requests.
This is the key distinction to understand at this stage. Oracle AI Vector Search gives us a way to retrieve relevant knowledge from stored data, but it does not give us memory. The system can answer policy questions because those policies are embedded and searchable, but it cannot remember something you just told it.
That limitation is intentional, because it sets up the next step. In the next episode we’ll introduce persistent chat memory, add conversation identifiers, and start maintaining context across requests.
For now, this version gives us a clean, grounded foundation: a Spring Boot service where Oracle stores embeddings, performs similarity search, and provides the context that the model uses to generate responses. Everything else we add will build on top of that.

Pingback: Add persistent chat memory to your Spring AI chatbot with Oracle (part 2 of 4) | RedStack