Skip to content
Bombyx Developer Docs

Memory API

What This Does

Section titled “What This Does”

The Memory API lets a connector work with Bombyx organization memory.

Use it when your app needs to:

  • Search for relevant organization context
  • Save a private work note for the same connector
  • Save an internal note for other internal tools
  • Propose a customer-facing fact for review
  • Report which search results were actually useful

Organization memory stays isolated by organization. Tool-private memory stays scoped to the same connector client key.

Before You Start

Section titled “Before You Start”

Use only the capabilities your app needs:

  • memory_search
  • memory_save
  • memory_propose

Search Memory

Section titled “Search Memory”
Terminal window
curl https://bombyxlabs.com/app/api/tool-connectors/v1/memory/search \
  -H "Authorization: Bearer btx_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "pricing package notes",
    "limit": 5,
    "include_context_package": true,
    "visibility": "organization_internal"
  }'

Example response:

{
  "ok": true,
  "trace_id": 1096,
  "results": [
    {
      "memory_item_id": 1008,
      "memory_source_id": 1024,
      "memory_chunk_ids": [16071],
      "summary": "External assistant reply and feedback API was deployed to production.",
      "type": "work_log",
      "source_label": "External assistant API deployed",
      "source_type": "tool_work_log",
      "review_status": "confirmed",
      "lifecycle_status": "active",
      "freshness_category": "current"
    }
  ],
  "context_package": {
    "context": "Short context package text for the connector.",
    "summary": "1 memory result(s)",
    "sections": {}
  }
}

Save trace_id if your app uses the results. Report usage after the task.

Fetch A Memory Item

Section titled “Fetch A Memory Item”
Terminal window
curl https://bombyxlabs.com/app/api/tool-connectors/v1/memory/items/1008 \
  -H "Authorization: Bearer btx_your_token_here"

This returns the same item shape as search, plus content when the item is available to the connector.

Save Tool Memory

Section titled “Save Tool Memory”

Save memory directly only for internal tool use. This does not create customer-facing assistant instructions.

Terminal window
curl https://bombyxlabs.com/app/api/tool-connectors/v1/memory/save \
  -H "Authorization: Bearer btx_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "handoff",
    "title": "Support inbox rollout note",
    "content": "The inbox connector should keep annual billing examples in the email thread until pricing docs are finalized.",
    "summary": "Inbox connector annual billing handoff.",
    "visibility": "tool_private",
    "idempotency_key": "support-inbox-rollout-note",
    "source_uri": "supportdesk://threads/123"
  }'

Example response:

{
  "ok": true,
  "memory_source_id": 1201,
  "memory_item_id": 1402,
  "status": "confirmed",
  "visibility": "tool_private",
  "unsafe_flags": []
}

Visibility options:

  • tool_private: only this connector client key can retrieve it.
  • organization_internal: other internal tools for the same organization can retrieve it.

Propose A Memory Update

Section titled “Propose A Memory Update”

Use proposals for customer-facing or business facts that should be reviewed before they affect assistant answers.

Terminal window
curl https://bombyxlabs.com/app/api/tool-connectors/v1/memory/proposals \
  -H "Authorization: Bearer btx_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Annual billing answer",
    "content": "Customers can ask for annual billing after onboarding.",
    "proposed_type": "fact",
    "source_uri": "supportdesk://threads/123",
    "proposed_policy": {
      "review_required": true,
      "customer_safe_candidate": true
    }
  }'

Example response:

{
  "ok": true,
  "memory_source_id": 1202,
  "proposal_id": 553,
  "status": "captured",
  "unsafe_flags": []
}

Report Usage

Section titled “Report Usage”

Tell Bombyx which search results helped.

Terminal window
curl https://bombyxlabs.com/app/api/tool-connectors/v1/memory/usage \
  -H "Authorization: Bearer btx_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": 1096,
    "used_item_ids": [1008],
    "ignored_item_ids": []
  }'

Example response:

{
  "ok": true
}

Common Mistakes

Section titled “Common Mistakes”
  • Saving customer-facing business facts directly with /memory/save. Use /memory/proposals.
  • Saving secrets or raw customer dumps. Bombyx blocks unsafe content when detected, but your app should still avoid sending it.
  • Forgetting to report usage after using search results.
  • Expecting tool_private memory to appear for a different connector.
Section titled “Related Pages”