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
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.0The [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_URLenv://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-dataThen run a CugaLite task, for example:
Identify the common cities between my cuga_workspace/cities.txt and cuga_workspace/company.txtTuning
| Setting | Effect |
|---|---|
async_save = true | Save in the background; does not block the answer |
save_on_success / save_on_failure | What to persist |
mode = "auto" | Registry first, then direct SSE |
mode = "registry" | Registry only |
mode = "direct" | Use url only |
lite_mode_only = true | Memory 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.
| Control | Scope |
|---|---|
| Personal memory | Inspect your memory records, open authorized source conversations, edit supported metadata, and forget records. |
| Personal memory preference | Turn retrieval and saving off for your conversations. Reading and personal deletion remain available while service memory is off. |
| Service memory | Administrators control memory for the service; user preferences cannot override a disabled service. |
| Episodic memory | Administrators control episodic processing/retrieval independently of semantic facts. |
| Retention | Administrators 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.
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.comChoose 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:
| Rule | Default action |
|---|---|
orphaned-conversations | Delete after the source conversation has been deleted for 7 days, where supported. |
unused-guidelines | Delete guidelines unused for 180 days; skip when access signals are missing. |
stale-guidelines | Flag guidelines older than 90 days. |
old-sessions | Delete 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.
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.
Related
- Knowledge — documents the agent can cite (not the same as Memory)
- Context summarization — compress this thread, not learn across runs
- Settings reference
