Workspace Durable Operating Surface
The Workspace is a managed filesystem-like structure used to store persistent state across sessions. It primarily consists of Markdown files that serve as the “long-term memory” for an agent’s operational context.Key Workspace Documents
MEMORY.md: Stores long-term facts, user preferences, and cross-session knowledge crates/palyra-daemon/src/domain/workspace.rs#100-100.HEARTBEAT.md: Captures high-frequency status updates and the current state of ongoing tasks crates/palyra-daemon/src/domain/workspace.rs#101-101.- Managed Blocks: Sections of files delimited by
<!-- PALYRA:BEGIN ... -->and<!-- PALYRA:END ... -->markers. These blocks are programmatically updated by the compaction system to prevent agents from overwriting human-authored content crates/palyra-daemon/src/domain/workspace.rs#30-33.
Security and Risk Scanning
The workspace includes aWorkspaceRiskScan mechanism that evaluates content for potential threats crates/palyra-daemon/src/domain/workspace.rs#208-211.
- Prompt Injection Detection: Scans for high-risk patterns like “ignore previous instructions” or “reveal the system prompt” crates/palyra-daemon/src/domain/workspace.rs#10-19.
- Sensitive Path Protection: Prevents access to critical directories such as
.git,.ssh, andvaultcrates/palyra-daemon/src/domain/workspace.rs#8-9. - Risk States: Documents are classified as
Clean,Warning, orQuarantinedbased on scan results crates/palyra-daemon/src/domain/workspace.rs#180-184.
Session Compaction Lifecycle
Session Compaction (also known as the “continuity planner”) is triggered when a session’s token count exceeds specific thresholds. It transforms a verbose eventTape into a concise OrchestratorCompactionArtifactRecord crates/palyra-daemon/src/application/session_compaction.rs#21-27.
Compaction Strategy: session_window_v1
The system employs a windowing strategy to maintain immediate context while summarizing the past:
- Retention: Keeps the most recent 6 text events exactly as they occurred crates/palyra-daemon/src/application/session_compaction.rs#33-33.
- Condensation: Summarizes older events into a structured JSON summary crates/palyra-daemon/src/application/session_compaction.rs#120-124.
- Candidate Generation: Identifies “candidates” for workspace updates—facts or status changes that should be moved from the ephemeral session to durable files crates/palyra-daemon/src/application/session_compaction.rs#159-169.
Implementation Data Flow
The following diagram maps the compaction process from the high-level logic to the specific code entities involved. Title: Session Compaction Data Flow Sources: crates/palyra-daemon/src/application/session_compaction.rs#1-195, crates/palyra-daemon/src/application/provider_input.rs#14-17Managed Block Updates
When the compaction system identifies a fact that belongs in the workspace, it usesapply_workspace_managed_block to perform a surgical update crates/palyra-daemon/src/domain/workspace.rs#43-47.
| Entity | Role |
|---|---|
WorkspaceManagedEntry | A single unit of information (e.g., a fact or task) with a unique ID crates/palyra-daemon/src/domain/workspace.rs#36-40. |
WorkspaceManagedBlockUpdate | A request to update a specific block with a list of entries crates/palyra-daemon/src/domain/workspace.rs#43-47. |
WorkspaceManagedBlockOutcome | The result of an update, including a diff of lines added/removed crates/palyra-daemon/src/domain/workspace.rs#60-66. |
Context References and Recall
The Workspace and Session history are exposed to the model through theContextReference system, which allows users or agents to explicitly “tag” resources using the @ symbol crates/palyra-common/src/context_references.rs#69-72.
Resolution Process
- Parsing:
parse_context_referencesidentifies@file,@folder,@url, and@memorytags in the input text crates/palyra-common/src/context_references.rs#5-12. - Previewing:
preview_context_referencescalculates token estimates and fetches content previews crates/palyra-daemon/src/application/context_references.rs#72-77. - Injection:
render_context_reference_promptformats the resolved content into a<context_references>XML-style block for the LLM crates/palyra-daemon/src/application/context_references.rs#131-134.
Checkpoint and Restore
Checkpoints allow a session to be “frozen” and later restored or branched. A checkpoint captures the state of the workspace and the condensed session summary at a specific point in time.OrchestratorCheckpointRecord: Stores the metadata and the state of workspace paths at the time of the checkpoint crates/palyra-daemon/src/journal/mod.rs.SessionCompactionCheckpointPreview: Provides a UI-friendly view of what will be included in a checkpoint, including the list of affected workspace paths crates/palyra-daemon/src/application/session_compaction.rs#184-189.