personal-agent-os/README.md

🧠 Personal Agent OS

A git-backed external brain for Hermes — projects, knowledge, automation patterns, and agent config, all in one compounding repository.

Why This Exists

Scattered notes don't compound. This repo is:

• A project hub — every active project has a home with goals, decisions, and next actions
• A knowledge base — high-signal finds from X, tools, research, and experiments preserved with structured metadata
• A context layer — Hermes reads from it, writes to it, and gets smarter over time

How It Works

You / Telegram                      Hermes                        Gitea
       │                              │                              │
       │─  "Find me everything on     │                              │
       │   wakeAgent gates" ─────────→│── search_files ─────────────→│
       │                              │←─ gate designs + notes ─────│
       │←─ 3 patterns found ─────────│                              │
       │                              │                              │
       │─ daily brief fires ─────────→│── fetches data ─────────────→│
       │                              │── saves to kb/daily-briefs/ ─→│
       │←─ formatted brief ──────────│                              │

Directory Layout

personal-agent-os/
├── _meta/                        # Root-level meta
│   └── decision-log.md           # Key decisions, rationale, dates
│
├── projects/                     # Active projects
│   ├── hermes-persistent-os/     # The OS project itself
│   ├── compliance-tracker/       # (create when ready)
│   ├── local-business-automation/ # (create when ready)
│   └── ...
│
├── knowledge-base/               # Cross-cutting knowledge
│   ├── automation-blueprints/    # Reusable pattern docs
│   │   └── hermes/               # Hermes-specific patterns (migrated from hermes-automation/)
│   ├── ai-agent-patterns/        # General agent design patterns
│   ├── hermes-integrations/      # Platform-specific setup notes
│   ├── x-threads/                # Curated X threads and discussions
│   ├── tool-evaluations/         # 6-part evaluations of tools
│   ├── local-entrepreneurship/   # Local business patterns (Phoenix, etc.)
│   └── daily-briefs/             # (auto-populated by cron)
│
├── archive/                      # Completed/closed projects
│
├── templates/                    # Consistent formats
│   ├── project-readme-template.md
│   ├── kb-entry-template.md
│   └── experiment-log-template.md
│
└── agent-config/                 # Hermes runtime reference material
    └── .gitkeep

Conventions

Creating a New Project

1. Copy templates/project-readme-template.md into projects/<name>/README.md
2. Fill in Overview, Status, Goals, Architecture
3. Create tasks.md with Now / Next / Backlog sections

Adding a Knowledge Entry

1. Copy templates/kb-entry-template.md into the relevant knowledge-base/ subfolder
2. Fill the YAML frontmatter (title, date, source, tags, related_projects, status)
3. Write Summary, Key Insights, Mechanics, Actionable Ideas, Open Questions

Naming

• Lowercase with hyphens for directories and files
• Dates in YYYY-MM-DD format
• Tags as comma-separated, lowercase

How This Stays Alive (Living/Cron Workflows)

This repo is designed to be written to by Hermes cron jobs.

Cron Job	What It Writes	Frequency	Status
daily-brief	Delivers to Telegram. Will also save to knowledge-base/daily-briefs/	Daily at 15:00 UTC	✅ Live
weekly tag index	Scans all KB entries, rebuilds _meta/tag-index.md	Weekly (Sun)	🔲 Planned
opportunity scan	Saves entries to knowledge-base/x-threads/	Daily	⏸️ Paused
email triage	Summary to Telegram + entry to knowledge-base/hermes-integrations/	Every 15m	🔲 Planned

Writing Rules for Cron Jobs

• Always use the kb-entry-template.md format when saving to knowledge-base/
• Tag entries with the originating cron job name + relevant project
• Use write_file to append or create; never overwrite another entry
• Silent delivery on no-change ticks (masterclass pattern)

Agent Hooks

Hermes reads from this repo for context:

• projects/<name>/README.md — project status and goals
• projects/<name>/tasks.md — next actions
• knowledge-base/**/*.md — structured knowledge retrieval via search_files
• _meta/decision-log.md — why things were done a certain way
• agent-config/ — reference configs and setup snippets

Getting Started

1. Browse projects/hermes-persistent-os/ for the current automation roadmap
2. Read knowledge-base/automation-blueprints/hermes/ for running patterns
3. Use templates/ when adding new content
4. Check _meta/decision-log.md for architectural reasoning