Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xhipai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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 everything for a specific user across all agents
await curator.clearAll({ userId: "user-123" });

// Clear everything for a specific agent (all users)
await curator.clearAll({ agentName: "assistant" });

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

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

​
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();

​
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
A weekly or monthly maintenance run keeps memory lean and context relevant.