Core Concepts

Honeycomb is your organization's memory. You send it the raw material of everyday work — messages, emails, documents, tickets — and it distills that into durable, connected, access-controlled knowledge that you can query in plain language. This page gives you the mental model behind everything else in these docs: what each building block is, how they relate, and why Honeycomb never forgets when it knew something.

At a glance

• Entries are the raw things you send — one message, email, or document per entry. Everything else is derived from them.
• Memories and facts are the distilled knowledge: atomic, timestamped statements extracted from your entries.
• Entities are the people, companies, and projects those statements are about — automatically deduplicated across sources, so tom.chen on GitHub and "Tom Chen" in email become one person.
• The knowledge graph connects entities with typed relationships that strengthen when re-confirmed and fade when they stop appearing.
• Spaces decide who can see what. Every record lives in one or more Spaces, and every read is scoped to the caller's access.
• Answers come with receipts. When you ask a question, Honeycomb cites the exact source entries behind every claim — or honestly declines when the evidence isn't there.

The memory model

One ingested artifact fans out into a small constellation of connected knowledge:

Each layer is explained below, in the order your data moves through them.

Entries: the raw material

An entry is one artifact exactly as you sent it — a Slack message, an email, a meeting transcript, a support ticket, a document. You create entries through POST /api/v1/ingest (or in batches, via file upload, via connectors, or the honeycomb_ingest MCP tool):

curl -X POST https://your-instance.example.com/api/v1/ingest \
  -H "Authorization: Bearer hck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Northwind Robotics renewed at $1.8M ARR. Priya Sharma owns the account now.",
    "metadata": {
      "namespace": "sales",
      "contentType": "message",
      "source": "slack",
      "sourceChannel": "#sales",
      "externalRef": "slack:C042:1719900000.12345"
    }
  }'

Honeycomb stores the entry, makes it immediately searchable, and returns 201:

{
  "id": "ent_9f2c81",
  "chunksCreated": 1,
  "entitiesExtracted": 0,
  "memoriesExtracted": 0,
  "factsRecorded": 0
}

Note: the extraction counts are always 0 in the immediate response. Distillation happens asynchronously in the background — the entities, memories, and facts land seconds later. The entry itself is findable by search right away.

Entries are the anchor of provenance: every memory, fact, and relationship in Honeycomb points back to the entry (or entries) that produced it. The externalRef you supply also powers deduplication — resending the same artifact is a safe no-op, so webhook retries never create duplicates.

Memories and facts: distilled knowledge

From each entry, Honeycomb extracts two kinds of knowledge:

Memories are the retrieval backbone — each one is individually searchable and self-contained, so it makes sense out of context. Facts power precise, structured recall: "what is Northwind's ARR right now?" and "what was it last March?" are both answerable, because each fact knows the window during which it was true.

Facts are also trust-ranked by source. When your HR directory and a chat message disagree about someone's job title, the directory wins — a lower-trust source never silently overwrites what a higher-trust source established.

Entities: one node per real thing

An entity is a deduplicated node for a real-world thing: a person, a company, a product, a project, a deal. Honeycomb resolves mentions across all your sources into a single canonical entity — "Priya", [email protected], and the Slack user who posted in #sales all converge on one Priya Sharma, accumulating aliases, attributes, and mention counts as evidence arrives.

This cross-source identity resolution is what makes organizational memory work: questions about a person surface everything known about them regardless of which tool the knowledge came from. Retrieve any entity's consolidated profile with GET /api/v1/entities/:name.

Note: identity resolution is deliberately conservative. When Honeycomb isn't sure two mentions are the same person, it keeps them separate — a duplicate entity is recoverable, a wrong merge is not. And fuzzy matches are never used to decide access: only strong identifiers like a verified email can act as someone's identity for permissions.

The knowledge graph: how it all connects

Entities are joined by typed, directional relationships: Priya Sharma manages Northwind Robotics, Northwind Robotics customer_of your company, Tom Chen reports_to Priya Sharma. The graph is living evidence, not a static diagram:

• Relationships reinforce. Every independent re-confirmation increases an edge's attestation count and confidence.
• Relationships decay. An edge that stops being mentioned gradually loses confidence — a one-off rumor fades, while a many-times-confirmed reporting line barely moves.
• Contradictions resolve by business time. If a newer document says someone else owns the account, the old edge is closed as of the date the change happened — not deleted. History stays queryable.

The graph powers org-level questions out of the box: GET /api/v1/org-chart, GET /api/v1/experts?topic=... ("who knows about X?"), and GET /api/v1/people/:name all read directly from it. Explore it visually on the console's Graph and Org screens.

Spaces: who can see what

Everything above lives inside your tenant — your organization's fully isolated memory store, resolved from your API key on every request. Within the tenant, Spaces control who sees what:

• Every entry (and everything derived from it) belongs to one or more Spaces.
• A Space is either org-public (visible to everyone in your organization) or private (visible only to principals holding a grant on it).
• At ingest, content is routed to the right Space automatically and fail-closed: a private email thread becomes a private Space granted to its participants; an ambiguous document is quarantined privately rather than exposed.

When an agent or application queries Honeycomb on behalf of a specific person, it passes the x-acting-user header — and every result is scoped to what that person is allowed to see. Someone outside a private channel simply never retrieves its contents, in search, recall, or answers.

See Spaces & Permissions for sharing, revoking, and the full access model.

Answers with citations

POST /api/v1/ask is where it all pays off — plain-language questions, answered from your memory with receipts:

curl -X POST https://your-instance.example.com/api/v1/ask \
  -H "Authorization: Bearer hck_your_api_key" \
  -H "x-acting-user: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{ "query": "What is Northwind ARR and who owns the account?" }'

{
  "answer": "Northwind Robotics renewed at $1.8M ARR [1]. Priya Sharma owns the account [1].",
  "answered": true,
  "confidence": 0.92,
  "results": [
    { "content": "Northwind Robotics renewed at $1.8M ARR...", "source": "slack" }
  ]
}

Every claim carries an inline citation like [1] pointing into results — the actual source material, so you (or your agent) can verify rather than trust. And when the evidence genuinely isn't there, Honeycomb says so instead of guessing: answered comes back false with an honest refusal. See Ask for question types, scoping, and tuning.

Beyond answering what you ask, Honeycomb also proactively mines your memory for insights — contradictions, reversals, stale commitments, automation opportunities — surfaced in the console's Insights screen, GET /api/v1/insights, and the GET /api/v1/digest rollup feed. See Insights.

Bi-temporal memory: two clocks, no deletion

Honeycomb tracks two timelines for every piece of knowledge: when it was true in the real world, and when Honeycomb learned it. When knowledge changes — Northwind's ARR goes up, the account changes hands — the old version isn't deleted; it's superseded, its validity window closed as of the date the change happened. That means you can ask "what is true now?", "what was true last quarter?", and even "what did we believe in March, before the correction came in?" — and get accurate answers to all three. Your memory behaves like a good historian: always current, never amnesiac.

Glossary

Where to go next

• Quickstart — send your first entry and ask your first question in five minutes.
• Ingesting Data — the full ingest API: batching, uploads, metadata, deduplication.
• Ask — everything about questions, answers, citations, and refusals.
• Spaces & Permissions — the complete access model.
• Agents & MCP — connect AI agents through the six MCP tools: honeycomb_search, honeycomb_ingest, honeycomb_recall, honeycomb_manage, honeycomb_context, and honeycomb_upload.
• API Reference — every endpoint, request, and response shape.