hashgraph-online/awesome-codex-plugins / plugins/ClickHouse/loom/skills/loom-optimize
loom-optimize
UnverifiedUse when the user says "optimize my loom namespace", "audit memory", "my memory search is bad", "loom keeps abstaining", or asks why recall over a namespace their agent writes to does not work, or when the mentor's `documents_as_memories` / `checkpoints_as_memory` / `records_for_identities` hint names rows to rework. Runs `namespace.audit`, turns each finding into a plan the owner approves, and reworks the rows with `memory.move` so every old key stays readable through a redirect. Retires nothing. NOT for deciding what to write in the first place (loom-memory) and NOT for client-side failures (loom-status).
loom-optimize — rework a namespace from its audit, with redirects
Run by the owner's agent over its own namespace, after the data is there.
The invariant: a writer never loses a key it still reads. Retiring old keys
by hand is how a running writer breaks (found: false, a local fallback,
two stores that disagree), so this skill moves rows and never deletes them.
Two ops do the work, both through loom_op unless your tool list shows
them (HTTP /v1/<op> otherwise): namespace.audit says what is wrong;
memory.move moves a row to a new key and leaves a redirect —
memory.get(from_key) still answers with the old value plus
canonical_key, follow=true serves the new row, and search and list show
only the new one. keep_redirect defaults to true; never pass false
(that tombstones the old key).
The store also asks for this skill by itself: a
namespace_health block in context.pack at session start, and one line
from the loom-namespace-health Stop hook at session end, each naming the
critical finding codes. Either one is the cue to start at Step 1.
Step 1 — audit, and stop if there is nothing to do
namespace.audit {org, namespace, window_seconds: 604800, sample_limit: 5}
Show summary as one line (live_rows, live_bytes, version_bytes,
unembedded_rows, gets / searches / sets, get_search_ratio) and the
findings as a table: code | severity | count | share | bytes | remedy. If
healthy is true and no finding is warning or critical, say so and stop
— an info finding is a note for the writer, not a rework. A finding of kind
system_state (telemetry_unavailable, index_backlog) is the deployment's
state, never a rework: name it to the owner and leave it out of the plan.
Step 2 — write the plan, one section per finding
Map each finding code the audit returned to its remedy with the tables in
reference.md beside this file (audit findings, and the three mentor hints
that are data changes: documents_as_memories, checkpoints_as_memory,
records_for_identities). Habit findings are writer changes: no data moves;
list them for the owner as a checklist.
Every section carries: the count and bytes from the finding, three
example keys before → after taken from the finding's samples, the exact
ops it will call with their arguments, and what it will not do:
- never
memory.delete; - never change a row's value in place — a rewritten value only ever lands
under a new key through
memory.move; - never touch a row written in the last hour — the writer may be mid-flight.
Write the plan as a knowledge document and show it:
knowledge.upsert {source_uri: "loom://<org>/<namespace>/_optimize/plan-<YYYYMMDD>",
title: "Optimize plan <namespace> <YYYYMMDD>", content: <the plan>}
Step 3 — wait for the owner
Apply nothing until the owner approves in this conversation, in words. A plan shown is not a plan approved; "looks fine, go ahead" is. If they approve some sections and not others, apply only those.
Step 4 — apply, section by section
- The first three moves of each section run with
dry_run: true; read the returnedto_key,redirectedandadvisoriesback to the owner. - Then real moves in batches of at most 50, in
created_atorder so revisions of one key land as versions of the new key. - Pass
if_match_sha256from the audit sample or thememory.getyou just did wherever it is available; a409means the row changed under you — pause the section, re-read the row, and ask before continuing. - Each reply must carry
memory_id,versionandcontent_sha256; a reply without them is a move that did not happen — say so, do not count it.
Step 5 — measure again
Re-run namespace.audit with the same window. Append the after-numbers to
the plan document (same source_uri, knowledge.upsert again) as a
before/after table, and hand the owner the writer changes as a checklist:
one json.dumps, claim-first values, readable keys, knowledge.upsert for
anything over ~2 KB, working_memory.* for leases and pointers, the same
key for a revision, no index rows.
Step 6 — retire nothing
Say plainly: every old key still answers memory.get with its old value
and a canonical_key; follow: true returns the new row; search and list
already show only the new rows. Once the writer has moved to the new keys,
the owner can tombstone the old ones with memory.delete — that is their
call, later, and not part of this skill.
Do not
- No in-place value rewrites. A better value goes under a new key via
memory.move; the old key redirects. - No
memory.delete, ever, from this skill, and nokeep_redirect: false. - No work on another agent's namespace without its owner in the conversation; the audit is fine to run, the plan is fine to write, the apply is not.
- No apply while the owner's writer is mid-run without saying so first
(the audit's
setsin the window says whether it is writing); rows from the last hour are out of scope regardless. - No inventing findings: only codes the audit (or
mentor.brief'sevidence) returned get a plan section, with their counts.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |