Knowledge maintenance

Knowledge runs one small scheduled pass. Part of the Knowledge plugin guide.

The pass currently does one job, relink: it links claims that knowledge_remember saved without a subject to the one entity page they name. Relink never calls a model, never creates pages or stores, and never changes claim text, evidence, or lifecycle.

Relink

A claim qualifies when it is active, valid, has no linked entities, and cites a retained knowledge_remember excerpt. Claims are processed in stable ID order:

A link is an entities annotation, published through the normal journal, receipt, and local Git path. Each link's request ID derives from the claim ID, revision, and subject, so an interrupted pass replays instead of duplicating. A link that cannot publish counts as failed and is retried on the next pass.

Run it on demand

knowledge_relink runs relink in the caller's authorized partition. It needs writes enabled.

• dryRun: true reports counts and up to 10 examples per outcome without publishing. Run it first.
• limit (1–500, default 100) bounds how many unlinked claims one call examines.
• Follow nextCursor with the same dryRun value until it is null.
• include: "all" (dry run only) lists every current claim with no linked page and no source page, whichever tool saved it. Relink links only remembered claims; the rest are for review.

Schedule

The pass is on by default and runs daily at 03:30 in the Gateway host's time zone. It uses the plugin service scheduler, so it does not appear in OpenClaw automations. It runs only while writesEnabled is true.

{  plugins: {    entries: {      knowledge: {        config: {          maintenance: {            enabled: true,            schedule: "30 3 * * *",            timezone: "America/Los_Angeles",          },        },      },    },  },}

schedule is a five-field cron expression (minute, hour, day, month, weekday). Schedules use local civil time in the configured zone. A spring-forward change on a skipped day does not discard matching midnight slots on the following day. A configured time that does not exist during the forward jump is skipped. An invalid schedule or time zone does not disable the plugin: the pass is not scheduled, a warning is logged, and Settings → Maintenance shows the error.

Each pass visits every store and every conversation partition in it, in pages of 500 claims. Stores that do not exist yet or are not ready are skipped and never created. One failing store does not stop the others. A plugin reload or store reassignment ends the current pass.

The next slot and the last results persist in <state dir>/knowledge/registry.sqlite. If a slot passes while the Gateway is down, the pass catches up 60 seconds after the next start. Two passes never run at once.

Status

Settings → Maintenance in the Knowledge page shows the schedule, next run, last run, and per-store counts. Operators with operator.read or higher can read the same data when operatorRead is true:

openclaw gateway call plugins.sessionAction --params '{"pluginId":"knowledge","actionId":"maintenance_status","payload":{}}' --json

Each pass logs one summary line, as a warning if any store failed.

Relink adapts the free page and mention tiers of gbrain's relink. It has no model tier: a claim that cannot be resolved stays unlinked rather than receiving an unsupported guess.

Agent review

Relink leaves claims that name no page, or more than one. Maintenance does not review them: it runs relink only and never starts an agent turn. An agent review handles them on its own schedule: an automation whose agent turn follows the knowledge-claim-consolidation skill over every private claim with no linked page and no source page, whichever tool saved it. It runs weekly by default (Sundays at 3:45 AM) or, if you choose, nightly at 3:45 AM, after the default 3:30 AM maintenance pass. Each run is an agent turn over every unlinked claim, so nightly costs more; a run that finds nothing left stops right away. The retired maintenance.reviewJobId setting fails validation; run openclaw doctor --fix to remove it.

The review edits private knowledge, so its automation must run in a session with the owner's private access. Turn on Knowledge Consolidation from the Scribes tab of the Knowledge page. To start it without the Control UI, open a new conversation in the owner's direct chat and send the prompt the Scribes tab would send; the example prompt shows it. Its settings are plain bullets, so set your schedule (45 3 * * 0 weekly or 45 3 * * * nightly) and IANA time zone there.

The conversation creates the automation, targets itself, and ends with a Scribe status: on — … line. Each scheduled run receives the automation's run message, which you can edit on the Automations page. To fix a broken setup, use Repair on the Scribes tab. If the scribe's conversation is reset or removed, it loses access: start the scribe again from a new conversation. Conversation partitions are not reviewed.

The knowledge-claim-consolidation skill is the agent workflow for the claims relink leaves unlinked. It chooses subject pages with judgment, creates pages for substantial missing subjects, retires exact duplicates, supersedes explicitly replaced claims and status snapshots by their outcome, and folds durable outcomes into page State. The same skill runs as a claim consolidation review over other scopes when you ask for one: the claims on one hub or oversized page, or the claims about one subject since a date. Scribe runs only review the unlinked residue.