KnowledgeOS

Overview

KnowledgeOS is a local-first personal knowledge system I designed and built for a problem I kept running into: useful context was created every day through AI conversations, project updates, research sessions, and product decisions, but most of it disappeared after the session ended.

Instead of treating the knowledge base as a place where I manually file notes, I designed KnowledgeOS as an agent-maintained system. I focus on thinking, building, and deciding; the agent handles the maintenance layer: classifying useful information, deduplicating repeated ideas, updating project memory, synthesizing weekly patterns, auditing structure health, and backing up the vault over time.

The system is intentionally simple at the storage layer. Markdown remains the source of truth, readable by Obsidian, VS Code, Git, Codex, and Hermes Agent. Its compiled knowledge layer borrows from LLM Wiki and GBrain: source-backed concept pages, entity memory, relationship mapping, and current judgments that agents can reuse across sessions.

Maintenance Ownership: September 2026

The first version used Hermes Agent for capture and maintenance. Since September 30, 2026, Codex is the primary maintainer of formal KnowledgeOS pages. Hermes provides candidates and supports existing backup and derived-view workflows; it no longer writes formal pages by default.

Formal updates follow a serialized submission process. The earlier diagrams and May inventory below describe the original system, while this ownership boundary describes the current maintenance model.

The Problem: Knowledge Maintenance, Not Knowledge Storage

AI tools make it easier to generate ideas, plans, code, research summaries, and decisions. They also create a new failure mode: useful context gets scattered across chat threads, local files, project notes, browser tabs, and memory systems that do not preserve structure over time.

Traditional note-taking tools mostly solve storage. They give users a place to put information, but they still depend on the user to decide what matters, where it belongs, when it should be merged, and how old notes should update when the truth changes. That maintenance work is exactly what breaks under speed.

The design challenge was to make AI responsible for maintenance as well as generation. The system decides what deserves to persist, connects it to the right durable context, and periodically rewrites scattered updates into current judgment.

Design Principles

The first principle was agent-maintained, not user-maintained. KnowledgeOS should not ask me to manually sort every useful thought. Capture rules decide whether information should be ignored, proposed as a candidate, merged into an existing page, or preserved as project memory. Codex owns formal updates; Hermes supports candidate collection.

The second principle was Markdown as source of truth. I avoided databases, proprietary dashboards, and premature vector infrastructure because the system needed to stay inspectable, portable, and resilient. Every durable piece of knowledge lives in a local file that can be read by humans and edited by agents.

The third principle was save less, maintain better. KnowledgeOS does not preserve raw transcript dumps. A note has to reduce future repeated explanation, support a project, improve a decision, become career material, capture a reusable workflow, or clarify a durable pattern. The system protects attention instead of archiving everything.

The final principle was current judgment over passive archive. Core pages maintain a current synthesis, an evidence timeline, and related links. Remembering what happened matters less than keeping the latest useful understanding easy to retrieve.

From Notes to Maintained Knowledge

KnowledgeOS evolved from a simple local vault into a running agent-maintained knowledge system through a sequence of architecture, rule design, automation, and operational hardening decisions.

Early Architecture: Local Source of Truth, Agent Maintenance Layer

The early diagram separates the system into four layers. Inputs come from conversations, project updates, research sources, learning notes, career material, and product ideas. The maintenance layer applies capture rules, privacy filtering, classification, deduplication, synthesis, and audits. Its original Hermes ownership is historical; formal maintenance now belongs to Codex.

The knowledge layer remains local and legible: a Markdown vault organized around projects, AI workflows, product ideas, research wiki pages, and review logs. Obsidian views, weekly HTML artifacts, resume bullets, portfolio material, and Git backups are generated from that source of truth instead of becoming separate knowledge silos.

Designing the Agent Workflow

The core workflow starts before anything is written. When a conversation or task produces potentially reusable knowledge, the agent first evaluates whether it will matter later. If it does, the agent checks privacy boundaries, searches for related existing notes, and decides whether to update a current page or create a new record.

This prevents the vault from becoming a transcript dump. New project progress updates existing project memory. Product strategy updates the relevant product idea. Stable preferences belong in lightweight agent memory, while structured durable knowledge goes into KnowledgeOS. Weekly synthesis and maintenance audits then keep the system from drifting as the vault grows.

From Saved Notes to Maintained Judgment

One of the most important shifts was moving from saved knowledge to maintained judgment. This layer is where the influence from LLM Wiki and GBrain becomes explicit: source-backed pages preserve provenance, entity memory keeps projects, people, concepts, and tools connected, and current-judgment blocks make the latest synthesis easy for future agents to reuse.

For example, a project page can hold the current strategic read, the dated events that support it, links to related workflows or research, and the next action. That structure makes the knowledge more useful to future AI sessions because the agent can retrieve the current state quickly instead of re-reading every historical note.

Review Loops as Product Infrastructure

KnowledgeOS uses review loops to keep the system alive. Daily capture turns high-value events into lightweight records. Weekly review synthesizes patterns across projects, decisions, learning, and career material. Maintenance audit checks structural health: broken links, vague placeholders, source coverage, backup status, and whether the system is drifting away from its rules.

This turned the knowledge base into operational infrastructure. The system does not only remember; it periodically checks whether its own memory is still organized, connected, and useful.

May 2026 Implementation Snapshot

These inventory and link-check counts were recorded in the May 2026 case-study notes. They describe that implementation snapshot, not a current audit or a measured productivity gain.

The workflow count includes three review and maintenance jobs—daily capture, weekly review, and maintenance audit—plus a separate Git backup workflow. It is a broader count than the three maintenance cron jobs listed in the earlier project summary.

Key System Decisions

I chose Markdown over a database because the early risk was not query speed; it was ownership, inspectability, and maintenance. Markdown keeps the knowledge layer portable and human-readable while still being easy for agents to search, edit, and back up.

I designed rules before automation because automating an unclear system only creates structured mess. The capture protocol defines what deserves to persist, what should be ignored, what needs privacy filtering, and when new information should update an existing page instead of creating another note.

I used LLM Wiki and GBrain as reference projects, but treated them as patterns rather than templates. From LLM Wiki, I pulled the idea of source-backed compiled pages. From GBrain, I pulled the idea of persistent entity memory and relationship-aware context. KnowledgeOS combines those ideas with a local-first Markdown workflow and explicit agent maintenance responsibilities.

I also prioritized review loops over passive archive. The folder tree matters, but the recurring process matters more: it is what turns scattered updates into current judgment.

From Personal System to Starter Vault

After building KnowledgeOS as a live personal system, I extracted the reusable layer into KnowledgeOS Starter Vault: a privacy-safe, configurable template for people who want their own agent-maintained knowledge system.

The starter vault does not copy my private taxonomy or personal notes. Instead, it packages the transferable infrastructure: capture protocol, memory rules, source-backed knowledge schema, taxonomy configuration, daily and weekly review templates, optional domain packs, privacy scanning, and wikilink validation.

This turns the project from a private productivity system into a reusable design artifact: a way to explore how personal knowledge management changes when AI agents become responsible for maintenance, not just generation.

The KnowledgeOS Starter Vault is available as a public GitHub template: github.com/princeniu/KnowledgeOS