Hopsule API: Memories Endpoint

Introduction to the Memories API

The Hopsule API provides a robust interface for managing the organizational memory layer of your engineering team. Memories are persistent, append-only entries that capture the "why" behind every technical choice, architectural shift, and strategic pivot. Unlike ephemeral communication or static documentation, memories are designed for high-fidelity context preservation and long-term organizational remembrance. By using the Memories endpoint, teams can programmatically integrate context capture into their existing workflows, ensuring that the reasoning behind decisions remains accessible to both human developers and AI agents via Hopsule MCP.

Each memory entry serves as a building block for the Knowledge Graph, creating a traceable history of organizational judgment. When integrated with Hopsule for VS Code or the Hopsule CLI, these memories provide the necessary context for decision enforcement, helping developers understand the constraints they encounter in their daily work. This API reference details how to interact with the memory layer to create, retrieve, and link context to your team's decision-making process.

Important: Memories in Hopsule are append-only. To maintain the integrity of the organizational record, memories cannot be deleted or overwritten once they are accepted into the system. This ensures that the historical context remains untampered and reliable for future audits and context retrieval by Hopper.

Authentication and Security

All requests to the Hopsule API require a valid API token for authentication. Tokens are managed through the Hopsule Dashboard under the organization settings. Every request must include the Authorization header with a Bearer token. Hopsule prioritizes data sovereignty and security; all API traffic is secured via TLS 1.3, and data at rest is protected using AES-256 encryption. For organizations utilizing Hopsule Enterprise (Self-Hosted), the API endpoints remain consistent with the cloud version, though the base URL will reflect your internal infrastructure.

Tip: Keep your API tokens secure and never commit them to version control. Use environment variables or a secure secret management system to handle authentication credentials in your CI/CD pipelines or custom integrations.

List Memories

GET /v1/memories

This endpoint retrieves a paginated list of memories from your organization's memory layer. It is the primary method for auditing historical context or feeding memory data into external reporting tools. The endpoint supports several query parameters to filter the results by decision association, tags, or full-text search, allowing you to narrow down the context to specific projects or timeframes.

Query Parameters

Response Structure

The response returns an object containing an array of memory entries and metadata for pagination. Each memory entry includes the unique identifier, the title, the content, and the timestamp of creation. Because memories are immutable, the updated_at field will always match the created_at field unless the memory is part of a Context Pack that has been versioned.

{
  "data": [
    {
      "id": "mem_01HF89ZXY",
      "title": "Rationale for adopting Event-Driven Architecture",
      "content": "During the Q3 planning, the team identified that our monolithic approach was creating bottlenecks in deployment. This memory captures the consensus that shifting to an event-driven model will allow for independent scaling of the order processing service.",
      "tags": ["architecture", "scaling", "q3-planning"],
      "created_at": "2023-10-24T14:30:00Z",
      "author": "engineering_lead_01"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 10
  }
}

{
  "data": [
    {
      "id": "mem_01HF89ZXY",
      "title": "Rationale for adopting Event-Driven Architecture",
      "content": "During the Q3 planning, the team identified that our monolithic approach was creating bottlenecks in deployment. This memory captures the consensus that shifting to an event-driven model will allow for independent scaling of the order processing service.",
      "tags": ["architecture", "scaling", "q3-planning"],
      "created_at": "2023-10-24T14:30:00Z",
      "author": "engineering_lead_01"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 10
  }
}

{
  "data": [
    {
      "id": "mem_01HF89ZXY",
      "title": "Rationale for adopting Event-Driven Architecture",
      "content": "During the Q3 planning, the team identified that our monolithic approach was creating bottlenecks in deployment. This memory captures the consensus that shifting to an event-driven model will allow for independent scaling of the order processing service.",
      "tags": ["architecture", "scaling", "q3-planning"],
      "created_at": "2023-10-24T14:30:00Z",
      "author": "engineering_lead_01"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 10
  }
}

{
  "data": [
    {
      "id": "mem_01HF89ZXY",
      "title": "Rationale for adopting Event-Driven Architecture",
      "content": "During the Q3 planning, the team identified that our monolithic approach was creating bottlenecks in deployment. This memory captures the consensus that shifting to an event-driven model will allow for independent scaling of the order processing service.",
      "tags": ["architecture", "scaling", "q3-planning"],
      "created_at": "2023-10-24T14:30:00Z",
      "author": "engineering_lead_01"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 10
  }
}

Create a New Memory

POST /v1/memories

Creating a memory is the act of committing context to the organizational record. This endpoint should be used whenever a significant realization occurs, a meeting results in new insights, or a lesson is learned during the development lifecycle. By programmatically creating memories, you can ensure that the "why" is captured at the moment of discovery, preventing the loss of critical organizational judgment over time.

Request Body Fields

• title (string, required): A concise summary of the memory. This is used for display in the Knowledge Graph and Hopsule Dashboard.

• content (string, required): The detailed reasoning, history, or lesson being preserved. This field supports rich text and is the primary source of context for Hopper.

• decisionSlug (string, optional): The slug of an existing decision to which this memory should be immediately linked.

• tags (array of strings, optional): A list of tags to categorize the memory for easier discovery and filtering.

Example Request

{
  "title": "Legacy Database Migration Constraints",
  "content": "We discovered that the legacy accounting database does not support concurrent connections above 50. This constraint must be remembered when designing the new reconciliation service to avoid connection exhaustion.",
  "decisionSlug": "db-migration-strategy",
  "tags": ["database", "legacy", "constraints"]
}

{
  "title": "Legacy Database Migration Constraints",
  "content": "We discovered that the legacy accounting database does not support concurrent connections above 50. This constraint must be remembered when designing the new reconciliation service to avoid connection exhaustion.",
  "decisionSlug": "db-migration-strategy",
  "tags": ["database", "legacy", "constraints"]
}

{
  "title": "Legacy Database Migration Constraints",
  "content": "We discovered that the legacy accounting database does not support concurrent connections above 50. This constraint must be remembered when designing the new reconciliation service to avoid connection exhaustion.",
  "decisionSlug": "db-migration-strategy",
  "tags": ["database", "legacy", "constraints"]
}

{
  "title": "Legacy Database Migration Constraints",
  "content": "We discovered that the legacy accounting database does not support concurrent connections above 50. This constraint must be remembered when designing the new reconciliation service to avoid connection exhaustion.",
  "decisionSlug": "db-migration-strategy",
  "tags": ["database", "legacy", "constraints"]
}

Important: Once a memory is accepted via this endpoint, it becomes a permanent part of the organization's memory layer. It can be linked to multiple decisions and included in various Context Packs, but the original content remains an immutable record of the team's perspective at that point in time.

Retrieve a Single Memory

GET /v1/memories/:id

This endpoint allows you to fetch the complete details of a specific memory using its unique identifier. This is particularly useful for deep-linking from external tools or for displaying detailed context within a custom developer portal. The response includes all metadata, associated tags, and the full content of the memory.

Response Body

The response will return the memory object. If the memory is linked to any active Context Packs, those associations will be included in the metadata to provide a complete picture of how this memory is currently being utilized for enforcement and remembrance.

{
  "id": "mem_01HF89ZXY",
  "title": "Rationale for adopting Event-Driven Architecture",
  "content": "...",
  "tags": ["architecture", "scaling"],
  "created_at": "2023-10-24T14:30:00Z",
  "linked_decisions_count": 3,
  "active_capsules": ["global-architecture-v2"]
}

{
  "id": "mem_01HF89ZXY",
  "title": "Rationale for adopting Event-Driven Architecture",
  "content": "...",
  "tags": ["architecture", "scaling"],
  "created_at": "2023-10-24T14:30:00Z",
  "linked_decisions_count": 3,
  "active_capsules": ["global-architecture-v2"]
}

{
  "id": "mem_01HF89ZXY",
  "title": "Rationale for adopting Event-Driven Architecture",
  "content": "...",
  "tags": ["architecture", "scaling"],
  "created_at": "2023-10-24T14:30:00Z",
  "linked_decisions_count": 3,
  "active_capsules": ["global-architecture-v2"]
}

{
  "id": "mem_01HF89ZXY",
  "title": "Rationale for adopting Event-Driven Architecture",
  "content": "...",
  "tags": ["architecture", "scaling"],
  "created_at": "2023-10-24T14:30:00Z",
  "linked_decisions_count": 3,
  "active_capsules": ["global-architecture-v2"]
}

Retrieve Linked Decisions

GET /v1/memories/:id/decisions

A core philosophy of Hopsule is that "enforcement is remembrance, not control." To understand why a decision is being enforced, one must look at the memories linked to it. This endpoint returns a list of all decisions that are currently supported by the specified memory. This traceability is essential for maintaining governance and ensuring that technical constraints are always backed by documented reasoning.

Response Structure

The response provides an array of decision objects, including their current lifecycle status (Draft, Pending, Accepted, or Deprecated). This allows teams to see how a single piece of context might be influencing multiple enforceable constraints across the organization.

{
  "memory_id": "mem_01HF89ZXY",
  "decisions": [
    {
      "id": "dec_09876",
      "slug": "use-kafka-for-messaging",
      "status": "Accepted",
      "title": "Standardize on Kafka for all inter-service communication"
    }
  ]
}

{
  "memory_id": "mem_01HF89ZXY",
  "decisions": [
    {
      "id": "dec_09876",
      "slug": "use-kafka-for-messaging",
      "status": "Accepted",
      "title": "Standardize on Kafka for all inter-service communication"
    }
  ]
}

{
  "memory_id": "mem_01HF89ZXY",
  "decisions": [
    {
      "id": "dec_09876",
      "slug": "use-kafka-for-messaging",
      "status": "Accepted",
      "title": "Standardize on Kafka for all inter-service communication"
    }
  ]
}

{
  "memory_id": "mem_01HF89ZXY",
  "decisions": [
    {
      "id": "dec_09876",
      "slug": "use-kafka-for-messaging",
      "status": "Accepted",
      "title": "Standardize on Kafka for all inter-service communication"
    }
  ]
}

Link Memory to a Decision

POST /v1/memories/:id/link

This endpoint establishes a formal link between an existing memory and an existing decision. Linking is a powerful way to build the Knowledge Graph and provide evidence for why a particular decision was accepted. When a developer views a decision in the Hopsule IDE Extension, any linked memories are surfaced to provide the necessary background, reducing friction and increasing compliance with organizational standards.

Request Body

• decisionId (string, required): The unique identifier of the decision to link.

• context_type (string, optional): An optional label to describe the nature of the link (e.g., "primary_reasoning", "historical_precedent", "counter_argument").

Tip: You can link a single memory to multiple decisions. For example, a memory regarding "Security Compliance Requirements" might be linked to decisions about "Data Encryption," "User Authentication," and "Audit Logging." This creates a web of context that makes the Brain visualization more effective for engineering leaders.

Best Practices for Memory Management

To maximize the utility of the Hopsule memory layer, engineering organizations should follow established patterns for context preservation. The goal is to create a high-density environment of organizational judgment that can survive team turnover and system changes. Using the API effectively requires more than just technical integration; it requires a commitment to the philosophy of remembrance.

Contextual Granularity

Avoid creating memories that are too broad or too narrow. A memory should capture a single cohesive thought, lesson, or piece of reasoning. If a memory covers too many topics, it becomes difficult to link it precisely to relevant decisions. Conversely, if it is too narrow, the Knowledge Graph may become cluttered with fragmented information. Aim for a level of detail that provides immediate clarity to a developer who was not present when the original judgment was made.

Tagging Strategy

Consistent tagging is crucial for the discoverability of context. Use the tags field in the POST /v1/memories endpoint to categorize entries by project, technology, or department. This allows Hopper to provide more relevant suggestions and helps engineering leaders filter the Hopsule Dashboard to see context specific to their domain. Common tagging patterns include architecture, security, onboarding, and post-mortem.

Integration with CI/CD

Consider automating the creation of memories during key lifecycle events. For example, when a post-mortem document is finalized, a summary can be pushed to the Hopsule API as a memory. This ensures that the lessons learned from an incident are preserved as enforceable context for future architectural decisions, rather than being lost in a document that no one reads. This programmatic approach turns passive documentation into active, enforceable organizational memory.

Error Handling and Status Codes

The Hopsule API uses standard HTTP response codes to indicate the success or failure of an API request. In the event of an error, the response body will contain a detailed message to help you diagnose the issue. Common error scenarios include authentication failures, attempts to link to non-existent decisions, or exceeding the rate limits of your plan tier.

For more information on managing your organization's decisions and how they interact with memories, please refer to the Decision Management Guide and the Context Packs Overview. If you are building a custom agent integration, the Hopsule MCP Documentation provides specific details on how AI agents consume this memory data.