Overview
What the agent knows by heart, what it looks up on every turn, and what it remembers about a caller.
An agent can answer from three kinds of information: what it knows by heart, what it looks up on each turn, and what it remembers about the caller. Each one lives in a different place, reaches the model in a different way, and is tested differently.
What is knowledge and memory?#
None of the three is written in your class. All three are kept by the gateway, are part of the agent's settings in sandbox and in production, and change without a deploy.
How they compare#
| Knowledge | Knowledge base | Memory | |
|---|---|---|---|
| What it holds | one page, small and always relevant | many documents, the long tail | facts about one caller |
| Who writes it | your team, on the agent's Configure ▸ Knowledge in the console or with pinecall agent knowledge edit; a setting, never a file of the class |
your team, on the agent's Knowledge ▸ Docs, or pinecall docs push |
one model call at hang-up, under the policy in Configure ▸ Memory |
| When the model sees it | every turn, in the cached knowledge block |
each turn, the chunks a search found | each turn, the facts recall found |
| How it arrives | part of the prompt | a tool_result |
a tool_result |
| How you test it | goldens and the grounded judge |
pinecall docs eval |
pinecall remember and pinecall memory eval |
Use knowledge for what every call needs: who the business is, its hours, what the agent may promise. A page is fine; a hundred documents are not. Use a knowledge base for everything too long to read whole. Use memory for what a caller told you that the next call should not ask again.
How it works#
On every turn of a call, while the caller is still speaking, the platform runs two lookups at once:
searchasks the bases attached to the agent, once the caller has said four words, on a turn that has at least one letter in it. A turn of digits alone (a number being read out) searches nothing.recallasks the caller's memory, when the agent has a memory policy and the platform knows who is on the line.
Both usually finish before the caller stops talking. A lookup that is late is cancelled, and the turn goes on without it. The model then reads what came back as tool results, after the conversation so far:
system: identity · knowledge · tools cached, unchanged while the call runs
messages: …the turns…
assistant tool_use recall {…}
user tool_result {"facts":[{"text":"Prefers mornings.","source":"call_8f5a…","since":"2026-09-10"}]}
assistant tool_use search {"query":"how much is a check-up?"}
user tool_result {"chunks":[{"path":"prices.md","heading":"Prices › Check-up","text":"…"}]}Neither result carries a score. A score means something to the ranking and nothing to the model.
A chunk of a document and a fact remembered from an earlier caller were written by someone other than you. They reach the model as JSON inside a
tool_result, never inside the words of your prompt, so a sentence planted in a document cannot speak with your authority. Prompt injection has the whole rule.
What the call's log keeps#
Every lookup is written into the call's log, joined to the turn it served:
| entry | what it says |
|---|---|
docs.sources |
the query, every chunk with its base, path, heading and score, and how long it took |
memory.ops |
the facts recalled on a turn, and at hang-up what was added or superseded |
error |
search_skipped or recall_skipped when a lookup could not run, remember_failed when memory was not written |
The console's Calls screen shows the same thing on each turn, for example search · 3 chunks · 181 ms.