> ## 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 Management
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](/integration/context-layer/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 query
* **`on-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.
```yaml theme={null}
---
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.
```
Instructions can have a body or consist of a title alone:
```yaml theme={null}
---
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.
```yaml theme={null}
---
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](mailto:support@honeydew.ai).
```yaml theme={null}
---
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 |
Content is cached per user. When an item is accessed and the cache is stale
(older than `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.
```yaml theme={null}
---
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.
```yaml theme={null}
---
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](/integration/mcp#context-items))
## 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
```
Names must be unique within a workspace across all context types.
[Agent](/integration/context-layer/agents) definitions use these names —
including glob patterns — to reference context items.
### Suggested Prefixes
| Prefix | Purpose |
| ----------- | ------------------------------------------------------- |
| `common/*` | Company-wide knowledge and instructions |
| `/*` | Team-specific knowledge (e.g. `finance/*`, `product/*`) |
| `/*` | Topic-grouped skills (e.g. `retention/*`, `growth/*`) |
| `/*` | 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.
```
/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
```yaml theme={null}
type: instructions
subtype: instruction
name:
apply: always | on-demand # optional; default always
enabled: true | false # optional; default true
title:
description: <description> # optional; required for on-demand
owner: <owner> # optional
```
### Skill
```yaml theme={null}
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
```yaml theme={null}
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
```yaml theme={null}
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
```yaml theme={null}
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>
```