Memory lets an AI remember the past. Statuz lets an AI understand where it stands, what matters now, and when human direction must be renewed.
Statuz is a Runtime that keeps users, agents, projects, and niches in continuous Reality Synchronization.
Statuz is the situated alignment ecosystem for AI agents and their human principals. It provides an open, verifiable, extensible stack for expressing:
- who the agent is and what role it is playing;
- what the agent is currently doing;
- what progress has already been made;
- **what other agents, projects, files, tools, users, products, or organizations are related;
- **where the agent stands in the ecosystem;
- **what changes in the environment affect the agent;
- when the agent needs to request human direction for strategic decisions.
Statuz is not another long-term memory database. It is the missing situated alignment layer between memory, tools, skills, projects, and multi-agent systems.
This is what makes Statuz unique.
Most agent tools focus on "what to do next." Statuz focuses on where you stand in relation to everything else.
┌───────────────────────────────────────────────────────────────────┐
│ Your Project Ecosystem │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Project A │ ◀──▶ │ Project B │ ◀──▶ │ Project C │ │
│ │ (frontend) │ │ (backend) │ │ (shared lib)│ │
│ └──────┬───────┘ └───────┬──────┘ └──────┬───────┘ │
│ │ │ │ │
│ └──────────────────────┼─────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ Statuz niche Layer │ │
│ │ - Who's related? │ │
│ │ - How do they connect?│ │
│ │ - What's changed? │ │
│ └──────────────────────┘ │
└───────────────────────────────────────────────────────────────────┘
The niche layer declares:
- 🎯 Position (who I am, what I do, what I don't do)
- 🌐 Boundaries (clear does/does_not separation)
- 🎲 Strategic bets (key architectural decisions)
- 📊 Success signals (how to measure alignment)
The calibration layer monitors:
- 🔗 Project relationships (what depends on what, who collaborates with whom)
- 🔄 Environment changes (what's shifting in the ecosystem)
- 📊 Impact assessment (which changes actually affect this agent)
- 🎯 Drift detection (declared vs. observed behavior)
⚠️ SYN triggers (when to escalate to human)
Search for "Statuz" in the VS Code Marketplace or install from Open VSX.
npm install -g @statuz/statuzThen use it:
# Initialize
statuz init --agent dev-agent --project my-ai-project
# Validate
statuz validate .statuz/statuz.yaml
# Resume
statuz resume .statuz/statuz.yaml# Only CLI
npm install -g @statuz/cli
# Only SDK
npm install @statuz/sdk-ts
# Only MCP Server
npm install @statuz/mcp-serverStatuz defines four layers of situated alignment—building from concrete runtime to reusable topology:
┌───────────────────────────────────────────────────────────────┐
│ 🔮 66 (Arrow Maps) │
│ Reusable, executable topologies — What is the invisible │
│ architecture that makes me possible? │
├───────────────────────────────────────────────────────────────┤
│ 🔄 SYN (Human Governance & Strategic Synchronization) │
│ When must I request human direction? How do I present │
│ strategic options with evidence? How do I record decisions? │
├───────────────────────────────────────────────────────────────┤
│ 🌍 niche (Ecological Position & Long-Term Calibration) │
│ Where do I stand in the ecosystem? What changes affect me? │
│ Should I recalibrate? Who should I collaborate with? │
├───────────────────────────────────────────────────────────────┤
│ ⚡ Statuz Core (Runtime Status) │
│ Who am I? What am I doing? What progress have I made? │
│ What should happen next? │
└───────────────────────────────────────────────────────────────┘
| Layer | Purpose | Status |
|---|---|---|
| Statuz Core | Compact runtime status + Pending Actions (agent ↔ human task tracking) | ✅ Stable (0.5.0) |
| niche | Ecological position declaration | ⚙️ Working Draft (0.5.0) |
| Calibration | Drift detection (declared vs. observed) | ⚙️ Working Draft (0.5.0) |
| SYN | Human governance for strategic decisions | ⚙️ Working Draft (0.5.0) |
| 66 | Topological abstraction with Arrow Maps | 🔧 Implementation (0.1.0-draft) |
┌─────────────────────────────────────────────────────────┐
│ Agent gets interrupted (context switch, model switch) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Statuz Core YAML file saved beside project │ │
│ │ - identity: dev-agent │ │
│ │ - task: implementing API layer │ │
│ │ - checkpoint: test failed at controller │ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Resume: statuz resume → picks up exactly │ │
│ │ where it left off, with full context │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ You have 3 related projects: Frontend ↔ Backend ↔ Shared Library │
│ ┌─────────────────────────────────────────────────┐ │
│ │ VCS changes in Shared Library → niche signal emitted │ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Assessment: "Shared Library API changed → │ │
│ │ affects both Frontend & Backend → impact 80% │ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Calibration proposal generated with evidence │ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ All agents in Frontend/Backend get notified, sync up │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────────┐
│ Project Graph (e.g., MuseRock + Statuz + oasis-cli │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Statuz tracks: "I'm used by MuseRock, depends on oasis-cli"│ │
│ │ - statuz.yaml for statuz.yaml │ │
│ └───────────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ When oasis-cli changes → Statuz detects: "Affects MuseRock?" │ │
│ │ because they use my validation features" │ │
│ └───────────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Smart collaboration triggered → all related agents get calibrated │ │
│ └───────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ Threshold crossed → SYN request initiated │
│ ┌─────────────────────────────────────────────────┐ │
│ │ VS Code Extension shows: "Strategic decision │ │
│ │ needed—boundaries, position, or authority" │ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Human reviews evidence → makes decision │ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Resolution recorded, accountability tracked │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Statuz in one sentence │
├─────────────────────────────────────────────────────────────┤
│ ┌──────────┐ ┌──────────────┐ ┌───────────────────────┐ │
│ │ Who am │ │ Where am │ │ When do I need │ │
│ │ I? │ │ I? │ │ human direction? │ │
│ └────┬─────┘ └───────┬──────┘ └───────────┬───────────┘ │
│ │ │ │ │
│ v v v │
│ ┌──────────┐ ┌──────────────┐ ┌───────────────────────┐ │
│ │ Core │ │ niche │ │ SYN │ │
│ │ │ │ │ │ │ │
│ │ ⚡ │ │ 🌍 │ │ 🔄 │ │
│ └──────────┘ └──────────────┘ └───────────────────────┘ │
│ │
│ = Complete Situated Alignment │
└─────────────────────────────────────────────────────────────┘
Statuz focuses on six primitives in the Core layer, plus ecological relationship tracking:
| Primitive | Question answered |
|---|---|
identity |
Who am I? |
role |
What am I responsible for? |
goal |
What am I trying to achieve? |
progress |
How far have I gone? |
relations |
What projects, agents, tools, users, and files are connected to this state? |
next_action |
What is the next most useful move? |
Statuz is not:
- a vector database;
- a replacement for MCP;
- a replacement for Agent Skills;
- a full project management system;
- a chat transcript archive;
- a knowledge graph pretending to be memory.
Statuz is the compact runtime state that tells the agent where it stands.
┌─────────────────────────────────────────────────────────────┐
│ Statuz Ecosystem │
├─────────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 📝 Protocol Layer │ │
│ │ - SPEC.md (Core specification) │ │
│ │ - JSON Schemas (validation) │ │
│ │ - niche & SYN schemas │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 🛠️ Tool Layer │ │
│ │ - CLI (npm: @statuz/cli) │ │
│ │ - TypeScript SDK (npm: @statuz/sdk-ts) │ │
│ │ - Python SDK (pip: coming soon) │ │
│ │ - MCP Server (npm: @statuz/mcp-server) │ │
│ │ - VS Code Extension (Open VSX: statuz.statuz-vscode)│ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 📚 Knowledge Layer │ │
│ │ - Examples (single-agent, multi-agent, niche) │ │
│ │ - ADRs (architecture decisions) │ │
│ │ - Best practices documentation │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 🚀 Distribution Layer │ │
│ │ - npm packages (published) │ │
│ │ - Open VSX (published) │ │
│ │ - VS Code Marketplace (coming soon) │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
The core runtime status layer that answers: who am I, what am I doing, where am I, and what's next.
Current implementation:
- CLI 0.5.0 -
statuz init,statuz validate,statuz resume - TypeScript SDK 0.5.0 - programmatic access to Statuz files
- MCP Server 0.5.0 - Model Context Protocol integration
- VS Code Extension 0.5.0 - in-editor validation and tree view
Our secret weapon! The ecological positioning layer that declares: who I am, what I do, what I don't do, and what success looks like.
Status: Working draft. Schemas and documentation are complete.
The drift detection layer that monitors the gap between declared niche and observed behavior. Answers: am I doing what I said I would do?
Status: Working draft. Schemas and documentation are complete.
The human governance interface for strategic synchronization requests when position, boundaries, or authority require renewal.
Status: Working draft. Schemas and documentation are complete; VS Code webview tooling is available.
statuz_version: "0.1"
identity:
agent_name: dev-agent
project_name: MuseRock
organization: Oasis Company
role:
name: implementation-assistant
responsibilities:
- implement features
- preserve existing architecture
- explain tradeoffs
current_state:
stage: implementation
task: add Statuz Layer
status: in_progress
last_checkpoint: designed the first API shape
next_action: create statuz service module
relations:
related_agents:
- doc-agent
- qa-agent
related_projects:
- statuz
- oasis-cli
related_files:
- apps/api/src/memory
- apps/web/src/stores
rules:
should_not:
- overwrite the existing memory system
- interrupt the user during focus modeAI agents do not only need more context. They need better self-location and ecological awareness.
A good agent should be able to say:
I am the coding assistant for this project. I am currently implementing the API layer. I stopped because a test failed. The related documentation agent should be notified. The next action is to inspect the controller contract. Also, I see that oasis-cli changed—does that affect what I'm doing?
That sentence is Statuz.
| Document | Purpose |
|---|---|
| ROOT_README.md | Repository overview with architecture and package status |
| SPEC.md | Core Protocol specification (Core, niche, SYN layers) |
| ADAPTERS.md | External Adapters guide (CLI, SDK, MCP, VS Code, Cloud) |
| CLAUDE_CODE_INTEGRATION.md | Complete user journey for Claude Code agents |
| ROADMAP.md | Development plan and staged priorities |
| examples/ | Ready-to-use Statuz file templates |
| docs/ | Architecture decisions and smoke tests |
| 66-implementation/ | Topological layer (Arrow Maps) implementation |
This project is maintained by:
- ceaserzhao (@zbbsdsb) from Oasis Company
Apache-2.0.