Memory

telnyx-acp set memory '{ "type": "agent_memory",
                          "namespace": "default",
                          "profile": "{{conversation}}" }'

support-agent/
├── agent.json                                         ◀
├── instructions.md
└── .telnyx/                        written by deploy
    ├── index.ts                                       ◀
    ├── telnyx.toml
    ├── telnyx-env.d.ts
    └── package.json

@telnyx/acp/                      the package
├── managed/
│   ├── index.ts
│   ├── agent.ts                                       ◀
│   ├── model.ts
│   ├── memory.ts                                      ◀
│   ├── tools.ts
│   ├── mcp.ts
│   ├── voice.ts
│   ├── direct-turn.ts
│   └── filler.ts
├── channels/
│   ├── index.ts
│   ├── phone.ts
│   ├── email.ts
│   ├── web.ts
│   └── wire.ts
├── synth/
│   ├── index.ts
│   ├── code-entry.ts
│   └── vendor.ts
└── spec/
    ├── schema.ts
    ├── model.ts
    ├── phone.ts
    ├── project.ts
    └── io.ts

The memory block is written by set memory, or by the wizard. It becomes spec.memory in .telnyx/index.ts, and each conversation’s memory is built on demand by memory() in managed/agent.ts:

// managed/agent.ts
async memory() {
  const conversation = this.memoryConversation ?? (await this.getState()).from ?? this.conversationName();
  if (conversation === undefined) return undefined;
  if (conversation !== this.memoryKey) {
    this.memoryKey = conversation;
    this.memoryInstance = createAgentMemory(this.spec.memory, this.env.TELNYX, conversation);
  }
  return this.memoryInstance;
}

this.getState() is getState(). Its from is the sender that admit wrote. On a fresh instance it returns initialState(), which the class defines as {}. this.env.TELNYX is the Telnyx binding of the instance’s env. Both calls on Agent Memory go through it, and without it there is no memory. The conversation key is the caller’s number on a call, set by the voice class, or the sender of the last text or email, held in state. A conversation with neither, such as one reached by invoke or chat, is keyed on its own name, which conversationName() decodes from the instance’s id:

// managed/agent.ts
conversationName() {
  try {
    return decodeAgentName(this.ctx.id);
  } catch {
    return undefined;
  }
}

decodeAgentName(this.ctx.id) is decodeAgentName().

this.ctx.id is the instance’s actor id, from ctx, which the mount encoded from the conversation’s name.
It returns that name, such as alice for invoke --conversation alice.
It throws for an id the mount did not make. The key is then undefined, and the conversation has no memory.

createAgentMemory in managed/memory.ts resolves {{conversation}} in the profile template to that key and makes two calls on Agent Memory.

The summary is read at the start, bounded by CARD_TIMEOUT_MS of one second.
The conversation is pushed at the end.

Memory is the user-facing page.

Get Started

Inside the Managed Harness

The Agent Harness SDK

The Agent Runtime SDK

The Agent Client SDK

For AI Agents