Memory

Sessions end. Memory does not. An agent with memory starts the next conversation knowing what it learned in the last one.

Memory is for what the agent worked out. For reference material you author, use a knowledge space; for a paragraph of standing context, use the agent's knowledge base.

Types

Write a memory

await commons.memory.create({
  agentId,
  memoryType: 'semantic',
  content: "Alex works in product management and prefers bullet-point answers.",
  summary: 'Alex — role and formatting preference',
  tags: ['user_info'],
  importanceScore: 0.8,
});

summary is the short label shown in listings; content is what gets embedded. importanceScore (0–1) biases retrieval when several memories are similarly relevant. Reserve the high end for things that should almost always surface.

Retrieve

Retrieval is semantic — content is embedded on write and matched by meaning, not keywords.

const { data: hits } = await commons.memory.retrieve(
  agentId,
  'how does this user like their answers formatted',
  5,
);

agc memory search "formatting preferences" --agent <agentId>

Browse and prune

agc memory list --agent <agentId> --type semantic --limit 50
agc memory stats --agent <agentId>
agc memory delete <memoryId>

const { data: stats } = await commons.memory.stats(agentId);
await commons.memory.update(memoryId, { content: 'Corrected fact…' });
await commons.memory.delete(memoryId);

A memory that was true and is not any more is worse than no memory. Update or delete stale entries rather than adding a contradiction and hoping retrieval picks the newer one.

Shared scopes

A shared scope is one attributed pool several agents draw on — useful when a team of agents should learn from each other's work rather than each rediscovering the same fact.

const { data: scope } = await commons.memory.createSharedScope({
  name: 'Support team knowledge',
  description: 'What the support agents have learned about our customers',
  agentIds: [triageAgentId, escalationAgentId, followUpAgentId],
});
 
const { data: scopes } = await commons.memory.listSharedScopes(agentId);

Entries stay attributed to the agent that wrote them, so a wrong fact can be traced back to where it came from.

Practical notes

• Write few, specific memories. "Prefers bullet points" retrieves well; a transcript does not.
• One fact per entry. Two facts in one entry retrieve as a compromise between them.
• Tag by subject, so you can list and prune a topic later.
• Do not store secrets. Memory is retrieved into prompts by design.
• Prune on a schedule. A task that reviews memories monthly keeps the pool honest.