knowledge_set_retention

Configure automatic data retention policies to archive outdated project memory entries based on time-to-live settings, managing storage efficiently.

Instructions

Set an automatic data retention policy (TTL) for a project's memory. Entries older than ttl_days will be soft-deleted (archived) automatically on every server startup and every 12 hours while running.

Use cases:

Set ttl_days: 90 to auto-expire sessions older than 3 months
Set ttl_days: 0 to disable auto-expiry (default)

Note: Rollup/compaction entries are never expired — only raw sessions.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`project`	Yes	Project to set retention policy for.
`ttl_days`	Yes	Entries older than this many days are auto-expired. Set to 0 to disable. Minimum: 7 days when enabled.

Implementation Reference

src/tools/sessionMemoryHandlers.ts:1847-1907 (handler)

The knowledge_set_retention tool handler, which sets a TTL for a project's memory and runs an initial sweep.

// ─── v3.1: Knowledge Set Retention Handler ────────────────

/**
 * Set a TTL (data retention policy) for a project.
 * Saves the policy to configStorage, then immediately runs one sweep
 * to expire any entries that are already over the TTL.
 */
export async function knowledgeSetRetentionHandler(args: unknown) {
  if (!isKnowledgeSetRetentionArgs(args)) {
    throw new Error("Invalid arguments for knowledge_set_retention");
  }

  const { project, ttl_days } = args;

  if (ttl_days < 0) {
    return {
      content: [{ type: "text", text: "Error: ttl_days must be 0 (disabled) or a positive integer." }],
      isError: true,
    };
  }

  if (ttl_days > 0 && ttl_days < 7) {
    return {
      content: [{ type: "text", text: "Error: Minimum TTL is 7 days to prevent accidental data loss." }],
      isError: true,
    };
  }

  const storage = await getStorage();

  // Save policy to configStorage so server.ts sweep can read it
  await storage.setSetting(`ttl:${project}`, String(ttl_days));

  if (ttl_days === 0) {
    return {
      content: [{
        type: "text",
        text: `✅ Data retention **disabled** for project \"${project}\".\n\nEntries will be kept indefinitely.`,
      }],
      isError: false,
    };
  }

  // Run an immediate sweep for entries already past TTL
  const result = await storage.expireByTTL(project, ttl_days, PRISM_USER_ID);

  return {
    content: [{
      type: "text",
      text:
        `⏱️ **Retention policy set** for project \"${project}\":\n\n` +
        `- Auto-expire entries older than: **${ttl_days} days**\n` +
        `- Sweep runs on: server startup + every 12 hours\n` +
        `- Rollup/compaction entries: **never expired**\n\n` +
        (result.expired > 0
          ? `🗑️ Immediately expired **${result.expired}** entries already past the ${ttl_days}-day threshold.`
          : `✅ No existing entries exceeded the ${ttl_days}-day threshold.`),
    }],
    isError: false,
  };
}

src/tools/sessionMemoryDefinitions.ts:819-846 (schema)

The tool definition and schema for knowledge_set_retention.

export const KNOWLEDGE_SET_RETENTION_TOOL: Tool = {
  name: "knowledge_set_retention",
  description:
    "Set an automatic data retention policy (TTL) for a project's memory. " +
    "Entries older than ttl_days will be soft-deleted (archived) automatically " +
    "on every server startup and every 12 hours while running.\n\n" +
    "**Use cases:**\n" +
    "- Set `ttl_days: 90` to auto-expire sessions older than 3 months\n" +
    "- Set `ttl_days: 0` to disable auto-expiry (default)\n\n" +
    "**Note:** Rollup/compaction entries are never expired — only raw sessions.",
  inputSchema: {
    type: "object",
    properties: {
      project: {
        type: "string",
        description: "Project to set retention policy for.",
      },
      ttl_days: {
        type: "integer",
        description:
          "Entries older than this many days are auto-expired. " +
          "Set to 0 to disable. Minimum: 7 days when enabled.",
        minimum: 0,
      },
    },
    required: ["project", "ttl_days"],
  },
};

src/server.ts:158-158 (registration)
Registration of knowledgeSetRetentionHandler in the main server tools list.
```
knowledgeSetRetentionHandler,
```

Prism MCP