Setting Up Your First Project

Setting up your first project is the foundational step in establishing a resilient memory layer for your engineering organization. This guide provides a comprehensive walkthrough of creating a project, establishing governance frameworks, and ensuring your team's collective judgment is preserved and enforceable from the very first commit.

By the end of this article, you will have a fully configured environment where decisions are first-class entities, memories provide the necessary context for future developers, and your AI agents are fully aware of the constraints and reasoning that define your technical landscape.

Prerequisites

Before initiating your first project, ensure you have completed the following requirements:

• An active Hopsule account with administrative or owner permissions within your organization.

• The Hopsule CLI installed on your local machine if you intend to link local codebases to the project context.

• Access to the Hopsule Dashboard via a supported web browser.

• A clear understanding of the initial engineering domain or service you wish to bring under governance.

Step 1: Creating the Project Entity

The project is the primary container for your decisions, memories, and context packs. To create one, navigate to the Hopsule Dashboard and select the Projects tab from the primary navigation sidebar. Click the Create New Project button located in the top-right corner of the interface.

In the configuration modal, you will be prompted to provide a Project Name and a Project Description. It is essential to use a name that is descriptive of the engineering domain, such as "Core-API-Service" or "Frontend-Design-System." The description should clearly state the purpose of the project and the scope of the governance it will provide. Once entered, click Initialize Project.

Upon initialization, Hopsule generates a unique Project ID. This ID is critical for connecting the Hopsule CLI and Hopsule for VS Code to this specific memory layer. You can find this ID at any time in the Project Settings view.

Step 2: Defining the Decision Lifecycle

Hopsule operates on a decision-first philosophy. Unlike static text, decisions in Hopsule have a lifecycle that dictates their authority and enforcement. Within your new project, navigate to the Governance Settings section.

By default, Hopsule projects utilize the standard lifecycle: Draft, Pending, Accepted, and Deprecated. You can configure the requirements for transitioning between these states:

• Draft: Decisions currently being authored. These are not yet visible to AI agents or enforced in IDEs.

• Pending: Decisions awaiting review from senior stakeholders or the broader team.

• Accepted: The active state of governance. Once a decision is Accepted, it becomes an enforceable constraint. Hopsule for VS Code will begin surfacing warnings if code contradicts these decisions, and Hopper will use them as authoritative context.

• Deprecated: Decisions that are no longer active but are preserved for historical remembrance.

Ensure your team understands that Accepted status is the trigger for active enforcement. This transition represents the moment of organizational commitment.

Step 3: Inviting Collaborators and Assigning Authority

Governance is a collective effort. To invite your team, navigate to the Team tab within the Hopsule Dashboard. Click Invite Member and enter the email addresses of your engineering colleagues.

Hopsule utilizes Role-Based Access Control (RBAC) to ensure organizational judgment is managed by the appropriate individuals. Assign one of the following roles:

1. Admin: Full control over project settings, member management, and the ability to move decisions to Accepted or Deprecated states.

2. Contributor: Can create Memories and Draft decisions, but cannot unilaterally accept decisions that affect the entire project.

3. Viewer: Read-only access to the Knowledge Graph and decisions. Ideal for cross-functional stakeholders who need context but do not participate in technical governance.

Remember: Enforcement is remembrance, not control. Roles should be assigned to facilitate the preservation of context rather than to restrict the flow of ideas.

Step 4: Initializing the First Context Pack (Capsule)

Context Packs, or Capsules, are portable bundles of decisions and memories. To make your project's context accessible to other services or AI sessions, you must create your first Capsule. Navigate to the Capsules section in the dashboard and click New Context Pack.

Select the initial set of Accepted decisions you wish to include. This might include your organization's "Genesis Decisions," such as architectural patterns, security requirements, or naming conventions. Once created, this Capsule can be shared via a secure token or imported into other projects, ensuring that your organizational judgment survives time and system changes.

Step 5: Connecting the Hopsule CLI

To bring the power of Hopsule to the terminal, you must authenticate the Hopsule CLI. Open your terminal and execute the following command:

This will open a secure authentication window in your browser. Once authenticated, navigate to your local project directory and initialize the connection:

The CLI will create a local configuration file that links your workspace to the Hopsule memory layer. You can now use hopsule status to view the current state of project decisions or hopsule decision create to draft a new decision directly from your terminal. This integration ensures that the reasoning behind your code is always a command away.

Step 6: Enabling IDE Enforcement with Hopsule for VS Code

The true power of Hopsule is felt where the work happens. Install the Hopsule for VS Code extension from the marketplace. Once installed, click the Hopsule icon in the activity bar and log in.

Select your newly created project from the list. The extension will automatically synchronize the Accepted decisions. Now, as you write code, Hopsule will monitor the context. If you attempt to implement a pattern that contradicts an Accepted decision, Hopsule will surface an inline warning. This is not a linter; it is the manifestation of your team's collective memory, reminding you of the commitments you have made.

Step 7: Activating Hopper and Hopsule MCP

To make your AI agents context-aware, you must configure the Hopsule MCP (Model Context Protocol). This allows agents like Claude or those within Cursor to read your project's decisions and memories. Navigate to the Integrations tab in the Hopsule Dashboard and select MCP Configuration.

Copy the provided connection string into your AI agent's configuration. Once connected, your AI assistant will no longer guess at your architectural preferences. It will have read-only access to the Accepted decisions and the Memories that explain the "why" behind them. Hopper, the built-in assistant, will also be available in the dashboard to help you draft new decisions or identify conflicts between existing ones.

Tips and Best Practices

• Start with "Why": When creating a Decision, always attach a Memory. Decisions tell the team what to do; memories tell them why it was chosen. This traceability is what prevents future teams from reverting critical choices.

• Use Hopper for Drafting: If you are unsure how to articulate a complex architectural constraint, describe it to Hopper in natural language. Hopper can draft the decision for you, which you can then refine and move to Pending.

• Leverage the Knowledge Graph: Periodically visit the Brain view in the dashboard. Visualizing how decisions and memories relate can help you identify gaps in your project's governance or areas where context is becoming siloed.

• Keep Decisions Atomic: Avoid creating "mega-decisions." Instead, create smaller, linked decisions. This makes them easier to deprecate or update without affecting the entire project's memory.

• Enforce Early: Don't wait for a project to be "finished" to start using Hopsule. The most important decisions are often made in the first week. Capture them immediately.

Troubleshooting

If you encounter issues during the setup process, refer to the table below for common causes and solutions.

Related Articles

• Managing the Decision Lifecycle: From Draft to Deprecation

• Building and Sharing Context Packs (Capsules)

• Using Hopsule for VS Code for Real-time Enforcement

• Advanced Governance: Using the Knowledge Graph to Identify Conflicts