Building Incremental Memory Updates with the Continual Learning Plugin for AGENTS.md

The Continual Learning plugin incrementally updates your workspace AGENTS.md file by scanning new agent transcripts, extracting durable user preferences and workspace facts, and merging them into structured sections while using a JSON index to avoid reprocessing historical data.

Building incremental memory updates with the Continual Learning plugin for AGENTS.md enables Cursor agents to persist critical context across sessions without expensive full-history reprocessing. The plugin implements a guard-rail-first architecture that strictly maintains two designated sections in AGENTS.md, caps memory items at twelve per section, and tracks processed transcripts via a lightweight modification-time index.

Architecture Overview

The plugin consists of three core components working in concert to provide atomic, resume-capable memory updates.

The Skill Orchestrator

Located at continual-learning/skills/continual-learning/SKILL.md, the skill serves as the entry point. Its sole responsibility is to invoke the agents-memory-updater sub-agent and return the result unmodified. This separation of concerns allows the complex update logic to remain isolated while providing a simple declarative interface for Cursor's runtime.

The Memory Update Agent

The agent defined in continual-learning/agents/agents-memory-updater.md implements the full incremental pipeline:

1. Load or create AGENTS.md with the two required sections (## Learned User Preferences and ## Learned Workspace Facts)

2. Load the incremental index from .cursor/hooks/state/continual-learning-index.json

3. Discover new transcripts in ~/.cursor/projects/<workspace-slug>/agent-transcripts/ by comparing file modification times against the index

4. Extract durable bullet points representing long-term preferences and stable facts

5. Merge extracted bullets into the appropriate sections, deduplicating semantically similar entries and enforcing the 12-item cap per section

6. Update the index with processed file paths and their latest mtime values

The Persistent Index

The continual-learning-index.json file stores a simple map of { transcriptPath: mtime }. This enables the plugin to perform incremental processing across invocations, ensuring that only newly modified or unseen transcripts are examined. The index also undergoes pruning to remove entries for deleted files, preventing phantom dependencies.

How the Incremental Update Loop Works

The update algorithm follows a strict six-phase flow designed to minimize I/O while maintaining consistency:

1. Initialization – If AGENTS.md does not exist, the agent creates it with the two required headings and no content.

2. Index Loading – The JSON index is read from disk or initialized as an empty object if absent.

3. Transcript Discovery – The agent walks the transcript directory and selects only files where stat.mtime is newer than the stored timestamp in the index.

4. Signal Extraction – Using heuristics defined by the skill author, the agent parses bullet-point-style statements that represent durable knowledge (e.g., " prefer TypeScript over JavaScript" or "CI runs on Node.js 20").

5. Merging – Existing bullets are updated in place when semantically similar, new bullets are appended, and the list is truncated to maintain the 12-item maximum per section.

6. Index Refresh – Processed transcripts are recorded with their current mtime, and the updated index is written back to .cursor/hooks/state/.

Because the index persists across invocations, the plugin never re-processes the same transcript, making updates cheap even for workspaces with extensive conversation histories.

AGENTS.md Structure and Constraints

The plugin enforces a rigid output format to ensure downstream agents can reliably parse the memory file.

## Learned User Preferences

- Prefer TypeScript over JavaScript for new projects.
- Use ESLint with the `@typescript-eslint` plugin.

## Learned Workspace Facts

- The primary repository is hosted on GitHub under `cursor/plugins`.
- CI runs on Node.js 20.

Guardrails enforced by the agent:

• Only the two headings above are ever written
• Output is restricted to plain bullet points
• No confidence tags, rationale, or private data are emitted
• Each section caps at 12 items to prevent context overflow

When the merge yields no changes, the agent returns the exact contract string:

No high-signal memory updates.

Implementing the Plugin

Triggering the Skill

Invoke the Continual Learning plugin from any Cursor prompt or parent skill by referencing its name:

# In a Cursor prompt or skill definition

name: continual-learning

The skill definition in continual-learning/skills/continual-learning/SKILL.md then delegates to the agent:

1. Call `agents-memory-updater`.
2. Return the updater result.

Plugin Configuration

The plugin registration occurs in continual-learning/.cursor-plugin/plugin.json, which declares the skill location and any runtime hooks:

{
  "skills": ["continual-learning"],
  "hooks": ["continual-learning"]
}

This declaration allows the Cursor runtime to locate the skill directory and initialize the state management required for the incremental index.

Conceptual Implementation Flow

While the actual implementation resides in the Markdown agent definition, the logic follows this TypeScript-inspired structure:

// Simplified flow based on agents-memory-updater.md logic
async function runContinualLearning() {
  const agentsMd = await readOrCreateAgentsMd();
  const index = await loadIndex('.cursor/hooks/state/continual-learning-index.json');
  
  const transcriptDir = `~/.cursor/projects/${workspaceSlug}/agent-transcripts/`;
  const newTranscripts = await findNewTranscripts(transcriptDir, index);
  
  const bullets = await extractBullets(newTranscripts);
  const merged = mergeBullets(agentsMd, bullets, { maxItems: 12 });
  
  if (merged.changed) {
    await writeFile('AGENTS.md', merged.content);
  }
  
  await saveIndex('.cursor/hooks/state/continual-learning-index.json', updatedIndex);
  return merged.changed ? 'AGENTS.md updated.' : 'No high-signal memory updates.';
}

Summary

• The Continual Learning plugin provides incremental updates to AGENTS.md by tracking processed transcripts via a JSON index stored in .cursor/hooks/state/

• The agent at continual-learning/agents/agents-memory-updater.md enforces strict guardrails, only writing to ## Learned User Preferences and ## Learned Workspace Facts with a maximum of 12 items per section

• The skill at continual-learning/skills/continual-learning/SKILL.md serves as a thin orchestration layer that invokes the updater and returns results directly

• Incremental processing works by comparing transcript modification times against the continual-learning-index.json index, ensuring only new content is examined

• No-change detection returns the exact string "No high-signal memory updates." to signal that no updates were necessary

Frequently Asked Questions

What is the Continual Learning plugin?

The Continual Learning plugin is a Cursor extension that maintains durable workspace memory by incrementally updating the AGENTS.md file with extracted user preferences and workspace facts. It operates as a self-contained unit within the cursor/plugins repository, consisting of a skill definition, an agent implementation, and a persistent JSON index for tracking processed transcripts.

How does the incremental index prevent reprocessing?

The plugin stores a JSON map of file paths to modification timestamps at .cursor/hooks/state/continual-learning-index.json. During each run, it compares the current mtime of transcript files in ~/.cursor/projects/<workspace-slug>/agent-transcripts/ against the stored values. Only files with newer timestamps or no index entry are processed, and the index is updated atomically after successful completion.

What happens when no high-signal updates are found?

When the agent determines that no new durable preferences or facts can be extracted from recent transcripts, or when all extracted content duplicates existing entries, it returns the exact string No high-signal memory updates. This contract allows upstream skills to detect idempotent runs and avoid unnecessary file writes to AGENTS.md.

Where are the plugin configuration files located?

The plugin metadata resides in continual-learning/.cursor-plugin/plugin.json, which declares the plugin's skills and hooks. The skill definition is located at continual-learning/skills/continual-learning/SKILL.md, while the core agent logic implementing the incremental algorithm is defined in continual-learning/agents/agents-memory-updater.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}