Knowledge Sources

Three Ways To Give An Agent Knowledge

Knowledge sources are how an agent learns facts that are not in its training data — your refund policy, product specs, internal runbooks, support history. On Macha they come in three shapes, each with different cost and freshness characteristics.

Injected Sources

Small CSVs and short documents (under ~2,000 rows for spreadsheets) get included in the system prompt directly. The agent always sees them, on every conversation, without having to call any tool to retrieve them.

Use when: the content is small (a few KB), always relevant, and changes infrequently. A list of valid product SKUs, a one-page refund policy, the names and ownership of your top 50 enterprise accounts.

Cost: every conversation pays the token cost for that content, even if the agent never uses it. Injected content adds to the prompt size on every message.

Avoid when: the content is large, mostly irrelevant on a typical query, or updates frequently. Injecting a 200-page PDF into every conversation is the classic credit-burn anti-pattern — chunk it and let the agent search instead.

Searched Sources

Larger documents (PDFs, DOCX, big CSVs, long Markdown files) get chunked, embedded, and indexed. The agent calls search_knowledge to retrieve relevant chunks for a given query, then optionally get_document to pull the full document if a chunk looks promising.

Use when: you have a meaningful corpus (dozens to thousands of documents) and only some of it is relevant to any given query. Customer support knowledge bases, product documentation, policy libraries.

Cost: pay per search. The agent only retrieves what it actually queries for. Scales to large libraries without inflating per-conversation token usage.

Configuration tip: when you add a searched source, you can scope it to all documents in the source or to selected documents. Use selected when an agent should only access a subset — e.g. a billing agent that should see billing policies but not engineering runbooks from the same source.

Live Connector Sources

Documents from Google Docs, Notion, and Confluence are not pre-indexed. The agent calls the connector's own read tool — google_read_doc, notion_get_page, confluence_get_page — to fetch fresh content on every read.

Use when: the content changes frequently and staleness would hurt. Live runbooks, in-progress documentation, product specs that get updated daily.

Cost: pay per read. The full document is fetched each time, so this is more expensive per-use than a searched chunk — but you always get the latest version.

Important: connector sources are always selected scope, not all. The OAuth permission model only grants access to specific files you pick. This is why connector sources do not get the search tools (search_knowledge, get_document) added — agents use the connector's read tool instead.

How To Choose

A simple decision tree:

1. Is the content under ~2 KB and used on every conversation? Inject.
2. Is it large but relatively static, with only a small portion relevant per query? Search.
3. Does it change daily or weekly and need to be current? Live connector source.

You can mix all three on a single agent. A reply agent might inject the brand voice guide (always relevant), search the help centre (large, mostly irrelevant per query), and live-read a Google Doc of current promotions (changes weekly).

The Anti-Pattern: Inject Everything

The most common mistake with knowledge sources is injecting too much. We have seen agents with 50 KB of injected content paying multiple cents per conversation just for the prompt overhead, when 90% of that content is never relevant to the typical query.

If a document is more than a couple of pages, default to searching it. The slight loss in always-on availability is dwarfed by the cost savings and the reduction in noise the model has to filter through.

Document IDs: Know What Goes Where

This is a subtle technical detail that occasionally trips up agent builders, especially when writing instructions that reference specific documents.

• Uploads, websites, webpages: documents have MongoDB ObjectIds. Stored in Macha's document collection.
• Google connector sources: documents have Google Doc IDs (strings like 1A2B3C...). Not stored in Macha — fetched live.
• Notion connector sources: documents have Notion Page IDs. Not stored in Macha — fetched live.

The practical implication: when an agent needs to fetch a specific connector document, the ID it passes to the connector tool is the connector's ID, not a Macha ID. The agent learns this naturally from search_knowledge results, but if you are scripting a workflow it is worth knowing.

Help Center Sync (Zendesk)

Special case worth calling out: if you have a Zendesk Help Center, sync it to Macha as a knowledge source. The articles get embedded and become searchable via zendesk_search_articles, with live webhook updates whenever an article is published or edited. This is one of the highest-leverage knowledge integrations on Macha — reply agents that draw on existing Help Center content are dramatically better than ones that improvise, and the content stays fresh automatically.

Same pattern works for Confluence. If your team uses Confluence as the primary internal knowledge base, syncing relevant spaces gives reply and research agents accurate, up-to-date facts without manual upload work.

Scope: All vs Selected

When you add a non-connector source to an agent, you can pick whether the agent has access to all documents in the source or only selected ones. Default to selected when:

• The source contains documents from multiple teams (engineering runbooks shouldn't be visible to a customer-facing agent).
• Some documents are confidential and should only be available to internal-only agents.
• The source is broad and the agent should focus on a narrow slice of it.

Default to all when the source itself is already curated for this agent's purpose — e.g. a "customer-facing FAQ" source where every document is meant to be cited in replies.