KnowledgeOS

An AI-maintained personal knowledge system you own.

Local-first · Markdown-native · Agent-driven

---

What is KnowledgeOS?

Most knowledge bases fail because humans have to maintain them manually. You capture notes, chats, research, and decisions — but the structure decays the moment you stop tending it.

KnowledgeOS gives AI-heavy users a Markdown-native system where agents handle the maintenance work: classifying what's worth saving, filtering private details, deduplicating repeated ideas, routing notes by taxonomy, and synthesizing current judgment over time.

You keep ownership of your files. The agent handles everything else.

Bring your own taxonomy. KnowledgeOS provides the maintenance system.

---

Quick Start

git clone https://github.com/princeniu/KnowledgeOS.git my-knowledge-os
cd my-knowledge-os
# Open the folder as an Obsidian vault, or use any Markdown editor

Then read QUICKSTART.md and customize config/taxonomy.yaml.

---

How It Works

KnowledgeOS separates into four layers: inputs from your real work (conversations, projects, research), an agent maintenance layer (capture rules, privacy filtering, deduplication, synthesis), a Markdown vault (the source of truth), and derived outputs (Obsidian views, weekly HTML artifacts, career material, Git backups).

The agent doesn't just write notes — it maintains a living knowledge system.

---

The Protocol

The reusable value isn't the folder names. It's the operating protocol:

1. Capture only useful knowledge — not raw transcript dumps
2. Filter noise and private details — privacy scan before any write
3. Route by semantic category — agents read config/taxonomy.yaml, not hardcoded paths
4. Deduplicate before writing — update an existing page when it already covers the topic
5. Preserve source provenance — where did this knowledge come from and when
6. Maintain current judgments — core pages hold a living synthesis, not just a log of old notes
7. Synthesize daily / weekly / audit reviews — scattered updates become structured understanding
8. Keep Markdown as source of truth — readable by humans, editable by agents, portable forever

Core pages maintain a current judgment, an evidence timeline, and related links — so your agent retrieves the latest understanding, not every historical note.

---

Vault Structure

00-inbox/      Temporary staging for unprocessed inputs
02-projects/   Project memory, decisions, status, next actions
03-workflows/  Reusable workflows, prompts, automations
04-ideas/      Product, research, writing, or system ideas
05-learning/   Courses, books, concepts, study notes
06-research/   Source-backed concepts, entities, comparisons
90-reviews/    Daily, weekly, and maintenance synthesis
99-archive/    Stale or inactive material

Optional domain packs are included but not forced: startup-builder, career, engineering, self-reflection, design-ux, trading-investing, content-creator, and research-academic. Enable only what matches your workflow.

---

Agent Workflow

Before writing, the agent reads: MEMORY_RULES.md, CAPTURE_PROTOCOL.md, KNOWLEDGE_SCHEMA.md, and config/taxonomy.yaml.

Every save follows the same loop:

1. Decide whether the content is worth saving
2. Remove sensitive or private details
3. Route by semantic category from config/taxonomy.yaml
4. Search for duplicates
5. Update an existing page when possible
6. Create a new page only when needed
7. Update the daily log
8. Report what changed

---

Who It's For

This starter vault is useful if you:

• use AI tools heavily and keep losing context between sessions
• run multiple projects, ideas, learning tracks, or research threads
• want a local Markdown system instead of a heavy SaaS knowledge base
• want your agent to maintain knowledge instead of manually organizing notes
• care about privacy, portability, and long-term ownership of your data

KnowledgeOS is a Markdown-native system, not a SaaS app, not a Notion clone, and not a vector database demo. It's infrastructure you control.

---

Privacy & Safety

Before sharing your vault or publishing it, run the built-in safety checks:

python3 docs/scripts/privacy_scan.py .
python3 docs/scripts/check_wikilinks.py .

These scan for private identifiers, local paths, credentials, and broken wikilinks.

---

Documentation

• docs/why-knowledgeos.md — product philosophy and design rationale
• docs/setup-hermes-agent.md — operate the vault with an AI agent
• docs/example-workflow.md — raw update → review synthesis walkthrough
• docs/taxonomy-customization.md — rename or extend the folder system
• docs/customization-playbook.md — safe customization workflow
• docs/release-checklist.md — checks before sharing or publishing

---

License

MIT © KnowledgeOS contributors