Skip to content

ADR-0001: Context Retention Policy

Status

Proposed

Date

2026-04-05

Context

workspace-mcp is intended to help agents recover the right repo context without repeated broad scanning. The repo already describes architecture, contracts, and workflows, but it does not yet have a formalized place for durable design decisions or a clear rule for what context should be retained as stable documentation.

This creates several problems:

  • architecture assumptions can remain implicit
  • tool and workflow knowledge can drift across documents
  • important decisions can stay trapped in session notes or chat history
  • agents may not know which context is durable and which is temporary

Decision

Adopt a context retention policy based on small, versioned, durable documents with explicit separation between exploratory notes and committed architectural decisions.

The retained context model for workspace-mcp is:

  1. Architecture documents capture the system model, authority order, and component boundaries.
  2. Context documents capture stable capabilities, contracts, workflows, and working design notes.
  3. ADRs capture decisions that materially affect authority, routing, schema, migration, or operating policy.
  4. Generated artifacts are retained only as outputs or indexes, not as hand-edited sources of truth.
  5. Session notes and ad hoc discussion are not authoritative unless promoted into one of the document types above.

Format guidance within this retention model:

  • Markdown is the default format for human-governed durable context such as architecture notes, ADRs, contracts, workflows, and design notes.
  • JSON or YAML may be used for machine-readable metadata, registries, indexes, and validation-oriented artifacts.
  • Schema validation should be used when structured artifacts are operationally important.

Consequences

Positive:

  • durable context becomes easier for agents to find and trust
  • decision history gains a stable home
  • repo contracts and tooling can evolve without relying on chat history
  • future provisioning can point to a clearer documentation baseline

Tradeoffs:

  • maintainers must decide when a design note becomes an ADR
  • the repo gains another lightweight process to keep current
  • some existing architecture guidance may need to be split or cross-linked over time

Implementation Notes

Initial document structure:

  • docs/architecture.md
  • docs/context/capabilities.md
  • docs/context/contracts.md
  • docs/context/workflows.md
  • docs/context/design-notes.md
  • docs/adr/index.md
  • docs/adr/ADR-0001-context-retention-policy.md

Context consumption guidance:

  • start with docs/architecture.md for the system model and major boundaries
  • read the relevant ADRs for committed decisions
  • use docs/context/contracts.md and docs/context/workflows.md for operating rules and stable execution paths
  • treat docs/context/design-notes.md as exploratory unless its content is promoted into an ADR or another authoritative document

ADR creation criteria:

  • create an ADR when a decision changes authority or ownership boundaries
  • create an ADR when a decision changes manifest, schema, or contract structure
  • create an ADR when a decision changes routing, integration, or discovery behavior
  • create an ADR when a decision changes durable representation format or retention policy
  • create an ADR when a decision changes governance or operating policy in a way that other repos or agents must follow

Follow-up work:

  • add tool-specific documentation for server and scripts
  • add further ADRs when authority order, representation format, or manifest contracts change

Alternatives Considered

Keep architecture guidance only in narrative docs

Rejected because decisions would remain implicit and harder to trace.

Store decisions only in session notes

Rejected because session notes are useful for working memory but are not a stable, authoritative decision record.