Knowledge maintenance, automatic extraction, and carrier contracts
This page owns implemented tags, automatic-extraction authorization, carrier saving/rebuilding, change reminders, and evaluation association. Start with the knowledge maintenance workflow; use this specification for fields, storage, and failure boundaries. The domain model and library specifications separately own content and organization links.
Conversation auto extraction and project inbox
Choose Enable auto extraction in the conversation header. Review the initial messages from the latest 3 finished turns, specify the candidate folder, executor, model and maximum calls (1–20), check the sending permission, then choose Approve and enable. USD cost is unknown; a call limit is not a dollar budget. Opening the preview does not call a model.
Permission covers only this conversation for 24 hours while the current Studio server runs. Subsequent windows include up to 3 new finished turns plus 2 preceding turns of context, after records remain stable for 30 seconds. Open or unknown turns wait until finished; the entire history is not reconciled for every correction. An identical source window is not sent twice; this does not guarantee semantic deduplication. Failure or interruption stops scheduling without a fresh model retry. Stop auto extraction cancels the owning server’s in-flight call; output already produced may still be saved. Enable again after restart. To regenerate a failed window, use manual extraction and confirm again.
The header’s Knowledge inbox shows the undecided count. Open it to retain, discard or revise candidates in place, inspect entities as needed, then generate and save artifacts from retained knowledge. Extract this turn and Extract conversation still support manual message selection and in-place review. Projects have the same Knowledge inbox, collecting candidates and decisions from currently indexed project conversations. This is source grouping, not an automatic ownership, similarity or conflict judgment. Unreadable folders and empty scopes have explicit states.
Scheduling permission and call reservations use auto-extraction/<thread-hash>.json under the selected knowledge folder, with schemaVersion: 1 and automationKind: conversation-knowledge-extraction. Calls and window digests are persisted before invocation; reservations count against the limit even if interruption prevents sending, with no refund or re-send. Each Studio registers at most 32 conversation scopes and invokes models serially; each conversation stores at most 2,000 finished turns and 1,000 attempted windows, then stops. Immutable permission-<id>.json and attempt-<run-id>.json records preserve each permission and its call/window associations across re-enabling; the directory is limited to 3,000 files. Existing source, knowledge, entity and run formats remain unchanged, and raw evidence is preserved. Complete, explicitly injected AGENTS.md instructions are collapsed only in the reading view; original messages remain expandable and present in source snapshots and sending previews.
One reconciliation under the workspace write lock shares an invocation-receipt inventory, reading and parsing each required receipt at most once within that reconciliation. Later transactions read again rather than permanently caching receipt validation. The hot cache for published cooldown facts records only successful durability confirmation, holds at most 3,000 entries, and is cleared when the service closes. Every observation still reads the complete fact bytes, validates the Schema and receipt-bound identities, recomputes the byte digest, and checks physical file identity; equal size or timestamps alone cannot skip these checks. A cache miss or invalidation synchronizes the fact file and its two parent directories, then rereads to confirm unchanged bytes and file identity before caching success. Failure removes the entry so a later observation confirms again. Cold recovery for a missing fact validates the run manifest and then fully reads and validates only the referenced attempt's outcome, instead of first parsing every native archive for that run. Real execution, resume, and writes retain their existing complete archive validation. Nonrefundable call accounting, known cooldowns, and post-persistence expiry/cancellation checks remain enforced.
Studio continues reading actual status every 5 seconds, including before automatic extraction is enabled and after it stops, with at most one status poll in flight for the component's current conversation scope. Successful responses always return HTTP 200 with complete JSON and Cache-Control: no-store; they use neither conditional requests nor 304. An optional weak ETag is only a UI invalidation hint, derived from the selected directory/conversation, current automation state, and metadata of published knowledge, run, tag, and entity JSON head files. It is not a content-integrity digest, admission proof, or persisted identity. An unchanged valid tag skips redundant inbox projection; initialization, a changed tag, or missing metadata refreshes it. Cooldowns, run completion, stopping, and head changes from manual retain/discard/revise actions remain visible through subsequent 5-second polls; existing in-page maintenance notifications can still refresh immediately. Late status replies from a previous conversation or before an explicit stop cannot replace newer state.
The inbox queue first filters run manifests to the selected conversation/project, then reads only knowledge histories and tags for knowledgeIds committed by those runs, rather than parsing every knowledge history. Directory enumeration, run manifests, status/receipt reconciliation, complete fact-byte reads, and refresh-tag metadata scans still perform I/O; zero I/O is not promised. These changes reduce repeated durability confirmation and unchanged inbox projection, not model calls or model/request identity rehashing. They do not cache those identity checks, move existing admission gates, or change persistent Schemas, historical bytes, permissions, or counting rules.
Organize and find knowledge
Edit Topic tags in candidate details and explicitly save them. Use Chinese characters, letters, numbers, underscores, hyphens, or / for nesting, without spaces or purely numeric names. Each knowledge item allows up to 32 tags of 80 characters each. Duplicate tags are case-insensitive. Tags are user-maintained, make no additional model call, and do not verify knowledge. Editing tags leaves claims, sources, revisions, and retention decisions unchanged.
The library searches titles and tags. tag:debugging matches “debugging” and nested tags such as “debugging/evidence”, together with the decision filter. Tags organize topics; knowledge types, applicability conditions, and evidence classifications still come from the selected knowledge revision.
Tag history is stored separately in tags/<identity-digest>.json under the knowledge directory, using omk-knowledge-tags/v1. Records bind the knowledge identity and preserve tags, modification time, and actor. Saving tags does not change knowledge, source, or run records. Unset tags are empty; concurrent updates reject stale generations and require reloading and review. Tags persist across knowledge revisions as organization information; check that they still apply.
Generate and save knowledge artifacts
Choose Generate knowledge artifact on a retained candidate or completed batch, or Generate from retained knowledge in Knowledge artifacts. Choose skill or prompt, enter a name, inspect the selected retained knowledge, and choose Generate and review. Initial selections include only the current candidate or retained items from this batch; explicitly add other retained items if needed, up to 100 per operation. Generation organizes existing material while retaining conditions, exceptions, unknowns, claim and evidence classifications, quotes, and source versions. It makes no additional model call.
Generation also exports a property snapshot: title, summary, topic tags, knowledge types, scenarios, evidence classifications, and exact knowledge/source versions. The summary uses knowledge titles, scenarios come from claim contexts, and multiple evidence classifications can coexist. verification_status: not_assessed means this generation provides no truth or task-effect validation. Prompts use top-level YAML properties with tags as a list, readable by tools such as Obsidian. Skills retain required name/description fields and put additional properties in the specification's metadata string mapping; lists are encoded as JSON strings.
Properties use omk-knowledge-metadata/v1 and describe knowledge incorporated in this artifact version; editing them does not update the knowledge library. Updating an OMK-generated artifact recomputes these properties. The first import of a local prompt preserves custom fields and existing tags. Tag changes after preview also reject stale saves. Older artifacts are not rewritten in the background; manifest.json remains authoritative for artifact and knowledge revision associations.
Review and edit the new content, then choose Save artifact. Content is saved directly under the current knowledge directory as artifacts/<artifact-id>/vN/content/<directory-name>/SKILL.md or artifacts/<artifact-id>/vN/content/<directory-name>.md. The artifact detail opens with the actual artifact path, content, knowledge sources, and version history. Display names may contain Chinese text. New artifacts receive distinct file names; skill frontmatter names match their directory names, and valid frontmatter is checked on save, following the Agent Skills format. No clipboard step is required. Source links open the exact incorporated knowledge revision. Saving does not verify truth or effectiveness; check applicability and run a controlled evaluation before use.
To update an artifact, select a saved artifact or explicitly provide a local file path. Saved artifacts rebuild their knowledge region from the explicitly selected current retained revisions. Omitted knowledge is removed from the new version; content, properties and manifest reference only the selection. Manual content outside the region and assets are preserved. New regions use omk:knowledge:v1 boundary markers. Unmarked old versions migrate only when the knowledge suffix exactly matches the manifest revisions; otherwise rebuilding is refused and a new artifact with reviewed manual content is required. Compare original content before saving a new version; old versions remain intact. Starting from local SKILL.md preserves original content and copies distributable assets in the same directory using existing filtering and content digest rules, without overwriting the original file. Choose another knowledge directory if the save location is inside the local skill being copied. Select the latest version before generating further updates.
Knowledge review in the artifact list and Review changes in details check existing references at read time: new revisions, current revisions not retained, and unavailable knowledge or sources prompt review. External file edits are indicated separately. Details show the check time, changed fields, and exact incorporated and current revision content. Choose Recheck knowledge changes to refresh; failed reads are not evidence of no changes. Checks exclude unreferenced new knowledge, do not assess truth or semantic expiry, and never automatically update artifacts or maintenance decisions. When generating a new version, Reference changes in this update lists added, replaced, removed and kept revisions. Compare the original content before saving; the latest version’s notices reflect a new read, while historical versions are still checked against their own references.
Each manifest.json uses omk-carrier-v1, recording artifact identity, version, save time, content digest, file directory name, baseline, and exact knowledge revision references. This is an additive artifact storage contract; candidates, source snapshots, and existing evaluation data are preserved. Knowledge review is a read-time projection and is not written to historical manifests. Changes to the current knowledge revision, retain decision, or artifact baseline after preview reject stale saves and require a new preview. External artifact edits are marked as content changes. A complete staged version is published atomically; failure or cancellation does not replace old versions. After a local writer exits, the next save recovers its dead lock once it is over 30 seconds old and removes unpublished staging; locks owned by another host are not taken over. If the save result cannot be read, choose Check saved version before attempting another write.
Evaluate an artifact change
Select “Evaluate this version” in artifact details. Updates preselect the original version; new artifacts require another saved version or an explicit local skill directory/SKILL.md or prompt file as control. Both versions must have the same form and different content. Select a local sample file or directory, executor and fixed model, configure model judges if needed, then preview the evaluation plan. This entry supports 1–100 local samples and excludes samples requiring remote content resolution.
Preview shows both versions, identical samples and scoring criteria, the task model, actual scoring models and planned task count, without calling models. Only “Confirm and evaluate” starts execution, including required preflight. Cost cannot be estimated precisely; preflight and model grading may add calls. There are no automatic retries. Previews expire after 15 minutes; changed artifacts, samples or runtime plans require a new review.
Evaluation attempts bind the exact artifact revision and source knowledge. Finished, failed, cancelled and interrupted states remain visible; cancel active work, open the existing Core results and evidence, then return to the evaluated version. Cancellation cannot undo calls or charges already incurred. If the start response is lost, check run status before another attempt. Server shutdown cancels owned work; attempts whose local process has exited show interruption and never restart model calls automatically. Existing Studio evaluation records remain accessible.
The selected knowledge directory is the operation root. Core artifacts use the existing .omk/eval contract; additive .omk/state/jobs/carrier-measurements/<measurement-id>.json records use omk-carrier-measurement-v1 for previews and attempt associations, without changing artifact manifests or existing measurement schemas. Records may contain private samples and artifact content; manage them as local data. A finished run, saved artifact or retained knowledge does not establish effectiveness. Review report conclusions and evidence scope; generated samples require review and are not automatically independent release evidence.