What if a Codebase Could Remember Why It Was Built?
Every mature codebase has a history.
Libraries were selected. Architectures changed. Pull requests were debated. Conventions emerged.
Some of that knowledge survives in documentation.
A lot of it doesn't.
So I built CodeCompass to explore what happens when that history becomes part of an AI assistant's memory.
The question behind the project
Imagine joining a project and asking:
«Why do we use Redis here instead of Memcached?»
The code can show you how Redis is being used.
It may not tell you why it was chosen.
That answer could be buried in a PR from months ago.
That's the context CodeCompass is designed to retrieve.
Three memory operations
The architecture revolves around three ideas:
Retain — store useful project information.
Recall — retrieve relevant information when a question is asked.
Reflect — identify broader patterns across accumulated memories.
The current application demonstrates retain and recall directly:
memory.retain(
bank_id=BANK_ID,
content=memory_text
)
and:
results = memory.recall(
bank_id=BANK_ID,
query=question
)
That provides the foundation for the larger idea.
From memories to conventions Individual memories answer individual questions.
Reflection can potentially reveal patterns.
For example, after enough project history has accumulated, CodeCompass could identify patterns such as: «The team prefers composition over inheritance.»
Or:
«Performance-critical paths generally avoid ORMs.»
«New features are normally introduced behind feature flags.»
These aren't single decisions.
They're characteristics of how the project evolves.
That's the part of Hindsight I find especially interesting.
A simple demonstration
For a demo, we can provide simulated project history: «Redis was selected because pub/sub was required.»
«Cache keys should use the "cache_" prefix.»
«Short TTLs previously caused a thundering-herd problem.»
Then ask:
«I'm adding a new caching layer. What should I know?»
Without project memory, an AI can provide generic caching advice.
With the relevant project memories, CodeCompass can answer using the project's own history.
The difference isn't more intelligence.
It's better context.
What I learned
The Hindsight documentation helped us build the memory layer, while the broader idea of agent memory shaped the project.
The biggest lesson for me was that source code is only part of a project's knowledge.
The reasoning behind the code matters too.
CodeCompass is an attempt to make that reasoning easier to recover.
Because sometimes the most important question about a line of code isn't:
"What does this do?"
It's:
"Why did we decide to do it this way?"
Our project: https://xzhapxf95r8xhycqrxdflq.streamlit.app/