Remember a returning caller across calls

AI Agentsconversation memory for voice AI (returning callers)

Have the platform save a summary when a call ends and hand it back when the same number calls again, so the agent picks up where it left off.

memorypost-prompt

The claim

An agent forgets everything when the call ends unless something keeps it. The platform offers to: save_conversation posts a summary to your post_prompt_url at the end of the call, and conversation_id says which conversation that summary belongs to. This recipe derives the id from the caller’s number, keeps each summary in a file, and answers the platform’s request for it on the next call.

Why it holds

Three sources carry the claim.

The docs for ai.params say save_conversation will “send a summary of the conversation after the call ends”, that it requires post_prompt_url and a conversation_id, and that conversation_id is “used by check_for_input and save_conversation to identify an individual conversation”.
The inbound-call payload the platform POSTs for a SWML document carries call.from, so the per-request callback can set both params before the document renders.
The SDK’s own post-prompt route handles the return trip. In 3.0.1 it calls on_summary(summary, body). When the body’s action is fetch_conversation it returns whatever on_summary returned. Its comment says the platform “expects conversation_summary in the response” (core/mixins/web_mixin.py).

The Python surface uses that route as it is. The TypeScript SDK, 2.0.5, answers every post-prompt POST with {ok: true} and drops onSummary’s return. Its surface therefore points post_prompt_url at a small handler of its own, which is what setPostPromptUrl is for.

How it works

def configure(query_params, body_params, headers, agent):
    caller = (body_params.get("call") or {}).get("from")
    if caller:
        agent.set_params({"save_conversation": True,
                          "conversation_id": conversation_id(caller)})

class FrontDesk(AgentBase):
    def on_summary(self, summary, raw_data=None):
        cid = raw_data.get("conversation_id")
        if raw_data.get("action") == "fetch_conversation":
            remembered = _load().get(cid)
            return {"conversation_summary": remembered} if remembered else {}
        if summary and cid:
            memory = _load(); memory[cid] = summary; _save(memory)

What the document carries for a call from +1 415 555 0123:

{"ai": {"params": {"save_conversation": true, "conversation_id": "caller-14155550123"},
        "post_prompt": {"text": "Summarise the call in two sentences, ..."},
        "post_prompt_url": "https://your-host/front-desk/post_prompt"}}

The callback runs against an ephemeral copy of the agent on every request. One caller’s id never leaks into another caller’s document, and a request with no caller renders no id at all. The id is the caller’s digits, which keeps it inside the characters the SDK accepts for a conversation id.

A post_prompt is set because in 3.0.1 that is what makes the SDK emit post_prompt_url. The summary it asks for is also the text that gets kept.

Limitations

A caller whose number carries no digits, an anonymous call or a SIP URI without any, gets no conversation id. Nothing is saved or fetched for them. One memory shared by every anonymous caller would hand one caller’s summary to the next.

The verifier proves the document and the two POSTs, not what the model does with the summary on the next call. That is the prompt’s job, and the Memory section is where it is asked.

The exact shape of the platform’s fetch request is documented in the SDK’s route rather than in a spec. The recipe reads action and conversation_id from the body, as the route does.

What to change first

Remove "save_conversation": True from configure and run the verifier. The document still carries the id and the post prompt, and the first assertion fails. That is the point: without that flag nothing is saved, and the next call has nothing to fetch.

Where this sits

Before this

Configure a voice AI agent per request for many tenants

Write call dispositions from data your handlers recorded Transfer a call without losing context Keep per-call state server-side, keyed by call id

python/app.py

"""Remember a returning caller across calls.

Two `ai.params` do the work. `save_conversation` makes the platform post a
summary of the conversation when the call ends, and `conversation_id` names
the conversation it belongs to. Name it after the caller's number and the next
call from that number can ask for the summary back: the platform POSTs
`action: fetch_conversation` to the same `post_prompt_url`, and whatever
`on_summary` returns is the answer. The SDK's post-prompt route says it expects
`conversation_summary` in that response (core/mixins/web_mixin.py).

The summaries live in a file here, keyed by conversation id, because the call
that saves and the call that asks are different requests to your server.

Written against signalwire-sdk 3.0.1 (AgentBase, set_dynamic_config_callback).

    python app.py          # serves /front-desk/ and /front-desk/post_prompt
"""
import json
import os
import re
from pathlib import Path

from dotenv import load_dotenv
from signalwire import AgentBase

# the SDK does not read .env for you
load_dotenv()

# where each caller's last summary lives; swap for your database
MEMORY_PATH = Path(os.getenv("MEMORY_PATH", "caller-memory.json"))


def conversation_id(number):
    """One conversation per caller, keyed on the digits of the number.

    A caller with no digits (anonymous, or a SIP URI with none) gets None, so
    no memory is kept rather than one memory shared by every such caller.
    """
    digits = re.sub(r"\D", "", number or "")
    return "caller-" + digits if digits else None


def _load():
    if not MEMORY_PATH.exists():
        return {}
    return json.loads(MEMORY_PATH.read_text(encoding="utf-8"))


def _save(memory):
    tmp = MEMORY_PATH.with_suffix(".tmp")
    tmp.write_text(json.dumps(memory, indent=2), encoding="utf-8")
    os.replace(tmp, MEMORY_PATH)


def configure(query_params, body_params, headers, agent):
    """Runs on every request, against an ephemeral copy of the agent.

    The SWML request body carries the call, and `call.from` is the caller.
    """
    cid = conversation_id((body_params.get("call") or {}).get("from"))
    if cid:
        agent.set_params({"save_conversation": True, "conversation_id": cid})


class FrontDesk(AgentBase):
    def __init__(self):
        super().__init__(name="front-desk", route="/front-desk")
        self.prompt_add_section("Role", "You answer the phone for Ridgeline Cycles, "
                                        "a bike shop. Be brief and warm.")
        self.prompt_add_section("Memory", "If a summary of a previous call is "
                                          "available, greet the caller as someone "
                                          "you have spoken to and pick up from it.")
        # a post_prompt is what makes the SDK emit post_prompt_url, which
        # save_conversation needs; the summary it asks for is what gets kept
        self.set_post_prompt("Summarise the call in two sentences, including "
                             "anything the caller asked you to remember.")
        self.set_dynamic_config_callback(configure)

    def on_summary(self, summary, raw_data=None):
        """Save at the end of a call; answer a fetch at the start of the next."""
        raw_data = raw_data or {}
        cid = raw_data.get("conversation_id")
        if raw_data.get("action") == "fetch_conversation":
            remembered = _load().get(cid)
            # the platform reads conversation_summary from this response
            return {"conversation_summary": remembered} if remembered else {}
        if summary and cid:
            memory = _load()
            memory[cid] = summary if isinstance(summary, str) else json.dumps(summary)
            _save(memory)
        return None


agent = FrontDesk()

if __name__ == "__main__":
    agent.serve(port=int(os.getenv("PORT", "3000")))

/**
 * Remember a returning caller across calls.
 *
 * Two `ai.params` do the work. `save_conversation` makes the platform post a
 * summary of the conversation when the call ends, and `conversation_id` names
 * the conversation it belongs to. Name it after the caller's number and the
 * next call from that number can ask for the summary back: the platform POSTs
 * `action: fetch_conversation` to the `post_prompt_url`, and the response is
 * expected to carry `conversation_summary`.
 *
 * `@signalwire/sdk` 2.0.5's own post-prompt route answers every POST with
 * `{ok: true}` and discards what `onSummary` returns, so it cannot answer a
 * fetch. This surface points `post_prompt_url` at a small handler of its own,
 * which is what `setPostPromptUrl` exists for.
 *
 * Written against @signalwire/sdk 2.0.5 (AgentBase, setDynamicConfigCallback).
 *
 *     npm start          # the agent on :3000, the post-prompt handler on :3001
 */
import "dotenv/config";
import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import { createServer, type IncomingMessage } from "node:http";
import { AgentBase } from "@signalwire/sdk";

// where each caller's last summary lives; swap for your database
export const MEMORY_PATH = process.env["MEMORY_PATH"] ?? "caller-memory.json";
// the public URL of the handler below, as the platform will call it
export const POST_PROMPT_URL = process.env["POST_PROMPT_URL"]
  ?? "http://localhost:3001/post_prompt";

const AUTH_USER = process.env["SWML_BASIC_AUTH_USER"] ?? "";
const AUTH_PASSWORD = process.env["SWML_BASIC_AUTH_PASSWORD"] ?? "";

/**
 * The platform gets only the URL, so the credentials travel inside it. They
 * are percent-encoded first: a literal % in a password would otherwise be read
 * as an escape by the client that decodes the URL before building Basic auth.
 */
export function withCredentials(url: string) {
  const u = new URL(url);
  if (!u.username) {
    u.username = encodeURIComponent(AUTH_USER);
    u.password = encodeURIComponent(AUTH_PASSWORD);
  }
  return u.toString();
}

/**
 * One conversation per caller, keyed on the digits of the number. A caller
 * with no digits (anonymous, or a SIP URI with none) gets undefined, so no
 * memory is kept rather than one memory shared by every such caller.
 */
export function conversationId(number: string | undefined) {
  const digits = (number ?? "").replace(/\D/g, "");
  return digits ? `caller-${digits}` : undefined;
}

type Memory = Record<string, string>;
const load = (): Memory =>
  existsSync(MEMORY_PATH) ? JSON.parse(readFileSync(MEMORY_PATH, "utf-8")) : {};
function save(memory: Memory) {
  writeFileSync(`${MEMORY_PATH}.tmp`, JSON.stringify(memory, null, 2), "utf-8");
  renameSync(`${MEMORY_PATH}.tmp`, MEMORY_PATH);
}

export class FrontDesk extends AgentBase {
  constructor() {
    super({ name: "front-desk", route: "/front-desk" });
    this.promptAddSection("Role", { body: "You answer the phone for Ridgeline Cycles, "
                                          + "a bike shop. Be brief and warm." });
    this.promptAddSection("Memory", {
      body: "If a summary of a previous call is available, greet the caller as "
          + "someone you have spoken to and pick up from it.",
    });
    // a post_prompt is what makes the SDK emit post_prompt_url, which
    // save_conversation needs; the summary it asks for is what gets kept
    this.setPostPrompt("Summarise the call in two sentences, including anything "
                       + "the caller asked you to remember.");
    this.setPostPromptUrl(withCredentials(POST_PROMPT_URL));
    // the SWML request body carries the call, and call.from is the caller
    this.setDynamicConfigCallback((_query, body, _headers, agent) => {
      const call = (body as { call?: { from?: string } }).call ?? {};
      const cid = conversationId(call.from);
      if (cid) {
        agent.setParams({ save_conversation: true, conversation_id: cid });
      }
    });
  }
}

type PostPromptBody = {
  action?: string; conversation_id?: string;
  post_prompt_data?: { raw?: string; parsed?: unknown[] };
};

/** Save at the end of a call; answer a fetch at the start of the next. */
export function handlePostPrompt(body: PostPromptBody): Record<string, unknown> {
  const cid = body.conversation_id ?? "";
  if (body.action === "fetch_conversation") {
    const remembered = load()[cid];
    // the platform reads conversation_summary from this response
    return remembered ? { conversation_summary: remembered } : {};
  }
  const summary = body.post_prompt_data?.raw
    ?? (body.post_prompt_data?.parsed?.[0] as string | undefined);
  if (summary && cid) {
    const memory = load();
    memory[cid] = typeof summary === "string" ? summary : JSON.stringify(summary);
    save(memory);
  }
  return { success: true };
}

function readBody(req: IncomingMessage): Promise<string> {
  return new Promise((resolve) => {
    const chunks: Buffer[] = [];
    req.on("data", (c: Buffer) => chunks.push(c));
    req.on("end", () => resolve(Buffer.concat(chunks).toString()));
  });
}

/** The post-prompt handler, behind the same basic auth the agent uses. */
export function servePostPrompt(port: number) {
  const user = AUTH_USER;
  const expected = "Basic " + Buffer.from(`${user}:${AUTH_PASSWORD}`).toString("base64");
  return createServer(async (req, res) => {
    const raw = await readBody(req);
    if (!user || req.headers.authorization !== expected) {
      res.writeHead(401, { "www-authenticate": "Basic" });
      return res.end();
    }
    let body: PostPromptBody = {};
    try { body = JSON.parse(raw); } catch { /* an empty body saves nothing */ }
    res.writeHead(200, { "content-type": "application/json" });
    res.end(JSON.stringify(handlePostPrompt(body)));
  }).listen(port);
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  for (const name of ["SWML_BASIC_AUTH_USER", "SWML_BASIC_AUTH_PASSWORD"]) {
    if (!process.env[name]) throw new Error(`${name} is required; see .env.example`);
  }
  servePostPrompt(Number(process.env["POST_PROMPT_PORT"] ?? 3001));
  new FrontDesk().serve({ port: Number(process.env["PORT"] ?? 3000) });
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # project id, API token, space, basic auth
python app.py                    # serves /front-desk/ and /front-desk/post_prompt

The TypeScript surface serves the agent on one port and its post-prompt handler on another, on Node 20.18.1 or newer:

cd typescript
npm ci
cp ../.env.example .env
POST_PROMPT_URL=https://your-host/post_prompt npm start

The code adds the basic auth credentials from .env to that URL. The platform gets only the URL, and the handler checks them.

Point a number at https://your-host/front-desk/ behind the basic auth in .env. Call it, say something worth remembering, hang up. Call again from the same number.

Verify it

No network, no account.

python verify.py          # from the recipe folder, not python/

The verifier drives the agent’s real app with TestClient and asserts the following.

a SWML request whose body carries call.from renders save_conversation: true, a conversation_id built from that number, a post_prompt, and a post_prompt_url ending in the post-prompt route, and the document validates
a second caller renders a second id, and a request with no caller renders none
a post_conversation POST for each caller returns {"success": true} and both summaries are in the file
after a module reload, fetch_conversation for the first caller returns {"conversation_summary": ...} with that caller’s text, an unknown id returns {}, and the file is unchanged
an unauthenticated fetch is a 401
the TypeScript surface renders the same two params per caller, points post_prompt_url at its own handler, and that handler saves, answers the fetch, returns {} for an unknown id, and refuses a request without credentials

Report an issue