Memory

Memory is what the agent keeps about one contact between calls: that they prefer mornings, who their usual doctor is, that they are allergic to penicillin. The next call recalls it, so the agent does not ask again.

What is memory?#

Memory is a list of facts per contact, each filed under a category in your own words. Three parts make it work:

Write a policy#

An agent remembers nothing until it has a policy. The policy is one field of the agent's settings, so it changes without a deploy, and a supervisor can edit it in the console, on the agent's Configure ▸ Memory.

pinecall memory policy \
  --remember "how they like to be addressed" --remember "allergies" --remember "their usual doctor" \
  --forget "payments"

--remember and --forget take one phrase each and are repeated.

With no list, the verb prints the policy in your settings, the team's and production's. --team writes the team's; --agent <slug> names the agent in a project of several. A policy written replaces the one before it, and pinecall agent clear memory takes yours out, so the team's holds again.

Who a contact is#

A contact is the id your app named for the caller when it named one, else the number the call came from. On the phone and on WhatsApp, the number is the identity. A web visitor nobody named is nobody, and the agent remembers nothing of them.

To try memory from your terminal, say who is calling:

pinecall chat --as +34600123456

How a call is remembered#

After the call ends and before its summary is written, the platform makes one model call, on the agent's own model and your org's provider keys. It reads the call's turns and the facts already held, and answers what to add, what to update and what no longer holds. Then:

• a fact outside the --remember categories, or under a --forget one, is dropped;
• a fact that names one of the agent's tools is refused;
• an updated fact is a new row that supersedes the old one. Nothing is deleted except by forget.

That model call is billed with the call. It has 8 seconds; past them, or if it fails, the log carries a recoverable remember_failed and the call ends normally. An org at its memory_facts quota writes nothing new, but its memory is still read.

How a turn recalls#

When the agent has a policy and the caller is known, recall runs beside the knowledge search on every turn. It ranks the contact's current facts by meaning and by words, then by recency and the confidence the extraction gave them, and hands the model the best six, each with the call that taught it and the date it was first held. It asks no model, so it costs only a query.

The contact recalled is always the one the platform knows is on the line, never one the model named.

Use it in your class#

remembers(text) is true once memory has told this call something under that category, or a fact containing that text. Use it in render() to change what the agent does:

{this.remembers("usual doctor") && <p>Offer their usual doctor's free slots first.</p>}

It is false until a fact arrives, which is exactly how a caller nobody has met looks. To keep a copy in your own CRM, override onMemory(ops, call): it hears every operation the runtime wrote.

Read and erase a contact#

pinecall memory +34600123456          # current facts first, then the superseded ones with the date they stopped holding
pinecall memory forget +34600123456   # erase everything kept about them

forget asks once on a terminal and prints how many facts went. It always works, on any plan.

Test it#

Testing knowledge & memory walks all three.

Next steps#