# Portent Portent is an open specification for work and personal knowledge bases. It defines a small, opinionated vocabulary of note types, relationships, and lifecycle states so that knowledge bases become "easy for humans and agents to understand." Released under the MIT license by [[Luca Rossi]] (founder of Refactoring), Portent extracts the patterns he refined across ~10,000 notes in his own tool, Tolaria. It is not a tool — it is a convention. The promise is "the Rails of knowledge bases": sane defaults you can extend or override, instead of starting every vault from a blank slate. ## The Three Dimensions Portent organizes a knowledge base along three axes. ### Types — 8 defaults in 2 groups **PORT** (actionable work): - **Projects** — outcome-driven, finite - **Operations** — recurring, process-driven - **Responsibilities** — ongoing areas of ownership - **Tasks** — atomic next actions **ENTP** (context and memory): - **Events** — moments in time - **Notes** — atomic ideas and observations - **Topics** — long-lived themes - **People** — humans and their context Types are differentiated by **size** and **recurrence**, not by domain. The same eight types span personal and professional life — "life-work integration" is a stated design principle. ### Relationships — graph over hierarchy Two primary relationship types do most of the work: - `belongs_to` — strong, hierarchical ownership (a Task belongs to a Project) - `related_to` — weak, many-to-many semantic association The model is explicitly graph-shaped. Folders are not the primary organizing structure; relationships are. Specialized relationship types can be added when needed. ### Lifecycle — capture, organize, archive Information passes through three states, each optimized differently: 1. **Capture** — friction-free intake; no organization required 2. **Organize** — assign type and connect once purpose is clear 3. **Archive** — separate completed/obsolete items from the working set The separation matters: forcing organization at capture time kills the capture habit. ## Design Principles 1. **Convention over configuration** — defaults you can keep or override 2. **Tool-agnostic** — native to Tolaria, but applicable to any markdown-capable knowledge tool 3. **Life-work integration** — one type system for both domains 4. **Flexibility** — extensible without rigid schemas A key bet: in the agent era, **AI handles consistency** so the spec doesn't need to be deterministic or strictly enforced. The spec aims at "less semantic surface" — fewer things for both humans and agents to learn before being productive. ## Portent vs md-base Both Portent and [[Typed Markdown Collections Specification|md-base]] are open specifications for treating markdown-with-frontmatter as a knowledge base. They occupy adjacent but distinct slots: | | **Portent** | **md-base** | |---|---|---| | Primary concern | A *content model* — which types and relationships you should have | A *data model* — how to declare types, validate fields, and resolve links | | Granularity | High-level vocabulary (8 default types, 2 relationships) | Low-level schema (field types, validation, query semantics) | | Enforcement stance | Loose — AI agents normalize after the fact | Progressive — strict mode optional, validation possible | | Native tool | Tolaria | Multiple ([[Obsidian Starter Kit plugin for Obsidian]], `mdbase-cli`, `mdbase-lsp`) | | Closest analogue | A starter kit / opinionated framework | A schema definition language | They are complementary. Portent tells you *what kinds of notes to have*; md-base tells you *how to declare what each kind looks like*. A Portent-conformant vault could declare its 8 types using md-base type definitions. The [[Obsidian Starter Kit]] makes similar opinionated content choices to Portent (48 pre-configured note types), but expresses them through md-base. ## What Makes It Interesting - It treats the **strategy gap** as the actual problem. Most tools (Obsidian, Notion, Tolaria) give you mechanics; users still struggle with "what types should I have, how do I connect them, what does maintenance look like?" Portent is an answer to that question, not another tool. - It's **AI-native by design**. The whole point of keeping the surface small and graph-shaped is that agents can reason over it without bespoke prompting. - It's **portable on purpose**. The spec is decoupled from Tolaria specifically so the same vocabulary can live in any markdown system, including [[Obsidian]] and file-based notebooks. - It validates an emerging consensus: file-based systems with wikilinks and frontmatter are the substrate; the open question is what *conventions* to layer on top. ## References - Official website: https://portent.md - Specification & template vault: https://github.com/refactoringhq/portent - Portent vault template: https://github.com/refactoringhq/portent-vault-template - Introduction post by Luca Rossi: https://refactoring.fm/p/introducing-portent - Tolaria (the native implementation): https://tolaria.app ## Related - [[Typed Markdown Collections Specification]] (md-base — the schema-level counterpart) - [[Obsidian Starter Kit]] - [[Obsidian Starter Kit plugin for Obsidian]] - [[Bases core plugin for Obsidian]] - [[Obsidian]] - [[Markdown]] - [[Personal Knowledge Management System (PKMS)]] - [[Knowledge Graph (KG)]] - [[AI Wiki - PKM - Typed Notes]] - [[AI Wiki - PKM - Entity-Relationship Modeling for PKM]] - [[AI Wiki - PKM - Object-Oriented Note-Taking]] - [[AI Wiki - PKM - Ontology]] - [[AI Wiki - PKM - Ontological Commitment]] - [[AI Wiki - PKM - Plain Text and Interoperability]]