--- name: exomem-media description: Search, inspect, cite, and preserve Exomem media artifacts such as PDFs, images, audio, and video. metadata: skill_contract: 559a751112793020de7a074aafa3713c510c410293d92246c7d3adffcaea3ef6 version: "0.1.0" --- # exomem-media ## Purpose Use Exomem's multimodal substrate without flattening every artifact into text. ## When to use Use when the user asks to find media evidence, look inside a recording, inspect a PDF/image/audio/video, or recall where something appeared. ## 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 with media-aware filters or artifact terms using `ask_memory`. 2. Use artifact-specific product tools: extracted text/OCR/transcripts, `process_media` status/retry, `read_media`, `preserve_artifacts` for file handles, fallback `transfer_artifact`, upload metadata, or preserved evidence paths. 3. Cite raw artifact paths and timestamps/pages/frames when available. 4. Preserve new raw artifacts with `capture_source`, `preserve_evidence`, `preserve_artifacts` for file handles, or fallback `transfer_artifact` before analyzing them. 5. Draft textual conclusions only when there is a durable finding, naming the preserved artifact in `sources:`. 6. Reuse known meaningful connections; use `connect_memory(operation="suggest-links")` when candidates are still missing and review them. Then write with `remember`, carrying the sources and accepted connections in the first write. ## 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 matching artifacts, what was inspected, citations, and any compiled conclusion path. ## Save rules Raw media belongs in `Sources/` or `Evidence/`; textual notes should summarize conclusions and link back to artifacts. ## Mistakes to avoid Do not claim visual/audio evidence from filenames alone. Do not discard raw media after extracting text. Do not over-transcribe when a cited artifact path is the durable evidence. ## 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. ```