agent-brief

A structured template for personal AI agents — the kind that live in your Obsidian vault, run on your laptop, or persist across Claude/ChatGPT/Codex/Gemini sessions.

You don't write this brief by hand. Your agent does.

You approve it.

The problem

Most personal AI agent setups are amnesiac. You write a 2-page system prompt; the agent reads it once; nothing accrues. Each new conversation starts cold. Retrospective work doesn't become memory.

The "fix" most templates propose — sit down and structure your whole life into a tagged markdown file — is the same problem in a different costume. Anyone who'd benefit from this format already lives inside agentic workflows. Hand-filling a template is exactly what they're trying to escape.

The shape

A markdown spec with three layers:

1. Identity & context — who you are, what's top of mind, how you communicate
2. Domain profiles — work, finance, family, health, whatever matters
3. Work log — chronicle of what you've done with AI, each entry tagged with what the agent should learn from it

Plus a small tag vocabulary the agent can grep across the file:

goal:   rule:   preference:   pattern:
cadence:   conviction:   drift:   note:

Eight tags. Used everywhere. Queryable memory.

The flow

The brief generates and refreshes itself. You stay in the approval loop.

┌─ Bootstrap ──────────────────────────────────────────┐
│  Hand the bootstrap prompt to your agent.            │
│  It interviews you OR drafts from existing context.  │
│  You review, edit, approve. v0 of the brief lives.   │
└──────────────────────────────────────────────────────┘
                          │
                          ▼
┌─ Session capture ────────────────────────────────────┐
│  After meaningful AI sessions, agent produces one    │
│  Work Log entry candidate, queues it for next        │
│  monthly refresh.                                    │
└──────────────────────────────────────────────────────┘
                          │
                          ▼
┌─ Monthly refresh ────────────────────────────────────┐
│  Scheduled run. Agent reads past month's work, adds  │
│  Work Log entries, updates priorities, surfaces      │
│  drift. Writes proposal to AGENT_BRIEF.proposed.md.  │
│  You review, accept or edit, append to changelog.    │
└──────────────────────────────────────────────────────┘
                          │
                          ▼
┌─ Quarterly drift audit ──────────────────────────────┐
│  Agent compares stated claims against observed       │
│  behaviour. Surfaces uncomfortable gaps.             │
└──────────────────────────────────────────────────────┘

All four prompts are in GENERATE.md, copy-pasteable into any agent — Claude, ChatGPT, Codex, Gemini, Hermes, OpenClaw, the next one.

Why not AGENTS.md / Claude.md / cursor rules?

Those are for coding agents — repo conventions, lint rules, build commands.

This is for personal agents — the ones reasoning about your portfolio, your kids' school admissions, your travel plans, your projects. Different surface area, different vocabulary.

The two coexist. AGENTS.md tells your coding agent how the repo works. agent-brief tells your personal agent how you work.

Repo contents

• TEMPLATE.md — the structure, with placeholders
• EXAMPLE.md — a fully worked example (fictional persona)
• GLOSSARY.md — tag vocabulary defined, with examples
• GENERATE.md — generation prompts + scheduling + approval pattern
• FAQ.md — common questions and pushback, answered
• SECURITY_AND_PRIVACY.md — what to put in a brief, what never to, threat model
• CONTRIBUTING.md — what kinds of PRs are welcome

How to start

1. Skim TEMPLATE.md so you know the shape
2. Open GENERATE.md, copy the bootstrap prompt
3. Paste it into your agent of choice with TEMPLATE.md and GLOSSARY.md as context
4. Answer questions or watch it draft from your existing context
5. Review, edit, save as AGENT_BRIEF.md
6. Schedule the monthly refresh

Total setup time: ~15 minutes. Ongoing: ~5 minutes per month for review.

Design principles

• The agent generates, you approve — no hand-filling
• Small vocabulary, used everywhere — eight tags is the cap
• Append-only Work Log — history compounds; nothing silently disappears
• Plain markdown, no tooling — if your agent can read text, it can use this
• Forkable, not framework — copy it, modify it, throw out what doesn't fit

Common questions

See FAQ.md for the most common pushback — how this differs from existing tools (Cursor rules, Mem, Letta, MemGPT, Zep), the eight-tag choice, hallucination handling, context window concerns, family/couple usage, and more.

Privacy

Your brief contains personal context — partner's name, kids' schools, financial positions, sometimes more. Don't commit your actual brief to a public repo. A .gitignore is included; see SECURITY_AND_PRIVACY.md for the threat model and a list of what should never go in a brief.

License

MIT. Fork it. Modify it. Make it yours.