Memory Curator

Maintenance operations for memory stores — prune, deduplicate, consolidate, and clear.

Memory Curator

The Curator provides maintenance operations across all memory stores. Access it via agent.memory.curator.

Pruning Old Data

Remove entries older than a specified number of days:

const pruned = await agent.memory.curator.prune({
  maxAgeDays: 90,
  userId: "user-123",
  agentName: "assistant",
});

console.log(`Pruned ${pruned} old entries`);

Deduplication

Remove duplicate user facts (case-insensitive):

const removed = await agent.memory.curator.deduplicate({
  userId: "user-123",
});

console.log(`Removed ${removed} duplicate facts`);

Consolidation (LLM-Powered)

Go beyond exact-text dedup — use an LLM to identify and merge semantically similar facts:

import { openai } from "@agentium/core";

const merged = await agent.memory!.curator.consolidate({
  userId: "user-123",
  model: openai("gpt-4o-mini"),
  similarityThreshold: 0.8,
});

console.log(`Consolidated ${merged} redundant facts`);
// "Likes dark mode" + "Prefers dark themes in apps" → "Prefers dark mode/themes in all applications"

Consolidation:

• Groups semantically similar facts using the LLM
• Merges each group into a single authoritative fact
• Preserves the most specific/recent information
• Returns the count of facts that were merged

This is more powerful than deduplicate(), which only catches exact text matches.

---

Clear All Data

Wipe all memory data for a user and/or agent:

await agent.memory.curator.clearAll({
  userId: "user-123",
  agentName: "assistant",
});

Scoping

You can scope clearAll to different levels:

// Clear all of user-123's memory (facts, profile, entities, procedures).
// Other users' data is untouched. This is the GDPR Article 17 path.
await curator.clearAll({ userId: "user-123" });

// Clear an agent's decision log (all users, that agent only).
await curator.clearAll({ agentName: "assistant" });

// Clear a specific user's data PLUS the agent's decision log.
await curator.clearAll({ userId: "user-123", agentName: "assistant" });

// Nuclear option: clear ALL memory data.
await curator.clearAll({});

clearAll({ userId }) never wipes data belonging to other users, regardless of how it is called. See Multi-User Isolation for the full contract.

Scheduling Maintenance

For production use, run curator operations on a schedule:

import { CronJob } from "cron";

new CronJob("0 3 * * *", async () => {
  await agent.memory.curator.prune({ maxAgeDays: 90, userId: "user-123" });
  await agent.memory.curator.deduplicate({ userId: "user-123" });
}).start();

---

Full Maintenance Example

A production-ready maintenance script that runs daily:

import { Agent, MongoDBStorage, openai } from "@agentium/core";

const storage = new MongoDBStorage({ uri: process.env.MONGODB_URI! });

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  memory: {
    storage,
    summaries: true,
    userFacts: true,
    entities: true,
    decisions: true,
  },
});

async function runMaintenance() {
  const curator = agent.memory!.curator;

  // Step 1: Prune old data (older than 90 days)
  const pruned = await curator.prune({
    maxAgeDays: 90,
    agentName: "assistant",
  });
  console.log(`Pruned ${pruned} old entries`);

  // Step 2: Deduplicate user facts for all active users
  const activeUsers = await storage.listUsers("assistant");
  let totalDeduped = 0;
  for (const userId of activeUsers) {
    const removed = await curator.deduplicate({ userId });
    totalDeduped += removed;
  }
  console.log(`Removed ${totalDeduped} duplicate facts across ${activeUsers.length} users`);

  // Step 3: Log maintenance results
  console.log(`Maintenance complete: ${pruned} pruned, ${totalDeduped} deduped`);
}

// Run daily at 3 AM
import { CronJob } from "cron";
new CronJob("0 3 * * *", runMaintenance).start();

---

Learnings Pruning (v2.6+)

prune({ maxAgeDays, agentName }) (or userId) now also sweeps the learnings store. Conservative defaults: only unverified (llm-extracted) learnings are age-pruned and old invalidated ones purged — human-authored knowledge is never removed. For fine-grained control (sources, includeUntagged), call learnings.pruneLearnings() directly.

---

Reconcile (v2.5+)

Vector-backed stores (Learnings, Corrections) dual-write to KV storage and the vector index. A crash between the two writes leaves KV records that are never retrieved. reconcile() repairs the drift by re-embedding and re-indexing anything missing from the vector store:

const { learnings, corrections } = await agent.memory!.curator.reconcile();
console.log(`Re-indexed ${learnings} learnings, ${corrections} corrections`);

Run it alongside prune/consolidate in your maintenance schedule.

---

Why Maintenance Matters

Without periodic maintenance:

• User facts accumulate — duplicate or stale facts waste context tokens
• Old sessions pile up — storage costs increase
• Entity memory grows — irrelevant entities dilute search results
• Decision logs expand — outdated decisions may mislead the agent
• Dual-write drift accumulates — KV/vector divergence silently hides learnings from retrieval

A weekly or monthly maintenance run keeps memory lean and context relevant.