Searching and Browsing Memories

Introduction

In high-velocity engineering organizations, the "why" behind a technical choice is often more valuable than the choice itself. Hopsule ensures that this context is never lost by treating memories as append-only, immutable records of organizational judgment that provide the necessary background for every accepted decision. This article provides an exhaustive guide on how to navigate, filter, and search through your team's collective memory using the Hopsule Dashboard, Hopsule CLI, and our AI assistant, Hopper, to ensure total context-awareness across your entire project lifecycle.

Effective retrieval of memories is the cornerstone of Hopsule’s philosophy: enforcement is remembrance, not control. By mastering the search and browsing capabilities of the system, you enable your team to understand the historical reasoning that informs current constraints, preventing the repetition of past mistakes and ensuring that every developer, regardless of their tenure, has access to the same depth of organizational context.

Prerequisites

Before you begin searching and browsing memories, ensure you have met the following requirements:

• An active Hopsule account with access to at least one Project or Organization.

• A minimum of "Reader" permissions within the project you wish to browse.

• The Hopsule CLI installed and authenticated if you intend to browse memories from the terminal.

• The Hopsule for VS Code extension installed if you wish to view context inline while coding.

• At least one Context Pack (Capsule) must be active to see memories associated with specific project states.

Navigating the Memories Tab in Hopsule Dashboard

The Hopsule Dashboard serves as the primary interface for visual exploration of your team's memory. To access your memories, log in to the dashboard and select Memories from the primary navigation sidebar on the left. This view is designed to provide a chronological and searchable record of every append-only entry ever created in your organization.

1. The Memory List View: By default, the Memories tab displays a list of all entries in reverse chronological order. Each entry shows the memory title, the author, the creation date, and the associated Context Pack.

2. Using the Global Search Bar: At the top of the Hopsule Dashboard, you will find the Global Search bar. This is powered by Hopper, our context-aware assistant. You can type keywords, phrases, or specific technical terms. Hopper does not just look for literal string matches; it understands the context of your query to surface relevant memories even if the exact wording differs.

3. Filtering by Category: On the right-hand side of the Memory List, use the Filter panel to narrow down entries by category. Common categories include "Architecture," "Security," "Performance," and "Legacy Migration." Filtering by category is essential when you are looking for specific types of organizational judgment.

4. Filtering by Author: If you recall that a specific senior engineer or architect provided the reasoning for a change, use the Author dropdown to isolate their contributions. This is particularly useful for tracking the evolution of thought from key technical leaders.

5. Date Range Selection: Use the calendar picker to view memories from a specific sprint, quarter, or year. This helps in auditing the reasoning behind decisions made during specific historical periods of the project.

6. Linked Decisions Filter: One of the most powerful features of Hopsule is the traceability between memories and decisions. Toggle the Linked Only filter to see only those memories that directly support an Accepted Decision. This allows you to ignore general context and focus strictly on the "why" behind active constraints.

Visualizing Context with the Knowledge Graph (The Brain)

For complex projects, a list view may not suffice to show the intricate web of reasoning that connects different parts of a system. The Knowledge Graph, also referred to as "The Brain," provides a multi-dimensional visualization of your project's memory.

1. Click the Brain icon in the top-right corner of the Memories view.

2. Nodes and Edges: In this view, memories are represented as nodes, and their relationships to Decisions and Context Packs are represented as edges (lines).

3. Interactive Exploration: Click on any memory node to open a side panel containing the full text of the memory, its version history, and its links.

4. Cluster Analysis: Observe how memories cluster around specific decisions. A dense cluster indicates a high-stakes decision with significant historical context, while isolated memories may indicate areas where the team’s reasoning has not yet been fully integrated into the governance layer.

5. Pathfinding: Use the graph to trace the lineage of a decision. By following the edges, you can see the sequence of memories that led from an initial draft to a final, enforced constraint.

Browsing Memories via Hopsule CLI

For developers who prefer to stay in the terminal, the Hopsule CLI offers a robust set of tools for memory retrieval. This is particularly useful during code reviews or when investigating a bug that seems to contradict existing project logic.

1. Basic Listing: Run hopsule memory list to see a paginated list of the most recent memories in your current project context.

2. Interactive TUI: Run hopsule memory browse to launch the interactive Terminal User Interface (TUI). This dashboard uses ASCII art and keyboard-driven navigation to let you scroll through memories, view details, and filter by tags without leaving your terminal.

3. Searching by Tag: Use the command hopsule memory search --tag [tag-name] to quickly find context related to specific components or technologies mentioned in your memories.

4. Viewing Detailed Context: Once you find a memory ID, use hopsule memory show [id] to read the full entry. The CLI will display the append-only history, ensuring you see the full evolution of that specific piece of context.

Context-Aware Retrieval with Hopper

Hopper is not a chatbot; it is an advisory AI assistant that uses your team's decisions and memories as its primary source of truth. When you search using Hopper, you are performing a RAG-powered (Retrieval-Augmented Generation) query against your organization's judgment.

1. Natural Language Queries: Instead of keywords, you can ask Hopper questions like, "Why did we decide to move away from centralized state management last year?"

2. Contextual Suggestions: As you type a new memory or draft a decision in the Hopsule Dashboard, Hopper will automatically suggest related memories in the sidebar. This prevents the creation of redundant or conflicting entries.

3. Conflict Detection: If you are browsing memories and find two entries that seem to offer contradictory reasoning, you can ask Hopper to "Analyze conflicts in the 'Authentication' category." Hopper will highlight the discrepancies, allowing a human lead to intervene and create a clarifying decision.

Using Hopsule for VS Code to Browse Memories

The Hopsule for VS Code extension brings memory retrieval directly into your development environment. This ensures that the "why" is always available at the point of implementation.

1. The Hopsule Sidebar: Open the Hopsule view in the VS Code Activity Bar. Here, you can browse a tree view of all memories associated with the Active Capsule for your current workspace.

2. Hover for Context: When the extension detects a code pattern that relates to an Accepted Decision, it will provide an inline warning. Hovering over this warning will display the associated Memories, explaining the reasoning behind the constraint.

3. Local Processing: Note that searching and browsing within the IDE extension happens with a focus on privacy. While the search queries are processed to find matches, your actual source code is never sent to Hopsule servers; only the metadata required to link memories to decisions is utilized.

Tips and Best Practices

• Use Specific Tags: When creating memories, use consistent tags. When browsing, use these tags to filter out noise. For example, tagging memories with #performance-tradeoff makes it easy to find all instances where speed was sacrificed for reliability.

• Link Early and Often: The most searchable memories are those linked to Decisions. When browsing, prioritize "Linked" entries as they represent the most authoritative context.

• Leverage Context Packs: If you are working on a multi-repo project, use the Capsule filter to only see memories relevant to the specific project surface you are currently handling.

• Review the Activity Feed: The Activity Feed on the Hopsule Dashboard is a great way to browse memories as they are created in real-time. This helps senior leaders maintain a pulse on the team's evolving reasoning.

• Trust the Append-Only Nature: Remember that memories are never deleted. If you can't find something, it's likely a filtering issue rather than a data loss issue. Always clear your filters if a search returns no results.

Troubleshooting

Related Articles

• Creating and Managing Memories

• Understanding the Decision Lifecycle

• Working with Context Packs (Capsules)

• Using Hopper for Contextual Assistance