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, and Hermes Agent. Its compiled knowledge layer deliberately borrows from LLM Wiki and GBrain: source-backed concept pages, entity memory, relationship mapping, and current judgments that agents can reuse across sessions.

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. Hermes Agent follows capture rules to decide whether something should be ignored, appended to an existing note, turned into project memory, or preserved as a longer-term pattern.

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.

System Architecture: Local Source of Truth, Agent Maintenance Layer

KnowledgeOS separates the system into four layers. Inputs come from real work: Hermes conversations, project updates, research sources, learning notes, career material, and product ideas. The agent maintenance layer applies capture rules, privacy filtering, classification, deduplication, synthesis, and audits.

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.

Evidence Snapshot

KnowledgeOS is a live personal system, so the clearest evidence is operational: the vault has structure, links resolve, automated workflows run, and the knowledge layer is backed up as a recoverable local asset.

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 Hermes-driven maintenance loops.

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