📋 Summary

Introduces a robust, file-based project state management system for Hermes Agent. Solves the fundamental conflict between the stateless nature of AI Agents and the stateful continuity required by long-term projects.

🧠 Architecture: Three-Layer Memory Model

┌─────────────────────────────────────────────────┐
│                User Session (Short-term)          │
│          Context lost after session ends          │
└────────────────────────┬────────────────────────┘
                         │ Read/Write
┌────────────────────────▼────────────────────────┐
│             Project Layer (STATUS.md)             │
│   Macro state per project: Goals, Todo, Decision  │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────┐ │
│  │ Project A   │  │ Project B   │  │ Archive  │ │
│  │ STATUS.md   │  │ STATUS.md   │  │ _archive/│ │
│  └─────────────┘  └─────────────┘  └──────────┘ │
└────────────────────────┬────────────────────────┘
                         │沉淀 (Distillation)
┌────────────────────────▼────────────────────────┐
│              Global Layer (MEMORY.md)             │
│    User Preferences + Cross-project Lessons       │
└─────────────────────────────────────────────────┘

📁 Directory Structure

~/.hermes/projects/
├── index.md              # Auto-maintained project index
├── {project-name}/
│   ├── STATUS.md         # Macro state (Goals, Todo, Decisions)
│   └── docs/src/         # Project artifacts
└── _archive/             # Completed/deprecated projects

🚀 Key Features

1. Zero Context Bloat: Project details live in STATUS.md, NOT injected into every session via memory.
2. Intent-Driven Activation: No rigid keywords. Agent infers resume, pause, switch, or new from conversational context.
3. Graded Templates:
   • Template A: Long-term, multi-stage, team collaboration.
   • Template B: Quick tasks (<3 days), auto-upgrades if complexity grows.
4. Concurrency Safe: Enforces read-before-write to prevent race conditions across multiple agent instances.
5. Index Self-Healing: Auto-creates index.md on first use; backfills missing entries if directories exist.

🛡️ Strict Constraints

• Memory Ban: memory tool MUST only store user preferences/cross-project lessons. Project progress lives exclusively in STATUS.md.
• Read-First: Agent MUST read STATUS.md before answering project-related queries.
• Surgical Updates: Only write to files on meaningful state changes (decisions, completed tasks, blockers). Skip cosmetic/intermediate noise.

📄 Documentation

• SKILL.md: Complete workflow, templates, and constraints for Agent execution.
• DESIGN.md: Design philosophy, architecture summary, and problem-solving analysis.