Memory

The memory namespace is what the agent remembers about your tenant. It comes in two flavors that serve different recall patterns and get assembled together at the start of every agent run.

Episodic vs semantic

	Episodic	Semantic
Shape	Concrete events with timestamps	Abstract facts, no time anchor
Example	"On 2026-05-30 the user asked to summarize Acme's pipeline"	"The user prefers brief summaries over verbose ones"
Lifetime	Bounded by retention (default 90 days)	Unbounded — semantic facts persist
Source	Auto-logged from every agent run	Promoted from episodic memory by the promotion pipeline
Storage	`agent_episodes` (Postgres)	`knowledge_graph` semantic nodes

The agent doesn't think about the split. It sees one MEMORY block that's been assembled from both sources, ordered by relevance to the current task.

How recall works

For each agent run, the context assembler:

Takes the user's question + the current surface (Today, Inbox, chat, etc.).
Embeds it.
Runs two parallel queries:
- Episodic: vector similarity over recent agent_episodes, filtered by tenant.
- Semantic: graph_semantic_search RPC over semantic nodes tagged kind='memory'.
Interleaves the top-N results into one MEMORY block.

You can see the exact assembled MEMORY for any agent run by clicking View context in the run drawer.

The promotion pipeline

Episodic memory is a firehose — it grows linearly with usage. If it never compacted, recall would degrade as the relevant signal got buried under repetition.

The memory promotion pipeline runs nightly and:

Scans recent episodes (default: last 7 days).
Clusters semantically similar episodes (cosine similarity > 0.85).
Asks the orchestrator to extract a single abstracted fact from each cluster (e.g. 100 "user asks for brief summaries" episodes → one "user prefers brief summaries" semantic fact).
Writes the fact to the knowledge graph as a semantic memory node.
Optionally archives the source episodes (configurable retention).

The result: as the platform learns more, MEMORY shifts from "here are 50 recent things that happened" to "here are 8 stable facts about you, plus the 3 most relevant recent events." The agent sees less noise and more signal over time.

What ends up in memory

Type	Captured?	Example
User questions to the agent	Yes (episodic)	"What's our pipeline look like?"
Agent responses	Summarized (episodic)	The orchestrator's final synthesis
Tool calls	Yes (episodic, structured)	`graph_semantic_search(...)` + result count
User preferences	Yes (semantic, promoted)	"prefers JSON over prose for technical answers"
Business facts	No — those live on the entity, not in memory	Deal stages, contact details

Memory is about how you interact with the agent. Entity facts (deals, contacts, etc.) live on the entities themselves and the agent retrieves them via the knowledge graph.

Resetting memory

Sometimes you want to start clean — for testing, or because the agent latched onto an outdated pattern.

Cloud: Settings → Privacy → Reset agent memory. Soft-deletes episodic + semantic memory for your user. Doesn't touch entity data.

Self-host: Same UI path, plus the ccd memory reset --user <id> CLI for scripted use.

Memory regenerates as you use the platform; there's no permanent loss beyond what was in memory itself.

Multi-tenant safety

Every memory query is strictly tenant-scoped at the database level via RLS. The agent never sees memory from another tenant even in cross-tenant flows like benchmarks — those flows operate on aggregates, not on raw memory rows. See Security model for the RLS contract.