Documentation Index
Fetch the complete documentation index at: https://honeydew.ai/docs/llms.txt
Use this file to discover all available pages before exploring further.
Context is an independent layer above the semantic layer.
It provides AI with organizational knowledge, analytical methods,
and historical memory that the semantic layer alone cannot express.
Context items can reference semantic objects (domains, entities,
metrics) but semantic objects do not reference context items.
Context items are best used for analytical methodologies, workflows,
and organizational knowledge that spans multiple entities or metrics.
How a metric is calculated belongs in its metric definition.
Field-specific context — such as the allowed values or meaning of a field
— belongs in AI metadata at the
field level, where it stays close to the data it describes. Types
Context items come in five subtypes across two categories.
Each subtype has a specific structure and a distinct set of valid fields.
| Subtype | Purpose | Category |
|---|
| Instruction | Short directives that shape AI behavior | instructions |
| Skill | Analytical methodologies the AI follows step-by-step | instructions |
| External Knowledge | Business definitions from external tools | instructions |
| Event | Historical occurrences that inform data interpretation and conclusions | memory |
| Decision Trace | AI-generated records of analytical reasoning | memory |
Loading Behavior
Apply Conditions
The apply field controls how a context item is loaded during analysis:
always — full content is injected before every analysis queryon-demand — the AI uses the description to decide whether the item is relevant,
then fetches the full content when needed. description is mandatory for on-demand items.
For memory items, the recorded date is also used to determine relevance — for example,
when analyzing a specific time period, events and traces relevant to that period
may be fetched.
Each subtype has a default:
| Subtype | Default |
|---|
| Instruction | always |
| Skill | on-demand |
| External Knowledge | on-demand |
| Event | on-demand |
| Decision Trace | on-demand |
Use on-demand for large reference items the AI may not need for every
question. This keeps the initial prompt size small while keeping the
content discoverable.
Enabled
The enabled field controls whether a context item is included in prompts at all.
Set enabled: false to exclude an item without deleting it. Defaults to true.
Subtypes
Instruction
Instructions are short, plain-text directives that shape how the AI behaves —
for example, preferred output formats, terminology, or analysis constraints.
Instructions are brief and are written as plain text, not Markdown.
---
name: common/output-format
type: instructions
subtype: instruction
apply: always # always (default) | on-demand
enabled: true # optional; default true
title: Output Format Preference
owner: analytics-team # optional
---
Always present numbers in thousands (e.g. 12.4K, not 12,400).
Use bullet points for lists of findings.
Avoid restating the user's question before answering.
---
name: common/always-use-usd
type: instructions
subtype: instruction
apply: always
title: Always present monetary values in USD
---
| Field | Description |
|---|
name | Unique name within the workspace. Use folder format (e.g. common/sales-rules) |
apply | always (default) or on-demand |
enabled | Optional. Set to false to exclude from prompts. Default: true |
description | Optional. Required when apply is on-demand |
Skill
Skills describe analytical methodologies — step-by-step approaches the AI
follows when analyzing a specific problem type, such as churn investigation,
funnel analysis, or cohort comparison.
---
name: retention/churn-investigation
type: instructions
subtype: skill
apply: on-demand # always | on-demand (default)
enabled: true # optional; default true
title: Churn Investigation Methodology
description: Step-by-step approach for investigating a churn spike
owner: analytics-team # optional
labels: [retention, analysis] # optional
related_objects: # optional; links to semantic objects
- name: customers
type: entity
- name: revenue
type: domain
---
# Churn Investigation Methodology
When investigating a spike in churn, follow these steps:
1. **Segment by cohort** — Break churn by acquisition month to determine whether
the spike affects all cohorts or a specific one.
2. **Check for external events** — Cross-reference the spike timing with events
in the memory context (pricing changes, outages, marketing campaigns).
3. **Compare by plan and region** — Segment churned customers by subscription
plan and geography.
4. **Look at engagement signals** — Check whether churned customers showed
declining usage before cancellation.
5. **Summarize findings** — State the most likely root cause with supporting
data, list alternative explanations, and flag any data gaps.
| Field | Description |
|---|
name | Unique name within the workspace. Use folder format (e.g. common/sales-rules) |
apply | on-demand (default) or always |
enabled | Optional. Set to false to exclude from prompts. Default: true |
description | Required. The AI uses this to decide whether to fetch the full skill content |
External Knowledge
External Knowledge items provide business definitions, policies, and reference
material fetched from external tools such as Notion or Confluence via MCP.
This is the only subtype that supports the external_source field.
Currently supported tools: Notion and Confluence. More integrations are coming soon.
To request a specific integration, reach out to support@honeydew.ai. ---
name: common/product-roadmap
type: instructions
subtype: knowledge
apply: on-demand # always | on-demand (default)
enabled: true # optional; default true
title: Product Roadmap
description: Product roadmap Notion page — upcoming features and release timeline.
owner: product-team # optional
labels: [product, planning] # optional
external_source:
tool: mcp__notion__getPage
resource_id: abc123
cache_max_age_in_seconds: 3600
---
| Field | Description |
|---|
name | Unique name within the workspace. Use folder format (e.g. common/sales-rules) |
apply | on-demand (default) or always |
enabled | Optional. Set to false to exclude from prompts. Default: true |
description | Required for on-demand. Helps the AI decide when to fetch the full content |
external_source.tool | MCP tool name for fetching (e.g. mcp__notion__getPage) |
external_source.resource_id | Identifier for the page or document in the external tool |
external_source.cache_max_age_in_seconds | Seconds before cached content is refreshed |
cache_max_age_in_seconds), fresh content is fetched using the
requesting user’s credentials. If the fetch fails, the stale version is served
with a staleness warning.
To use External Knowledge, each user must authenticate the external source via
OAuth. Go to Settings → MCP connections in the Honeydew UI and connect the
relevant tool. Content is fetched using the user’s own credentials, preserving
their access permissions in the external system.
Event
Events capture historical occurrences — pricing changes, product launches,
outages — that help the AI interpret data patterns and draw conclusions.
---
name: 2025/q4-pricing-change
type: memory
subtype: event
apply: on-demand # always | on-demand (default)
enabled: true # optional; default true
title: Q4 2025 Pricing Change
description: Switched to usage-based pricing in Q4 2025, affecting churn and MRR
from_date: 2025-10-01 # start date of the event (YYYY-MM-DD)
to_date: 2025-10-31 # optional; end date for events that span a period
owner: product-team # optional
labels: [pricing, revenue] # optional
---
In October 2025, our company moved from seat-based to usage-based pricing.
This change affected MRR calculations and caused a temporary spike in churn
as customers re-evaluated their plans.
| Field | Description |
|---|
name | Unique name within the workspace. Use folder format (e.g. common/sales-rules) |
apply | on-demand (default) or always |
enabled | Optional. Set to false to exclude from prompts. Default: true |
from_date | Start date of the event, in YYYY-MM-DD format |
to_date | Optional. End date for events that span a period, in YYYY-MM-DD format |
description | Required for on-demand. Helps the AI decide whether the event is relevant |
Decision Trace
Decision traces are AI-generated records of analytical reasoning — the steps
the AI followed, the data it examined, and the conclusions it reached.
They are created automatically and are not authored manually.
---
name: 2026/jan-revenue-drop
type: memory
subtype: decision_trace
apply: on-demand # always | on-demand (default)
enabled: true # optional; default true
title: Revenue Drop Analysis — January 2026
description: AI analysis of the January 2026 revenue anomaly
from_date: 2026-01-13
---
Creating Context Items
Context items can be created in a few ways:
- Honeydew Studio — use the context item builder in the UI
- Git repository — commit files to the
ai/instructions/ or ai/memory/
directories in your workspace
- Coding agent — use a coding agent connected via MCP to create and manage context items
(see MCP context item tools)
Naming
Context item names use a folder-style format: lowercase words separated by
hyphens, grouped into folders with slashes. Use a folder prefix to group
related items within a subtype.
Context items created by Honeydew reflect the folder prefix in the file path
within the repository.
common/company-overview
retention/churn-investigation
finance/revenue-recognition
2025/q4-pricing-change
Suggested Prefixes
| Prefix | Purpose |
|---|
common/* | Company-wide knowledge and instructions |
<team>/* | Team-specific knowledge (e.g. finance/*, product/*) |
<topic>/* | Topic-grouped skills (e.g. retention/*, growth/*) |
<year>/* | Year-grouped events and decisions (e.g. 2025/*) |
Repository Structure
Context items are stored in the ai/instructions and ai/memory directories
within your workspace. The folder prefix in a name becomes a subdirectory
within the subtype directory.
<workspace>/ai/
├── instructions/
│ ├── instruction/
│ │ └── common/
│ │ └── output-format.md
│ ├── skill/
│ │ └── retention/
│ │ └── churn-investigation.md
│ └── knowledge/
│ └── common/
│ └── product-roadmap.md
├── memory/
│ ├── event/
│ │ └── 2025/
│ │ └── q4-pricing-change.md
│ └── decision-trace/
│ └── 2026/
│ └── jan-revenue-drop.md
└── agents/ # agent definitions — see Agents
└── growth-analyst.md
YAML Schema
Context items are Markdown files with YAML frontmatter. The schema varies by subtype.
Instruction
type: instructions
subtype: instruction
name: <name>
apply: always | on-demand # optional; default always
enabled: true | false # optional; default true
title: <title>
description: <description> # optional; required for on-demand
owner: <owner> # optional
Skill
type: instructions
subtype: skill
name: <name>
apply: on-demand | always # optional; default on-demand
enabled: true | false # optional; default true
title: <title>
description: <description> # required for on-demand
owner: <owner> # optional
labels: [label1, label2] # optional
related_objects: # optional
- name: <object name>
type: entity | metric | domain
External Knowledge
type: instructions
subtype: knowledge
name: <name>
apply: on-demand | always # optional; default on-demand
enabled: true | false # optional; default true
title: <title>
description: <description> # required for on-demand
owner: <owner> # optional
labels: [label1, label2] # optional
external_source:
tool: <mcp tool name>
resource_id: <resource id>
cache_max_age_in_seconds: <seconds>
Event
type: memory
subtype: event
name: <name>
apply: on-demand | always # optional; default on-demand
enabled: true | false # optional; default true
title: <title>
description: <description> # required for on-demand
from_date: <YYYY-MM-DD>
to_date: <YYYY-MM-DD> # optional
owner: <owner> # optional
labels: [label1, label2] # optional
Decision Trace
type: memory
subtype: decision_trace
name: <name>
apply: on-demand | always # optional; default on-demand
enabled: true | false # optional; default true
title: <title>
description: <description> # required for on-demand
from_date: <YYYY-MM-DD>
