# 🧠 Personal Agent OS

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

## AgentOS vault (canonical)

**Live VPS path:** `/home/vpsadmin/AgentOS`  
**Mirror in this repo:** `memory-systems/agent-os/`  

Start with:

- `memory-systems/agent-os/HOME.md` — constitution  
- `memory-systems/agent-os/DESKTOP_SYNC.md` — laptop Obsidian  
- `memory-systems/agent-os/STATUS.md` — snapshot  
- `memory-systems/agent-os/04_Daily/` — consolidations  
- `memory-systems/agent-os/04_projects/` — athena, ai-talk-show, phoenix, …

Open the live AgentOS tree (or a sync of `memory-systems/agent-os`) in desktop Obsidian. Hermes `OBSIDIAN_VAULT_PATH` points at the VPS live path.

## 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 (legacy layout)
├── knowledge-base/                 # Cross-cutting knowledge
├── memory-systems/agent-os/        # **Canonical AgentOS vault mirror**
├── archive/
├── templates/
└── agent-config/
```

See `memory-systems/agent-os/HOME.md` for the operating loop. Older sections below may lag the vault — prefer AgentOS paths for new work.

## Conventions

### Creating a New Project
1. Prefer `memory-systems/agent-os/04_projects/<name>/status.md` + `decisions.md`
2. Or copy `templates/project-readme-template.md` into `projects/<name>/README.md` for legacy layout

### Adding a Knowledge Entry
1. Copy `templates/kb-entry-template.md` into the relevant `knowledge-base/` subfolder
2. Fill 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

## Agent Hooks

Hermes reads for context:

- `memory-systems/agent-os/HOME.md` + project `status.md`
- `memory-systems/agent-os/04_Daily/`
- `knowledge-base/**/*.md` via search_files
- `_meta/decision-log.md`
- `agent-config/`

## Getting Started

1. Read `memory-systems/agent-os/HOME.md`
2. Read `memory-systems/agent-os/DESKTOP_SYNC.md` for laptop Obsidian
3. Browse `memory-systems/agent-os/04_projects/` for live project status
4. Use `templates/` when adding new KB content outside AgentOS