Notes

What it is

Notes is one native tool, technically identified as manage_notes. It keeps a key/value object that the agent can read and update during service. Use it for durable facts provided by the user, such as a name, preferences, qualification data, or the current step in a process.

Do not confuse this memory with an Internal note. An Internal note is a free-form human message in the timeline and is not added to the agent context. Notes are structured data shared by the agent and administrative screens.

Where the memory lives

The agent does not select the destination record. The conversation being processed determines the scope:

Context	Record used	Practical lifetime
Conversation with an external contact, including WhatsApp, Telegram, Instagram, and API	Contact	Notes follow the contact into future conversations
Internal Hub conversation without an external contact	Conversation	Notes stay in that conversation only

On external channels, treat this memory as part of the contact profile, not as a disposable session draft. See Contacts to understand where the team sees this data.

Add it to an agent

You need a saved agent and the agents.write permission.

1. Open Agents, select the agent, and open Tools.
2. Click Add Tool.
3. Under Native Tools, choose Notes.
4. Confirm that the tool appears as active in the list.

There is no configuration form. The entry is hidden from the available tools while it is connected; to remove it, use the delete action in the tool list.

Available operations

All operations use the same tool:

Goal	Expected call	Result
Read all Notes	action: "read", without key	Full object
Read one Note	action: "read" and key	The value, or null if the key does not exist
Create or update	action: "write", key, and value	Full object after the change
Delete	action: "write", key, and value: null	Full object without that key

Writing to the same key replaces its previous value. Using a different spelling creates a second Note; there is no automatic merge or version history.

Guide the agent in its prompt

The tool contract recommends reading existing Notes before writing. This prevents duplicate keys and lets the agent update the right fact.

Define a small, stable schema in the prompt, with lowercase English snake_case keys. For example:

Before writing, read the existing Notes and reuse the matching key.
Use only the keys producer_name, preferred_channel, and qualification_stage.
Store only data supplied by the user and useful in future conversations.

Prefer producer_name over variants such as name, Producer Name, or producer. Always send both key and value when writing. The current runtime treats an omitted value as null and deletes the key; this is a known product limitation.

Do not persist secrets, credentials, payment data, or sensitive information without an appropriate purpose and handling policy. The tool accepts any JSON value, so the prompt is responsible for restricting what should be stored.

Visibility and maintenance

The team can read and edit structured Notes under Conversations → Context → Contact and in the profile under Contacts. For an internal conversation without a contact, the context panel displays that conversation’s Notes.

These edits have no history. In addition, the controls embedded in Conversations and the current RPCs can still diverge from granular permissions: a control may appear and then fail to write, or a legacy role may retain access removed from its capability. Ask an administrator to review the role when this happens.

Important limitations

• No versioning: updating a key discards its previous value.
• No cross-contact lookup: the tool accesses only the contact or conversation currently being processed.
• Durable external scope: completing a conversation does not delete the contact’s Notes.
• Internal memory vulnerable to cleanup: in the current runtime, deleting any message from the conversation clears all Notes stored on the conversation record. Technical message cleanup can trigger this too; do not use this scope for critical storage.
• Context cost: each read returns data to the model. Avoid large objects and read one specific key when the flow allows it.

If the agent creates duplicates, update the prompt to require a read before each write and normalize existing keys. If it does not use the memory, confirm that Notes is active and explicitly tell it when to read or write.