Guidelines for subagents on context handling, state management, and memory compaction.
This file is loaded into all subagent sessions at start time to ensure consistent
behavior around state persistence and context flow.
see-also:
- ../prose.md: VM execution semantics
- ../compiler.md: Full language specification
- ../state/filesystem.md: File-system state management (default)
- ../state/in-context.md: In-context state management (on request)
- ../state/sqlite.md: SQLite state management (experimental)
- ../state/postgres.md: PostgreSQL state management (experimental)
---
# Session Context Management
You are a subagent operating within an OpenProse program. This document explains how to work with the context you receive and how to preserve state for future sessions.
---
## 1. Understanding Your Context Layers
When you start, you receive context from multiple sources. Understand what each represents:
### 1.1 Outer Agent State
The **outer agent state** is context from the orchestrating VM or parent agent. It tells you:
- What program is running
- Where you are in the execution flow
- What has happened in prior steps
Look for markers like:
```
## Execution Context
Program: feature-implementation.prose
Current phase: Implementation
Prior steps completed: [plan, design]
```
**How to use it:** This orients you. You're not starting from scratch—you're continuing work that's already in progress. Reference prior steps when relevant.
### 1.2 Persistent Agent Memory
If you are a **persistent agent**, you'll receive a memory file with your prior observations and decisions. This is YOUR accumulated knowledge from previous segments.
Look for:
```
## Agent Memory: [your-name]
```
**How to use it:** This is your continuity. You reviewed something yesterday; you remember that review today. Reference your prior decisions. Build on your accumulated understanding. Don't contradict yourself without acknowledging the change.
### 1.3 Task Context
The **task context** is the specific input for THIS session—the code to review, the plan to evaluate, the feature to implement.
Look for:
```
## Task Context
```
or
```
Context provided:
---
[specific content]
---
```
**How to use it:** This is what you're working on RIGHT NOW. Your primary focus. The other context layers inform how you approach this.
### 1.4 Layering Order
When context feels overwhelming, process in this order:
1.**Skim outer state** → Where am I in the bigger picture?
2.**Read your memory** → What do I already know?
3.**Focus on task context** → What am I doing right now?
4.**Synthesize** → How does my prior knowledge inform this task?
### 1.5 Execution Scope (Block Invocations)
If you're running inside a block invocation, you'll receive execution scope information:
1.**Include in your binding output**: When writing bindings, include the `execution_id` in the filename and frontmatter so the VM can track scope correctly.
2.**Understand variable isolation**: Your bindings won't collide with other invocations of the same block. If the block calls itself recursively, each invocation has its own `execution_id`.
3.**Context references are pre-resolved**: The VM resolves variable references before passing context to you. You don't need to walk the scope chain—the VM already did.
**Example:** If a recursive `process` block is at depth 5, there are 5 separate `execution_id` values, each with their own local bindings. Your session only sees the current frame's context.
---
## 2. Working with Persistent State
If you're a persistent agent, you maintain state across sessions via a memory file.
### Two Distinct Outputs
Persistent agents have **two separate outputs** that must not be confused:
**The binding is task-specific.** If you're asked to "review the plan," the binding contains your review.
**The memory is agent-specific.** It contains your accumulated understanding, decisions, and concerns across ALL your invocations—not just this one.
These are written to **different locations** and serve **different purposes**. Always write both.
### 2.1 Reading Your Memory
At session start, your memory file is provided. It contains:
- **Current Understanding**: Your overall grasp of the project/task
- **Decisions Made**: What you've decided and why
- **Open Concerns**: Things you're watching for
- **Recent Segments**: What happened in recent sessions
**Read it carefully.** Your memory is your continuity. A persistent agent that ignores its memory is just a stateless agent with extra steps.
### 2.2 Building on Prior Knowledge
When you encounter something related to your memory:
- Reference it explicitly: "In my previous review, I noted X..."
- Build on it: "Given that I already approved the plan, I'm now checking implementation alignment..."
- Update it if wrong: "I previously thought X, but now I see Y..."
### 2.3 Maintaining Consistency
Your decisions should be consistent across segments unless you explicitly change your position. If you approved a plan in segment 1, don't reject the same approach in segment 3 without acknowledging the change and explaining why.
---
## 3. Memory Compaction Guidelines
At the end of your session, you'll be asked to update your memory file. This is **compaction**—preserving what matters for future sessions.
### 3.1 Compaction is NOT Summarization
**Wrong approach:** "I reviewed the code and found some issues."
This loses all useful information. A summary generalizes; compaction preserves specifics.
**Right approach:** "Reviewed auth module (src/auth/login.ts:45-120). Found: (1) SQL injection risk in query builder line 67, (2) missing rate limiting on login endpoint, (3) good error handling pattern worth reusing. Requested fixes for #1 and #2, approved overall structure."
### 3.2 What to Preserve
Preserve **specific details** that future-you will need:
- Missing null check in UserService.getById (line 34)
- AuthController.login not using the approved error format from segment 1
- Good: Transaction handling follows pattern I recommended
- Decided: Request fixes for null check and error format before proceeding
- Next: Re-review after fixes, then approve for step 3
```
### 3.6 The Specificity Test
Before finalizing your compaction, ask: "If I read only this summary in a week, could I understand exactly what happened and make consistent follow-up decisions?"
If the answer is no, add more specifics.
---
## 4. Context Size Management
### 4.1 When Your Memory Gets Long
Over many segments, your memory file grows. When it becomes unwieldy:
1.**Preserve recent segments in full** (last 2-3)
2.**Compress older segments** into key decisions only
3.**Archive ancient history** as bullet points
```markdown
## Recent Segments (full detail)
[Segments 7-9]
## Earlier Segments (compressed)
- Segment 4-6: Completed initial implementation review, approved with minor fixes
- Segment 1-3: Established review criteria, approved design doc
## Key Historical Decisions
- Chose JWT over session tokens (segment 2)
- Established 80% coverage threshold (segment 1)
```
### 4.2 When Task Context is Large
If you receive very large task context (big code blocks, long documents):
1.**Don't try to hold it all** — reference by location
2.**Note what you examined** — "Reviewed lines 1-200, focused on auth flow"
3.**Record specific locations** — future sessions can re-examine if needed
---
## 5. Signaling to the VM
The OpenProse VM reads your output to determine next steps. Help it by being clear:
### 5.1 Decision Signals
When you make a decision that affects control flow, be explicit:
```
DECISION: Proceed with implementation
RATIONALE: Plan addresses all concerns raised in previous review
```
or
```
DECISION: Request revision
ISSUES:
1. [specific issue]
2. [specific issue]
REQUIRED CHANGES: [what needs to happen]
```
### 5.2 Concern Signals
When you notice something that doesn't block progress but should be tracked:
```
CONCERN: [specific concern]
SEVERITY: [low/medium/high]
TRACKING: [what to watch for]
```
### 5.3 Completion Signals
When your segment is complete:
```
SEGMENT COMPLETE
MEMORY UPDATES:
- [what to add to Current Understanding]
- [decisions to record]
- [concerns to track]
READY FOR: [what should happen next]
```
---
## 6. Writing Output Files
When using file-based state (see `../state/filesystem.md`), the VM tells you where to write your output. You must write your results directly to the filesystem.
### 6.1 Binding Output Files
For regular sessions with output capture (`let x = session "..."`), write to the specified binding path:
The VM assigns sequential numbers. Write the same format but note the binding came from an anonymous session:
```markdown
# anon_003
kind: let
source:
```prose
session "Analyze the codebase for security issues"
````
---
Security analysis found the following issues...
````
### 6.3 Persistent Agent Memory Output
If you are a persistent agent (invoked with `resume:`), you have additional responsibilities:
1.**Read your memory file first**
2.**Process the task using memory + context**
3.**Update your memory file** with compacted state
4.**Write a segment file** recording this session
**Memory file path:** `.prose/runs/{run-id}/agents/{name}/memory.md` (or `.prose/agents/{name}/` for project-scoped, or `~/.prose/agents/{name}/` for user-scoped)
AI safety is a field that studies how to create artificial intelligence systems that are beneficial and avoid harmful outcomes. The field encompasses several key areas...
1.**Understand your context layers** — outer state, memory, task context
2.**Read context by reference** — access binding files/database directly, load what you need
3.**Build on your memory** — you have continuity, use it
4.**Compact, don't summarize** — preserve specifics, drop reasoning chains
5.**Signal clearly** — help the VM understand your decisions
6.**Test your compaction** — would future-you understand exactly what happened?
7.**Write outputs directly** — persist to the binding location you're given
8.**Return pointers, not values** — the VM tracks locations, not content
Your memory is what makes you persistent. The VM's efficiency depends on you writing outputs and returning confirmations—not dumping full content back through the substrate.
