RecallIQ — Part 2 of 5
A technical deep dive into the architecture, API design, persistent memory layer, and rule-based decision analysis behind RecallIQ.
A Decision-Memory App in Three Layers
RecallIQ helps teams keep the reasoning behind their decisions so that past experience can inform future choices.
This article looks under the hood:
- How the application is structured
- How it uses Hindsight Cloud for persistent memory
- How recalled memories are combined with preliminary risk checks
- What is working today
- What is not yet implemented or verified
The goal is to keep the architecture simple, understandable, and honest about the current prototype's capabilities.
The Technology Stack
RecallIQ is built using a lightweight stack designed for rapid development and clear separation of responsibilities.
| Layer | Technology |
|---|---|
| Frontend | React, TypeScript and Vite |
| Backend | Python with FastAPI |
| Data Validation | Pydantic |
| Memory Service | Hindsight Cloud |
| Development & Testing | Cursor, Browser, PowerShell and FastAPI Swagger UI |
Why FastAPI?
FastAPI was a natural fit for the backend because it automatically generates interactive API documentation through Swagger UI.
This allowed us to test individual endpoints directly from the browser before the dashboard was connected.
For example, we could create a decision through the API, inspect the response, and verify the behavior independently of the frontend.
Why Pydantic?
Pydantic provides validated request and response models.
This means that malformed requests can be rejected early with clear validation errors.
For example, a decision without a required title or with incorrectly structured fields can be caught before the request reaches the application logic.
System Architecture
The flow of RecallIQ is deliberately simple.
┌──────────────────────────────┐
│ User │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ React + TypeScript Dashboard │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ FastAPI Backend │
└───────┬──────────────┬───────┘
│ │
▼ ▼
┌──────────────┐ ┌────────────────┐
│ Decision │ │ Hindsight Cloud│
│ Records │ │ Memory Service │
└──────────────┘ └───────┬────────┘
│
▼
Relevant Memories
│
▼
Rule-Based Analysis
│
▼
Risks + Recommendations
A user works through the React and TypeScript dashboard.
The dashboard communicates with the FastAPI backend.
The backend manages decision records and communicates with Hindsight Cloud.
This separation is intentional.
The frontend never communicates directly with the memory service.
Creating a Decision
When a user creates a decision, the backend performs two important operations.
1. Record the decision
The backend receives the decision information and records it.
A decision contains:
- Title
- Description
- Assumptions
- Expected outcome
- Status
The status can be:
pendingsuccessfulfailedwarning
2. Retain the decision in Hindsight
The backend then attempts to retain the decision-related information in Hindsight.
This allows important context to survive beyond a single application session.
The flow can be summarized as:
User creates decision
↓
FastAPI receives request
↓
Validate with Pydantic
↓
Record decision
↓
Send relevant information to Hindsight
↓
Memory retained
The use of the word "attempts" is deliberate.
Because Hindsight is an external service, a network request can fail. The application should therefore handle external-service failures rather than assuming that every retention request succeeds.
Recalling Memories
The second major operation is memory recall.
Later, when a user is dealing with a new situation, the backend can send a query describing that situation to Hindsight.
Hindsight returns memories that are relevant to the query.
The flow looks like:
New decision or situation
↓
FastAPI creates recall query
↓
Hindsight Cloud
↓
Relevant memories
↓
FastAPI returns results
↓
User receives historical context
The important point is that recall is not simply a keyword lookup.
The memory service attempts to find information that is relevant to the situation being described.
This means that the quality of recalled memories depends on both:
- What information was previously retained
- How the new situation is described
The API Surface
RecallIQ currently exposes several backend endpoints.
POST /api/decisions
Creates a new decision.
A successful creation returns HTTP 201.
GET /api/decisions
Retrieves the recorded decisions.
POST /api/memories/recall
Retrieves relevant memories from Hindsight.
POST /api/decisions/analyze
Retrieves related memories and applies the predefined risk rules to produce potential risks and recommendations.
POST /api/memories/retain
Requests memory retention directly.
The API-first approach made it possible to test the backend independently before connecting everything to the dashboard.
Why Decision Status Matters
A decision is not simply a piece of historical information.
Its outcome matters.
For example:
Decision A
Status: Successful
is a very different signal from:
Decision B
Status: Failed
And:
Decision C
Status: Warning
may indicate that the approach worked but introduced problems worth remembering.
This is why RecallIQ stores decision status alongside the decision context.
When a relevant memory is recalled, the person reviewing it can understand not only what was tried, but also how it turned out.
How Hindsight Is Used
Hindsight is the persistent-memory component of RecallIQ.
It plays two primary roles.
Retention
When a decision is created, the backend sends relevant information to Hindsight for retention.
This can include:
- The decision
- Reasoning
- Assumptions
- Expected outcome
- Other relevant context
This is what allows the information to outlive a single session.
Recall
Later, the backend submits a query describing a new situation.
Hindsight returns memories that are relevant to that situation.
Those memories provide historical context:
What was tried before?
What was assumed?
What happened?
Was the previous decision successful or problematic?
It is important to be precise about the division of responsibility.
Hindsight supplies the memories.
Our backend performs the analysis.
Hindsight does not generate the final risk analysis used by RecallIQ.
From Recalled Memories to Risks and Recommendations
The analysis endpoint combines two inputs:
- Memories recalled from Hindsight
- Predefined risk rules
The rules look for known patterns in the new decision's text.
When a pattern is matched, the system produces a potential risk and a corresponding recommendation.
A Worked Example
Consider the decision:
Migrate to a cheaper cloud provider
The description is:
Reduce cloud spending by moving to a cheaper provider.
The assumptions are:
- Costs will decrease by at least 20%.
- Transfer fees will be minimal.
- Performance will remain stable.
The expected outcome is:
A 20% reduction in monthly cloud costs without reducing performance.
The rules identify three potential risks.
Risk 1 — Data Transfer and Migration Costs
Data-transfer charges and one-time migration costs may reduce the expected savings.
Recommendation: Calculate the total cost of ownership rather than comparing provider prices alone.
Risk 2 — Performance or Reliability
Moving workloads could affect latency, performance, or reliability.
Recommendation: Benchmark the workload before and after migration.
Risk 3 — Incomplete Savings Estimates
The estimated savings may not include recurring or one-time costs.
Recommendation: Validate the assumptions and include all relevant costs before committing.
If Hindsight also recalls a previous decision involving similar assumptions, that memory appears alongside the rule output.
This makes the warning more specific to the team's own history.
Why Start With Rules?
The rule-based design is limited, but it has several useful characteristics for an early prototype.
Transparency
Anyone can read the rule and understand why a risk was raised.
There is no hidden reasoning to audit.
Predictability
The same input produces the same output.
This makes the system easier to test and demonstrate.
No Fabricated Content
A rule cannot invent a risk that nobody defined.
The purpose is to prompt careful thinking rather than produce an authoritative-sounding answer.
Lower Complexity
The system does not require additional model calls for the current analysis layer.
This keeps the prototype simpler and easier to debug.
Current Status
The current state of the prototype is deliberately described conservatively.
Working
- React and TypeScript dashboard
- FastAPI backend
- Decision creation
- Hindsight memory retention/recall workflow
- Decision retrieval
Decision creation and Hindsight memory recall have been tested successfully.
Still Being Verified
The analysis endpoint has been added to the backend, but its availability and integration with the dashboard still need verification.
Therefore, we do not claim that users can currently run the complete analysis workflow directly from the dashboard.
This distinction is important.
A feature existing in backend code is not the same as a feature being fully verified and available through the user interface.
Known Limitations
In-Memory Storage
The current decision list is held in a Python list inside the running backend.
This means it may reset when the backend restarts.
It should not be treated as a production database.
Rule-Based Analysis
The analysis is not generated by an LLM.
The rules cover selected patterns only and should not be considered a comprehensive risk assessment.
Human Review
The results are preliminary.
A person should review the output before acting on any recommendation.
Security Practice
The Hindsight API key is stored in a backend environment file and loaded through environment variables.
The basic security practices are:
- Never commit the
.envfile. - Never place API keys directly in source code.
- Never include credentials in screenshots or documentation.
- Keep the memory service behind the backend.
The final point is particularly important.
Because the frontend communicates only with our backend, the Hindsight credentials do not need to reach the browser.
These practices may seem small, but they are important when moving from a demo toward a deployable system.
What Comes Next?
The current prototype provides the foundation for several future improvements.
1. Persistent Database
Add a database such as PostgreSQL so that decisions survive backend restarts.
2. LLM-Generated Analysis
Integrate an LLM that can analyze a new decision together with the relevant memories.
3. Outcome Tracking
Track what actually happened after a decision and compare it with the expected outcome.
4. Better Memory Relevance
Improve memory filtering, relevance, and citations.
5. Authentication and Team Workspaces
Allow different teams to maintain separate decision histories with appropriate access control.
6. Feedback and Evaluation
Allow users to indicate whether a risk or recommendation was useful.
This would provide data for evaluating whether RecallIQ is actually helping teams make more informed decisions.
Conclusion
RecallIQ demonstrates a simple architectural idea:
Persistent memory should be separated from reasoning.
Hindsight provides the memory.
FastAPI manages the application logic.
Predefined rules provide transparent preliminary analysis.
React and TypeScript provide the user interface.
This separation makes the prototype easier to understand, test, and improve.
The larger goal is to move beyond simply storing decisions.
The goal is to build a system that can remember what a team tried, understand what happened, and eventually help the team learn from that history.
Explore RecallIQ
🔗 GitHub Repository: https://github.com/ravikanthbojja44-create/Recall-IQ
RecallIQ is currently a prototype and does not have a public live demo deployed yet.
RecallIQ Series
Part 1 — The Problem of Forgotten Decisions: Why AI Systems Need Persistent Memory
Part 2 — Inside RecallIQ ← You are here
Part 3 — Memory Plus Rules: Designing Trustworthy Decision Analysis Without an LLM
Part 4 — Building RecallIQ: Development Workflow, Testing and What We Learned
Part 5 — From Decision Memory to Decision Learning: The Future of RecallIQ
This article is Part 2 of the RecallIQ technical series exploring persistent memory, trustworthy decision support, and the evolution from decision memory to decision learning.
Top comments (0)