CUGA LogoCUGA AGENT
Build

Memory

Learn from past runs — inject guidelines on similar tasks and save trajectories after each run.

Memory

Memory lets CUGA learn from past runs. Before a similar task, it injects guidelines into the prompt. After the run, it saves the trajectory so the next time is faster and less error-prone.

The engine behind it is altk-evolve. You enable Memory in settings; you do not wire Evolve as a separate product.

Architecture: Memory is a Capability layer feature. Trajectories persist in Postgres/pgvector (Persistence). See How CUGA works.


What happens during a run

Task
Recall guidelines
Prompt + run
Save trajectory
Next run is better
Memory looks up guidelines before the run, then saves the trajectory after — it never blocks the task.

If Memory is unavailable, times out, or returns nothing, CUGA continues — it never blocks the task.


Enable

Memory is used in CugaLite. Turn it on in settings.toml:

[evolve]
enabled = true
mode = "auto"
app_name = "evolve"
lite_mode_only = true
save_on_success = true
save_on_failure = true
async_save = true
timeout = 30.0

The [evolve] keys are the Memory backend. Full list: Settings reference.


How the Memory service runs

Let the CUGA MCP registry launch it. In the Manage UI, add an MCP tool with:

  • Name: evolve
  • Connection type: Command (stdio)
  • Command: uvx
  • Args: --from altk-evolve --with setuptools<70 evolve-mcp

Add these env values on the same tool:

EVOLVE_BACKEND=postgres
EVOLVE_PG_HOST=localhost
EVOLVE_PG_PORT=5432
EVOLVE_PG_USER=postgres
EVOLVE_PG_PASSWORD=postgres
EVOLVE_PG_DBNAME=evolve
EVOLVE_MODEL_NAME=Azure/gpt-4o
OPENAI_API_KEY=env://OPENAI_API_KEY
OPENAI_BASE_URL=env://OPENAI_BASE_URL

env://VAR reads from CUGA's own environment at runtime. Leave mode = "auto" (or "registry") and app_name = "evolve".

Run the service yourself (useful for debugging):

# From a checkout of altk-evolve:
uv sync --extra pgvector
evolve-mcp --transport sse --port 8201
[evolve]
enabled = true
url = "http://127.0.0.1:8201/sse"
mode = "direct"

mode = "direct" skips registry lookup.

The Memory MCP server needs model credentials (EVOLVE_MODEL_NAME, OpenAI/LiteLLM keys). Without them, saving trajectories can fail even if the connection works.


Try it

cuga start demo_crm --sample-memory-data

Then run a CugaLite task, for example:

Identify the common cities between my cuga_workspace/cities.txt and cuga_workspace/company.txt

Tuning

SettingEffect
async_save = trueSave in the background; does not block the answer
save_on_success / save_on_failureWhat to persist
mode = "auto"Registry first, then direct SSE
mode = "registry"Registry only
mode = "direct"Use url only
lite_mode_only = trueMemory only on the CugaLite path

Experimental Memory workspace

The supported full image includes the experimental memory-management workspace. When memory features are available, open Memory from chat navigation to inspect guidance, preferences, source conversations, and usage.

ControlScope
Personal memoryInspect your memory records, open authorized source conversations, edit supported metadata, and forget records.
Personal memory preferenceTurn retrieval and saving off for your conversations. Reading and personal deletion remain available while service memory is off.
Service memoryAdministrators control memory for the service; user preferences cannot override a disabled service.
Episodic memoryAdministrators control episodic processing/retrieval independently of semantic facts.
RetentionAdministrators manage rules, schedules, pending candidates, and activity when the backend exposes the required capabilities.

Memory records and preferences are scoped to the service and caller. Administrative access requires the server's Manage authorization; personal access uses Chat authorization. See Authentication.

CUGA Memory workspace showing illustrative memory records

Illustrative sample data from the product UI; this screenshot does not show a live inference run. Media provenance.

Bundled management and retention

Use the full image for the bundled Evolve HTTP worker. The slim image excludes Evolve and its PII subsystem. Configure a stable service instance ID and PostgreSQL for durable retention:

DYNACONF_SERVICE__INSTANCE_ID=cuga-production
DYNACONF_EVOLVE__ENABLED=true
DYNACONF_EVOLVE__MODE=direct
DYNACONF_EVOLVE__URL=http://127.0.0.1:8201/sse
CUGA_EMBEDDED_EVOLVE=true
EVOLVE_BACKEND=postgres
EVOLVE_PG_HOST=your-postgres-host
EVOLVE_PG_PORT=5432
EVOLVE_PG_USER=your-evolve-user
EVOLVE_PG_PASSWORD=<your-evolve-password>
EVOLVE_PG_DBNAME=evolve
EVOLVE_MODEL_NAME=Azure/gpt-4o
OPENAI_API_KEY=<your-evolve-model-key>
OPENAI_BASE_URL=https://your-inference-endpoint.example.com

Choose an Evolve model/provider configuration compatible with your inference endpoint. Evolve needs its own model configuration in this version; configuring an agent's Manage LLM connection does not automatically configure the worker. See the configuration guide.

The container supervisor starts the private worker and CUGA together, generates an internal API credential, and scopes Evolve to the service instance. Keep that private API internal. Registry-managed or explicit external Evolve endpoints remain external; an MCP-only integration can retrieve guidelines and save trajectories but does not expose the bundled native retention API.

Retention capabilities

The UI reflects the backend's reported capabilities. Durable collection and source-deletion handling require PostgreSQL and the bundled native service. The standard policy contains these rules:

RuleDefault action
orphaned-conversationsDelete after the source conversation has been deleted for 7 days, where supported.
unused-guidelinesDelete guidelines unused for 180 days; skip when access signals are missing.
stale-guidelinesFlag guidelines older than 90 days.
old-sessionsDelete trajectories older than 365 days with derived-record cascading.

Review rules and pending candidates before running retention. Schedules are stored and executed by Evolve; activity records the outcomes.

CUGA administrator retention controls with illustrative data

Retention controls shown with illustrative sample data from the same product capture.

Protection hooks

The full image includes configured memory-write and model-egress protection hooks, including structured-identifier filtering and READI named-entity redaction. Check the workspace's compliance/capability status for the active deployment. The slim image does not include these Evolve hooks.