# 🧠 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