Raw view: Saving Workspace Context
No invisible, zero-width, or bidi-control characters detected.
---
name: saving-workspace-context
description: >-
Persist project knowledge that should outlast this conversation: decisions,
gotchas, research, and commands. Writes to AGENTS.md or a docs folder the
project already uses. Use when the user asks to save or record something for
future sessions, or at the end of a task that uncovered non-obvious facts.
user-invocable: true
disable-model-invocation: true
---
# Saving Workspace Context
Build institutional memory for a code repo without littering it. The goal is that the next agent session starts knowing what this one learned.
## Where things go
| What was learned | Where to save it |
|------------------|------------------|
| A command, path, env var name, or gotcha an agent needs every session | `AGENTS.md` (the matching section) |
| A decision with reasoning that a future reader might question | `docs/decisions/YYYY-MM-DD-<slug>.md`, or the repo's existing decisions folder |
| Research that would be painful to redo | `docs/research/<slug>.md`, or the repo's existing docs folder |
| A port, route, or integration change | `ConnectionGuide.txt` (see the shared rule) |
| A repeatable multi-step workflow | A new skill in `.agents/skills/` (ask first) |
| A convention the user keeps repeating | A repo-local rule in `.cursor/rules/` (ask first; see `suggesting-cursor-rules`) |
Prefer the harness's own memory feature for personal preferences that are not project facts.
## Rules
- **Check before creating.** Read `AGENTS.md` and the docs folder first. Update an existing entry instead of adding a parallel one.
- **Ask before creating a new top-level directory** or a new skill or rule. Small additions to existing files do not need permission; mention them in your report.
- **Never save secrets**, tokens, connection strings with credentials, or personal data.
- **Keep `AGENTS.md` short.** It loads every session. Facts, commands, and gotchas only. Long explanations go in `docs/` with a one-line pointer.
- **Date entries** in decision and research files, newest first.
- **Skip what is easily re-derived.** If the next agent can find it with one grep, do not record it.
- **Commit is the user's call.** Cloud Agents read from git, so mention that the saved file is uncommitted.
## Decision file format
```markdown
# {Decision title}
Date: {YYYY-MM-DD}
Status: accepted | superseded by {link}
## Context
{What prompted this}
## Decision
{What was chosen}
## Consequences
{What this makes easier or harder}
```
## End-of-task check
Before finishing a task, ask:
- Did I discover a command, path, or gotcha that is not in `AGENTS.md`?
- Did the user make a decision that a future reader would want the reasoning for?
- Did I do research that took more than a few minutes to reproduce?
If yes to any, save it using the table above and say what you saved.