ZeroScan (.agent/) — Project Memory V2.1

# Instant Installation via pip
pip install zeroscan

# Instant Bootstrap in any repository
zeroscan-bootstrap --name "my-awesome-project" --mission "Build scalable AI apps"

🇬🇧 English | 🇻🇳 Tiếng Việt | 📘 Usage Guide | 📕 Hướng dẫn sử dụng | 🚀 Deep-Dive Article

The Zero-Scan, Git-Aware Context Engine for AI Coding Agents
Compatible with Hermes Agent, Claude Code, OpenAI Codex, and OpenCode.

🌟 Overview

Project Memory V2.1 is an open standard designed to eliminate context bloat, hallucination, and directory-crawling overhead in AI-driven software development.

Traditional coding agents waste tens of thousands of tokens scanning entire codebases upon startup. Project Memory replaces scanning with a lightweight, Git-bound Level 0 Boot Anchor (BOOT.md < 1 KB) and an architectural GPS Map (PROJECT_MAP.json), ensuring agents boot instantly with <= 10 KB of total context.

💡 Why It Saves 90–95% Tokens

1. Zero-Scan Startup (Level 0 Boot Anchor)

Traditional agents ingest entire repositories on every session turn, easily burning 30,000–100,000+ tokens before writing a single line of code. With Project Memory, the agent reads only BOOT.md (~1 KB / ~500 tokens), gaining immediate architectural clarity and task direction without exploring irrelevant directories.

2. GPS Navigation via PROJECT_MAP.json

Instead of performing costly regex searches across the tree, agents query the structured domain map to resolve exact source and test file paths just-in-time. Irrelevant modules are never loaded into working context.

3. Lean Multi-Agent Task Delegation

When an orchestrator agent delegates tasks to subagents or workers (e.g. specialized coding models), it passes only BOOT.md and NEXT_TASK.md. Worker agents operate in isolated, razor-sharp context windows without paying the token tax of the full repository.

📊 Token Consumption Comparison

📌 Engineering Scope Note: Token savings specifically measure context initialization, recursive directory crawling, and exploratory search overhead. Tokens required to author or modify actual code files depend naturally on the size of the generated diff.

📁 Standard .agent/ Architecture

Every compliant project contains an .agent/ directory with the following structure:

.agent/
├── BOOT.md               # [Level 0] Ultra-light session anchor (< 1 KB / ~30 lines)
├── PROJECT_STATE.json    # [Level 1] Machine state tied to git verified_commit & metrics
├── PROJECT_MAP.json      # Codebase GPS: Maps functional domains to files & tests
├── DECISIONS.md          # Architectural Decision Records (ADRs) with [LOCKED] status
├── TASK_LEDGER.jsonl     # Immutable append-only record of completed tasks & evidence
├── NEXT_TASK.md          # Concrete active task spec, acceptance criteria & test commands
├── MEMORY_PROTOCOL.md    # The 10 Golden Rules for agent execution & evidence verification
└── memory.py             # Pure Python 3.11+ zero-dependency engine (validate, checkpoint, status)

🚀 Quick Start: Scaffolding a New Project

Option A: Instant One-Liner (No Clone Required)

curl -fsSL https://raw.githubusercontent.com/chauvuusvn/zeroscan/main/bootstrap.py | python3 - -n "Quantum Engine" --domains "engine,storage,network,api" --git-init

Option B: Using local bootstrap.py

Use bootstrap.py to generate a standard .agent/ memory system in any target repository:

# Basic usage in current directory
python3 bootstrap.py

# Custom scaffolding for a specific project
python3 bootstrap.py \
  --target /path/to/my-project \
  --name "Quantum Engine" \
  --mission "High-performance distributed event processing engine" \
  --phase "Phase 1 - Core Architecture" \
  --domains "engine,storage,network,api" \
  --git-init

CLI Arguments for bootstrap.py:

🛠️ Operating .agent/memory.py in Target Projects

Once bootstrapped, agents interact with the memory engine directly:

1. View Project Status & Budget

python3 .agent/memory.py status

Displays mission, current phase, active task, git HEAD vs verified commit, and context size budget breakdown.

2. Validate Memory Integrity

python3 .agent/memory.py validate

Validates JSON schemas, git commit alignment, and verifies that BOOTSTRAP_CONTEXT_BYTES <= 10,240 bytes (10 KB).

3. Checkpoint State Atomically & Synchronize Next Task

python3 .agent/memory.py checkpoint \
  --phase "Phase 2 - Feature Development" \
  --status "IN_PROGRESS" \
  --record-ledger \
  --task-id "TASK-002" \
  --task-summary "Completed user registration and password hashing" \
  --evidence "pytest_exit_0_hash_abc123" \
  --test-status "ALL_PASS (48/48)" \
  --next-task "Build JWT Refresh Token Rotation" \
  --next-task-id "TASK-003" \
  --next-task-desc "Implement Redis-backed refresh token rotation with revoke whitelist"

• Atomically updates PROJECT_STATE.json.
• Synchronously regenerates BOOT.md.
• Synchronously updates NEXT_TASK.md with acceptance criteria.
• Appends task evidence to TASK_LEDGER.jsonl.
• Recalculates exact context metrics.

4. Append Architectural Decision (ADR)

python3 .agent/memory.py add-decision \
  --id "ADR-002" \
  --title "Use SQLite with WAL mode for local cache" \
  --status "LOCKED" \
  --context "High concurrent read requirements without external DB services" \
  --decision "Use embedded SQLite database with WAL and 64MB mmap" \
  --consequences "Zero external runtime dependencies; single-node only"

🔌 Model Context Protocol (MCP) Server Integration

Zero-Scan includes a native Model Context Protocol (MCP) server for 1-click integration with Cursor, Claude Desktop, Windsurf, Trae, and Claude Code.

Setup in Claude Desktop (claude_desktop_config.json) / Cursor:

{
  "mcpServers": {
    "zeroscan": {
      "command": "npx",
      "args": ["-y", "zeroscan-mcp"]
    }
  }
}

Or using Python directly:

{
  "mcpServers": {
    "zeroscan": {
      "command": "python3",
      "args": ["-m", "core.mcp_server"]
    }
  }
}

🛠️ Exposed MCP Tools:

• zeroscan_boot: Instant Level 0 Boot Anchor (< 1 KB / ~500 tokens). Eliminates repository scanning.
• zeroscan_get_map: Structured architectural GPS map (PROJECT_MAP.json).
• zeroscan_get_state: Milestone progress, git hash alignment, and execution state.
• zeroscan_get_next_task: Immediate actionable next task (NEXT_TASK.md).
• zeroscan_record_decision: Append ADRs to DECISIONS.md across sessions.
• zeroscan_validate: Enforce <= 10 KB context budget.

📊 Context Size Metrics & Limits

Project Memory V2.1 strictly enforces context budgets:

• Bootstrap Context Budget (BOOTSTRAP_CONTEXT_BYTES): $$\text{Size}(\text{BOOT.md}) + \text{Size}(\text{PROJECT_STATE.json}) + \text{Size}(\text{NEXT_TASK.md}) \le 10,240 \text{ bytes (10 KB)}$$
• Zero Directory Traversal: Agents read BOOT.md and PROJECT_MAP.json to navigate directly to relevant files instead of listing/reading entire trees.

📜 The 10 Golden Rules

1. Level 0 Boot First: Read .agent/BOOT.md on boot. Never recursive-scan codebase.
2. Verified Commit Binding: All state transitions must reference valid git commit hashes.
3. GPS Routing via Map: Use PROJECT_MAP.json to load only relevant domain files.
4. Immutable Locked Decisions: Never violate [LOCKED] ADRs in DECISIONS.md.
5. Atomic State Checkpointing: Use memory.py checkpoint for all updates.
6. Append-Only Ledger: Never modify or truncate TASK_LEDGER.jsonl.
7. Single Active Task Focus: NEXT_TASK.md governs the current single focus.
8. Evidence-Based Verification: Only mark tasks complete after passing verified test suites.
9. Strict Context Budget: Keep combined bootstrap files under 10 KB.
10. Memory Validation Guard: Run memory.py validate in pre-commit / CI.

⚠️ Common Pitfalls & Anti-Patterns (and How to Avoid Them)

❓ Frequently Asked Questions (FAQ)

python3 bootstrap.py --target /path/to/existing-repo --domains "auth,api,db,ui"

👤 Author & Maintainer

Justin — @chauvuusvn
Architected for high-autonomy multi-agent ecosystems and lean AI workflows.

🧪 License

Apache-2.0 / MIT. Created for high-autonomy agent workflows.