Choosing How to Add Knowledge
The platform gives you five different ways to put knowledge in front of an agent. They overlap enough to be confusing and differ enough that the wrong choice quietly hurts quality, cost, or freshness. This page explains what each one is for and how to pick.
| Mechanism | What it is | Best for |
|---|---|---|
| Memory | Facts the agent learns from its own past sessions, extracted when a session ends and recalled when relevant | Preferences, recurring context, and outcomes an agent should remember over time |
| Knowledge Bases | Documents you curate, indexed semantically and retrieved at runtime | Grounding answers in your docs, policies, specs, and FAQs |
| Manifests | Declarative, versioned, schema-validated structured data | Exact rules, thresholds, taxonomies, and configuration that must be precise |
| Data Sources | Authenticated, cached bindings to live external/internal data | Current values — spend, open PRs, metrics, billing |
| Functions | Tools the agent calls on demand | Open-ended lookups you can't predefine — web search, arbitrary APIs, computed answers |
The four questions that decide it
Most of the confusion disappears once you answer four questions about the knowledge itself.
1. Who authors it — you, or the agent?
- You curate it → Knowledge Base, Manifest, Data Source, or Function.
- The agent learns it itself, from its own runs → Memory.
Memory is the only mechanism that accumulates automatically. Facts are extracted from each session as it ends, facts that several sessions agree on are distilled into durable ones, and a nightly sweep archives what goes unused and keeps each agent's memory within its caps. Everything else is content you author and the agent consumes read-only.
2. Is it static, or does it change?
- Static reference that changes only when you edit it → Knowledge Base or Manifest.
- Live data that's different every time you look → Data Source (cached, refreshable) or Function (fetched fresh on each call).
Putting a live value (today's spend, current PR list) in a knowledge base means it's stale the moment it's indexed. Putting a stable 200-page policy behind a function call means re-fetching and re-paying for it on every turn. Match the mechanism to how often the content changes.
3. Is it fuzzy prose, or exact structure?
- Fuzzy / semantic — paragraphs, articles, explanations where "close enough" retrieval is fine → Knowledge Base or Memory.
- Exact / structured — thresholds, rules, mappings, config where a wrong value is a bug → Manifest.
Knowledge bases chunk and embed text, then return the most similar chunks. That's perfect for "what does our refund policy say?" and wrong for "what is the exact escalation threshold?" — semantic retrieval can return a near-miss. When the answer must be precise and versioned, use a manifest.
4. Should it always be present, or only when the agent reaches for it?
- Pushed in (added before the agent thinks) → Memory and Knowledge Bases: the platform searches them for what is relevant to the conversation and adds the best matches to the agent's context, within a token budget. Both require memory to be enabled on the agent.
- On demand (pulled mid-task when the agent decides it needs it) → Data Sources (through the
read_data_sourcetool) and Functions are called by the agent during the run. A memory-enabled agent can also search its own memory on purpose with its built-in recall tool. Manifests are read on demand too, by an agent given a function that reads them, or pushed in by ingesting them into a knowledge base.
This matters for cost and focus. Pushed-in knowledge costs tokens whenever something clears the relevance bar and nothing when nothing does, so it's great for "things the agent should have in mind" without asking. On-demand tools cost nothing until called but rely on the agent choosing to call them — which depends entirely on a good function/tool description.
Pick by scenario
| You want the agent to… | Use | Why |
|---|---|---|
| Remember a user's preferences across sessions | Memory | Self-learned, agent-scoped, private to that user by default, persists between sessions |
| Answer questions grounded in your product docs | Knowledge Base | Large authoritative prose, semantically retrieved |
| Apply exact business rules or a classification taxonomy | Manifest | Deterministic, validated, versioned — no fuzzy retrieval |
| Report current cloud spend / open PRs / live metrics | Data Source | Live, cached, refreshable, also bindable to dashboards |
| Look up something arbitrary on the open web | Function (web search) | Can't predefine the corpus; needs a real-time call |
| Query an external API mid-task | Function or Data Source | Function for one-off computed calls; Data Source if the result is reused, cached, or shown on a dashboard |
| React when external data changes | Data Source with Emit a datasource.refreshed event on update | Each refresh publishes a datasource.refreshed platform event that event-driven agents and workflows can respond to |
Common confusions
Knowledge Base vs Data Source. Both bring in information, but a knowledge base is static curated reference and a data source is live cached data. "Our onboarding guide" is a knowledge base; "this customer's current usage" is a data source.
Data Source vs Function. Both fetch live data. Reach for a data source when the result is reused, cached, refreshed on a schedule, shown on a dashboard, or shared across a project — the platform manages fetching and caching for you. Reach for a function when it's a one-off, computed, or open-ended call where caching adds no value. (A data source can even use a function as its connector — the function does the fetch, the data source adds caching, scheduling, and sharing on top.)
Memory vs Knowledge Base. Memory is experiential and self-authored — what the agent learned. A knowledge base is authoritative and you-authored — what you told it. Don't use memory as a document store, and don't expect a knowledge base to remember what happened in a previous conversation.
Manifest vs Knowledge Base. A manifest can be ingested into a knowledge base, but they serve opposite needs: manifests are for exact structured values; knowledge bases are for searchable prose. If a wrong-but-similar answer would be a bug, you want a manifest.
Combining them
These aren't mutually exclusive — a well-built agent often uses several at once. A support agent might have a knowledge base of product docs, a manifest of escalation rules, memory of the current customer's history, and a data source for that customer's live account status. Start with the one mechanism that fits the primary knowledge need, then layer in others as distinct needs appear.