Memory API

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

Use only the capabilities your app needs:

• memory_search
• memory_save
• memory_propose

Search Memory

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,
    "contract_version": "2026-07-11",
    "visibility": "organization_internal"
  }'

Example response:

{
  "ok": true,
  "contract_version": "2026-07-11",
  "trace_id": 1096,
  "grounding_status": "grounded",
  "grounding_reason": "approved_evidence_directly_supports_request",
  "generated_at": "2026-07-11T19:22:31Z",
  "corpus_revision": "corpus-2026-07-11-1",
  "index_revision": "index-2026-07-11-1",
  "results": [
    {
      "reference_id": "memory-item:1008:revision:7:chunk:16071",
      "memory_item_id": 1008,
      "memory_source_id": 1024,
      "memory_chunk_ids": [16071],
      "title": "External assistant API release notes",
      "source_uri": "https://example.com/docs/assistant-api",
      "source_date": "2026-07-10T18:00:00Z",
      "revision_date": "2026-07-11T18:45:00Z",
      "visibility": "organization_internal",
      "audience": "internal",
      "authority": {
        "level": "approved_source",
        "score": 90,
        "role": "authoritative"
      },
      "excerpt": "The external assistant can draft replies and accept reviewed feedback.",
      "relevance": {
        "score": 0.91,
        "method": "semantic"
      },
      "freshness": {
        "status": "current",
        "effective_at": "2026-07-10T18:00:00Z",
        "expires_at": null
      },
      "limitations": [],
      "conflicts": [],
      "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": {
    "grounding_status": "grounded",
    "context": "Short context package text for the connector.",
    "summary": "1 memory result(s)",
    "sections": {},
    "gaps": []
  }
}

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

grounding_status is grounded only when semantic sufficiency evaluation confirms that eligible authoritative evidence directly supports the request as asked. Related subject matter is not enough. grounding_reason records that decision. Under authoritative_required, an insufficient response has empty results and empty context_package.context. Standard internal-memory searches may still return authorized tool-private, organization-internal, supporting, or background records with grounding_status: insufficient; those records are useful memory results, but they are not authoritative grounding for a factual answer. Do not treat headings, summaries, or non-grounding results as authoritative evidence.

{
  "ok": true,
  "contract_version": "2026-07-11",
  "trace_id": 1097,
  "grounding_status": "insufficient",
  "grounding_reason": "approved_evidence_does_not_support_request",
  "generated_at": "2026-07-11T19:25:00Z",
  "corpus_revision": "corpus-2026-07-11-1",
  "index_revision": "index-2026-07-11-1",
  "results": [],
  "context_package": {
    "grounding_status": "insufficient",
    "context": "",
    "summary": "No eligible evidence found",
    "sections": {},
    "gaps": ["No current approved source supports the query."]
  }
}

The source policy configured by the organization determines whether a result is authoritative, supporting, background, or internal. Your connector does not infer authority from wording, URLs, or organization-specific keywords.

trace_verified confirms that a result belongs to this organization-scoped recall trace. For backward compatibility, grounding_eligible remains true only for approved, current, conflict-free authoritative evidence. approved_evidence_eligible is true for authoritative or supporting evidence that passes the same approval and freshness checks. Supporting evidence can supplement an authoritative answer, but it cannot ground a response by itself. Consumers must not reconstruct either value from caller-provided labels.

Leave workflow out to search all eligible memory available to the organization and connector. Supply it only when your integration intentionally needs a narrower workflow scope. Workflow records provenance; it is not an organization boundary.

Use source_workflow when you need to narrow source provenance without changing the trace workflow. Use chatbot_id to narrow results to an organization-owned assistant. Both fields are optional, and Bombyx rejects a chatbot from another organization.

Fetch A Memory Item

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

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

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

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

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

Tell Bombyx which search results helped.

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,
  "used_count": 1,
  "ignored_count": 0,
  "unreported_count": 0
}

The used and ignored IDs must belong to the trace and cannot overlap. unreported_count tells you how many returned items were in neither list.

Dynamic Brain Wiki

The Brain Wiki exposes the current compiled Brain as organization-specific pages. The catalog is dynamic. Discover it instead of hard-coding topic keys.

List pages with a connector that has memory_search:

curl "https://bombyxlabs.com/app/api/tool-connectors/v1/brain/wiki?query=service&limit=25" \
  -H "Authorization: Bearer btx_your_token_here"

Get the complete current page before using or replacing it:

curl https://bombyxlabs.com/app/api/tool-connectors/v1/brain/wiki/services \
  -H "Authorization: Bearer btx_your_token_here"

The response includes generation_uuid, bucket_artifact_hash, and display_body_hash. These bind a proposed replacement to the exact page state you read. Allowed pages and sources are filtered by the connector’s Brain access policy.

To propose a reviewed change, send the complete replacement body with a connector that also has memory_propose:

curl https://bombyxlabs.com/app/api/tool-connectors/v1/brain/wiki/services/proposals \
  -H "Authorization: Bearer btx_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "replacement_markdown": "Complete current services page in Markdown.",
    "reason": "Clarify the current service scope.",
    "generation_uuid": "generation-from-latest-get",
    "bucket_artifact_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "display_body_hash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "idempotency_key": "services-refresh-2026-07-19"
  }'

The endpoint returns 201 for the pending proposal. It never publishes or approves. Exact retry replays are idempotent; stale page hashes return 409. Unknown input fields fail validation.

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.
• Treating grounding_status: insufficient as a grounded result.
• Using a result without checking its authority, freshness, limitations, and conflicts.
• Expecting tool_private memory to appear for a different connector.
• Assuming Brain Wiki topic keys are the same for every organization.
• Sending only a patch or excerpt instead of a complete Brain Wiki page replacement.

Related Pages

• Authentication
• MCP Connector
• API Reference