Decisions in ContextStream: The memory event that tells the agent what's been decided.

"Remembers everything" kept popping up in agent-written drafts of ContextStream copy.

It surfaced in landing page heroes, product tooltips, and onboarding headlines. Not every draft, but often enough to notice. It is a tempting phrase for any system built on top of an LLM, because the LLM-default instinct is more tokens, more recall, more "context," and the agents kept reaching for it.

We pushed back every time it showed up.

Not because it sounded wrong. Because it described a different product than the one we built. ContextStream was not built to remember everything. It was built to remember the right things and surface them at the right times. That is a fundamentally different promise. Coding agents do not get smarter when you hand them everything you have ever said. They get noisier. They drift. They start re-debating things you already settled because the signal is buried under a week of half-formed thoughts. Selective, hierarchical context beats total recall, which is why "Remembers everything" never made it onto any surface of the product or the marketing site. The whole company is built on the opposite idea.

That idea has a name. We call it a decision.

Decisions are the part of memory that should never get re-litigated

A decision is a project-level truth your team has chosen to treat as settled.

It is not a chat log or a vibe. It is a specific choice about architecture, stack, workflow, or product direction that future agents and future teammates should follow by default. Decisions are the highest-priority slice of context your AI gets, because they are the choices you have explicitly told it not to overturn.

This is what makes them different from "memory."

Why coding agents need decisions specifically

Every developer working with AI agents has hit the same wall.

You decide on a stack. You settle an architecture direction. You agree on a process rule. The session ends. A week later, a new agent suggests the opposite, a teammate revisits the same debate, and someone spends an afternoon reconstructing reasoning that was already good enough the first time.

This is one of the most expensive forms of context loss. Not because the decision was hard to make. Because once it dissolves back into chat, the team has to keep paying for it.

Decisions exist to stop that bleeding.

What actually counts as a decision

A good decision removes ambiguity. It tells future agents and teammates what the project has chosen, so they stop proposing conflicting alternatives by default.

What counts:

• A chosen architecture direction
• A settled tech stack choice
• A workflow rule the team intends to follow
• A design or product constraint that should stay consistent
• A project-specific implementation choice that should not be re-debated every session

Examples of the real thing:

• "We will build all new features using the existing canvas-based game engine rather than introducing a new framework."
• "The project will use a monorepo structure with shared packages for common utilities."
• "All API endpoints must follow REST conventions and return consistent error formats."
• "We prioritize shipping a working MVP before optimizing for performance."

What does not count:

• A loose observation that still needs validation
• A personal style preference
• A temporary one-task tactic
• An unresolved debate
• A vague statement with no clear operational consequence

If it is still emerging, it is an insight. If it describes how someone likes to work, it is a preference. If it is a settled project choice that should guide future work, it is a decision.

How decisions get into ContextStream

Three natural paths. None of them require ceremony.

You record them directly

When you or your team make a key choice about architecture, design, stack, or process, you save it from the dashboard or the desktop app. That single act turns a fragile conversation into reusable project memory for the whole team and every agent that touches the repo.

Agents capture them while they work

As your AI coding agents help you, they detect and save decisions that come up mid-conversation. When you choose a specific game architecture, settle on an API style, or agree on a folder convention, the agent can turn that into a lasting decision without you cleaning up after it later.

They get pulled from past work

ContextStream can review prior sessions and turn explicit choices or recurring patterns into decisions. Important project truths stop slipping through the cracks of old transcripts.

When to actually save one

Use a simple test.

If a new agent started tomorrow, would it make a worse choice without knowing this? If yes, save it.

You should capture a decision when the team is ready to stop re-discussing the topic, when future work would benefit from following it by default, when a conflicting suggestion would waste time or create drift, when the choice applies across the project rather than one narrow task, and when the reasoning matters enough that future agents should inherit it.

Anything else is probably an insight or a preference.

What to tell your AI

Speak naturally. The agent will figure out the rest.

• "Capture this as a decision: we are using TypeScript for the whole project."
• "Record that we've decided to keep the API REST-based instead of switching to GraphQL."
• "Save this as a project decision: all complex features start with a structured plan."
• "Make this durable: we are shipping browser-first and not building native apps in v1."

The goal is not perfect ceremony. The goal is to stop settled choices from dissolving back into chat.

How agents use decisions once they exist

This is where the real shift happens.

When you start a new session or ask an agent to work on something, ContextStream surfaces the most relevant decisions automatically. The agent treats them as settled truth. It follows them by default instead of reopening old debates. If a decision is relevant to what it is doing, it can also explain why it is following it and point back to the original reasoning.

A decision you made in March is still respected in May unless you explicitly change it.

That is what durable context actually looks like in practice.

What changes downstream

A good decision changes future work in three ways.

Consistency. Agents and teammates stop suggesting contradictory paths by default. The project speaks with one voice across sessions and tools.

Speed. The team spends less time re-deciding what has already been decided. Hours that used to go into rehashing old debates go into shipping.

Continuity. Project direction survives across sessions, tools, and people instead of resetting every time the work moves.

A decision is not a record of the past. It is a control on future behavior.

Priority: why decisions sit at the top

Decisions, preferences, and insights are not the same shape of context.

Decisions are settled rules. Agents follow them by default. Preferences guide style and approach, and agents align with them when possible. Insights help improve judgment. They inform suggestions but should not override decisions.

That hierarchy matters. If everything is treated like a soft suggestion, agents drift. Decisions exist to prevent that drift, which is exactly why they sit at the top of the pile.

This is also why ContextStream was not built to remember everything. It was built to remember the right things and surface them at the right times. A flat pile of memory is just noise. A ranked pile of memory, with decisions on top, then preferences, then insights, is the thing that actually makes an agent feel like it knows your project.

Tips for writing strong decisions

Make them clear and specific. A good decision removes ambiguity instead of creating it.

Include brief context or reasoning when it helps. Future agents do better when they understand not just what was chosen, but why.

Focus on project-level truths. Decisions work best when they apply across the project or team, not just one isolated task.

Treat them as settled. Only create a decision when you are ready for agents to follow it by default.

Update or retire them when circumstances change. Do not leave outdated decisions active.

Use decisions for what and preferences for how. A decision says, "We use TypeScript." A preference says, "We prefer strict type checking with minimal any types."

Examples that work

Architecture and tech stack

• "We will build all new features using the existing canvas-based game engine rather than introducing a new framework."
• "The project will use a monorepo structure with shared packages for common utilities."
• "All API endpoints must follow REST conventions and return consistent error formats."

Process and workflow

• "We always create a structured plan before implementing complex features."
• "All code changes must be reviewed before merging into the main branch."
• "We prioritize shipping a working MVP before optimizing for performance."

Design and user experience

• "The application will use a dark theme with retro pixel-art styling to match the game aesthetic."
• "User interfaces should remain simple and focused. Avoid adding unnecessary visual elements."
• "All games must be playable directly in the browser without requiring installation."

Constraints and rules

• "We will not use external dependencies unless they are well-maintained and solve a clear problem."
• "Database schema changes require updating the corresponding documentation."
• "We will maintain backward compatibility for all public APIs."

Project-specific choices

• "For the Space Invaders clone, we will use keyboard controls only and skip touch support in the first version."
• "The authentication system will use JWT tokens stored in HTTP-only cookies."
• "We have decided to implement real-time multiplayer using WebSockets instead of polling."

Team and collaboration

• "All major decisions must be recorded in ContextStream so the whole team and agents stay aligned."
• "We will use feature branches for new development and keep the main branch stable."

Common mistakes

Saving a debate instead of a decision. If the team has not actually settled the issue, do not store it as settled truth.

Writing it too vaguely. "We care about performance" is weak. "We prioritize shipping a working MVP before optimizing for performance" is usable.

Confusing decision with preference. "We use TypeScript" is a decision. "We prefer minimal any types" is a preference.

Leaving outdated decisions active. A stale decision is dangerous because agents will keep following it until you change or retire it.

Recording task-level trivia. Decisions should shape the project, not clutter memory with one-off execution details.

Why this beats leaving it in chat

A decision left in chat is a rumor.

Someone has to remember it, search for it, and decide whether it was actually final. That uncertainty is exactly what causes drift. A decision captured in ContextStream is durable project memory. The agent follows it by default. The team builds on top of it. The project stops wasting time re-litigating settled choices.

Quick way to start

Capture the five to eight most important choices that have already shaped your project. These are usually around stack, architecture patterns, workflow rules, and core constraints.

Once those are recorded, agents stop suggesting alternatives that contradict your established direction. You will feel the difference inside a week.

The bigger point

ContextStream was not built to remember everything. It was built to remember the right things and surface them at the right times. Decisions are the most important "right thing" it carries.

Good context is not a dragnet. It is a hierarchy. Decisions sit on top because they are the choices you have committed to. Preferences sit underneath because they shape style. Insights sit below that because they inform but do not bind. When your project remembers its decisions and pulls them up at the moment they matter, future work starts from truth instead of from scratch, and your agents finally stop quietly undoing the choices you already made.

P.S. What decisions actually do for a small team

If you are a two- or three-person team running a fleet of agents across engineering, marketing, design, and ops, decisions are how you stop being the bottleneck. The architecture call you make on Monday shows up in Tuesday's marketing copy, Wednesday's support replies, and Thursday's onboarding flow, because every agent on every surface is pulling from the same ranked memory instead of waiting on you to repeat yourself. That means fewer "wait, did we decide X?" pings in chat, no more contradictory drafts from agents working in different domains, and a code reviewer agent that already knows your stack rules without being re-briefed. A small team using decisions well stops feeling like a small team. Two people stay aligned with twenty agents, the work stays coherent across surfaces, and the hours you used to spend re-explaining your own product go back into building it.

Which decisions actually travel across surfaces depends on how you configure your workspaces and projects. If you prefer to keep domains mostly separate, you can use context capsules to share only the slice of memory you want to cross over. That is its own topic, and worth a dedicated post.

Want a follow-up on context capsules, or on workspace and project configuration? Email me at [email protected] or DM @kevoscott on X and tell me which one to write next.