How to Keep a Run Ledger for a Scheduled AI Agent?

A run ledger is an append-only record of what each scheduled run did, kept where the next run can read it. Each run writes one entry: when it ran, what it checked, what it decided, what it changed, what failed, and what is still open. The next run reads it first, so it never redoes finished work.

A scheduled agent without a ledger is a new hire on every shift. It can run perfectly and still repeat yesterday's work, because yesterday left no trace it can read. The platform's execution history is not a ledger: it records that a run happened, not what the run learned, and it expires.

Why does a scheduled agent need a ledger if the platform already keeps run history?

Platform history answers a different question. It tells you a run started at 2 AM, finished at 2:04, and exited clean. It does not tell the next run which items were already handled, which source was rejected and why, or which follow-up is still waiting on a human.

Three gaps make platform history a poor substitute:

1. It expires. Automation platforms prune execution data after days or weeks, so a question from last month has no answer in the history screen.
2. The next run cannot read it. A run history page is for humans. The next run needs the same facts inside its own context, in a format it can query.
3. It records outcomes, not reasoning. "Success" hides the decision that mattered: why this lead was scored as junk, why that source was skipped, why the digest went out late. When the reasoning is gone, the next run re-derives it from scratch.

A ledger closes all three gaps. It is written by the run, for the next run, and it keeps the reasoning next to the result.

What goes in one ledger entry?

One entry per run, seven fields, no more. A ledger that asks for an essay will not get written. A ledger that asks for seven short lines will.

1. Run identity. Date, time, and a run ID. This is what lets the next run ask "what did the last run do" and get one answer.
2. Trigger and inputs. What kicked the run off and what it looked at: new rows since yesterday, inbox items, API responses, file changes.
3. Decisions. What the run concluded, and the reason in one line each. "12 leads marked spam: no company domain and no reply to two prior messages." The reason is the part that saves the next run's work.
4. Actions and evidence. What the run changed, with proof: emails sent, rows updated, tickets closed, each with an ID or link where one exists.
5. Failures. What broke or was skipped, with the error or the missing input. A skipped step with no note is a silent failure waiting for its second month.
6. Open items. What is still waiting: approvals, replies, retries, and who or what each one waits on.
7. Next run's first check. One line telling the next run where to start: "Start from lead 481. Re-check the pricing page; it returned a stale snapshot on this run."

Write the entry at the end of the run, as the run's last step. A ledger written only on good runs is a highlight reel, not a record.

How do you write the ledger so the next run actually reads it?

Two rules do most of the work.

Read it first, update it last. The run's first step loads the latest entries, especially open items and the last run's first check. Its last step appends its own entry. Without read-first, you have a log nobody consults.

Append only, never rewrite. Correct a mistake with a new dated line saying what changed and why. Never edit an old entry: the moment old entries become editable, nobody trusts them, including the next run.

A file works for one workflow and one operator. A table works when several workflows share it, since every run can query the same rows. A shared memory layer works when the work crosses tools, so a correction made in a phone chat reaches the morning run without anyone copying it anywhere.

Vilix AI is that shared layer option: a cloud-hosted memory layer your agents read and write over MCP, with no infrastructure to manage and the same memory across every connected tool. A run pulls the relevant past entries at the start and saves what it learned at the end, and it stores full conversation history, not just extracted facts. The free plan stays free forever, plus a 7-day Pro trial with no credit card, and everything is exportable or deletable anytime. Learn more at Vilix AI.

What about runs where nothing happened?

Log them anyway. A no-op entry is one line: "No new items. Previous open items unchanged. Next check at the usual time." That line is what separates a healthy quiet week from a broken one.

A run that finds nothing once is normal. A run that finds nothing for a week, when it usually finds something daily, is a signal: the source changed format, the filter broke, the trigger stopped firing. Without no-op entries, you cannot tell "nothing to do" from "not doing its job," because both look like silence. With them, the date the silence started is visible at a glance.

The same logic applies to counts. When a step usually matches a nonzero number of items, record the count even when it is zero. Zero once is fine. Zero for a week is the alert.

How do you keep the ledger from going stale?

A ledger grows forever if you let it, and an unbounded ledger becomes a pile the next run cannot use. Prune it on a schedule:

1. Keep recent entries whole. The last 30 days stay complete, because recent runs are the ones the next run asks about.
2. Summarize older entries monthly. Roll a month of entries into a summary of standing decisions, recurring failures, and still-open items, then archive the detail. The summary is itself a dated ledger entry, so the chain never breaks.
3. Retire closed items explicitly. When an open item resolves, append a line closing it, with the outcome. Open items that never get closed are how a ledger quietly becomes fiction.

Review the ledger yourself once a month: which open items are older than a month, which failures repeat, which decisions would surprise you cold.

Frequently asked questions

Is a run ledger the same as a log file? No. A log file records everything inside a run, mostly for debugging. A ledger records what the run decided and did, in a small fixed format, for the next run to act on. Logs are for humans after a crash. Ledgers are for agents before the next run.

Is a run ledger the same as a done list? No, but they work together. A done list says which items are finished. A ledger says what happened on each run, including failures, open items, and reasoning. The done list stops repeat work on items. The ledger stops repeat reasoning about everything else.