---
summary: "Knowledge scheduled maintenance: zero-model claim relink, schedule configuration, and status"
read_when:
  - You want to change or disable the Knowledge maintenance schedule
  - You are checking why remembered claims are or are not linked to entity pages
  - You are running knowledge_relink on demand
title: "Knowledge maintenance"
sidebarTitle: "Maintenance"
---

Knowledge runs one small scheduled pass. Part of the
[Knowledge plugin](/plugins/knowledge) 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:

| 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.