--- name: exomem-defrag description: Reconcile duplicate, stale, or conflicting Exomem memory while preserving history through review, merge, or supersession. metadata: skill_contract: 559a751112793020de7a074aafa3713c510c410293d92246c7d3adffcaea3ef6 version: "0.1.0" --- # exomem-defrag ## Purpose Reduce duplicate, stale, or conflicting memory without losing provenance. ## When to use Use when the user asks to defrag a topic, reconcile notes, resolve contradictions, merge duplicates, or inspect what is stale. ## 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 the topic with `ask_memory`, using `ask_memory(deep=true)`, `connect_memory`, or `review_memory` when graph, stale, audit, or evolution context matters. 2. Group findings into keep, merge, supersede, or leave alone. 3. Read candidate pages with `read_memory`, including history when needed. 4. Use `replace_memory` for changed conclusions and `edit_memory` only for minor corrections. 5. Preserve raw sources and evidence; keep superseded history visible. 6. When you supersede or merge, carry the merged notes' `sources:` and outbound links onto the survivor — a merge that drops edges loses graph value the superseded page can no longer carry. Check `review_memory(mode="relation-debt")` on the survivor afterwards. ## 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 Return the reconciliation decision for each candidate and the paths changed or left alone. ## Save rules Only mutate when the correct action is clear. Use supersession for meaningful changes. ## Mistakes to avoid Do not auto-delete memory. Do not treat semantic proximity as contradiction by itself. Do not merge notes that answer different questions. ## 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. ```