agent-os is a filesystem-based continuity system that lets multiple AI agents share memory, context, and active work — across sessions, across tools, and across time.
It solves the #1 problem with AI-assisted development: when you close the chat, the agent forgets everything.
┌─────────────┐
│ WebUI Chat │
└──────┬──────┘
│
┌──────────┐ ┌──────▼──────┐ ┌───────────┐
│ Discord │◄──►│ agent-os/ │◄──►│ Codex │
│ Bot │ │ │ │ Agent │
└──────────┘ │ 📁 Shared │ └───────────┘
│ Continuity │
┌──────────┐ │ Layer │ ┌───────────┐
│ Claude │◄──►│ │◄──►│ Future │
│ Code │ └─────────────┘ │ Agents │
└──────────┘ └───────────┘
- 🔁 Session-proof memory — Agents pick up exactly where the last one left off
- 🤝 Multi-agent handoffs — WebUI → Discord → CLI → back again, seamlessly
- 📋 Structured knowledge — Not chat logs. Real, organized, queryable docs
- 🏗️ Long build tracking — Multi-hour jobs survive session death with build-state files
- 🧩 Tool-agnostic — Works with Claude, Codex, OpenClaw, or any agent that can read files
- 🛡️ Safety rails — Built-in workflows to prevent SSH bans, production accidents, and data loss
# Clone the repo
git clone https://github.com/AlphaMine-Tech/agent-os.git ~/agent-os
cd ~/agent-os
# That's it. Point your agents at ~/agent-os/ and go.Then tell your agent:
"Read ~/agent-os/MANAGEMENT.md and follow the startup read order."
The agent will bootstrap itself into your continuity system automatically.
agent-os/
│
├── 📜 MANAGEMENT.md # How the system works (start here)
├── 📋 TODO.md # Active priorities across all agents
├── 🧠 MEMORY.md # Curated active durable truth
├── 🤖 AGENT-BOOTSTRAP-PROMPT.md # Copy-paste prompt to onboard any new agent
│
├── 📅 memory/ # Daily notes (append-only raw context)
│ └── YYYY-MM-DD.md
│
├── 📚 docs/
│ ├── projects/ # Stable per-project knowledge
│ ├── workflows/ # Reusable operating procedures
│ └── decisions/ # Important decisions + rationale
│
├── 🔧 build-state/ # Resumable state for long-running jobs
│
├── 🔀 handoffs/ # Active task handoff notes between agents
│
└── 🗺️ index/ # Infrastructure maps (hosts, repos, services)
agent-os uses a 5-layer memory system — from hot session context to cold archival docs:
Layer 1: Live Session Context ← immediate reasoning (volatile)
Layer 2: Daily Notes ← raw residue from today's work
Layer 3: MEMORY.md ← curated active truths
Layer 4: Decision Records ← rationale and tradeoffs
Layer 5: Project & Workflow Docs ← stable long-term knowledge
| Principle | What It Means |
|---|---|
| 🎯 Canonical truth is global | Agent-local memory is a cache. agent-os/ is the source of truth |
| 📝 Transcripts are fallback | If a fact matters later, write it to a file. Don't rely on chat history |
| 🏠 Every fact gets one home | No duplicating truth across TODO, memory, and docs |
| 🔄 Long jobs must be resumable | Multi-step work uses build-state/ files to survive session death |
When any agent joins a fresh session, it reads in this order:
1. MANAGEMENT.md → understand the system
2. TODO.md → know what's active
3. memory/today.md → recent context
4. memory/yesterday.md → recent context
5. MEMORY.md → durable truths
6. docs/projects/ → relevant project knowledge
7. docs/workflows/ → relevant operating procedures
8. build-state/ → any resumable active work
One of agent-os's most powerful patterns: seamlessly hand off work between different agent interfaces.
When pausing work in one session (e.g., WebUI), write a handoff:
# handoffs/my-task-2026-04-25.md
## Current Status
What's done, what's running, what's blocked.
## Blocker
The specific issue preventing completion.
## Exact Next Steps
1. Try this first
2. If that fails, try this
3. Validation command: `some-command --check`
## Files/Paths
| Path | Description |
|------|-------------|
| /path/to/thing | What it is |In the next session (e.g., Discord bot), the agent reads the handoff and continues:
"Check the latest handoff and continue from the recorded next steps."
The new agent has full context without needing the old chat transcript.
For multi-hour builds, deployments, or migrations that must survive agent restarts:
# build-state/my-build.md
## Goal
What we're building and why.
## Definition of Done
How we know it's complete.
## Milestones
- [x] Step 1: Clone and configure
- [x] Step 2: Build image
- [ ] Step 3: Deploy and validate ← current
- [ ] Step 4: Cutover and verify
## Last Checkpoint
Step 2 completed at 2026-04-25 20:30 UTC.
Image: my-image:v1.0 (sha256:abc123...)
## Blockers
None currently.If the session dies mid-build, the next agent reads build-state/ and picks up from the last checkpoint.
agent-os includes built-in safety patterns to prevent common AI-agent accidents:
# Never guess SSH usernames — wrong guesses trigger fail2ban lockouts
# Always verify host, user, and port from index/hosts.md first# Never make destructive changes without explicit human approval
# Always check for active jobs before shutting down services
# Never assume resource usage alone proves active work# Always checkpoint before multi-step operations
# Never leave more than one milestone only in transient state
# If worker dies, resume from build-state + repo, not memoryCopy-paste this into any AI agent to onboard it into your agent-os:
You are joining an active multi-agent operating environment.
Read these files in order:
1. ~/agent-os/MANAGEMENT.md
2. ~/agent-os/TODO.md
3. ~/agent-os/memory/<today>.md
4. ~/agent-os/MEMORY.md
Then read relevant docs/projects/ and docs/workflows/ files.
Rules:
- agent-os/ is the canonical source of truth
- Transcripts are fallback, not primary memory
- Write durable facts to the appropriate canonical file
- Use build-state/ for any work lasting > 15 minutes
- Never make destructive changes without human approval
Report what you found and what's currently active.
# Active Durable Truth
## Infrastructure
- Primary server: <hostname> at <role>
- Services: <list of running services>
## Operating Rules
- Rule 1: Never do X without approval
- Rule 2: Always verify Y before Z
## Lessons Learned
- <Date>: <What happened and what we learned># Active Priorities
## High Priority
- [ ] Task description — context and blockers
## Medium Priority
- [ ] Task description
## Completed Recently
- [x] Task — completed YYYY-MM-DDagent-os was born from real production pain:
We were running AI agents across WebUI, Discord, and CLI to manage infrastructure, deploy services, and coordinate multi-hour builds. Every time a session ended, the next agent started from scratch. We lost context, repeated mistakes, and wasted hours re-learning what the last agent already knew.
agent-os fixes this by making the filesystem the memory — not the chat window.
It's intentionally simple: just markdown files in a directory. No database, no API, no lock-in. Any agent that can read files can participate in the continuity system.
 AlphaMine 🏗️ Creator & Architect |
 Lord Beerus 🤖 AI Co-Author (Claude Opus) |
If agent-os saved you time or inspired your setup, consider leaving a tip:
| Network | Address |
|---|---|
| ₿ Bitcoin | bc1q52ceav67rp8mxa3ptany2l59kfdat6q7ne86ck |
| ⟠ Ethereum | 0x8A69d2C99b8a537acC7Da124E00cf38d876815D4 |
| 🔴 Quai Network | 0x003078b752c0cabF8bbf2b956711DfA44864BA6C |
| 🟢 Kaspa | kaspa:qypcrq3zu0ufvvg8ch5spclu2nwpjywl5rsmcjrxs1u34dwyuh7yhyg5268s8d4 |
MIT License — use it, fork it, make it yours.