Troubleshooting

Overview of Troubleshooting Philosophy

Hopsule is designed to be a resilient, context-aware memory system that preserves organizational judgment across time and tools. When the flow of decision-making or enforcement is interrupted, it is often a matter of context synchronization or authentication alignment. This guide provides comprehensive solutions for restoring the integrity of your decision and memory layers across all Hopsule product surfaces. Our goal is to ensure that your team's remembrance remains uninterrupted and that enforcement continues to serve as a guiding light rather than an obstacle.

Important: Before diving into specific surface issues, ensure that your local environment has a stable connection to the Hopsule network. Most synchronization issues are resolved by verifying that your session is active and that your local tools are correctly linked to your organization’s central memory. If you are using Hopsule Enterprise (Self-Hosted), please consult your internal infrastructure team to verify that the local deployment is reachable.

Hopsule Dashboard

Session Persistence and Login Issues

The Hopsule Dashboard serves as the central authority for managing the lifecycle of decisions and the visualization of your organization's Brain. If you encounter issues where your session appears to expire prematurely or you cannot log in, it is typically related to browser-level security settings or token expiration. Hopsule uses high-security session management to protect your organization's memories, and certain aggressive browser configurations may interfere with these protocols.

1. Clear your browser's site data specifically for the Hopsule Dashboard domain to remove any stale authentication tokens.

2. Ensure that third-party cookies are not being blocked, as Hopsule relies on secure, encrypted tokens to maintain your session across the memory layer.

3. If you are using a VPN or corporate proxy, verify that it is not stripping the security headers required for Hopsule’s end-to-end encryption.

Tip: If you are frequently logged out, check if your organization has enforced a strict session duration policy within the Security Settings of the Hopsule Dashboard. Administrators can adjust these durations to balance security and convenience.

Performance and Knowledge Graph Rendering

The Knowledge Graph, or the Brain, is a complex visualization of the relationships between decisions, memories, and capsules. For organizations with thousands of active decisions, the Brain may occasionally experience rendering delays. This is usually not a data issue but a client-side resource limitation. Ensure that your hardware acceleration is enabled in your browser settings to allow the Knowledge Graph to utilize your system's resources effectively.

If specific decisions or memories are missing from the Knowledge Graph, verify that they have not been moved to a Deprecated or Historical state. By default, the Brain prioritizes active governance and current enforcement constraints. You can adjust the filters in the sidebar to include historical context if you need to trace the evolution of a specific decision path.

Search and Notification Failures

Search within the Hopsule Dashboard is powered by a context-aware indexing system that links memories to decisions. If a search does not return expected results, it may be because the index is currently processing a large batch of new memories or capsule imports. Wait a few moments and try again. Additionally, ensure that your search terms align with the tags and categories established by your team, as Hopsule prioritizes structured organizational judgment over raw text matching.

Notification preferences are critical for staying informed about decision lifecycle changes. If you are not receiving real-time updates, navigate to User Settings and verify that your notification triggers are correctly mapped to the projects you are monitoring. If preferences fail to save, ensure you are not running any browser extensions that interfere with outgoing API requests to the Hopsule governance layer.

Hopsule CLI

Installation and Environment Configuration

The Hopsule CLI is the primary interface for developers to interact with the memory system from their terminal. Installation failures are often the result of permission conflicts or path environment variables. When installing the Hopsule CLI, ensure that your system's binary path is correctly configured to recognize the hopsule command. If the installation script fails, verify that you have the necessary write permissions for your global binary directory.

Important: Hopsule CLI requires a secure connection to the memory layer. If you are operating behind a strict firewall, you must whitelist the Hopsule API endpoints to allow the CLI to synchronize decisions and memories. Failure to do so will result in "Connection Refused" or "Timeout" errors during command execution.

Authentication and Token Management

The CLI uses secure tokens to represent your authority within the organization. If you receive authentication errors, your local token may have expired or been revoked from the Hopsule Dashboard. You can re-authenticate by running the login command, which will guide you through a secure browser-based handshake. For CI/CD environments, ensure that the HOPSULE_TOKEN environment variable is correctly set and has the appropriate permissions to read or write to the decision layer.

Interactive TUI and Shell Completions

The Hopsule CLI features a rich terminal user interface (TUI) for managing decisions. If the TUI displays garbled characters or fails to render the ASCII art, ensure that your terminal emulator supports UTF-8 encoding and that your font includes the necessary symbols. If shell completions are not working, you must manually source the completion script in your shell configuration file (e.g., .zshrc or .bashrc). The CLI provides a dedicated command to generate these completion scripts for various shell environments.

Hopsule for VS Code

Extension Activation and Enforcement

Hopsule for VS Code is designed to surface decision enforcement directly within your development workflow. If the extension fails to activate, it is often due to a conflict with other IDE extensions or an outdated version of the editor. Ensure that you are using a supported version of VS Code or Cursor. If the Hopsule icon does not appear in the sidebar, check the Extension Output log for any initialization errors related to local workspace indexing.

A common issue is the lack of visible diagnostics (warnings) when code contradicts an accepted decision. This occurs if the extension has not correctly mapped the local file structure to the relevant Context Packs. Ensure that your project root contains a valid Hopsule configuration file and that you have synchronized the latest decisions from the dashboard. Enforcement is a reflection of remembrance; if the extension does not "remember" the decision, it cannot enforce it.

Resource Consumption and Connectivity

Hopsule for VS Code processes your code locally to ensure that no source code ever leaves your environment. This privacy-first approach requires some local computational resources. If you notice the extension consuming excessive memory, it may be attempting to index a very large directory that should be excluded (e.g., build artifacts or third-party dependencies). You can refine the enforcement scope in the extension settings to focus only on your primary source directories.

If the connection to the Hopsule memory layer is lost, the extension will enter a "Degraded Mode." In this state, it will continue to enforce decisions that were cached during the last successful synchronization, but it will not be able to pull new memories or suggest improvements via Hopper. To restore connectivity, verify your authentication status in the Hopsule sidebar within the IDE.

Hopsule MCP

AI Agent Connectivity

The Hopsule MCP (Model Context Protocol) server allows AI agents to become context-aware by granting them read-only access to your team's decisions and memories. If your AI agent (such as Claude or an agentic workflow) cannot connect to the MCP server, the primary cause is usually an incorrect configuration of the MCP host. Ensure that the MCP server path is correctly defined in your agent's configuration file and that the Hopsule CLI is installed, as the MCP server often leverages the CLI's underlying authentication layer.

Tip: Always verify that the Hopsule MCP server is running by checking the process list in your terminal. If the server crashes on startup, it is likely due to a port conflict or a lack of permissions to access the local decision cache.

Context Visibility and Decision Retrieval

When an AI agent is connected but fails to reference existing decisions, it is likely a matter of context scoping. AI agents can only "see" the decisions and memories that are included in the active Context Packs shared with that agent. Use the Hopsule Dashboard to verify that the decisions you expect the AI to know are part of an Active or Frozen Capsule. If a decision is still in Draft or Pending status, it will not be surfaced via the MCP to prevent the AI from providing guidance based on unaccepted governance.

Remember that Hopsule MCP provides read-only access. If you are attempting to have an AI agent create or mutate a decision via the MCP, it will fail by design. Decisions are human-driven commitments; the AI is there to remember and advise, not to exercise authority.

Hopsule API

Authentication and Rate Limiting

The Hopsule API provides programmatic access to your organization's memory layer. 401 Unauthorized errors are the most frequent issue, typically caused by missing or incorrectly formatted Bearer tokens in the Authorization header. Ensure that your API keys are active and have not been rotated. If you are receiving 429 Rate Limit Exceeded errors, your integration is exceeding the request threshold for your current plan tier. Hopsule implements these limits to ensure the stability of the governance layer for all users.

To mitigate rate limiting, we recommend implementing local caching for decisions and memories that do not change frequently. Since Hopsule decisions are designed to be durable, you rarely need to fetch the entire decision set more than once per session. Use webhooks to listen for specific lifecycle changes and update your local cache only when necessary.

Webhook Delivery and Timeouts

Webhooks are essential for maintaining real-time synchronization between Hopsule and your custom internal tools. If you are not receiving webhook events, verify that your endpoint is publicly reachable and returns a 2xx status code within the required timeout period. Hopsule will attempt to redeliver failed webhooks using an exponential backoff strategy, but after a certain number of failures, the webhook subscription may be automatically disabled to prevent system strain.

Important: All Hopsule webhooks are signed for security. Your integration must verify the signature header to ensure that the event originated from the Hopsule authority. If signature verification fails, check that you are using the correct secret key associated with that specific webhook configuration in the Hopsule Dashboard.

General and Account Management

Data Sync Delays

Hopsule is a distributed system where decisions made in the Dashboard must propagate to the CLI, IDE, and AI agents. While this usually happens in near real-time, network latency or local caching policies can occasionally cause a delay. If you have accepted a decision in the Dashboard but do not see it enforced in VS Code, use the Sync button in the extension or run hopsule sync in the CLI to force an immediate refresh of the local memory cache.

Organizational memory is preserved through append-only entries. If you feel that the context of a decision is missing, check the Memories tab associated with that decision. Memories are never deleted or overwritten, ensuring that the reasoning behind a decision is always traceable, even if the decision itself has been deprecated.

2FA Recovery and API Key Resets

If you lose access to your two-factor authentication (2FA) device, you must use one of the recovery codes provided during the initial setup. Hopsule support cannot bypass 2FA requirements due to our strict security and encryption protocols. If you have lost both your 2FA device and your recovery codes, your organization administrator must reset your account's security factors from the Member Management panel.

API keys should be treated with the same level of security as your primary password. If an API key is compromised, revoke it immediately from the Hopsule Dashboard and generate a new one. All integrations using the old key will immediately lose access to the memory layer. This is a critical step in maintaining the integrity of your organization's governance and ensuring that unauthorized entities cannot influence or view your decision history.

Restoring Context Packs

Context Packs (Capsules) are designed to survive time and system changes. If a Capsule appears to be empty or missing data, verify its lifecycle state. A Historical Capsule may be hidden from the primary view to reduce clutter. You can restore a Capsule to Active status if the decisions within it need to be enforced again in a new project context. This portability is what allows Hopsule to function as a long-term memory system rather than a temporary project management tool.

For further assistance, please contact your organization's Hopsule administrator or reach out to our support team through the official channels. We are committed to ensuring that your organization never forgets its most important decisions.