I Added Hindsight to Give TeamForge Persistent Project Memory

Aashritha Sriramoju — Mon, 28 Sep 2026 16:36:12 +0000

The hardest part of building an engineering assistant was not getting a model to answer a question. It was making the assistant remember what the project had already decided — and know the difference between an old decision and current truth.

That became the design problem behind TeamForge’s Project Brain. I already had structured project state for requirements, architecture, tasks, dependencies, risks, team members, and tools. What I was missing was the history around that state: the decisions, rejected alternatives, implementation discoveries, and handoff context that explain how the project got here.

The problem: the system knew what, but not why

TeamForge is designed to take a software project from idea to an executable engineering plan. It evaluates problem statements, checks feasibility, chooses an SDLC approach, recommends an architecture, breaks the work into dependent tasks, assigns work against team skills, recommends tools, and flags risks.

That created a deceptively simple question for the mentor:

Why did we choose this architecture?

The database can answer:

We chose a modular monolith.

It cannot naturally answer:

We considered microservices, rejected them because the operational overhead was not justified for the current scope, and kept logical module boundaries so we could extract services later if the constraints change.

That distinction matters.

Chat history was not a good substitute. It is tied to a conversation, contains a lot of noise, and is a poor place to establish durable project knowledge. I wanted memory that belonged to the project itself and could be retrieved when a future engineering question made it relevant.

I used Hindsight for persistent AI agent memory as that layer.

TeamForge is a planner first, and memory has to fit around it

I did not want to turn TeamForge into a giant prompt containing the entire project.

The application already has authoritative state. Users, teams, assignments, task statuses, architecture records, and risk records belong in PostgreSQL. If I need to know who owns a task, I want a database query to answer it. I do not want a semantic-memory lookup pretending to be a database.

The architecture therefore has two distinct sources of context:

Current project state
│
▼
PostgreSQL
│
├── requirements
├── architecture
├── tasks
├── assignments
└── risks

Project history
│
▼
Hindsight
│
├── decisions
├── rejected alternatives
├── discoveries
├── conventions
└── handoff context

The Project Brain sits above both. It retrieves the current state from the application and relevant history from Hindsight, then gives the reasoning layer only the context needed for the question.

I made memory project-scoped

The first design decision I made around Hindsight was the memory boundary.

Every project gets its own memory bank. A project identifier is part of that boundary:

from hindsight_client import Hindsight

memory = Hindsight(base_url=HINDSIGHT_URL)

memory.retain(
bank_id=f"project:{project.id}",
content=decision_or_discussion,
context="project engineering discussion",
tags=[f"project:{project.id}"],
)

The important part is not the syntax. It is the isolation model. Two projects can make opposite decisions about the same framework or deployment strategy and neither project should inherit the other project's reasoning.

Project scope also gives the Project Brain a stable identity. In the UI, each project is treated as its own working environment, and that maps naturally to the memory boundary. The Hindsight documentation describes persistent memory as something agents can retain and later recall; TeamForge uses the project as the boundary that gives those memories meaning.

The database tells me what is true now; Hindsight tells me what happened

That became the rule I kept returning to:

Current state is authoritative. Memory is contextual.

For example, suppose an API contract changes. Hindsight may still contain the old contract because that was once a valid decision. I do not want the Project Brain to repeat that historical contract as if it were current.

The retrieval path is therefore explicit:

memories = memory.recall(
bank_id=f"project:{project.id}",
query=user_question,
)

memory_context = "
".join(
result.text for result in memories.results
)

A developer's question starts by identifying the active project. TeamForge loads the current project state from PostgreSQL, recalls relevant memories from the project's Hindsight bank, combines those sources, and only then asks the reasoning layer to answer.

The Vectorize agent memory overview describes the broader idea well: an agent needs a durable way to retain and retrieve experience instead of treating every interaction as an isolated request.

Retrieval is useful because engineering history is rarely phrased the same way twice

One reason I like Hindsight for this use case is that project history is messy.

The original decision might say:

“Keep deployment simple for the first release.”

Six weeks later someone might ask:

“Why aren't these modules separate services?”

Those two sentences do not share much vocabulary, but they describe the same engineering history.

Hindsight's retrieval approach combines semantic and lexical signals with relationship and temporal context. That is useful for engineering memory because the question a developer asks later is often a paraphrase of the discussion that created the decision in the first place.

The Project Brain then follows a deliberately boring pipeline:

Developer question
│
├── Query current PostgreSQL state
│
└── Recall relevant Hindsight memories
│
▼
Build grounded context
│
▼
Project Brain
│
▼
Traceable answer

That separation is more important to me than the model choice. If the context assembly is wrong, a better model does not fix the underlying architecture.

Memory becomes more valuable at team handoffs

The next place I saw a concrete benefit was between agents and teammates.

Imagine an Architect agent has already settled on a PostgreSQL schema and an API boundary. A Backend agent should not have to rediscover those decisions. It should be able to recall the architectural context, generate the backend implementation against it, and produce an API contract that the Frontend agent can consume.

The workflow becomes:

Architect
│
├── schema decision
├── component boundary
└── API constraints
│
▼
Hindsight
│
▼
Backend agent
│
└── REST routes + Pydantic models
│
▼
OpenAPI contract
│
▼
Frontend agent

This is where persistent memory stops being a “chatbot feature.” It becomes an integration mechanism between pieces of engineering work.

The Project Brain should explain the project, not invent it

I wanted the mentor to answer technical questions without becoming a second source of truth.

For example, a frontend developer might ask how a UI action should call a backend task endpoint. The answer should come from the project's actual API conventions and authentication model, not from a generic tutorial.

A representative call looks like this:

const response = await fetch(
${API_BASE}/api/v1/projects/${projectId}/tasks,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": Bearer ${userToken}
},
body: JSON.stringify(payload)
}
);

The important detail is not that an LLM can write fetch(). Any competent coding model can do that. The useful part is that the Project Brain can ground the answer in the project's current API contract, task state, and historical context.

I kept the memory layer separate from the workflow engine

TeamForge also has an execution side. Agents work through staged engineering tasks, and the workflow layer is responsible for deciding what can run and in what order.

I did not want Hindsight to become a scheduler or a task database.

The responsibilities stay separate:

Workflow layer
→ What should execute next?

PostgreSQL
→ What is the current project state?

Hindsight
→ What useful project history should the reasoning layer remember?

LLM
→ How should the available context be interpreted and explained?

That separation means I can change the model provider without redesigning memory, and I can change the workflow engine without moving task state into an embedding store.

The same memory model works across the engineering pipeline

The broader TeamForge flow is intentionally connected:

Problem Statement
↓
Feasibility
↓
SDLC
↓
Architecture
↓
Data Architecture
↓
Tasks + Dependencies
↓
Team Assignment
↓
Tools
↓
Risks
↓
Project Brain
↓
Execution

Each stage creates information that another stage may need later. The engineering pipeline is where this matters most: an architectural decision becomes a task boundary, the task becomes an API contract, the contract becomes an implementation dependency, and the resulting change can become useful history for the next decision.

The interactive build plan turns those decisions into staged work instead of leaving them as a static architecture document.

The painful lesson: memory needs curation

The easiest mistake is to assume that more memory is automatically better.

It is not.

If I retain every generated sentence, every temporary debugging thought, and every low-value interaction, retrieval becomes noisy. The useful memories are the ones with future engineering value:

architecture decisions and rejected alternatives

important constraints

project conventions

discoveries that changed the implementation

handoff context

changes that explain why the current system differs from an earlier design

I still consider deciding what deserves to become durable memory an engineering problem. Hindsight gives me the memory machinery, but TeamForge still needs project-specific retention rules.

What I learned

Do not make the LLM your source of truth

If the database knows the answer, query it. Memory should add context, not compete with authoritative state.

Scope memory to a meaningful boundary

Using the project as the memory boundary keeps retrieval tied to the thing the developer is actually working on.

Store the why

Current state tells me what exists. Historical memory explains why it exists.

Treat memory as infrastructure

Once memory influences multiple engineering steps, it deserves its own interface, isolation rules, retention policy, and failure model.

Design for handoffs

The biggest payoff is not a better answer to a single user question. It is preserving enough project context that another developer or agent can continue from an earlier decision without starting over.

Where this leaves TeamForge

I started with a simple goal: build an assistant that could help a software team plan and execute a project.

The harder problem turned out to be continuity.

Real software has history. Requirements change. APIs get revised. Architecture decisions have trade-offs. Tasks move between people. A useful engineering assistant cannot behave as if the project was created five minutes ago.

Hindsight gives TeamForge an explicit place to retain and retrieve that history. PostgreSQL remains the source of truth for current state. The Project Brain reasons across both.

That is the architecture I wanted: not an assistant that remembers everything, but one that can remember the project without pretending memory is the same thing as truth.

DEV Community: Aashritha Sriramoju

I Added Hindsight to Give TeamForge Persistent Project Memory