skip to content
iii / worker
$registry / workers

memory-consolidate

v0.1.15

Scheduled hygiene for the memory worker — deterministic dedup of near-duplicate memories, applied supersede-only through the public memory functions, pinned untouchable, with catch-up-on-boot scheduling. Install, stop, or remove it without touching stored memory.

worker
iiiverified
31 installs1 in 7d0 today
install
$iii trigger compose::add worker=memory-consolidate
binarylicense: Apache-2.0cleanupdeduplicationmaintenancememoryschedule
  • macOS: arm64 · x64
  • Linux: arm64 · armv7 · x64
  • Windows: arm64 · x64
4functions0triggers0skills3depsv0.1.15version
repoiii-hq/workers

exact versions are immutable; binary and bundle artifacts are digest-pinned.

functions

4

memory-consolidate::on-config-change

function

Internal: hot-reload memory-consolidate from the authoritative configuration when it changes.

request
  • idstring
response
  • okbooleanrequired

memory-consolidate::on-tick

function

Internal: schedule heartbeat (cron trigger + boot catch-up backstop). Runs a pass only when interval_hours have elapsed since the last one.

request
  • actual_timestring
  • job_idstring
  • scheduled_timestring
  • triggerstring
response
  • ranbooleanrequired

    A pass actually ran (false = not due yet or disabled).

memory-consolidate::run

function

Run one consolidation pass now (all configured banks, or one bank). Deterministic near-duplicate dedup, plus the optional LLM tiers when enabled (reorder judge; semantic merge/supersede of new memories, each with a reason), applied strictly through memory::supersede; pinned memories are untouchable. dry_run plans without writing.

request
  • bankstring

    Consolidate only this bank (must be in the configured allowlist, when one is set).

  • dry_runboolean

    Override the configured dry_run for this call.

response
  • banksobject[]required
    • bankstringrequired
    • cappedinteger· uintmin 0

      Work left behind by the per-run cap; the next pass picks it up.

    • errorsstring[]

      Real failures (reads, writes). Any error keeps the pass due.

    • groupsobject[]required
      • loser_idsstring[]required
      • loser_textsstring[]required

        Texts of the losers, aligned with `loser_ids` (the judge tier and human review need the words, not just ids).

      • report_onlyboolean

        True = surfaced for review only (token-set match: same words, different order — potentially different meaning). Never written automatically.

      • skipped_pinnedstring[]

        Losers left alone because they are pinned (pinned is untouchable).

      • winner_idstringrequired
      • winner_textstringrequired
    • llm_mergedinteger· uintmin 0

      Reorder groups merged after the LLM judge confirmed equivalence.

    • notesstring[]

      Soft skips (an optional tier unavailable, a sibling too old) — telemetry only: they never block the checkpoint, so an absent router cannot re-run the whole pass on every heartbeat.

    • promotedinteger· uintmin 0

      Standing-instruction lines the judge promoted into the bank's `learned` rule.

    • reinforcedinteger· uintrequiredmin 0

      Winner reinforcements applied (one per absorbed duplicate).

    • scannedinteger· uintrequiredmin 0

      Live memories scanned.

    • semanticobject[]

      Semantic-tier decisions (applied, or planned on dry runs), each with the judge's reason.

      • appliedbooleanrequired

        False on dry runs. Actions dropped by the pre-write freshness check are not listed here; they count in `semantic_rejected` with a note.

      • keep_idstringrequired

        Merge survivor / supersede replacement.

      • keep_textstringrequired
      • kindstringrequiredenum: merge, supersede
      • reasonstringrequired
      • retire_idstringrequired

        Merge duplicate / supersede outdated record.

      • retire_textstringrequired
    • semantic_failedstring[]

      New memories the judge could not decide even alone (a poison input); skipped past the cursor so they cannot wedge the tier.

    • semantic_rejectedinteger· uintmin 0

      Judge actions dropped by validation (unknown alias, pinned target, wrong direction, a lost number, ...).

    • supersededinteger· uintrequiredmin 0

      Supersedes actually applied (0 on dry runs).

  • checkpointedbooleanrequired

    The pass completed cleanly AND its last-run checkpoint persisted. False = the schedule will retry the pass next check.

  • dry_runbooleanrequired
  • supersededinteger· uintrequiredmin 0

    Total supersedes applied across banks this pass.

memory-consolidate::status

function

Check the consolidation schedule and last pass: enabled, interval, last run, due, and the latest per-bank results.

request
empty object
response
  • dry_runbooleanrequired
  • duebooleanrequired

    A scheduled pass is overdue right now.

  • enabledbooleanrequired
  • interval_hoursinteger· uint64requiredmin 0
  • last_reportunknown
  • last_runinteger· uint64requiredmin 0

    Milliseconds since epoch of the last completed pass; 0 = never.

triggers

0
no triggers registered