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 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.

---
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:

---
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

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.

---
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

Names must be unique within a workspace across all context types. Agent definitions use these names — including glob patterns — to reference context items.

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>

Quick Start

Semantic Ecosystem

Modeling Reference

Context Layer

Management

Integrations

Security

Release Notes

Types

Loading Behavior

Apply Conditions

Enabled

Subtypes

Instruction

Skill

External Knowledge

Event

Decision Trace

Creating Context Items

Naming

Suggested Prefixes

Repository Structure

YAML Schema

Instruction

Skill

External Knowledge

Event

Decision Trace

​Types

​Loading Behavior

​Apply Conditions

​Enabled

​Subtypes

​Instruction

​Skill

​External Knowledge

​Event

​Decision Trace

​Creating Context Items

​Naming

​Suggested Prefixes

​Repository Structure

​YAML Schema

​Instruction

​Skill

​External Knowledge

​Event

​Decision Trace

Types

Loading Behavior

Apply Conditions

Enabled

Subtypes

Instruction

Skill

External Knowledge

Event

Decision Trace

Creating Context Items

Naming

Suggested Prefixes

Repository Structure

YAML Schema

Instruction

Skill

External Knowledge

Event

Decision Trace