news

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 Re

Sebastien Dubois

02 Jun 2026 — 3 min read

Canonical version: Portent.

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:

Capture — friction-free intake; no organization required
Organize — assign type and connect once purpose is clear
Archive — separate completed/obsolete items from the working set

The separation matters: forcing organization at capture time kills the capture habit.

Design Principles

Convention over configuration — defaults you can keep or override
Tool-agnostic — native to Tolaria, but applicable to any markdown-capable knowledge tool
Life-work integration — one type system for both domains
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 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

About Sébastien

I'm Sébastien Dubois, and I'm on a mission to help knowledge workers escape information overload. After 20+ years in IT and seeing too many brilliant minds drowning in digital chaos, I've decided to help people build systems that actually work. Through the Knowii Community, my courses, products & services and my Website/Newsletter, I share practical and battle-tested systems.

I write about Knowledge Work, Personal Knowledge Management, Note-taking, Lifelong Learning, Personal Organization, Productivity, and more. I also craft lovely digital products and tools.

If you want to follow my work, then become a member and join our community.

Ready to get to the next level?

If you're tired of information overwhelm and ready to build a reliable knowledge system:

📚 KM for Beginners — 10+ hours of structured video lessons
🚀 Obsidian Starter Kit — Ready-made vault with 40+ templates
💼 Knowledge Worker Kit — Complete guides + lifetime community
🦉 1-on-1 Coaching — Personalized guidance
🎯 Join Knowii — Community + ALL courses & tools