--- name: exomem-curate description: Improve Exomem note quality by adding links, clarifying compiled notes, and organizing safely without editing raw Sources or Evidence. metadata: skill_contract: 559a751112793020de7a074aafa3713c510c410293d92246c7d3adffcaea3ef6 version: "0.2.0" --- # exomem-curate ## Purpose Improve the KB graph and compiled-note quality without damaging provenance. ## When to use Use when the user asks to clean up, organize, link, tidy, or improve a set of Exomem notes. ## Portable operating rules Before the first operation, inspect the exposed bootstrap schema. If it lacks `skill_contract`, obtain `bootstrap(profile="compact")` directly. Otherwise obtain `bootstrap(profile="session", skill_contract=)` if current policy or capabilities are missing; honor `engagement.envelope` and `available_product_tools`. Reuse returned state until policy, connection, adapter, or returned vault configuration/registry state changes. If the server rejects the session profile or argument, obtain `bootstrap(profile="compact")` once. Use the harness's supported discovery mechanism and load only the tools needed now. If the applicable local procedure cannot be read, obtain the portable compact contract; do not improvise a write. Do not invoke tools absent from `available_product_tools`; use the live capability list even when a bundled workflow mentions a withheld operation. Use `configure_memory` set/clear only for an explicit user request to change saved engagement. Recall, capture, installation and missing hooks use the existing preference; none authorizes changing it. Inspect first when the user requests a change. Sources/Evidence are immutable, and content outside the managed Knowledge Base is read-only. Before a compiled write: reuse current relevant search/read results, check for duplicates, and include known source references and reviewed connections in the first write. Use `connect_memory(operation="suggest-links")` when useful connections are still unknown, not to recheck links already established in context. Honor the live confirmation ceiling; a workflow or standing capture preference does not grant restructure authority. Inspect mutation results before reporting success. On `success: false`, follow the structured error. For warming, busy, pending, or `MUTATION_COMMITTED_ACKNOWLEDGEMENT_UNCERTAIN`, preserve the same mutation identity and unchanged payload; wait/reconcile/retry only as instructed, never with a new identity after an uncertain commit. ## Workflow 1. Search related notes with `ask_memory`; use `connect_memory(operation="suggest-links")` for link candidates, `"suggest-relations"` when direction matters, and `"graph-context"` for graph shape or inbound links. 2. Identify safe improvements — missing links, stale wording, weak titles, duplicate tags, or unlinked entities — starting from `review_memory(mode="relation-debt")` for pages with no outbound edges and `mode="relation-queue"` for already-reviewed candidates. 3. For a bounded set of explicitly selected pages, call `maintain_memory(mode="curation", curation_action="work-item", refs=[...], paths=[...])`. This is `structural_suggestions`: it assembles recorded context and never chooses semantics or writes content. 4. Author the typed plan yourself, then call `maintain_memory(mode="curation", curation_action="propose", plan={...})`. Inspect it with `maintain_memory(mode="curation", curation_action="preview", run_id=...)`; preview the immutable plan once and surface its exact actions, blockers, fingerprint, and compensation classes. 5. Before any execution, treat the plan as `restructure_execution`: obtain one explicit confirmation for that exact plan fingerprint. Do not infer confirmation from the request to inspect or improve notes, and do not accept standing approval. 6. On confirmation, call `maintain_memory(mode="curation", curation_action="apply", run_id=..., plan_id=..., expected_plan_fingerprint=..., why=...)`. If the phase remains `executing`, resume automatically one step per request with `maintain_memory(mode="curation", curation_action="resume", run_id=..., plan_id=...)` until terminal; stop on `partial` or `blocked` and report the durable evidence instead of improvising. 7. Compensation is a new reviewed plan, never rollback. `curation_action="propose-compensation"` is `structural_suggestions`: use it to derive the plan, then preview it and obtain a fresh exact-plan confirmation before `maintain_memory(mode="curation", curation_action="apply-compensation", run_id=..., plan_id=..., expected_plan_fingerprint=..., why=...)`. Continue the already-approved compensation plan only through the same one-step `resume` route; resume does not need a fresh confirmation for each step. 8. Leave raw `Sources/` and `Evidence/` untouched except for metadata the core contract explicitly allows. 9. Check `review_memory(mode="audit", categories=["unregistered_relation"])` for relation labels that recur but are not registered; promote the ones that have earned it with `schema_memory(subject="relations")`, which turns them into real typed edges instead of standing review debt. ## Vocabulary Read [vocabulary](references/vocabulary.md) before changing a registry. If the vocabulary reference is missing, inspect the exposed bootstrap schema. Use `bootstrap(profile="compact", section="vocabulary")`, or `bootstrap(profile="full")` when `section` is unavailable. Follow the returned inspect routes and `save` contract. Reuse or alias before proposing justified new meaning; save with the current hash and `why`. Report saved versus queued and the returned restore route. Use only exposed operations. ## Relation governance Resolve typed meaning with `resolve-relation` before authoring. Reuse a specific truthful match; otherwise choose honest `relates_to` or no edge. Durable recurring meaning is proposal-first through `propose-relation` and hash-guarded `save-relations`; corrections use a new canonical key and deprecate the old one. ## Output contract Summarize changes made or proposed, citing affected paths. Flag risky changes instead of applying them silently. ## Save rules Preserve history. Prefer supersession when meaning changes. Keep links useful, not decorative. ## Mistakes to avoid Do not rewrite raw sources or evidence. Do not mass-edit without reading the relevant notes. Do not collapse distinct conclusions just because they share keywords. Do not reuse a forward approval for compensation, silently continue a partial or blocked run, or turn one confirmation into standing approval. ## Semantic authoring contract Every new, replaced, or activated compiled note in the live class needs at least one valid, non-empty semantic unit. Either compact or rich form satisfies the minimum; compact is preferred, and a valid rich unit does not need a duplicate compact restatement. Semantic roles: - Category: One primary open-vocabulary label describes what a unit is about; rich category defaults to its governed kind unless explicitly overridden. - Tag: Zero or more optional secondary retrieval labels refine lookup and never replace category or determine kind. - Kind: The governed semantic form: compact units always use `observation`; rich units use their recognized heading kind. Compact grammar: `- [category] content #tags (context) ^anchor`. Parse valid compact observations anywhere outside fenced code blocks. Exomem writers use `-` under the canonical `## Observations` section. Parser bullet markers are `-`, `*`, `+`; the canonical marker is `-`. Parse from the end by taking anchor, then context, then trailing tags; the authored display order remains tags, context, anchor. Category uses open vocabulary. - Compact category: the unit's one primary open-vocabulary subject or domain label. After trimming, use 1-64 Unicode code points; begin with a Unicode letter; then use only Unicode letters or digits, spaces, `_`, or `-`. Apply Unicode NFKC and casefold, then collapse runs of spaces, `_`, and `-` to one `_`. Registry alias resolution is separate from authored canonicalization; an unseen valid category needs no registry write. - Compact content: the unit's substantive observation. Use non-empty content that remains on one Markdown line. Escaped parentheses, embedded hashes, and non-trailing tag-like text remain content. - Compact tags: zero or more optional secondary retrieval labels; tags do not replace the primary category or governed kind. Write `#slug`. Use 1-64 Unicode letters or digits, `_`, `-`, or `/`; begin with a letter or digit; do not use empty path segments or a trailing `/`. Use one contiguous trailing run after content and before optional context and anchor. - Compact context: one optional authored qualifier for the observation. Write `()`. Use one balanced, unescaped parenthesized suffix preceded by whitespace. - Compact anchor: one optional stable authored unit identifier. Write `^anchor`. Use 1-64 ASCII letters, digits, or hyphens and begin and end alphanumeric. Place it at the end of the line. - Compact exclusions: observation-shaped rows inside fenced code blocks; task labels `[ ]`, `[x]`, `[X]`, and `[-]`; reserved or punctuation-bearing bracket labels outside category grammar. Compact units do not carry typed unit relations; use a canonical note-level relation or the rich form. - Rich: write `## ` with optional leading metadata `- category: `, `- id: `, `- tags: `, `- context: `, `- relations: : [[Target]]`. Metadata rows are optional and leading; the canonical writer emits category, id, tags, context, then relations; category defaults to the governed kind when omitted. Accepted metadata order is flexible while rows remain leading. After optional leading metadata, add a blank line and a substantive Markdown body. Typed unit relations require the rich form. A `#anchor` target addresses a unit. - Rich boundary: A heading at level N owns content until the next non-fenced heading at level N or shallower; deeper headings remain in its body. `empty_rich_unit` means a recognized rich heading has no substantive body; Add substantive body content or remove the empty recognized heading. - Exact applicability: obtain `bootstrap(profile="compact", section="authoring")` and read `semantic_authoring.minimum_semantic_unit` for current structural applicability and the status-class rule. If the exposed bootstrap schema lacks `section`, use `bootstrap(profile="full")` instead; released profiles reject section arguments. Apply `compiled_intent(after_state) = canonical_compiled_destination(path) OR the normalized type's note-type role is compiled`. Shipped compiled types: `research-note` in `Notes/Research`, `insight` in `Notes/Insights`, `failure` in `Notes/Failures`, `pattern` in `Notes/Patterns`, `experiment` in `Notes/Experiments`, `production-log` in `Notes/Productions`. More may be registered; `schema_memory(subject="note-types", operation="inspect")` lists the live set. Reject missing, invalid, or mismatched compiled frontmatter before evaluating the minimum-unit predicate. The minimum predicate applies when the path and normalized compiled type structurally match; the result is writable managed Markdown in the governed subtree; the result is outside Sources, Evidence, and trash; no activation exclusion applies; the admitted effective status class is live. Check live creates, replacements and transitions to live; pending compiled notes may remain unit-free until activation. - Existing active pages: A post-activation compliant page cannot lose its final valid semantic unit. - Exempt content: arbitrary non-compiled Markdown, dataset cards, Evidence artifacts, hubs, indexes, logs, non-Markdown files, schema and admin artifacts, snapshots, Sources, templates, trash. - Routes: use `remember` for a new compiled note, `replace_memory` for a replacement, `observe_memory` for one unit, and `edit_memory` for a small edit or activation. Tier 2 manage_memory_file create, overwrite, and append receive the same semantic precommit contract on the complete resulting compiled Markdown; prefer remember or replace_memory when their typed route fits. - Findings: `missing_semantic_unit` means an applicable live-class compiled result has no valid non-empty unit; `empty_rich_unit` means a recognized rich heading has no substantive body. Add substantive body content or remove the empty recognized heading. - Compact remediation: Add `## Observations` and `- [operating constraint] Keep retries bounded #reliability`. - Rich remediation: Alternatively add `## Decision`, a blank line, and a substantive body. - Semantic-unit coverage and relation-review disposition are independent obligations. - Portable categories: Choose exactly one primary category: prefer a meaningful epistemic or operational role and put the domain in tags, but if the role would only be a generic fact, finding, or observation and the domain is the durable lens, use a domain category instead. The category vocabulary is open: these core keys are a shared starting point, not a closed list. When no core key is a good primary fit, author a new meaningful category rather than forcing an ill-fitting one. Use exactly one primary category; kind is the governed form, tags are secondary facets, and relations are typed edges. The rich form's category defaults to its kind, so `category: decision` is redundant when the kind is Decision. Create multiple distinct semantic observations and typed relations when the source genuinely supports them, but never multiply units or relations to satisfy a quota and never duplicate the same fact. Core keys are `action`, `assumption`, `code`, `config`, `constraint`, `decision`, `design`, `fact`, `finding`, `insight`, `preference`, `problem`, `question`, `requirement`, `risk`, `technique`. Core aliases are `actions` → `action`, `assumptions` → `assumption`, `configs` → `config`, `configuration` → `config`, `configurations` → `config`, `constraints` → `constraint`, `decisions` → `decision`, `designs` → `design`, `facts` → `fact`, `findings` → `finding`, `insights` → `insight`, `open_question` → `question`, `open_questions` → `question`, `preferences` → `preference`, `problems` → `problem`, `questions` → `question`, `requirements` → `requirement`, `risks` → `risk`, `techniques` → `technique`. Role example: `- [decision] Relocate to a coastal city next spring #life ^relocation`. Domain example: `- [nutrition] Evening protein improves adherence #experiment ^evening-protein`. Breadth example (life, finance, legal/travel, and career alongside one retained code line): ```markdown - [constraint] Keep retry windows bounded #code ^retry-windows - [risk] Variable-rate mortgage payments could spike #finance ^mortgage-rate-risk - [question] Does the destination require a visa before travel #legal #travel ^visa-requirement - [career] Weigh a sabbatical before the next promotion cycle #growth ^sabbatical-timing ``` Rich example: ```markdown ## Decision - id: commit-to-morning-training - tags: health - relations: supports: [[Knowledge Base/Notes/Health/Morning training]] Commit to a fixed 6am training block on weekdays so consistency compounds and health stays the durable lens for this decision. ```