OpenClawDocs
On this page

On this page

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Plugin guides

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.

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:

Outcome Rule
linked (tier page) The claim's source_page is an active entity page.
linked (tier hint) The claim's subject_hint names exactly one entity page.
linked (tier mention) The claim text names exactly one entity page by ID, title, or alias, with no competing name.
ambiguous / no_subject Anything else. The claim stays unlinked.

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.

json5
{  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). 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:

bash
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. An operator can hand those to an agent: set maintenance.reviewJobId to an automation whose agent turn follows the knowledge-unlinked-claims skill. After a pass that leaves private claims with no linked page and no source page, whichever tool saved them, maintenance queues that automation once. It does not queue it when nothing is left, and a disabled automation does not run. The last pass reports the review's outcome (enqueued, not_needed, skipped, unavailable, or failed) and how many claims were left.

The review edits private knowledge, so the automation must run in a session with the owner's private access: a kept worker spawned from the owner's direct conversation. The skill's "Setting up the scheduled review" section gives the steps. Conversation partitions are not reviewed.

The knowledge-unlinked-claims 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 and explicitly replaced claims, and folds durable outcomes into page State.

Was this useful?