refactoringhq/portent

Portent is not a software product so much as a written specification. It proposes a small, opinionated set of rules for how a personal or work knowledge base should be organized, so that both people and AI agents can read it in a consistent way. The idea is that everyone who keeps notes ends up inventing their own folder structure and tag system, and Portent offers a shared starting point instead of that one-off design work. The spec is built on three ideas. The first is types. Every item in a Portent knowledge base belongs to one of eight default types, split into two groups. PORT types cover things you can act on: Projects, Operations, Responsibilities, and Tasks. ENTP types cover things you record but do not act on directly: Events, Notes, Topics, and People. The second idea is relationships, and the spec keeps these to two defaults: belongs_to for ownership and composition, and related_to for looser links. The third idea is a lifecycle: an item is first captured quickly so it is not lost, then organized by giving it a type and relationships, then archived when it is no longer useful. For a system to count as Portent-compatible, it needs three things: a way to mark each item with one Portent type, a way to record its lifecycle state, and a way to link items together, for example through Markdown wikilinks or frontmatter fields. The spec is intended to be portable across file-based note systems, note-taking apps, documentation tools, and agent-readable vaults, with a tool called Tolaria being the easiest place to apply it. The repository also contains a documentation website built with VitePress that lives in the site folder. The project has 20 stars and the language listed by GitHub is CSS, reflecting the docs site rather than any application code.