Personal OS

A Markdown-based personal knowledge system designed for both humans and AI agents.

Personal OS gives multiple AI tools one shared source of truth for your context, preferences, goals, source material, and curated knowledge. You can browse it in Obsidian, edit it with any text editor, and store it in a private GitHub repository so local and remote agents can work from the same canonical files.

This repository contains a public starter system. It uses placeholder and fictional content only. Do not add private information to a public copy.

How It Works

The system has three layers:

1. Operating context: AGENTS.md, LLMMEMORIES.md, and SYSTEMPROMPT.md tell agents how the repository works, what they should know about you, and how you want them to behave.
2. Raw sources: raw/ holds unprocessed material. Agents read source files but do not rewrite them, except for the designated capture inboxes.
3. Curated wiki: wiki/ contains concise, organized, cross-linked knowledge that agents maintain over time.

A typical workflow looks like this:

1. Capture an idea in raw/BACKLOG.md or add a source document to raw/.
2. Ask an agent to process the backlog or ingest the source.
3. The agent reads the repository instructions and existing wiki first.
4. It synthesizes the new information into the appropriate wiki pages.
5. Future agents use the updated wiki and canonical context instead of starting from scratch.

The result is a compounding knowledge base rather than a collection of disconnected chat histories.

Getting Started

Recommended: create a private repository from this template

1. Click Use this template on GitHub.

2. Create a new private repository.

3. Clone that private repository to your computer.

4. Replace the placeholder sections in LLMMEMORIES.md, SYSTEMPROMPT.md, and wiki/GOALS.md.

5. Open the folder as an Obsidian vault if you use Obsidian.

6. Open the repository with your preferred agent and say:

   Read AGENTS.md completely, inspect wiki/index.md, and help me personalize this knowledge base.

If you keep your copy public, do not store personal, financial, employment, health, credential, or private relationship information in it.

Directory Structure

personal-os/
├── AGENTS.md              # Authoritative operating instructions for agents
├── LLMMEMORIES.md         # Persistent personal and professional context
├── SYSTEMPROMPT.md        # Communication, safety, and execution preferences
├── raw/                   # Source-material inbox
│   ├── BACKLOG.md         # Fast capture inbox
│   └── JOURNAL.md         # Journal capture inbox
├── tools/                 # Optional local tooling (no dependencies beyond Python 3)
│   └── kanban.py          # Generates a visual Kanban dashboard from Tasks/
└── wiki/                  # Curated knowledge maintained by agents
    ├── index.md            # Navigation hub
    ├── GOALS.md            # Goals and priorities
    ├── Tasks/              # One Markdown file per active task
    └── Knowledge/          # Research, concepts, projects, and reference notes

Core Files

AGENTS.md

Defines repository boundaries and agent workflows. It tells every agent what to read, where it may write, how to synthesize sources, and how to preserve the integrity of the vault.

LLMMEMORIES.md

Stores durable context that would otherwise be repeated in every conversation: your roles, active projects, tools, recurring collaborators, shorthand, and working preferences.

SYSTEMPROMPT.md

Captures how you want AI systems to communicate and operate, including writing style, technical preferences, confirmation gates, privacy rules, and escalation behavior.

raw/

Preserves source material. Most files in this directory are read-only for agents. BACKLOG.md and JOURNAL.md are explicit capture exceptions.

wiki/

Contains the useful, maintained knowledge layer. Agents synthesize raw inputs into canonical notes, connect related pages with wikilinks, and consult the wiki before answering questions.

Kanban Task Dashboard

The repository includes an optional visual dashboard that turns wiki/Tasks/ into a Kanban board you open in your browser:

python3 tools/kanban.py --open

• Columns: 🔥 Today · In Progress · Blocked · Waiting On · Up Next · Later, derived from each task's status, priority, due_date, and optional today: true flag.
• Project radar: a strip of per-project health cards (At Risk / Waiting / Active / Clear, open counts, nearest due date). Add an optional project: field to a task's frontmatter to group it; click a radar card to filter the board.
• Cards: color-coded project tags, priority badges, overdue and due-soon highlighting, stale flags for long-running started work, time estimates, and the task's next unchecked action. Card titles deep-link into Obsidian.
• Filters: priority chips and live search, combinable with project filters.

The board is read-only by design — Markdown task files remain the single source of truth, and the generated tools/dashboard.html is a gitignored build artifact. It is a single self-contained HTML file (no external requests, works offline) generated by a dependency-free Python 3 script, so it works on a fresh clone with no setup. Run python3 -m unittest tools.tests.test_kanban to test it.

Example Use Cases

Daily prioritization

Capture unfinished thoughts in raw/BACKLOG.md, then ask an agent to convert them into structured task files aligned with wiki/GOALS.md.

Research synthesis

Add articles, reports, transcripts, or notes to raw/. Ask an agent to ingest one source at a time, update existing topic pages, flag contradictions, and link related concepts.

Project memory

Maintain one canonical project page with decisions, status, open questions, and next actions. Other task and meeting notes link back to that page instead of duplicating the plan.

Meeting follow-through

Add a transcript or meeting note to raw/. The agent can create a concise meeting record, update relevant people or project pages, and capture action items as tasks.

Cross-agent context

Store the private instance in GitHub so local tools and remote agents can read the same canonical files. Each agent begins with AGENTS.md, then loads only the context relevant to the current task.

Design Principles

• Markdown remains portable and human-readable.
• The private repository is the source of truth.
• Raw sources are preserved; the wiki is synthesized.
• Agents update existing canonical pages before creating duplicates.
• Context is loaded progressively instead of indiscriminately.
• Humans retain control over destructive, external, or sensitive actions.
• Private information belongs only in a private instance.

Inspiration and Attribution

This implementation combines ideas from several public approaches:

• Aman Khan's Personal OS, particularly Markdown-based task management, backlog processing, and goal-aware agent workflows.
• Bill Mongan's private AI knowledge base, particularly shared canonical context across AI systems using AGENTS.md, LLMMEMORIES.md, and SYSTEMPROMPT.md.
• Andrej Karpathy's LLM Wiki, particularly the raw sources, curated wiki, and agent schema pattern.

This repository is an independent starter implementation shaped by practical use across multiple AI agents.

License

This work is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International.

You may share and adapt it with attribution for noncommercial purposes. Adaptations must use the same license.

Copyright © 2026 Michael Fisher.