Memory
What gets remembered
A complete guide to durable facts and preferences, significant project events, session continuity, structured work, and how each returns later.
Memory isn't one bucket. Different kinds of knowledge behave differently—a decision can be superseded, a lesson should interrupt you, a preference applies quietly, and a session snapshot is a bookmark rather than a standing rule.
This is the durable side of the agent partnership. You confirm a choice, correct a mistake, define a boundary, or preserve a stopping point once. ContextStream keeps the right shape and your assistant can bring it back when later work matches, without asking you to teach the project again.
Durable knowledge
Short-form knowledge records hold the things that should remain true or useful beyond the moment when they were learned:
| Kind | What it holds and how it helps later |
|---|---|
| Fact | A stable project or workspace truth that can ground relevant work; update or supersede it when the truth changes |
| Decision | A choice and its reasoning, used to answer why and superseded when a later choice replaces it |
| Preference | How you prefer work to be done, applied quietly when it is relevant rather than treated as a procedure |
| Constraint | A boundary that can surface when proposed work risks crossing it |
| Habit | A recurring way of working that helps the assistant follow your normal rhythm |
| Lesson | A mistake, its impact, and a specific prevention that warns matching future work |
| Goal | A short distilled objective that supplies direction; use a structured goal when you also need ownership and measurable progress |
| Risk | A short distilled exposure that supplies caution; use a structured risk when you need active mitigation and status |
| Term | A canonical definition that keeps project vocabulary consistent across sessions and clients |
These short goal and risk records are pointers for context. Use the structured goal and risk records when you need owners, status, metrics, mitigation, timelines, or active tracking.
Knowledge can be read, updated, deleted, or superseded. Superseding is the right choice when the old record is historically meaningful but no longer current.
Significant moments and project history
Timeline events preserve things that happened rather than claims that remain true forever. They include:
- decisions, preferences, insights, notes, and general observations;
- implementations, operations, commands, and file work worth retaining;
- tasks, bugs, features, corrections, lessons, warnings, and moments of frustration that explain a change in direction;
- conversations and session snapshots;
- standups, status updates, questions, approvals, feedback, discoveries, and achievements.
That breadth does not mean every command should become history. Capture the moment when it explains future work: the approval that unblocked a launch, the failed operation that revealed a constraint, the customer feedback that changed the design, or the snapshot that says where a migration stopped.
Events can be searched as a timeline, summarized, edited when necessary, distilled into durable knowledge, or imported in a batch from an approved source.
Records with their own shape
Some context needs a dedicated lifecycle rather than a memory label:
| Record | Why it is separate |
|---|---|
| Plans, tasks, and todos | Ordered execution, progress, blocking, and completion |
| Documents and runbooks | Long-form Markdown with one of twenty-two purposes |
| Diagrams | A named visual model that can be found and revised |
| Tickets and operations | Ownership, status, severity, versions, metrics, dates, or review state |
| Handoffs | A transfer of responsibility |
| Reminders | A dated prompt that can repeat, snooze, complete, or dismiss |
| Capsules | A portable context package with a share policy |
Keeping these distinctions is what lets a later assistant answer “what is still open?” differently from “why did we decide this?” and “what is the recovery procedure?”
How things get captured
Through supported workflows. Approved plans can be saved with their linked tasks. Connected clients can capture exchanges and snapshots when transcript capture is enabled. Incident, review, release, reminder, and handoff workflows create their own records when you ask for them.
Because you asked. "Remember that…", "record that decision", "lesson: never…". Use these when it matters and you want a durable record with the correct behavior. Do not make an important rule depend on an assistant inferring that a passing sentence was a decision or lesson.
From connected services. Their supported searches and sync actions can make pull requests, issues, documents, and selected discussions available as knowledge. Connecting a service does not capture everything in it. See Connecting GitHub, Slack, and the rest.
From an intentional import. Events, skills, repository records, and media can enter through their supported import or ingest paths. Scope and access still apply; an import is not permission to absorb an entire account.
One production change, several useful records
Suppose you harden webhook delivery after a provider outage. One session can produce several records without turning them into one vague “memory”:
| What happened | Durable shape | What it helps with later |
|---|---|---|
You chose capped exponential backoff with jitter for transient 503 responses | Decision | Answers why the sender waits and what alternatives were rejected |
| You changed the sender and fixed stale requests in the dashboard | Implementation events | Preserves the significant changes and evidence, not every command |
The staging mock had no 429 fixture | Lesson | Warns before the next retry or provider-mock change |
| The incident still needs a reproducible response procedure | Runbook | Gives an operator prerequisites, steps, verification, rollback, and stop conditions |
| A rate-limit fixture remains to be added | Ticket or plan task | Keeps active work, ownership, and completion separate from knowledge |
| The session ends with one failing test and an open provider question | Snapshot | Lets the next session resume from the real stopping point |
| Another agent will review the traffic bound | Handoff | Transfers a scoped responsibility with evidence and next steps |
| The runbook must be exercised next month | Reminder | Brings the dated obligation back with the procedure attached |
This separation is practical. “Why did we choose this?” should not return an open ticket. “What is left?” should not require reading a postmortem. “What must I not repeat?” should surface the lesson before work begins.
How it comes back
Configured clients are instructed to ground each turn before acting. Relevant saved context is pulled in and weighted by recency and specificity. You see the result rather than the machinery — the assistant starts with the records that match the work.
That lets you state “continue the migration” rather than “open the old chat, find the approved plan, read the database lesson, and check the remaining tasks.” The assistant can choose those retrievals itself. You still control the goal and any consequential action; grounding supplies evidence, not authority.
Two things get special treatment:
Lessons interrupt. A lesson matching the current work is surfaced as a warning, not as background reading. That's the point of recording one.
Freshness counts. Recent records normally rank ahead of stale ones on the same subject. Superseded decisions stay readable but should no longer be treated as the current answer.
The shape controls retrieval. “What is our rollback procedure?” should find a runbook. “What did we try last time?” should search captured sessions. “What is blocking the release?” should inspect active work. The assistant may use several sources for one investigation, but they do not become one undifferentiated bucket.
Team views without team-only assumptions
An individual can use all of the core memory and continuity features. In a shared workspace, authorized views can also collect team tasks, todos, diagrams, documents, discussions, and transcript topics.
Those views do not make personal records public or bypass project membership. Account mode chooses which boundary to work in; it does not erase access control.
Changing your mind
Say so. "We moved off Redis in March" supersedes the old decision rather than sitting beside it, contradicting. The history stays — you can see what changed and when — but there's one current answer.
What isn't kept
Source is not stored as a memory record, but eligible file contents are sent to ContextStream to build and operate hosted search. Ignore rules and secret-pattern filters run before ingest. Managed editor transcript capture can be turned off independently from indexing. See Privacy and what gets indexed.
If it doesn't work
Something we discussed isn't there. Discussion isn't a decision. Say “remember that…” for what matters, and check whether transcript capture was enabled if you expected the conversation itself.
An old decision keeps winning. It was never superseded. Correct it once.
Too much surfaces and it's noisy. Usually two repositories sharing one project. See Workspaces and projects.
A short risk or goal lacks tracking fields. Promote the idea into a structured goal or risk record. Short-form memory is useful context, not a complete operating register.