Maintaining an organized and efficient "brain" often means adapting to evolving schema standards. For those managing a knowledge base built on an older schema, especially one with a fragmented page taxonomy, the task of modernization can seem complex. This is where schema-unify provides a structured solution. It is an AI agent skill designed to migrate a brain from an older base schema to a v2 schema. Its core function is consolidating a fragmented page taxonomy, specifically collapsing dozens of distinct page types – potentially as many as 94 – into a more manageable set of 15 canonical types. A important aspect of this migration is that it preserves the original type for rollback, ensuring data integrity and providing a safety net. This tool is built to streamline your data structure and improve consistency without manual, tedious re-categorization. It addresses a common issue for long-standing brain instances, ensuring your knowledge base remains agile and easy to navigate.
The Migration Flow
The migration process with schema-unify follows a rigorous five-phase approach, designed to ensure accuracy and safety at each step. The first phase is discovery, where the tool confirms the current schema structure of your brain. This initial check establishes a baseline understanding of the existing data space, identifying the specific variations and fragmentation patterns present. Following this, the preview phase conducts a dry-run analysis. During this stage, schema-unify identifies all potential changes without modifying any data. This gives you a clear, comprehensive report of what will happen before any commitment is made, allowing for thorough review and informed decisions on the proposed structural changes. The preview report details the proposed retypings and data transformations.
Once the preview is satisfactory, the apply phase executes the actual migration. This phase runs the migration via a protected job handler, ensuring that changes are implemented under controlled and secure conditions. The use of a protected job handler is key for operational security and stability, minimizing risks during the critical data transformation. After the migration job completes, the verify phase confirms the success of the process. This involves automated checks to ensure that the new schema is correctly applied and that all data transformations have occurred precisely as expected, validating the integrity of your modernized brain. Finally, the post-migration cleanup phase handles any residual tasks, ensuring your brain environment is tidy, optimized, and ready for continued use after the significant schema update. Each phase builds upon the last, providing a systematic, auditable, and safe path to a modernized schema.
Data Transformation Specifics
During the migration, schema-unify performs several specific data transformations to align with the v2 schema. A primary action is that pages are retyped to canonical categories. This means existing page types, regardless of their fragmentation, are mapped and assigned to one of the 15 standard, unified types. For example, a legacy brain might have separate page types for "meeting-notes-client", "meeting-notes-internal", and "meeting-summary". With the migration, all these might be retyped to a single canonical 'meeting' type. This consolidation simplifies the overall taxonomy significantly, making it easier to manage and query your information consistently.
Beyond simple retyping, concept-redirects within your old schema become alias rows in the new structure. This preserves the associative links and ensures that existing references continue to function correctly while adopting a more standardized representation. Additionally, edge-shaped pages, which often represent transient or linking information in older schemas, convert to dedicated link rows. This clarifies their role and integrates them cleanly into the v2 schema's relational model. For any unknown legacy types encountered during the migration, the tool defaults them to the 'note' canonical type, with the original type meticulously kept in the page's metadata. This ensures no information loss and provides traceability for any necessary manual review or further refinement post-migration, maintaining the richness of your historical data.
Activating and Controlling the Migration
The activation of schema-unify is not automatic; it requires explicit user intent and approval. It triggers when onboarding checks show upgrade warnings, indicating that your brain's schema is outdated or fragmented and could benefit from modernization. This proactive detection helps users identify potential inefficiencies in their data structure. Another trigger is when the user explicitly requests taxonomy cleanup, signaling a clear desire for a more organized and consolidated data structure. Furthermore, if a user asks about the canonical taxonomy, the tool can suggest or initiate the migration process as a means to achieve that standard, guiding them towards best practices.
It is important to understand that schema-unify is not designed for autopilot execution. It explicitly needs manual approval via an allow-protected flag to proceed with the apply phase. This design choice prioritizes data safety and user control above all else, preventing unintended changes to your core knowledge base. This manual gate ensures you maintain full oversight over such a fundamental structural alteration. To check for potential upgrades, you would use the onboard --check command. If warnings appear indicating a need for schema consolidation, you can then submit the migration job using jobs submit unify-types, remembering to include the important allow-protected flag to explicitly confirm the operation. For more granular control or information regarding your schema, various schema utilities are also available, offering additional diagnostic and management capabilities. This ensures that the migration is always a deliberate, informed process under your direct supervision.
FAQ
Q: What happens to my original page types after migration? A: The original page types are preserved for rollback purposes. Additionally, for any unknown legacy types, the original type is kept in the page's metadata, while the page is retyped to the 'note' canonical type.
Q: Is the schema migration fully automatic once triggered?
A: No, the apply phase of the migration is not for autopilot execution. It specifically requires manual approval by including the allow-protected flag when submitting the migration job.
Q: How do I know if my brain needs this type of schema migration?
A: You can use the onboard --check command. If upgrade warnings are displayed, it indicates that your brain's schema could benefit from modernization and consolidation via schema-unify.
Conclusion: This tool offers a clear, controlled path to modernizing and consolidating your brain's schema. By following its structured phases and leveraging explicit controls, you can maintain a clean, efficient data environment.
