Long-running agents that stay on course

A long-running agent — a migration, a refactor, a research sweep — drifts across sessions. It forgets the constraints you set on day one, re-proposes approaches you already rejected, and loses track of what's done versus in-progress.

This tutorial shows how to back an agent run with Stateful so it resumes where it left off, without drift.

What you'll need

• Stateful connected to GitHub (or GitLab), and the Local Codebase source if you want the agent to see your files
• MCP wired to your AI (Claude.ai, Cursor, or Claude Code)
• The task your agent will work on

Step 1: Capture your constraints before you start

Tell the assistant the hard rules for this project, one at a time:

"For the migration project: never modify files in services/node/src/app/core/ directly — those changes go through PR review. Always run pnpm test before marking a task complete. Prefer small, atomic commits."

Each one is captured as a typed constraint and added to your profile. From then on they're surfaced to the agent via get_context every time it starts a new session. You set them once; the agent follows them across every restart.

Step 2: Write the project brief

In your wiki, type [[ and create a new page for this run as a Project — something like "Migration: Node → Python services." Fill it in with:

• Goal — one sentence
• Scope — what's in, what's out
• Decisions made — choices already locked in
• Progress — what's done, what's next

The agent can read this page with read_subject and propose updates with propose_subject_edit (which land in your inbox for approval).

Step 3: Start the agent with a grounded prompt

Your first prompt should make the agent read its context before doing anything:

You're working on a multi-day migration. Before you start:
1. Call get_context with "what is the migration project and its current state?"
2. Read the project brief.
3. Summarize what you know and what you're about to do.

Don't start work until you've confirmed your understanding.

Step 4: End each session with an update

Before you close a session, have the agent update its own brief:

Update the migration project brief with what you completed, what's next,
and any decisions or constraints you ran into. Use propose_subject_edit —
I'll approve it.

The proposed edit lands in your inbox. Approve it, and the next session starts from the updated brief.

Step 5: Spot-check for drift

At the start of each session:

Before we continue, tell me from your context (don't guess):
1. What constraints apply to this project?
2. What did we complete last session?
3. What's next?

If the answers are right, you're in sync. If something's off, correct it explicitly so your wiki reflects the truth.

Why this works

The agent loses its conversational memory at every reset. What it keeps is access to Stateful. Your wiki becomes the agent's external memory — persistent, structured, and editable by you when it drifts. The constraints you set on day one are still there on day six, surfaced automatically via get_context.