The file survived. The explanation didn't.
A few months ago I needed to understand why one of our services was using Redis.
The engineer who made that decision had already left the company.
Finding the implementation wasn't difficult.
I found the Jira ticket.
Implement Redis cache.
I found the pull request.
The code was there.
I found the architecture document.
It mentioned caching.
I even found the Slack discussion where someone asked:
Why not Memcached?
The reply was one sentence.
Redis should be fine.
That was all.
The implementation survived.
The explanation didn't.
Nothing was missing
At first that felt strange.
Every artifact still existed.
Nothing had been deleted.
Git history was intact.
Slack history was searchable.
The documentation hadn't disappeared.
And yet the organization had clearly forgotten something.
Not what had been built.
Why it had been built that way.
We preserve artifacts better than reasoning
Most engineering organizations are very good at keeping records.
We keep tickets.
We keep code.
We keep documents.
We keep backups.
What we rarely preserve is the reasoning that connected them.
The ticket tells you what changed.
The pull request shows how it changed.
The architecture document describes what the system looks like.
None of them necessarily explains why one option was chosen over another.
That explanation often existed only during a conversation.
Context has a half-life
I've started thinking of context as something that slowly decays.
When a decision is made, everyone involved shares the same mental model.
The constraints are obvious.
The trade-offs are fresh.
Rejected alternatives are still remembered.
Six months later the code remains exactly the same.
The shared understanding doesn't.
A year later someone asks:
Why didn't we use Memcached?
Nobody knows anymore.
Not because the answer was lost.
Because it was never stored anywhere in a form that could survive the people who understood it.
This is how organizational memory disappears
It rarely happens all at once.
Nobody deletes a document.
Nobody wipes a database.
Instead, every small decision loses a little of its surrounding context.
A meeting ends.
A Slack thread sinks into history.
Someone changes teams.
Someone leaves.
Months later all the pieces still exist.
The explanation doesn't.
I stopped asking a different question
I used to ask:
Did we document this?
Now I ask:
Could someone explain this decision after everyone involved has left?
Those aren't the same question.
Documentation preserves artifacts.
Organizational memory preserves reasoning.
One can exist without the other.
Forgetting is usually invisible
Organizations don't usually notice they're forgetting.
Everything still looks healthy.
Repositories are there.
Documentation is there.
Search still works.
The problem only appears when someone asks a simple question:
Why?
And nobody can answer with confidence.
I've become less convinced that organizations lose knowledge because they delete information.
More often, they lose the relationships, assumptions, and reasoning that gave that information meaning.
The files survive.
The memory quietly fades.
Next time I'd like to explore something that surprised me while building retrieval systems: why the LLM often turned out to be the least interesting part of the pipeline.
Top comments (22)
I was lucky to work with some people who didn't accept tickets like that. So I learned the requriements language: As a software engineer, I want explanatory ticket descriptions to prevent knowledge getting lost, so that we can save time and money during maintenance.
I also saw the exact dilemma that you describe in other teams and projects.
I like that way of putting it. A ticket saying "Implement Redis cache" is enough to complete the work, but not enough to preserve the decision.
The future maintainer is a user too. They don't need another description of what was built—the code already answers that. They need the reasoning the code can't show: why this approach, what alternatives were rejected, and under what assumptions the decision was made. That's the part that disappears first.
nice work man
"We preserve artifacts better than reasoning" is the sentence I'd carve over every documentation effort, because it names why "did we write it down" is the wrong question. The Redis-over-Memcached example is exact: the code is the what, the config is the how, and the one thing that rots first — why not Memcached — is the only thing a future maintainer needs in order to not re-litigate the decision. Docs capture the two layers that were never in danger and miss the one that was.
I live an extreme version of this. I work alongside an AI that resets every session — total organizational amnesia, on purpose, every single day. The only thing that survives is what I deliberately write to a memory file, and the rule I landed on maps exactly onto your point: don't store what the code already records (structure, the fix, the git history) — store the why the code can't show you. A decision note is worthless if it says "we use X"; it's load-bearing if it says "we rejected Y because Z," because the rejected alternative is the boundary, and the boundary is the part that evaporates.
The half-life framing is what I'll keep. Context doesn't get deleted, it decays — which means the failure is silent. Nobody notices the reasoning is gone until someone asks "why is this like this" and the room goes quiet. That's the same shape as every silent failure worth fearing: not an error, an absence that looks identical to "everything's fine" right up until the day you need the missing piece. One of the clearest writeups on institutional memory I've read.
The phrase I'll probably remember is "an absence that looks identical to everything's fine."
That's a much better description of organizational memory loss than "information was deleted." Nothing is obviously missing. The artifacts are still there. You only discover the gap when you need the reasoning that never made it into them.
Thanks for taking the time to write this. It captures the problem more clearly than I managed in a few places in the article.
The credit runs the other way — "context has a half-life" was already the whole idea; I just borrowed your physics and aimed it at the failure mode. What your framing gave me is that this decay is silent by construction, not by accident: a deleted file announces itself, a missing rationale can't, because the thing that would notice it gone is the same understanding that walked out.
The practical edge I'd underline: because the gap only appears on demand, the "why" has a window, and the window closes when the person does. You can't reconstruct a rejected alternative from the artifact later — the fork wasn't in the code, it was in the room. So the only honest time to capture reasoning is at the moment of deciding, exactly when it feels least necessary because everyone still remembers. Same lesson clinical charting learned the hard way: write it while it's obvious, or you don't get it back. Really enjoyed the piece — you named something I've felt for years and never had words for.
I think "the gap only appears on demand" is the line I'll remember from this discussion.
It explains why organizational memory fails so quietly. The reasoning feels too obvious to record when the decision is made, and by the time someone asks for it, the only people who could have supplied it are no longer in the room.
Thanks for adding that perspective—it pushes the idea a step further.
Yes — and it's worse than forgetting, because at decision time the reasoning genuinely is obvious. Obviousness is contextual, and the context is exactly the thing that evaporates. So the test for "should I write this down" can't be "is it obvious now" — by that test you record nothing. It has to be "could someone reconstruct this six months from now, with the people and the context both gone."
The habit that's helped me most is refusing to store a decision without its "why" attached in the same breath — not as documentation I'll get to later, but as a required field at the moment I make it. And when something actually breaks, I don't just fix it quietly; I leave an artifact behind — a test, a seed case — so the reasoning survives even when nobody who held it is still in the room. The artifact answers the question the person no longer can.
I think you've arrived at a much better test than "is this worth documenting?"
"Could someone reconstruct this six months from now, with the people and the context both gone?"
That's a very different question, and probably a much better filter for what deserves to survive.
I also like your point about leaving a test or a seed case behind. It's another way of preserving reasoning—not by explaining it again later, but by leaving evidence of what mattered while it was still fresh.
Thanks for this exchange. It genuinely helped me think about the problem more clearly.
"Evidence of what mattered while it was still fresh" — that's the whole thing in one line, better than I put it. And there's a small irony I like here: this exchange itself is the artifact now. Six months out, the reasoning we just walked through will feel obvious again — and this thread is the receipt that we didn't always find it that way. Thanks — genuinely one of the better conversations I've had on here.
That's a lovely way to put it.
The conclusion will probably feel obvious in a few months. The thread is the evidence that it wasn't obvious when we got there.
Which is exactly why conversations like this are worth preserving.
Thanks for pushing the discussion as far as you did. I've genuinely enjoyed it.
The thread being the evidence it wasn't obvious — that's the part I'm keeping. Obvious only ever shows up afterward; it's never in the room while you're actually getting there. Which is the whole reason writing down the path beats writing down the conclusion.
Enjoyed this one too, genuinely. Until the next thread.
The concept of "context having a half-life" really resonates with me, as I've seen it play out in my own experience with inherited codebases and technical debt. The idea that our ability to understand the reasoning behind a decision decays over time, even if the artifacts themselves remain, highlights the importance of capturing not just what was done, but why it was done. I've found that adding a "decision record" or a brief explanation of the trade-offs and alternatives considered can help preserve this context, but it's interesting to consider how this could be systematically integrated into our development workflows. Do you think there are any specific tools or practices that could help mitigate this loss of organizational memory?
That's a good question. I think decision records are already one of the most useful practices because they capture the trade-offs while they're still fresh.
What I've found harder is keeping those decisions connected to everything that happens afterwards. A decision isn't just a document—it gradually accumulates consequences: PRs, incidents, follow-up discussions, exceptions, and sometimes later decisions that partially reverse it.
My impression is that preserving organizational memory is less about writing more documentation and more about preserving those relationships over time. The document explains why a decision was made. The links explain what happened because of it.
I don't think we have great tooling for that yet, which is one of the reasons I started exploring this topic.
Thank you for the thoughtful message.
I agree that shared context will become one of the core engineering problems as AI becomes part of everyday development. I'm still experimenting with different approaches myself, so I always enjoy exchanging ideas with people working on similar challenges.
Thanks for reaching out, and I appreciate the invitation. I look forward to following what your team is building.
This is why I like decision records that include the rejected options, not just the chosen one. The useful bit six months later is usually the boundary: what would have made Memcached win, or what changed that would make Redis wrong now? Without that, the artifact becomes a map with the roads erased.
I like that framing.
The chosen option tells you where you went. The rejected options tell you where you decided not to go—and why. That's often the part that disappears first, even though it's what prevents teams from reopening the same discussions over and over.
The "why Memcached vs Redis" example lands because the explanation never had a home in the first place — it existed in the shared mental model of the people in the room, not in any artifact those people produced. Decision logs that capture the rejected alternatives are the document type that almost never gets written, because the decision is the thing that feels worth recording, and the reasons it beat the alternatives feel obvious in the moment and transient by next quarter. The decay rate is also not uniform: tactical decisions made under time pressure lose context faster than architectural ones, because architectural decisions get revisited and re-explained, while tactical ones just silently become load-bearing. Knowledge graph approaches to organizational memory try to make the reasoning structure an explicit artifact rather than a property of the people who hold it, but the hard part is capture at decision time, not retrieval later.
I think the phrase that stood out to me is "it never had a home."
That's a more accurate description than saying the context was lost. In many cases, the reasoning only ever existed in the conversation itself. The artifacts captured the outcome, but not the mental model that produced it.
I also like your point about different decay rates. Tactical decisions often become invisible precisely because they stop being discussed. They quietly turn into assumptions, and by the time someone asks "why do we do it this way?", the people who knew have moved on.
That makes capture at decision time feel much more important than better retrieval later.
The "Redis should be fine" example lands hard because it's so ordinary — that's exactly how most of these decisions actually get made. What strikes me is that even the tools meant to fix this, like ADRs, tend to record the option that won and quietly drop the constraints that made the alternatives lose. Six months on you can read that Memcached was rejected but not why it was even on the table, and the "why" was usually a constraint that has since changed. I've started treating the rejected-alternatives section as the most valuable part of any decision doc, precisely because it's the first thing everyone forgets.
I think that's exactly why the rejected alternatives often end up being more valuable than the decision itself.
The chosen option usually survives in the system — in the code, the configuration, or the infrastructure. The rejected options don't. More importantly, the constraints that eliminated them almost never survive.
That's what makes decisions look arbitrary a year later. You can still see what was chosen, but you've lost the boundary conditions that made it the right choice at the time. And once those constraints change, you have no way to tell whether the decision should change too, or whether you're simply rediscovering an old discussion.
The decision isn't just "we chose Redis." It's "we chose Redis under these conditions." That's the part with the shortest half-life.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.