Skip to main content
The Persistence Contract defines how sub-agents determine where to read from and write to. All SDD sub-agents follow this contract to ensure consistent behavior.

​
Mode Resolution

The orchestrator passes artifact_store.mode with one of: engram | openspec | none.

​
Default Resolution

When the orchestrator does not explicitly set a mode:
  1. If Engram is available → use engram
  2. Otherwise → use none
openspec is NEVER used by default — only when the orchestrator explicitly passes openspec. When falling back to none, sub-agents should recommend the user enable engram or openspec for better results.

​
Behavior Per Mode

ModeRead fromWrite toProject files
engramEngram (see Engram Convention)EngramNever
openspecFilesystem (see OpenSpec Convention)FilesystemYes
noneOrchestrator prompt contextNowhereNever

​
Common Rules

  • If mode is none, DO NOT create or modify any project files. Return results inline only.
  • If mode is engram, DO NOT write any project files. Persist to Engram and return observation IDs.
  • If mode is openspec, write files ONLY to the paths defined in OpenSpec Convention.
  • NEVER force openspec/ creation unless the orchestrator explicitly passed openspec mode.
  • If you are unsure which mode to use, default to none.

​
Detail Level

The orchestrator may also pass detail_level: concise | standard | deep. This controls output verbosity but does NOT affect what gets persisted — always persist the full artifact.

​
Examples

​
Example 1: Engram Mode

Orchestrator passes:
- artifact_store.mode: "engram"
- change_name: "add-dark-mode"

Sub-agent behavior:
1. Search Engram for existing artifacts: mem_search("sdd/add-dark-mode/proposal")
2. Read full content: mem_get_observation(id)
3. Generate new artifact
4. Save to Engram: mem_save(topic_key: "sdd/add-dark-mode/design", content: "...")
5. Return observation ID: #obs_xyz789
6. NEVER create openspec/ directory or any project files

​
Example 2: OpenSpec Mode

Orchestrator passes:
- artifact_store.mode: "openspec"
- change_name: "add-dark-mode"

Sub-agent behavior:
1. Read from filesystem: openspec/changes/add-dark-mode/proposal.md
2. Generate new artifact
3. Write to filesystem: openspec/changes/add-dark-mode/design.md
4. Return file path: "openspec/changes/add-dark-mode/design.md"

​
Example 3: None Mode

Orchestrator passes:
- artifact_store.mode: "none"
- change_name: "add-dark-mode"
- (All context passed inline in prompt)

Sub-agent behavior:
1. Read context from orchestrator's prompt
2. Generate artifact
3. Return artifact inline in result envelope
4. DO NOT create any files
5. Recommend: "Enable `engram` or `openspec` for artifact persistence"

​
Why Three Modes?

​
Engram Mode (engram)

Use case: Ephemeral exploration, prototyping, no file pollution
  • Stores artifacts in memory (Engram tool)
  • No project files created
  • Fast iteration
  • Disappears when conversation ends (unless Engram persists across sessions)
Pros:
  • No filesystem pollution
  • Works in any project without initialization
  • Fast
Cons:
  • Not shareable with team
  • No audit trail outside conversation
  • Depends on Engram availability

​
OpenSpec Mode (openspec)

Use case: Long-term projects, team collaboration, audit trail
  • Stores artifacts on filesystem in openspec/ directory
  • Full audit trail
  • Shareable with team (commit to git)
  • Survives conversation end
Pros:
  • Persistent across sessions
  • Shareable via git
  • Complete audit trail
  • No tool dependencies
Cons:
  • Creates project files
  • Requires initialization (sdd-init)
  • More verbose

​
None Mode (none)

Use case: One-off questions, quick prototyping, no persistence needed
  • No storage
  • All context inline in conversation
  • No files created
Pros:
  • Simplest mode
  • No side effects
Cons:
  • Loses everything when conversation ends
  • Can’t resume work later
  • Not suitable for real projects

​
Migration Between Modes

You can switch modes mid-workflow:

​
From none to openspec

  1. Run /sdd-init with openspec mode
  2. Orchestrator re-runs previous sub-agents with openspec mode
  3. Artifacts written to filesystem

​
From engram to openspec

  1. Run /sdd-init with openspec mode
  2. Orchestrator retrieves artifacts from Engram
  3. Orchestrator re-runs sub-agents with openspec mode, passing retrieved context
  4. Artifacts written to filesystem

​
From openspec to engram

Not recommended — you’d lose the filesystem audit trail. If needed:
  1. Read artifacts from openspec/
  2. Save to Engram with proper topic_keys
  3. Optionally delete openspec/ (not recommended)

Build docs developers (and LLMs) love

Get started for freeTalk to us