Migration Guide: Moving to Hopsule

The Philosophy of Migration: From Static Records to Active Remembrance

Migration to Hopsule represents a fundamental shift in how an engineering organization maintains its professional authority. Most teams suffer from organizational amnesia, where the reasoning behind critical architectural choices is lost to time, turnover, or the fragmentation of legacy document storage. Moving your decisions to Hopsule is not merely a data transfer exercise; it is the act of transforming passive text into an enforceable governance layer. By centralizing your commitments within a context-aware memory system, you ensure that every decision remains a living constraint that guides both human developers and AI agents.

The goal of this migration is to establish a single source of truth that is portable, persistent, and actionable. Unlike traditional repositories where information goes to die, Hopsule integrates your decisions directly into the development workflow via the Hopsule IDE Extension and Hopsule CLI. This guide outlines a structured approach to identifying, prioritizing, and preserving your institutional judgment, ensuring that your team's hard-won lessons are never forgotten.

Phase 1: Assessment and Discovery

Before initiating the migration, you must conduct a comprehensive audit of your existing decision landscape. Decisions in modern engineering teams are rarely found in one place; they are scattered across various unstructured environments. You must identify these "decision silos" to ensure that the context surrounding your architecture is fully captured. Look for records of organizational judgment in legacy document repositories, shared text files, and project management boards. Even informal channels like chat transcripts and meeting minutes contain the "why" that Hopsule's memories are designed to preserve.

Identifying Decision Silos

Start by mapping out where your team currently records its commitments. Common sources include Architecture Decision Records (ADRs) stored in version control, design docs in collaborative editors, and governance policies buried in internal portals. It is essential to distinguish between general information and actual decisions. A decision in Hopsule is an explicit commitment the team agrees to follow. If a record describes a mandatory pattern, a chosen framework, or a rejected alternative, it belongs in Hopsule. If it is merely a tutorial or a status update, it may not require formal migration.

Evaluating Decision Health

Not every legacy record is worth migrating in its current state. As you audit your sources, categorize them by their relevance and clarity. Many older decisions may have become "tribal knowledge"—rules everyone follows but no one can find the written justification for. This migration is the perfect opportunity to formalize that tribal knowledge. Use the following table to prioritize which records should be moved to the Hopsule Dashboard first.

Phase 2: Strategic Planning

Successful migration requires a strategy that balances speed with accuracy. Attempting to move years of context in a single day often leads to low-quality entries that lack the necessary enforcement metadata. Instead, we recommend a tiered approach where the most critical, high-impact decisions are migrated first, followed by a gradual ingestion of historical context. This ensures that the Hopsule for VS Code extension begins providing value immediately by surfacing the most relevant constraints to your developers.

Defining the Migration Scope

Begin by defining your "Initial Active Set." This set should include any decision that currently governs how code is written or how systems are deployed in your organization. By focusing on active constraints, you establish the Hopsule Dashboard as the primary authority for governance from day one. Historical data, while important for the Knowledge Graph, can be backfilled once the active set is established. This prevents the team from feeling overwhelmed by the volume of legacy data.

Important: Do not delete your legacy records until the migration is verified. Hopsule is designed to be the primary memory system, but maintaining the original source during the transition period provides a safety net for cross-referencing metadata and timestamps.

Mapping Lifecycle States

Hopsule uses a specific lifecycle for decisions: Draft, Pending, Accepted, and Deprecated. During migration, you must map your existing statuses to these Hopsule states. For example, a "Proposed" ADR should be imported as Pending, while a "Superseded" record should be imported as Deprecated. This mapping is crucial for the Hopsule MCP, as AI agents will only treat Accepted decisions as enforceable constraints.

Phase 3: Executing the Migration

There are three primary methods for moving data into Hopsule, depending on the volume of records and the technical proficiency of the migration lead. Most organizations use a hybrid approach, utilizing the Hopsule API for bulk imports of structured records and the Hopsule Dashboard for nuanced, manual entries.

Bulk Import via Hopsule API

For organizations with hundreds of existing ADRs or structured documents, the Hopsule API is the most efficient path. You can programmatically create decisions and link them to their corresponding memories. When using the API, ensure you are capturing the original creation dates and authors as metadata to preserve the audit trail. This programmatic approach allows you to maintain the continuity of your organizational judgment without manual data entry errors.

Tip: When using the Hopsule API for bulk migration, group related decisions into Context Packs (Capsules) during the import process. This immediately makes the data portable and searchable within the Brain visualization.

Manual Migration via Hopsule Dashboard

For high-context decisions that require refinement, the Hopsule Dashboard offers a superior interface. This method allows you to clean up old language, update tags, and explicitly link memories to decisions. As you manually migrate a record, take the time to use the Knowledge Graph to visualize how it relates to other decisions. This often reveals contradictions or redundancies in your legacy governance that were previously invisible.

AI-Assisted Ingestion with Hopper

Hopper, our built-in AI assistant, is an invaluable tool for migrating unstructured data. You can feed Hopper raw meeting notes or long-form design documents, and it will suggest drafts for formal decisions. Hopper can also help identify the "why" behind a decision, suggesting entries for your append-only memories. Remember that Hopper is advisory only; a human administrator must always review and accept the decisions Hopper drafts to ensure total authority and governance.

Phase 4: Preserving Context through Memories

The most common mistake in migration is moving the "what" (the decision) but losing the "why" (the memory). Hopsule's philosophy is that enforcement is remembrance. To truly enforce a decision, the team must understand the reasoning and the lessons that led to it. During migration, every legacy record should be split into two parts: the enforceable decision and the supporting memories.

Capturing the Reasoning

Memories in Hopsule are persistent and append-only. When migrating an ADR, the "Context" and "Consequences" sections should be converted into memories linked to the decision. This creates a full traceability chain. If a decision was made because of a specific outage or a limitation in a previous system, that history must be preserved as a memory. This ensures that future team members—and AI agents connected via Hopsule MCP—understand the gravity of the decision.

Handling Version History

Hopsule maintains a full version history of every decision. If your legacy records show that a decision evolved over several months, you should migrate the final state as the current version but add the evolution history as a series of memories. This preserves the organizational judgment process without cluttering the active enforcement layer with outdated versions of a constraint.

Phase 5: Verification and Enforcement

Once the data is migrated, you must verify that the transition from a passive record to an active memory system is complete. Verification involves checking for conflicts, ensuring proper categorization, and confirming that the enforcement mechanisms are active.

Conflict Detection in the Knowledge Graph

Use the Knowledge Graph (also known as the Brain) to visualize your migrated decisions. The Brain will help you identify clusters of decisions that might be redundant or, more importantly, contradictory. Since Hopsule is a governance system, resolving these contradictions is essential. Hopper can assist by analyzing your Context Packs and flagging decisions that appear to overlap or conflict with one another.

Testing IDE Enforcement

The true test of a successful migration is whether the decisions are being remembered where work actually happens. Open your primary projects in Hopsule for VS Code. Browse the decision tree in the sidebar and ensure that the migrated decisions are visible. If you have defined specific code patterns in your decisions, verify that the IDE extension surfaces warnings when those patterns are violated. This confirms that your migration has successfully moved from "documentation" to "enforcement."

Phase 6: Decommissioning Legacy Tools

To prevent a "split authority" scenario, you must decommission the legacy tools once migration is verified. If team members continue to look at old documents for guidance, the benefits of Hopsule's context-aware memory system will be diminished. Governance requires a single, authoritative source.

1. Set Legacy Records to Read-Only: Lock your old ADR repositories or document folders to prevent new entries.

2. Redirect Links: Update any internal pointers (such as README files or onboarding guides) to point directly to the relevant Context Pack in the Hopsule Dashboard.

3. Final Archive: Create a final export of your legacy data for compliance purposes and store it in a secure, non-active location.

Important: Ensure that all team members have their Hopsule CLI authenticated and their Hopsule for VS Code extension installed before the final decommissioning of legacy tools. This ensures a seamless transition without a gap in governance.

Phase 7: Training and Cultural Transition

The final step in migration is cultural. Your team must move from a mindset of "writing docs" to a mindset of "preserving memory." This requires training on how to interact with Hopsule's various surfaces. Engineering leaders should demonstrate how to use the Hopsule CLI to check project status and how to use Hopper to query the organization's collective judgment.

Onboarding Developers

New developers should be introduced to Hopsule on day one. Show them how Context Packs provide the necessary background for their specific projects. Explain that the Hopsule IDE Extension is there to help them remember the team's agreements, not to control their creativity. When a developer understands that "enforcement is remembrance," they are more likely to contribute high-quality memories and respect the established decisions.

Establishing a Rhythm of Remembrance

Incorporate Hopsule into your existing rituals. During architecture reviews, use the Hopsule Dashboard to record new decisions in real-time. During post-mortems, add the lessons learned as memories linked to the relevant architectural decisions. By making Hopsule a natural part of the engineering lifecycle, you ensure that the migration is not a one-time event, but the beginning of a more resilient, context-aware organization.

Tip: Use the Hopsule API to send activity feeds to your team's communication channels. This keeps the organization aware of new decisions and changes to existing Capsules, reinforcing Hopsule's role as the central authority for governance.