schema-pack-pattern.md

Schema Pack Pattern

A KnowledgeOS schema pack is a small, agent-readable contract that explains how the vault should be maintained.

It is not a database schema. It is not a rigid ontology. It is a practical routing and quality layer for agents that write to Markdown.

Why this exists

A folder map tells an agent where files live. A schema pack tells the agent how to decide:

• whether something deserves to be saved
• which page type it belongs to
• which existing page should be updated
• when creating a new page is safe
• which sections a page should maintain
• how to preserve evidence and avoid duplicate notes

Core files

• config/taxonomy.yaml — source of truth for semantic routes, page types, evidence labels, and update policies.
• MEMORY_RULES.md — what is worth saving.
• CAPTURE_PROTOCOL.md — how an agent should capture information.
• KNOWLEDGE_SCHEMA.md — how durable knowledge pages should be structured.

Agent workflow

Before writing to the vault, an agent should:

1. Read MEMORY_RULES.md, CAPTURE_PROTOCOL.md, KNOWLEDGE_SCHEMA.md, and config/taxonomy.yaml.
2. Decide whether the input passes the quality bar.
3. Apply privacy filtering.
4. Pick a page_type by meaning, not by hardcoded folder path.
5. Resolve the path from taxonomy and optional path_suffix.
6. Search likely target pages and adjacent pages.
7. Label retrieval evidence and create safety.
8. Update an existing page when possible.
9. Create a new page only when the schema and create-safety state allow it.
10. Update the daily log after manual captures.

Retrieval evidence labels

Use these labels to make deduplication and create decisions explainable:

• exact_title_match — title, filename, or frontmatter title matches the target topic.
• alias_hit — alias, abbreviation, translated name, or synonym matches.
• keyword_exact — core keyword or phrase appears in a likely target page.
• high_semantic_match — topic is highly related without exact keyword evidence.
• weak_semantic — weak similarity only; not enough to block a new page by itself.
• no_match — no reliable candidate page found.

Create safety states

• exists — a clear target page exists. Update it instead of creating a duplicate.
• probable — a target may exist. Inspect candidates or ask before creating.
• unknown — no reliable candidate exists. Creation is allowed if the quality bar passes.

Page type contract

Each page_type in config/taxonomy.yaml can define:

• name — semantic type the agent should choose.
• path_key — key under taxonomy used to resolve the folder.
• path_suffix — optional subfolder inside the route.
• purpose — what this page type is for.
• quality_bar — minimum reasons this note deserves to exist.
• required_sections — sections that should appear on durable pages of this type.
• update_policy — whether to update, append, rewrite current judgment, or create.

Good behavior

Input: Save this: Project Atlas now has a working beta and users asked for CSV export.

Expected agent decision:
- page_type: project
- target route: projects -> 02-projects
- retrieval_evidence: keyword_exact or exact_title_match if Project Atlas page exists
- create_safety: exists
- action: update existing project page and daily log

Bad behavior

Input: Save this: Project Atlas now has a working beta.

Bad agent decision:
- creates 02-projects/project-atlas-beta.md without searching first
- does not update the existing Project Atlas page
- does not update daily log

Customization rules

• Rename folders by changing taxonomy values, not by editing agent prompts everywhere.
• Add new page types only when repeated maintenance decisions need clearer rules.
• Keep page types generic enough for public/template use.
• Do not add private personal categories to the starter vault.
• Optional packs should stay optional and domain-specific.