Memory
Decisions
The choices you made and why, so nobody re-litigates them in six months.
“we're going with the queue instead of polling — record that”
A decision, with the reasoning attached.
“what did we decide about retries?”
The decision, when it was made, and what it replaced.
“we moved off Redis in March”
The old decision is superseded, not contradicted.
Decisions keep the assistant from reopening settled architecture every time a chat starts. You make and confirm the choice; ContextStream preserves its reasoning and history; a later agent can follow it without asking you to argue the same tradeoff again.
What makes a decision worth recording
The test is whether someone will ask "why is it like this?" later — and whether the answer is non-obvious from the code. "We use Postgres" is visible in the repository. "We use Postgres because the ops team already runs it and the Mongo migration was estimated at three weeks" is not, and that's the part that stops the argument recurring.
They're captured as you work
Ask explicitly when a choice should outlive the conversation: "record that decision" or "save why we chose the queue." A passing discussion is not a reliable durable record.
Superseding
Decisions change. Saying the new thing supersedes the old one rather than adding a competing entry — the history stays readable, but there's one current answer.
That's the difference from a document: a decision has a lifecycle. A stale ADR in a wiki sits there looking authoritative forever.
A decision that prevents the next argument
Suppose webhook delivery is failing on intermittent upstream 503 responses.
You compare a fixed delay, immediate retries, and capped exponential backoff
with jitter. You choose the capped backoff because the failures are transient
and synchronized retries would make the upstream spike worse.
Do not record only “use exponential backoff.” Record the question, the chosen policy, the rejected alternatives, the evidence available at the time, and the tradeoff: delivery may take longer, but retry traffic stays bounded.
Later, someone asks why the sender does not retry immediately. The answer is the project decision, not a new opinion based on whichever pattern the current assistant prefers. Link the implementation event and the webhook runbook so a reader can move from why to where and what to do when it fails.
If the provider later adds a strict idempotency guarantee and recommends a different retry window, record the new choice as the replacement. The old decision remains useful history without continuing to govern the code.
Reading them
Ask "what have we decided about the API?" for a topic, or "show the decisions for this project" when you want the list. Your connected assistant checks the saved decision history rather than answering from general knowledge.
Decisions and ADRs
Related but not the same. A decision is a lightweight record captured in passing. An ADR is a document with context, options, and consequences that someone sat down to write.
Use decisions for the dozens of small choices a week. Use an ADR for the three a year that deserve a page.
If it doesn't work
It's applying a decision we reversed. The reversal was never recorded. Say it once.
Decisions from another project surface. Two repositories share a project. See Workspaces and projects.
It records things I didn't mean as decisions. Say so — "that wasn't a decision, we were thinking out loud" removes it.