I Removed an API Field. Hindsight Found Who Still Needed It.

Rahul Reddy Maram — Mon, 28 Sep 2026 14:09:39 +0000

API compatibility problems are rarely difficult because removing a field is technically hard. The difficult part is knowing who still depends on that field.
I started with a simple question: if I remove phone from a Customer API response, how can an agent tell me whether some downstream consumer still needs it?
That question led me to build an API Compatibility Agent around Spring Boot, Flask, Hindsight, and Groq. The interesting part was not teaching the system that removing a field can be breaking. That is easy. The interesting part was giving it memory so it could connect a proposed change to a dependency recorded earlier.

The result is a system with a clear separation of responsibilities: Java manages the application and compatibility rules, Python runs the memory-backed analysis, Hindsight stores relationships and previous analyses, and the language model turns retrieved evidence into an explanation.

The Problem: An API Change Is Smaller Than Its Impact

Consider a Customer API:

GET /api/customers/{id}

with a response such as:

{ "id": 1042, "name": "Rahul", "email": "rahul@example.com", "phone": "+91..." }
Now imagine I decide that phone is no longer needed.

The code change might be tiny:

Remove phone from the Customer API response

But the real question is:

Who is still reading phone?

A web client might display it. A billing service might use it. A notification workflow might depend on it. A client released months ago might still expect it.

A basic compatibility rule can tell me that removing a field may break consumers. It cannot, by itself, tell me which known consumer is connected to that field.

So I separated the problem into two layers:

Deterministic compatibility: What kind of API change is this?

Remembered context: What consumers have previously been associated with the changed field?

The first belongs in application logic.

The second is where persistent memory becomes useful.

The Architecture I Built

The project has two application layers.

The Java side is a Spring Boot application backed by MySQL. It models API endpoints and API changes and exposes REST endpoints for compatibility operations.

The Python side is a separate Flask service. It exposes /analyze for compatibility analysis and /remember for recording an API-consumer dependency.

The high-level flow is:

                Developer
                   |
                   v
          +------------------+
          |   Spring Boot    |
          | Application/API  |
          +--------+---------+
                   |
                   | /analyze
                   v
          +------------------+
          |  Python / Flask  |
          |   Agent Layer    |
          +--------+---------+
                   |
         +---------+---------+
         |                   |
         v                   v
  +-------------+      +-----------+
  |  Hindsight  |      |   Groq    |
  |   Memory    |      | Explanation|
  +-------------+      +-----------+

I intentionally kept these boundaries visible.

Spring Boot is not trying to become the memory system. Hindsight is not deciding compatibility by itself. The language model is not treated as the source of truth for consumer dependencies.

Each component has a narrower responsibility.

Remembering the Dependency

Suppose I know that the Billing Service depends on phone:

API: Customer API
Consumer: Billing Service
Dependency: Billing Service depends on the phone field.

The Python service exposes a /remember endpoint for this. The core implementation is straightforward:

def remember_dependency(api_name, consumer, field):
client = create_hindsight_client()

try:
    client.retain(
        bank_id=BANK_ID,
        content=(
            f"API: {api_name}. "
            f"Consumer: {consumer}. "
            f"Dependency: {consumer} depends on the {field} field."
        ),
        context="api-consumer-dependency"
    )
finally:
    client.close()

I like this representation because it is deliberately concrete: an API, a consumer, a field, and a dependency between them.

This is where Hindsight GitHub becomes important. Instead of passing every dependency into every analysis request, the relationship can persist in memory and become available when a related API change appears later.

That is the difference between giving an agent context for one request and giving it context that survives across requests.

What Happens When I Remove a Field?

The analysis endpoint accepts a natural-language change:

Remove phone from the Customer API response

The agent first extracts the field name:

match = re.search(
r"remove\s+([A-Za-z0-9_]+)",
change,
re.IGNORECASE
)

if not match:
return (
"UNKNOWN",
"Could not identify the API field being removed."
)

field = match.group(1)

For this example, the extracted field is phone.

The agent then asks Hindsight for consumers associated with that field:

result = hindsight_client.recall(
bank_id=BANK_ID,
query=(
f"Which API consumers depend on the {field} field? "
f"Return only direct consumer dependencies."
)
)

This is the point where the project moves beyond a static rule.

The system is no longer asking an LLM to guess whether an API change might be dangerous.

It first asks the memory layer:

What do I already know about this field?

I Did Not Want the LLM Inventing Consumers

This became one of the most important design decisions.

A language model can produce a convincing answer even when the underlying dependency does not exist. I did not want the model deciding which consumers existed.

After Hindsight returns memories, the agent filters them for the requested field and dependency relationship:

matching_memories = []

for memory in result.results:
text = memory.text

if (
    field.lower() in text.lower()
    and "depends on" in text.lower()
):
    matching_memories.append(text)

Those memories become evidence for the Groq request.

The prompt explicitly tells the model:

Do not invent consumers or dependencies that are not present
in the Hindsight memories.

That gives the system a useful separation:

Component

Responsibility

Spring Boot

Application API, persistence, and compatibility operations

Python agent

Parses the proposed change and coordinates analysis

Hindsight

Stores and retrieves dependency evidence

Compatibility logic

Applies deterministic compatibility rules

Groq

Explains the result using retrieved evidence

I find this easier to reason about than an architecture where the model discovers, judges, and explains everything.

The Same Change Can Produce Different Results

Suppose Hindsight contains:

API: Customer API
Consumer: Billing Service
Dependency: Billing Service depends on the phone field.

I submit:

Remove phone from Customer API

The agent extracts phone, retrieves the dependency, finds a matching consumer, and classifies the change as:

POTENTIALLY_BREAKING

The remembered dependency is then included in the prompt sent to Groq, allowing the explanation to connect the proposed change to a known consumer.

If Hindsight has no matching dependency, the agent returns:

NO_KNOWN_IMPACT

I deliberately chose those words.

I did not want the system to say SAFE, because "I don't know of a dependency" is not the same as "no dependency exists."

Persistent memory can tell me what the system has recorded. It cannot prove that an unrecorded consumer does not exist.

Keeping Deterministic Rules in Java

The memory-backed agent is not the only compatibility mechanism.

The Java CompatibilityService handles basic change categories directly:

if ("FIELD_ADDED".equalsIgnoreCase(changeType)) {
return new CompatibilityResult(
"COMPATIBLE",
"Adding a new field is generally backward compatible."
);
}

if ("FIELD_REMOVED".equalsIgnoreCase(changeType)) {
return new CompatibilityResult(
"POTENTIALLY_BREAKING",
"Removing a field may break existing API consumers."
);
}

I do not need an LLM to tell me that removing an existing response field may affect clients.

The interesting question is what comes next:

Do I have remembered evidence about a consumer that actually depends on this field?

The two layers therefore complement each other:

   ** Static Compatibility Rule
              |
              v
      POTENTIALLY BREAKING
              |
              v
        Hindsight Lookup
           /       \
          /         \
         v           v
Known Consumer    No Known Consumer
      |                  |
      v                  v

Explain Impact NO_KNOWN_IMPACT**

Spring Boot and Python Have a Clean Boundary

The Java application communicates with the Python service through RestClient:

public String analyzeChange(String change) {

Map<String, String> request = Map.of(
        "change", change
);

return restClient.post()
        .uri("/analyze")
        .body(request)
        .retrieve()
        .body(String.class);

}

This keeps the application boundary simple.

Spring Boot does not need to embed the Hindsight client, while the Python agent can evolve its memory and model workflow independently.

The flow is easy to trace:

Spring Boot
|
| HTTP
v
Flask Agent
|
+---- Hindsight
|
+---- Groq

For a system with several external dependencies, explicit boundaries make debugging easier.

Hindsight Stores More Than the Dependency

The most interesting part of the design is what happens after the first analysis.

The agent also stores the compatibility result in Hindsight:

hindsight_client.retain(
bank_id=BANK_ID,
content=(
f"API compatibility analysis: "
f"Proposed change: {change}. "
f"Field: {field}. "
f"Result: {status}. "
f"AI analysis: {ai_reason}"
),
context="api-compatibility-analysis"
)

So the memory layer can contain both:

api-consumer-dependency
└── Billing Service depends on phone

api-compatibility-analysis
└── Removing phone was potentially breaking

That changes how I think about the agent.

A conventional utility processes a request and returns an answer.

A memory-backed agent can accumulate context that remains useful for later requests.

The Hindsight documentation describes the underlying memory capabilities. In this project, I use those capabilities specifically for API-consumer relationships and compatibility analysis.

What I Learned

1. API compatibility is partly a knowledge problem

The syntax of an API change is easy to inspect.

The difficult part is understanding the ecosystem around that API.

Removing a field may require only a small code change, but its impact depends on the consumers behind the contract.

2. Persistent memory fits slowly changing relationships

Consumer dependencies are a natural fit for persistent memory. They do not need to be rediscovered every time someone proposes a change.

Record the relationship once and retrieve it when the related field appears in a future analysis.
**

Evidence and explanation should be separate**

I deliberately let Hindsight provide remembered evidence and let the language model explain that evidence.

That makes the system easier to inspect and reduces the temptation to treat a generated explanation as authoritative dependency data.
**

"No known impact" is not "safe"**

If no matching memory is found, the agent knows only that it has no recorded dependency matching the query.

That should not become an absolute safety guarantee.

5. Not everything needs an LLM

The Java compatibility service can handle straightforward compatibility categories deterministically.

The model becomes useful when there is contextual information to explain.

That keeps the system more predictable and makes the role of the LLM clearer.

Where I Would Take It Next

The current implementation gives me a foundation for a more complete compatibility platform.

The biggest improvement would be reducing manual dependency recording. Today, /remember explicitly accepts:

api_name
consumer
field

A production version could populate this memory automatically from API specifications, service repositories, client code, gateway information, or deployment metadata.

I would also make change detection more robust. The current implementation focuses on phrases such as Remove phone; a broader engine should understand:

field removals

field renames

field type changes

endpoint removals

response-shape changes

authentication changes

required-field changes

Another useful extension would be API-version awareness. Removing a field from an existing /v1 contract has a different operational meaning from making the same change while introducing /v2.

The principle would remain the same:

Identify what changed, retrieve what is known about its consumers, and explain the impact using evidence rather than speculation.

Final Thought

The part of this project that stayed with me was how small an API change can look in a diff.

Remove one field.

Delete one property.

Clean up one response.

The code change can take minutes. Understanding who depends on that field can take much longer.

That is the gap I wanted to address with memory.

I did not build the agent simply to tell me that API changes can be dangerous.

I built it to answer a more useful question:

*Who do I already know depends on this change, and what evidence do I have?
*
With Hindsight behind that question, the agent can carry knowledge from one analysis into the next instead of starting from zero every time.

And that is the part of API compatibility I found most interesting: the difficult problem is not detecting that a contract changed. It is remembering who was relying on it when it did.

DEV Community: Rahul Reddy Maram

I Removed an API Field. Hindsight Found Who Still Needed It.