Memory

Memory keeps selected information available across sessions without replaying a full transcript. It is different from Session history and project Knowledge:

Session history is the canonical conversation.
Memory contains durable facts, preferences, open threads, styles, and selected operational learnings.
Knowledge contains project or company source material such as documents and repositories.

Configure an agent

Memory is disabled unless the agent explicitly enables the capabilities it needs. The agent-level configuration is portable between self-hosted Polpo and Polpo Cloud.

{
  "memory": {
    "tools": {
      "search": true,
      "remember": true,
      "update": true,
      "forget": true,
      "writeScope": "invocation-user",
      "writableKinds": ["fact", "preference", "open_thread", "style"]
    },
    "learning": {
      "mode": "suggest",
      "surfaces": ["chat", "channel"],
      "kinds": ["fact", "preference", "open_thread", "style"]
    }
  }
}

writeScope: "invocation-user" requires a trusted external user supplied by the host or Channel identity resolver. Polpo never derives that identity from message text or from the model.

Explicit Memory tools

The tool settings expose only the corresponding typed tools:

Setting	Tool	Purpose
`search`	`memory_search`	Retrieve bounded relevant items
`remember`	`memory_remember`	Store an explicit durable item
`update`	`memory_update_item`	Correct an existing item
`forget`	`memory_forget`	Remove an item from active retrieval

The agent’s global and per-surface tool policies must also allow each tool. Memory settings can narrow tool availability but cannot widen the agent’s authorization ceiling.

Automatic learning

Automatic learning analyzes a successfully completed canonical conversation turn after it is durably persisted. It runs outside the response path and does not depend on the SSE connection remaining open.

Mode	Behavior
`off`	Do not analyze turns or create suggestions. This is the default.
`suggest`	Create pending suggestions for an authorized operator to review.
`automatic`	Apply only policy-safe candidates; ambiguous or sensitive candidates remain reviewable or are rejected.

The initial eligible surfaces are direct chat and Channels. Nested Project Loop agent steps, failed or cancelled turns, incomplete ask-user/client-tool continuations, tasks, and schedules do not independently create Memory. The extractor receives bounded visible conversation content. It does not receive hidden reasoning, Connection secrets, trusted hidden bindings, or unrelated history. Assistant claims alone cannot establish a user fact.

Automatic learning also requires the host rollout to permit it. A saved agent setting does not override a Cloud kill switch, project rollout, authorization policy, or entitlement.

Review suggestions

In Polpo Cloud, open the agent’s Memory page and select Learning. Enter the hosted application’s external user ID to inspect that user’s pending suggestions. Approval and rejection use optimistic revisions so concurrent reviews fail instead of overwriting one another. The CLI offers the same authorized workflow for a linked project:

polpo memory candidates list \
  --agent support-agent \
  --user customer_123 \
  --status pending

polpo memory candidates approve candidate_id \
  --agent support-agent \
  --user customer_123 \
  --revision 1 \
  --apply

polpo memory candidates reject candidate_id \
  --agent support-agent \
  --user customer_123 \
  --revision 1 \
  --reason "Temporary request"

Use polpo memory candidates get, audit, and apply for inspection, audit history, and a separate apply step. Add --json for automation. The external user ID is sent as trusted request context and is not accepted from candidate content.

Typed Memory API

Project API keys manage Memory through the agent-scoped data plane:

Method	Path	Description
`GET`	`/v1/memory/agents/{agentName}/memory/items`	List typed items with cursor pagination
`POST`	`/v1/memory/agents/{agentName}/memory/items`	Create an authorized item
`POST`	`/v1/memory/agents/{agentName}/memory/search`	Retrieve bounded relevant items
`GET`	`/v1/memory/agents/{agentName}/memory/items/{itemId}/usage`	Inspect usage events
`PATCH`	`/v1/memory/agents/{agentName}/memory/items/{itemId}`	Update mutable fields
`DELETE`	`/v1/memory/agents/{agentName}/memory/items/{itemId}`	Forget an item
`GET`	`/v1/memory/agents/{agentName}/memory/candidates`	List learning candidates
`POST`	`/v1/memory/agents/{agentName}/memory/candidates/{candidateId}/decision`	Approve or reject
`POST`	`/v1/memory/agents/{agentName}/memory/candidates/{candidateId}/apply`	Apply an approved candidate

For user-scoped operations, send x-polpo-external-user-id from trusted application code. Never let the model or untrusted message content choose this header.

Legacy static Memory

.polpo/memory.md and .polpo/memory/{agentName}.md are the legacy static prompt-memory format. They remain compatible, but they are not a serialization of typed Memory items and do not provide external-user isolation, selective retrieval, provenance, lifecycle, candidate review, or precise forget semantics.

Getting Started

Platform

Agents

Orchestration

Configure an agent

Explicit Memory tools

Automatic learning

Review suggestions

Typed Memory API

Legacy static Memory

​Configure an agent

​Explicit Memory tools

​Automatic learning

​Review suggestions

​Typed Memory API

​Legacy static Memory

Configure an agent

Explicit Memory tools

Automatic learning

Review suggestions

Typed Memory API

Legacy static Memory