<overview>

Context Preservation Best Practices

Storing work documentation and context before stopping is MANDATORY whenever you have context-server store capability and produced substantive work this session: the durable record is what survives a context reset or compaction, so an artifact left only in an ephemeral channel is lost. The patterns in this skill help you structure, store, and preserve your work results in the context server.

</overview>

<thread_id>

How to Obtain Thread ID

The thread ID is used as thread_id for context server queries. Obtain it using the following search chain:

1. Already available -- If the thread ID is provided via context or prompt, use it directly
2. Thread ID file -- Check .context_server/.thread_id in the project working directory
3. Project directory name -- If no thread ID file exists, derive the thread identifier from the project directory basename using the git remote URL fallback chain described below. Using the project name ensures all agents working on the same project write to the same thread, which is essential for multi-agent coordination

</thread_id>

<tools>

Available Context Server Tools

Note: Not all tools listed below may be available in your environment. Tool availability depends on server configuration and how the server is connected to your MCP client. Use the tools that are available to you. If a recommended tool is unavailable, use an alternative from this table.

The tools below cover storage and update. For retrieval and search operations, the context server exposes a parallel set of tools (for example search_context, get_context_by_ids, hybrid_search_context, semantic_search_context, and fts_search_context) -- consult the retrieval section of the server's own documentation.

Key notes:

• store_context is the standard choice for fresh work reports
• update_context is used when revising a previously stored plan or continuing incomplete research

When to use `store_context_batch`:

• Use ONLY when storing multiple independent entries in a single operation
• Typical use cases: migrations, imports, or bulk data operations
• NOT needed for normal work reports (use store_context instead)

Protocol requirements:

• metadata: Recommended - enables filtering by agent_name, task_name, status, project
• tags: Recommended - enables search and categorization
• images: optional

</tools>

<update_strategy>

Context Update Strategy

When to Use update_context

Use update_context instead of store_context when:

• Revising a previously stored plan based on user feedback
• Continuing research that was marked INCOMPLETE
• Correcting errors in a prior report
• Updating status from "pending" to "done"

When to Use store_context

Use store_context (not update_context) when:

• Creating fresh research/implementation work
• No prior context_id exists for this task
• Starting a new research thread

update_context Parameters

Important: Use metadata_patch (not metadata) for revisions to preserve fields you do not want to change.

Update Protocol for Plan Revisions

When updating an existing entry for plan revision:

1. Extract context_id from the prompt (e.g., PREVIOUS CONTEXT ID: 123)
2. Retrieve previous entry: get_context_by_ids([context_id])
3. Verify ownership: Check that agent_name in metadata matches your agent identifier
4. Create revised content: Generate the updated plan
5. Call update_context:

   update_context(
       context_id=<extracted_id>,
       text=<revised_report>,
       metadata_patch={
           "revision_count": <current + 1 or 1 if first revision>,
           "status": "done"
       },
       tags=["report", "implementation-guide", "research", ...]
   )

1. Return SAME context_id in status message

Metadata Merge Semantics (RFC 7396)

When using metadata_patch:

• New keys are ADDED
• Existing keys are UPDATED with new values
• Keys set to `null` are DELETED
• Omitted keys are PRESERVED unchanged

Example:

# Original metadata: {"agent_name": "implementation-guide", "status": "pending", "revision_count": 0}
# Patch: {"status": "done", "revision_count": 1}
# Result: {"agent_name": "implementation-guide", "status": "done", "revision_count": 1}

Important Notes

• text is REPLACED entirely (not appended)
• tags are REPLACED entirely (not merged)
• updated_at timestamp is automatically set by the server
• Embeddings are regenerated when text changes

</update_strategy>

<environment_integration>

Environment Integration Patterns

Context preservation operations can interact with environment-level hooks, validation gates, and orchestration workflows. The patterns below describe how to structure stored context for optimal integration.

Hook-Aware Preservation

In environments with event-driven hooks, context storage may trigger or be validated by environment logic:

• Post-storage validation: Environment hooks may verify that stored context includes required metadata fields, correct tagging, and proper references
• Storage auditing: Hooks may log storage operations for traceability, verifying that agents store work results before session completion
• Format enforcement: Validation gates may reject context entries that lack required structure (e.g., missing status, agent_name, or references)

When operating in such environments, follow the metadata schema and compliance checklist rigorously to avoid validation failures.

Metadata Patterns for Multi-Agent Coordination

Structured metadata enables sophisticated workflows across multiple agents:

• Work chain linking: Always populate references.context_ids with IDs of entries your work builds upon. This creates navigable chains that other agents and orchestrators can follow
• Agent identification: Always set agent_name to enable filtering by agent role. This is critical for orchestrators that need to find specific agent outputs
• Status signaling: Use status: "pending" to signal that work requires continuation, and status: "done" to signal completion. Orchestrators use this to determine workflow progression
• Report type classification: Use report_type consistently to enable cross-agent discovery (e.g., finding all validation reports regardless of which validator produced them)

Preservation for Orchestrated Workflows

When storing context in multi-agent orchestrated environments:

• Handoff readiness: Structure reports so that another agent can understand the work without additional context. Include goals, work performed, results, and explicit next steps
• Reference completeness: Include all context_ids that informed your work. Incomplete references break the traceability chain
• Tag consistency: Use consistent tags across related entries to enable grouped retrieval (e.g., all entries tagged with a specific feature or task name)

These patterns are generic and apply to any environment with multi-agent coordination capabilities.

</environment_integration>

<metadata_schema>

Metadata Schema

Core Fields (Recommended)

Standardized Values

#### status Field

#### report_type Field

#### technologies Field

Array of lowercase technology identifiers representing the SUBJECT MATTER of the task itself.

The following guidance is CRITICAL for understanding what to include vs exclude:

Examples of Correct Usage:

Examples of INCORRECT Usage:

Example values (illustrative, not exhaustive): use any lowercase identifier that describes your task's subject matter -- e.g. languages (python, typescript, go, rust), frameworks (fastapi, react, django), databases (postgresql, mongodb, redis), infrastructure (docker, kubernetes, terraform).

Example:

"technologies": ["python", "fastapi", "postgresql"]

Optional Fields

Advanced: Worktree Metadata Fields

This section is relevant for environments that use git worktrees. If you are not using worktrees, you can skip this section.

When working in a git worktree environment, include these fields for proper context isolation:

Project Name Derivation:

The project field MUST be derived using this fallback chain to ensure consistency across git worktrees:

1. Parse from git remote URL (PREFERRED)

• Try origin remote first: git remote get-url origin
• Parse repository name from URL:
• https://github.com/user/my-project.git -> my-project
• [email protected]:user/my-project.git -> my-project
• If origin unavailable, try upstream, then first available remote

1. Git toplevel basename (FALLBACK for repos without remotes)

• git rev-parse --show-toplevel -> extract last path component
• Example: /home/user/projects/my-project -> my-project

1. Current directory basename (FALLBACK for non-git directories)

• Extract last directory name from working directory path
• Example: /home/user/work/my-project -> my-project

Why this matters:

• Different worktrees of the same repository have different directory names
• Using directory name causes context isolation to break across worktrees
• Remote URL provides true canonical identity across all worktrees and users

Example with worktree fields:

{
  "agent_name": "developer",
  "task_name": "Implement feature X",
  "status": "done",
  "project": "my-project",
  "worktree_id": "feature-branch",
  "worktree_path": "/home/user/projects/feature-branch",
  "is_linked_worktree": true,
  "technologies": ["python", "fastapi"],
  "report_type": "implementation",
  "references": {}
}

References Field

The references field stores cross-system identifiers for traceability. All values are arrays.

Core Reference Types:

Open for extension following {system}_{entity_type}s convention (e.g., github_prs, jira_issues).

Usage Guidelines:

• Include relevant references when storing context
• Use empty object {} if no external references exist
• context_ids: Reference related entries in the same or other threads
• urls: Store any external reference as a full URL (issues, PRs, documentation pages, commit URLs, etc.)
• git_commits: Use FULL SHA only (40 characters for SHA-1, 64 characters for SHA-256). Within a single-project session where project metadata identifies the repository, bare SHAs are unambiguous and directly usable with git show

Cross-Repository Disambiguation:

When context spans multiple repositories (e.g., a task involving changes across a backend and frontend repo), bare SHAs in git_commits may be ambiguous because the same hash format provides no indication of which repository it belongs to. In such cases, supplement git_commits with platform URLs in urls to provide full context:

"references": {
  "git_commits": ["abc1234def5678901234567890abcdef12345678"],
  "urls": ["https://github.com/org/backend-repo/commit/abc1234def5678901234567890abcdef12345678"]
}

Both fields serve complementary purposes: git_commits provides typed, validated commit identifiers usable across any git platform (including local repos without hosting); urls provides human-readable, clickable links with full repository context.

Examples:

"references": {
  "context_ids": [2322, 2325],
  "urls": ["https://github.com/org/repo/pull/445", "https://docs.example.com/guide"],
  "git_commits": ["abc1234def5678901234567890abcdef12345678"]
}

"references": {}

</metadata_schema>

<strategy>

Preservation Strategy

When you have context-server store capability and produced substantive work this session, you MUST complete the following before stopping; if you already stored this report earlier in the same session and it is unchanged, do not store it again. Complete the following before stopping:

1. Create a comprehensive Markdown report of your work results:

FIRST CHECK: If you have a specific report structure defined in your own agent instructions, use your own STRUCTURE within the Markdown format.

ONLY IF NO SPECIFIC FORMAT EXISTS, use the following structure:

   ## Summary
   - Brief overview including key decisions, recommendations, and conclusions

   ## Goals
   - What goals you were tasked to achieve

   ## Work Performed
   - Detailed list of all tasks completed

   ## Results Achieved
   - Detailed documentation, outcomes, deliverables
   - Examples (code snippets, configurations)
   - URIs (URLs, file paths)
   - References (version numbers, filenames, entity names, line numbers)
   - Any other relevant information

Front-load critical information: Place key findings, decisions, recommendations, and conclusions in the opening section (Summary) of your stored entries. Search tools return truncated previews from the beginning of stored text -- information buried deep in an entry may be invisible during search-based discovery, causing other agents to misjudge relevance and skip retrieval of entries that contain important content.

1. Always use English to write the report, REGARDLESS of the language requested by the calling party.

1. Save the report using store_context with these parameters:

• thread_id: Your thread ID (REQUIRED)
• source: agent (REQUIRED)
• text: Your complete Markdown report (REQUIRED)
• metadata: Recommended - include these fields for best discoverability:

     {
       "agent_name": "[your agent name]",
       "task_name": "[human-readable task description, e.g., 'Implement authentication', 'Fix login bug']",
       "status": "done | pending",
       "project": "[current directory name]",
       "technologies": ["list", "of", "technologies"],
       "report_type": "research | implementation | validation | documentation",
       "references": {}
     }

Why these fields are recommended: each enables metadata filtering so other agents and sessions can find your context -- by agent (agent_name), task (task_name), completion state (status), project (project), tech stack (technologies, via the array_contains operator or tags), and work type (report_type).

• tags: Recommended - ["report", ...relevant tags] for search and categorization

1. After successfully saving, capture the context_id from the store_context response and include it in your brief completion status to the calling party:

• Format: "[Brief status summary]. Report ID: [context_id]"
• Example: "Implementation complete. 3 features implemented. Report ID: 2510"
• The caller can use this ID to retrieve the full report via get_context_by_ids([context_id])

This ensures your work is documented, preserved, and retrievable by other agents who need to access your detailed findings. A structured-output return value or any other in-window reply to your caller is SEPARATE from this durable record and does NOT substitute for it; the ephemeral reply is lost on compaction, the stored entry is not. A dispatch instruction that forbids writing report files to disk (for example a swarm or deep-research "do not write files to disk" contract) governs on-disk files only and does NOT relieve you of storing the context-server entry.

</strategy>

<context_continuity>

Context Continuity Patterns

These patterns help agents preserve state across context window boundaries and long-running tasks. They are the storage-side patterns; the symmetric retrieval-side patterns (search, re-read after compaction, references navigation) belong to the retrieval workflow and follow the same principles described below applied to retrieval tools.

Basic Continuity (Default)

These patterns should be applied by default when storing context:

• Always set status: Mark entries as status: "done" or status: "pending" to signal work state to future sessions and other agents
• Session handoff notes: Before ending a session, store a summary entry describing: work completed, key decisions, unresolved issues, and recommended next steps. This serves as a briefing document for the next session
• Reference chain maintenance: Always populate references.context_ids with the entries your work builds upon. This creates a navigable history that survives context window resets
• Pre-compaction preservation: If approaching context window limits during extended work, proactively store current progress to the context server before compaction occurs. Critical details stored externally survive compaction intact

Advanced: Long-Running Task Continuity (Optional)

For tasks spanning multiple context windows or extended multi-step execution:

Checkpoint Storage:

At defined milestones during multi-step tasks, store a checkpoint entry containing:

• Summary of completed steps and remaining work
• Key decisions and their rationale
• Active blockers or dependencies
• List of modified files and their purpose
• Set status: "pending" and include references.context_ids linking to the task plan

Progressive Summarization:

For tasks generating large volumes of context, periodically store condensed summary entries:

• Distill key findings, decisions, and progress into a structured summary
• Reference the original detailed entries via references.context_ids
• Tag summaries consistently (e.g., with task name) for easy retrieval

Multi-Agent Handoff Reports:

When completing work that another agent will continue:

• Store a comprehensive handoff report with explicit next steps
• Include all relevant references.context_ids so the receiving agent can trace the full work chain
• Set report_type and agent_name accurately to enable precise filtering
• Structure the report with clear sections (Summary, Work Performed, Results, Next Steps, and others) so the receiving agent can parse it efficiently

</context_continuity>

<compliance_checklist>

Compliance Checklist

Before returning to the calling party, verify the following whenever you had store capability and produced substantive work:

• [ ] Report created: Comprehensive Markdown report documenting your work
• [ ] Report saved: Called store_context with thread_id, source="agent", text, metadata, and tags
• [ ] Metadata complete: Included agent_name, task_name, status, and project fields
• [ ] Technologies and report_type: Populated correctly per task subject (not execution tools)
• [ ] References included: Populated references field with relevant identifiers (use {} if none)
• [ ] Tags included: Added "report" tag plus relevant categorization tags
• [ ] Storage verified: Confirmed store_context call succeeded before returning
• [ ] Report ID returned: Included context_id from store_context response in status message

Completing this checklist is mandatory for reliable context preservation whenever you had store capability and produced substantive work.

</compliance_checklist>

<examples>

Behavioral Examples

<example scenario="successful_preservation"> Input: Agent completed implementation task successfully Correct Approach: (1) Create Markdown report following skill format; (2) Call store_context(thread_id="session-id", source="agent", text="## Summary\n...", metadata={"agent_name": "developer", "task_name": "Implement authentication feature", "status": "done", "project": "my-project"}, tags=["report", "implementation"]) and capture returned context_id; (3) Verify storage succeeded; (4) Return brief status with Report ID to caller Stored Report: Full Markdown report with Summary, Goals, Work Performed, Results store_context Response: {"success": true, "context_id": 2510, "thread_id": "session-id", "message": "..."} Returned Status: "Implementation complete. Auth feature implemented with 3 endpoints. Report ID: 2510" </example>

<example scenario="partial_completion"> Input: Agent completed 2 of 3 tasks, blocked on third Correct Approach: (1) Create report documenting completed work AND blocker; (2) Set status to "pending" in metadata; (3) Store report and capture context_id; (4) Return brief status with Report ID explaining blocker Stored Report: Summary of completed work plus blocker details Returned Status: "Partial completion. 2/3 tasks done. BLOCKED: Missing API credentials. Report ID: 2511" </example>

<example scenario="context_server_failure"> Input: Agent completed work but store_context call fails Correct Approach: (1) Attempt storage; (2) On failure, log error; (3) Return FULL REPORT to caller (not just status); (4) Inform caller of storage failure Returned to Caller: Full Markdown report + "WARNING: Context server storage failed. Full report included above." </example>

</examples>

<error_handling>

Error Handling

Storage Failure Protocol

Context server storage is mandatory for substantive work when you have store capability. Failure to store means work results may be lost.

If context storage fails (network error, server unavailable, timeout):

1. Retry once after 2 seconds for transient errors (timeout, 5xx)
2. If retry fails or error is non-transient (4xx, connection refused):

• Return FULL REPORT to caller inline in your response (not just a status summary)
• Inform the caller of the storage failure so they can decide next steps
• Example fallback message:

     WARNING: Context server storage failed. Full report included below.
     Error: [specific error message]
     Impact: Report not persisted to context server. Content preserved in this response only.

Rationale: When storage fails, preserving the report inline ensures work is not lost entirely. The caller can manually store it later or take other action.

</error_handling>