Context Packs (Capsules)

Understanding Context Packs

In the Hopsule ecosystem, Context Packs—often referred to as Capsules—represent the primary unit of portability and organizational remembrance. While individual decisions and memories provide the granular foundation of your team's governance, Context Packs allow you to bundle these entities into cohesive, shareable, and enforceable units. They are designed to solve the fundamental problem of organizational amnesia: the tendency for critical reasoning and architectural commitments to dissipate as projects evolve, teams reorganize, or personnel change.

A Context Pack is more than a simple collection of documents; it is a curated snapshot of authority. By grouping specific Decisions with their supporting Memories, a Capsule provides a complete narrative of "what" was decided and "why" it matters. This structure ensures that whenever a developer interacts with a project—whether through the Hopsule Dashboard, the Hopsule CLI, or within their IDE via Hopsule for VS Code—they are guided by the full weight of the team's collective judgment rather than fragmented or outdated information.

Context Packs are built for longevity. They are designed to survive the transition between different AI models, development tools, and human generations within an engineering organization. By treating context as a portable asset, Hopsule ensures that enforcement is an act of remembrance, allowing your team to move faster without repeating past mistakes or violating established constraints.

The Anatomy of a Capsule

Every Context Pack is composed of several critical elements that define its scope, authority, and utility. Understanding these components is essential for effective context management and long-term organizational governance. A Capsule acts as a container that synchronizes disparate pieces of information into a unified framework for decision-making.

• Metadata and Identity: Each Capsule includes a unique identifier, a descriptive title, and a comprehensive summary. This metadata allows Hopper and other team members to quickly understand the intent and scope of the pack before it is activated or imported.

• Selected Decisions: These are the explicit commitments and constraints that the pack enforces. When a Capsule is active, the decisions within it become live constraints that appear in the Knowledge Graph and trigger warnings in Hopsule for VS Code.

• Linked Memories: Memories provide the "why" behind the decisions. They are append-only entries that preserve the history, reasoning, and lessons learned. By including memories in a Capsule, you ensure that future contributors understand the context that led to a specific decision, preventing the "Chesterton's Fence" problem where people remove constraints they don't understand.

• Enforcement Rules: Capsules define how the contained decisions should be surfaced across different product surfaces. This includes how Hopsule MCP presents context to external AI agents and how the Hopsule CLI reports on project compliance.

Important: A Context Pack does not "own" its decisions or memories; rather, it references them. This allows a single decision to be part of multiple Capsules, such as a "Global Security Standards" pack and a "Frontend Architecture" pack simultaneously.

Creating and Configuring Context Packs

Creating a Context Pack is a deliberate act of curation. It involves selecting the most relevant pieces of organizational judgment to solve a specific problem or guide a particular team. The process is managed primarily through the Hopsule Dashboard, providing a visual interface for assembling your team's collective memory.

1. Navigate to the Context Packs section of the Hopsule Dashboard and click the Create Capsule button.

2. Provide a clear, authoritative name and a detailed description. The description should explain the intended use case, such as "Onboarding Context for Senior Backend Engineers" or "Architecture Constraints for Microservices Migration."

3. Use the selection interface to browse your organization's library of Decisions. You can filter by tags, categories, or status. Select the decisions that form the core of this pack's authority.

4. Select the Memories that provide the necessary background for the chosen decisions. It is best practice to include any memory that explains the trade-offs or historical failures that led to the current state.

5. Review the Knowledge Graph (Brain) visualization to ensure that the relationships between the selected entities are logical and complete.

6. Set the initial lifecycle state to Draft while you refine the content, or Active if the pack is ready for immediate enforcement.

Tip: Keep your Context Packs focused. While it is tempting to create one giant "Everything" pack, smaller, more modular Capsules are easier to maintain, share, and enforce across diverse projects.

Managing the Capsule Lifecycle

Context Packs follow a structured lifecycle that reflects the evolution of organizational knowledge. This lifecycle ensures that teams are not overwhelmed by deprecated information while maintaining a clear audit trail of how decisions have changed over time. Managing these states is a core responsibility of engineering leadership and senior developers.

The transition between these states should be handled with care. Moving a Capsule to Active immediately pushes those constraints to every developer using Hopsule for VS Code on projects where the pack is linked. Conversely, moving a pack to Historical preserves the reasoning for future reference without cluttering the day-to-day development workflow with outdated rules.

Sharing and Distribution

The true power of Context Packs lies in their portability. Hopsule is designed to ensure that context can move seamlessly between projects, teams, and even organizations. This portability is what makes Hopsule a "memory system" rather than a static repository.

Internal Sharing

Within an organization, Capsules can be shared across different projects. For example, a "Security & Compliance" Capsule created by the infrastructure team can be imported into every application project. This ensures that every team is working under the same set of enforceable constraints without needing to manually duplicate decisions. Updates made to the original Capsule can be synchronized across all linked projects, ensuring organizational alignment.

Public Sharing via Secure Tokens

Hopsule supports public sharing of Context Packs through secure, read-only tokens. This is particularly useful for open-source projects, consulting engagements, or sharing architectural standards with external partners. When a Capsule is shared via a token, the recipient can view the full history of decisions and memories in a secure web view without needing a Hopsule account. This transparency fosters trust and ensures that external collaborators are aware of the team's "organizational judgment" before they contribute code.

Important: Publicly shared Capsules are read-only. External viewers cannot modify decisions or add memories unless they are granted explicit member access to the project within the Hopsule Dashboard.

Context Packs in the AI Ecosystem

Context Packs are the primary mechanism for making AI agents "context-aware." Whether you are using the built-in Hopper assistant or connecting external agents via Hopsule MCP, Capsules provide the boundaries and intelligence those agents need to be effective. Without this layer, AI agents often suggest code that violates internal standards or ignores historical lessons.

Hopper Integration

When interacting with Hopper in the dashboard or CLI, you can explicitly attach one or more Context Packs to the session. This tells Hopper to prioritize the decisions and memories within those packs when generating suggestions, drafting new decisions, or explaining existing code. Hopper uses these packs as the primary source for its RAG-powered reasoning, ensuring its advice is always grounded in your team's specific commitments.

Hopsule MCP (Model Context Protocol)

For organizations using external AI tools like Cursor or Claude, Hopsule MCP acts as a bridge. By exposing specific Context Packs via the MCP server, you allow these external agents to "read" your team's memories and decisions. This creates a seamless experience where an AI agent can say, "I see you're trying to implement a new caching layer, but the 'Core Architecture' Context Pack explicitly forbids using Redis for this specific use case because of a decision made last quarter." This is the pinnacle of context-aware engineering.

Versioning and Immutability

Engineering organizations are dynamic, and decisions inevitably change. Hopsule manages this evolution through a robust versioning system for Context Packs. Every time a Capsule is modified—whether a decision is added, removed, or updated—a new version is tracked. This allows teams to see exactly how their governance has shifted over months or years.

The Frozen state is a unique feature of Hopsule designed for high-stakes environments. When a Context Pack is frozen, it becomes an immutable record. This is essential for SOC 2 compliance, post-mortem analysis, or legal audits. A frozen Capsule serves as a "black box" recording of what the team's standards were at a specific point in time. If a system failure occurs, you can look back at the frozen Capsule to determine if the failure was a result of a bad decision or a failure to enforce an existing one.

Tip: Always freeze a Context Pack before a major release or at the end of a significant architectural phase. This creates a permanent landmark in your organization's memory.

Strategic Use Cases

Context Packs can be applied to various engineering challenges to improve efficiency and reduce cognitive load. By thinking of Capsules as "contextual templates," teams can standardize how they handle recurring situations.

Onboarding Packs

One of the most common use cases is the Onboarding Capsule. Instead of forcing a new hire to read through months of chat logs or fragmented documents, you can provide them with an "Onboarding Context Pack." This pack contains the most critical architectural decisions they need to follow, the memories of why the system is built the way it is, and the enforcement rules that will guide them in their IDE. This reduces time-to-productivity and ensures that new developers don't inadvertently break established patterns.

Architecture Decision Records (ADR)

Hopsule transforms the traditional ADR from a static file into an enforceable Context Pack. By grouping related ADRs into a Capsule, you create a living document of the system's evolution. When a developer works on a specific module, the relevant ADR Capsule is surfaced, providing them with the necessary constraints and reasoning in real-time.

Migration and Refactoring Guides

During a major migration—such as moving from a monolith to microservices—a dedicated Context Pack can act as the "guardrails" for the project. The pack can contain decisions about service boundaries, communication protocols, and data ownership. As developers work on the migration, Hopsule for VS Code will warn them if they attempt to create dependencies that violate the migration's goals.

Best Practices for Context Preservation

To maximize the value of Context Packs, teams should adopt a disciplined approach to curation and maintenance. Preservation is not a one-time event but a continuous process of organizational hygiene.

• Consistent Naming Conventions: Use clear, descriptive names that indicate the scope and authority of the pack. Avoid vague titles like "General Info" or "Team Notes." Instead, use "Backend Performance Standards" or "API Design Governance."

• Curate for Relevance: Periodically review Active Context Packs to ensure they still reflect the team's current commitments. If a decision is no longer relevant, deprecate it within the pack or move the entire pack to the Historical state.

• Link Decisions to Memories: Never include a decision in a Capsule without its supporting memories. A decision without context is just a rule; a decision with memory is a lesson. This is the difference between control and remembrance.

• Leverage the Knowledge Graph: Use the Brain visualization to identify gaps in your context. If you see a cluster of decisions that aren't part of a Context Pack, it may be time to create a new one to formalize that area of governance.

• Empower the CLI: Use the Hopsule CLI in your CI/CD pipelines to check project compliance against specific Context Packs. This ensures that no code is merged that contradicts the "Accepted" decisions within your authoritative Capsules.

By following these practices, your organization ensures that its most important decisions are not just stored, but are actively remembered and enforced across every project and every developer's workflow. Hopsule Context Packs turn the ephemeral nature of engineering discussions into a permanent, portable, and powerful asset.