Quick Start Guide

Welcome to Hopsule

Welcome to Hopsule, the decision and memory layer for AI teams and engineering organizations. Hopsule is designed to help your team preserve, enforce, and share its most important decisions and the crucial reasoning behind them. Organizations often forget the context of their past choices, leading to repeated discussions, inconsistent implementations, and a loss of valuable organizational judgment. Hopsule ensures that every commitment, every constraint, and every lesson learned is remembered and accessible, transforming remembrance into enforcement.

This Quick Start Guide will walk you through the essential steps to get Hopsule up and running for your team in under 10 minutes. You'll learn how to create your account, establish your organization and project, craft your first decision, document its underlying memory, and explore the intuitive Hopsule Dashboard. By the end of this guide, you will have a foundational understanding of how Hopsule empowers engineering excellence through persistent context and enforceable organizational judgment.

Step 1: Create Your Hopsule Account

Your journey with Hopsule begins by establishing your personal account. This account serves as your gateway to creating and managing organizational decisions, memories, and context packs. Hopsule prioritizes security and data integrity from the very first step, ensuring that your valuable organizational judgment is protected.

1. Navigate to the official Hopsule sign-up page.

2. Enter your email address and choose a strong, unique password. Alternatively, you may sign up using a supported single sign-on (SSO) provider for a streamlined experience.

3. After entering your details, a verification email will be sent to the address you provided. Please check your inbox and click the verification link to confirm your account. This step is crucial for activating your Hopsule account and ensuring the security of your data.

4. Once your email is verified, you will be prompted to choose a Hopsule plan. Hopsule offers various tiers, including a comprehensive Free plan that provides full access to all core features, including end-to-end encryption, to help you get started without any commitment. Select the plan that best suits your current needs; you can always upgrade or change your plan later as your team scales.

Important: Hopsule provides end-to-end encryption for all plans, including the Free tier. Data in transit is secured with TLS 1.3, and data at rest is protected with AES-256 encryption. This commitment to security is a baseline guarantee, not a premium feature, ensuring your organizational judgment remains private and secure. For enterprise customers requiring full data sovereignty, the Hopsule Enterprise (Self-Hosted) option allows deployment within your own infrastructure.

Step 2: Establish Your Organization

With your Hopsule account successfully created, the next step is to establish your organization. An organization in Hopsule acts as the top-level container for all your projects, teams, decisions, and memories, providing a centralized space for your collective organizational judgment. It defines the scope within which decisions are made, shared, and enforced.

1. Upon successful sign-up and plan selection, you will be automatically directed to a page prompting you to create your first organization.

2. Enter a meaningful name for your organization in the provided field. We recommend using a name that clearly identifies your company or primary engineering division, such as "Acme Engineering" or "Global Tech Solutions R&D." This name will be visible to all members within your organization.

3. You may also be presented with basic settings for your organization, such as default timezones or notification preferences. For a quick start, you can generally accept the default settings and adjust them later from the Hopsule Dashboard's Settings section as your needs evolve.

4. Click the Create Organization button to finalize this step. Once created, you will be taken to your new organization's Hopsule Dashboard.

Tip: While you can create multiple organizations under a single Hopsule account, it's often best to start with one primary organization that encompasses your main engineering efforts. This helps consolidate your decisions and memories for maximum impact and coherence.

Step 3: Set Up Your First Project

Within your organization, projects serve as logical groupings for related decisions and memories, reflecting your actual development initiatives. Setting up a project helps categorize your organizational judgment, making it easier to manage and apply context to specific areas of your work.

1. From your Hopsule Dashboard, locate the sidebar on the left. You will see a section for Projects.

2. Click the + New Project button, typically found near the projects list or in the main content area if you have no projects yet.

3. A dialog will appear, prompting you to enter a name for your new project. Choose a name that accurately reflects a specific engineering initiative, product, or team, such as "Backend API Service," "Mobile Application v2," or "Data Science Platform."

4. You may also have the option to add an optional description, which can provide further clarity on the project's scope or goals. This is particularly useful for larger organizations with many projects.

5. Click Create Project to add it to your organization. Your Dashboard will now update to show your newly created project.

Important: Each project in Hopsule provides a distinct context boundary. Decisions and memories created within a project are primarily associated with it, ensuring that the right context is available to the right teams and tools. You can switch between projects using the project selector in the Hopsule Dashboard.

Step 4: Craft Your First Decision

Decisions are the core entities in Hopsule — explicit commitments that your team agrees to follow. They represent the foundational agreements that guide your engineering work and become enforceable constraints once accepted. Creating your first decision is a pivotal moment in leveraging Hopsule's power for organizational judgment and remembrance.

1. Ensure you have selected the project you created in the previous step from the project selector in the Hopsule Dashboard.

2. In the left sidebar, click on the Decisions menu item. This will take you to the Decisions overview page for your current project.

3. Locate and click the Create Decision button, usually prominently displayed at the top right or center of the Decisions view.

4. A form will appear, prompting you to define your decision.

   Decision Details

   • Title: Provide a clear, concise title that summarizes the decision. For this quick start, let's use: "Use event-driven architecture for notifications". This title should immediately convey the essence of the commitment.

   • Description: Elaborate on the decision, explaining what it entails and its scope. A good description might be: "This decision mandates the use of an event-driven architecture pattern for all notification mechanisms within the Backend API Service. All system notifications, user alerts, and internal communication events must be published and consumed via a dedicated message broker, ensuring loose coupling and scalability across services."

   Adding Context and Tags

   • Initial Reasoning: While a full Memory will be created in a later step, you can add initial reasoning here to provide immediate context for why this decision is being proposed. For example: "Proposed to improve scalability, reduce direct service dependencies, and enable real-time processing capabilities over traditional polling methods."

   • Tags: Assign relevant tags to your decision. Tags help categorize, search, and filter decisions within your organization. For our example, consider adding tags like Architecture, Notifications, Backend, and Scalability. You can type in new tags or select from existing ones.

5. Review all the information you've entered to ensure accuracy and clarity.

6. Click the Submit for Review button. Your decision will now enter the Draft stage of its lifecycle.

Tip: Decisions in Hopsule are versioned. Any changes made to an accepted decision will create a new version, preserving the full history of your organizational judgment. This ensures complete traceability and understanding of how decisions evolve over time.

Step 5: Submit and Accept Your Decision

Once a decision is drafted, it typically undergoes a review process before it becomes an accepted, enforceable constraint. Hopsule supports various workflows for decision acceptance, from formal multi-approver processes to immediate self-acceptance, especially useful in solo mode or small, agile teams.

1. After clicking Submit for Review in the previous step, your decision will transition from Draft to Pending status. This means it's awaiting approval.

2. On the decision's detail page, you will see its current status prominently displayed. Depending on your organization's settings and your role, you will have options to manage its lifecycle.

3. For individual developers or small teams using Hopsule, you often have the authority to self-accept decisions. Locate the Accept Decision button (or similar approval action) on the decision's detail page.

4. Clicking Accept Decision will change the decision's status from Pending to Accepted.

Important: An Accepted decision in Hopsule is more than just a document; it becomes an active, enforceable constraint. This means that Hopsule's integrated tools, such as Hopsule for VS Code, can detect when code or actions contradict these accepted decisions, providing real-time feedback and promoting consistent adherence to organizational judgment. The philosophy is clear: enforcement is remembrance, not control.

Step 6: Document Your First Memory

Memories are the persistent, append-only context entries that explain why decisions were made. They capture the reasoning, discussions, trade-offs, and lessons learned, ensuring that the invaluable history behind your organizational judgment is never lost. Linking memories to decisions provides full traceability and enriches the context for future reference.

1. Navigate back to the detail page of the decision you just accepted (e.g., "Use event-driven architecture for notifications").

2. On the decision's detail page, look for a section related to Memories or an Add Memory button.

3. Click the Add Memory button. A form will appear, allowing you to create a new memory entry.

4. Since you initiated this from a specific decision, the memory will likely be pre-linked to that decision. Confirm that the "Use event-driven architecture for notifications" decision is associated.

5. In the content area, write a detailed explanation of the reasoning and context behind the decision.

   For example: "During the design phase for our notification system, we extensively evaluated two primary approaches: traditional polling and event-driven architecture. Polling, while simpler to initially implement, presented significant scalability challenges, potential for increased network overhead, and latency issues as the number of users and notification types grew. We identified that an event-driven model, utilizing a message broker, would offer superior decoupling of services, better fault tolerance, and greater flexibility for future integrations with other microservices. Although it required a slightly higher initial setup cost, the long-term benefits in maintainability, performance, and extensibility justified this architectural choice. Key considerations included potential message ordering guarantees and exactly-once processing, which we addressed through specific broker configurations and idempotent consumer design patterns."

   
   

6. Click Save Memory. Your memory is now permanently recorded and linked to your decision.

Important: Memories in Hopsule are append-only. They are never deleted or overwritten, ensuring a complete and immutable historical record of your team's context and lessons learned. This commitment to preservation underpins Hopsule's philosophy of remembrance.

Step 7: Explore the Hopsule Dashboard

The Hopsule Dashboard is your central hub for managing all aspects of your organization's decisions, memories, and context packs. It provides a comprehensive overview, intuitive navigation, and powerful visualization tools to help you understand and leverage your organizational judgment.

Navigating the Dashboard

Take a moment to familiarize yourself with the layout of the Hopsule Dashboard:

• Sidebar: On the left, you'll find the primary navigation. This allows you to quickly jump between major sections such as Decisions, Memories, Context Packs, Knowledge Graph, Hopper (your AI assistant), and Settings.

• Activity Feed: The main area of the Dashboard often features an activity feed, providing a real-time stream of recent actions and updates within your organization or selected project. This helps you stay informed about new decisions, memory additions, and other relevant events.

• Decision Counters: You'll typically see summary statistics at the top or within the Decisions section, indicating the number of decisions currently in Draft, Pending, Accepted, and Deprecated states. These counters offer a quick snapshot of your team's decision-making progress.

• Project Selector: At the top of the sidebar or main header, you can switch between different projects within your organization. This allows you to focus on the decisions and memories relevant to your current work.

Understanding the Knowledge Graph

One of the most powerful features of the Hopsule Dashboard is the Knowledge Graph (also referred to as the Brain).

1. In the left sidebar, click on Knowledge Graph.

2. The Knowledge Graph visualizes the intricate relationships between your decisions, memories, and context packs. You will see nodes representing your newly created decision and memory, connected by lines illustrating their association.

3. You can zoom in and out, drag nodes, and click on them to reveal more details or navigate directly to their respective pages. This visual representation helps you understand the interconnectedness of your organizational judgment, identify dependencies, and uncover the full context surrounding any given decision.

Tip: As your organization grows its collection of decisions and memories, the Knowledge Graph becomes an invaluable tool for understanding the holistic impact of your choices and ensuring that new decisions are made with full awareness of existing context.

Step 8: (Optional) Bundle Your First Context Pack

Context Packs, also known as Capsules, are portable bundles of decisions and memories. They are designed to encapsulate specific sets of organizational judgment, making them shareable across projects, teams, and even with AI sessions. Creating a context pack allows you to curate and disseminate focused sets of agreements and their underlying reasoning.

1. In the left sidebar of the Hopsule Dashboard, click on Context Packs.

2. Click the Create Context Pack button.

3. Provide a meaningful name for your context pack, such as "Core Backend Principles" or "API Design Standards." You can also add an optional description to explain its purpose.

4. After creating the context pack, you will be taken to its detail page. Here, you can add existing decisions and memories to it.

5. Locate the section to add decisions and memories. Search for and select the decision you created earlier, "Use event-driven architecture for notifications," and its linked memory.

6. Add these items to your context pack.

7. Once you've added the desired content, the context pack will be in Draft status. You can then transition it to Active when it's ready for broader use and sharing.

Important: Context Packs are designed to survive time, people, and system changes. They are versioned and can be frozen or historical, providing a robust mechanism for preserving and distributing critical organizational judgment without loss of context.

What's Next?

Congratulations! You've successfully completed the initial setup of Hopsule, created your first decision, documented its reasoning in a memory, and explored the Hopsule Dashboard. You now have a solid foundation for leveraging Hopsule to preserve and enforce your organizational judgment. But this is just the beginning. Hopsule offers a rich ecosystem of tools and features to integrate seamlessly into your engineering workflow.

Deepen Your Understanding with Hopper

Explore Hopper, Hopsule's built-in AI assistant. Hopper is RAG-powered, using your team's existing decisions and memories as context to provide intelligent assistance. You can use Hopper to draft new decisions from natural language descriptions, detect potential conflicts with existing accepted decisions, explain the reasoning behind complex choices, and suggest improvements. Remember, Hopper is advisory only; it never makes decisions autonomously, ensuring that human judgment remains at the core of your processes.

Expand Your Team's Reach

Invite your team members to your Hopsule organization. Collaboration is central to Hopsule's design, enabling shared decision-making, collective memory preservation, and consistent enforcement across your entire engineering organization. You can manage roles and permissions within the Settings section, ensuring appropriate access control.

Integrate with Your Workflow

Hopsule offers several powerful integrations to bring decisions and memories directly into your development workflow:

• Hopsule for VS Code: Install the Hopsule IDE Extension for VS Code and Cursor. This extension provides inline decision enforcement, surfacing warnings when your code contradicts accepted decisions. It allows developers to browse decisions and conflicts directly within their IDE, fostering immediate awareness and adherence to organizational judgment. No source code leaves your local environment with this extension.

• Hopsule CLI: For developers who prefer the command line, the Hopsule CLI allows you to create, list, accept, and deprecate decisions directly from your terminal. It's designed to integrate seamlessly into CI/CD pipelines, enabling automated checks and status reporting based on your accepted decisions.

• Hopsule MCP: Connect any MCP-compatible AI agent (like Cursor or Claude) to your team's decisions and memories using the Hopsule Model Context Protocol server. This makes your AI agents context-aware, allowing them to leverage your organizational judgment without ever being able to mutate it.

• Hopsule API: For custom integrations and advanced automation, the Hopsule API provides programmatic access to your decisions, memories, and context packs. Build custom workflows, synchronize with other systems, and leverage webhooks for real-time event notifications.

Explore Advanced Features

Dive deeper into Hopsule's capabilities by exploring features such as role-based access control, detailed audit trails for compliance reporting, and secure public sharing of specific decisions or context packs via tokens. Hopsule is built to scale with your organization's needs, providing the governance and context preservation required for enterprise-grade engineering.

For more in-depth information on any of these features, refer to the comprehensive documentation available in the Hopsule documentation portal. Your journey towards more consistent, informed, and effective engineering decision-making has just begun.