Maintaining an organized personal knowledge base or "brain" can be a significant undertaking, especially as its content grows. Misfiling new pages at creation time leads to eventual disorganization, and pages can outgrow their initial location. To address these challenges, we are introducing brain-taxonomist, an AI agent skill designed to automate the initial classification and ongoing review of your brain pages. This tool decides the correct filing path for a new brain page before it is written, effectively preventing misfiling. Additionally, it periodically scans for pages that have outgrown their location, suggesting better placements.
Unlike systems that rely on hardcoded directory tables, brain-taxonomist queries the active schema pack via schema show --json to make its filing decisions. This approach ensures that filing logic is dynamic and always aligned with your current, defined knowledge schema. Developers and knowledge workers who manage extensive personal brains will find this agent particularly useful for maintaining structure and discoverability.
How brain-taxonomist Operates
The brain-taxonomist agent follows a precise five-step process to determine the optimal filing path for a new page or to assess an existing one. This methodical approach ensures consistency and adherence to your defined schema. First, it identifies the primary subject type of the content. This foundational classification can be one of several categories: a person, an organization, an event, a concept, a piece of media, or a source. This initial step is important because it dictates the subsequent logical flow for path construction.
Once the subject type is identified, the tool looks up the matching directory within your active schema pack. By querying the schema show --json output, it retrieves the dynamically defined structural rules, ensuring that the filing decision aligns with your current knowledge architecture rather than relying on outdated or rigid internal tables. This means your filing logic evolves with your schema.
For specific content types, like books under the 'media' category, the agent determines appropriate subcategories. This allows for granular organization, for instance, distinguishing between fiction, non-fiction, technical manuals, or journals, based on the schema's definitions. Following this, the agent constructs a kebab-case slug for the page. This standardized format is essential for clean URLs and file paths, improving system readability and interoperability.
Finally, the tool validates the constructed path against the active schema pack. This validation step confirms that the proposed path conforms to all defined rules and constraints, preventing the creation of malformed or non-standard paths within your brain structure. This systematic process ensures that every page is placed logically and consistently.
Key Capabilities and Triggers
The brain-taxonomist agent is designed to be invoked through specific, clear triggers, making its integration into your workflow straightforward. Users can activate the tool by phrases such as 'where does this brain page go', 'file this in the brain', 'create brain page', or by issuing a 'taxonomy check'. These triggers allow for both proactive filing suggestions during content creation and reactive checks for existing pages.
For instance, if a user issues the command 'create brain page for "The Lord of the Rings" by J.R.R. Tolkien', brain-taxonomist identifies "The Lord of the Rings" as a piece of media. It then determines that it's specifically a book, and by querying the schema, it finds the designated directory for books, perhaps /media/books/. It then constructs a kebab-case slug like the-lord-of-the-rings-by-jrr-tolkien and validates the full proposed path: /media/books/the-lord-of-the-rings-by-jrr-tolkien.md.
This immediate path generation helps in standardizing your brain's structure from the outset. Furthermore, for users managing multiple brains or diverse information sources, the agent respects per-source overrides. This functionality is enabled via a --source flag, which allows the tool to apply specific filing rules or schema interpretations depending on the origin of the content. This is useful for maintaining distinct organizational patterns across different knowledge domains without constant manual adjustments.
What It Doesn't Do
It is important to understand the scope of this tool. brain-taxonomist is specifically designed for initial page classification and re-evaluation of filing locations. It is not intended for updating existing pages in place. Its function is to propose or validate a file path, not to modify the content within a page once it has been created. Therefore, it will not append to timeline sections or propagate entities to existing pages. The agent focuses solely on the structural placement of brain pages within your schema, ensuring correct and consistent organization rather than content manipulation.
Frequently Asked Questions
Q1: Does brain-taxonomist modify existing content? No, the tool's primary role is to determine and validate file paths for new brain pages before they are written. It also identifies existing pages that may have outgrown their location and suggests re-filing, but it does not alter the content within those pages.
Q2: How does it know where to file pages?
The agent queries your active schema pack using schema show --json. This allows it to make dynamic, schema-driven decisions based on your current knowledge structure, rather than relying on static, hardcoded rules.
Q3: Is the agent's behavior customizable?
Yes, its behavior is directly influenced by your active schema pack. By modifying your schema, you can define how different types of content are categorized and where they should be filed. Additionally, the --source flag allows for per-source overrides for multi-brain users.
This agent provides a pragmatic solution for automating brain page organization, ensuring that your knowledge base remains coherent and easy to navigate. By preventing misfiling and suggesting appropriate relocations, it supports a more efficient and structured knowledge management workflow.
