# PULSE OS - Universal Agent Brain

> V10.1 (Package Migration + Project Cleanup) | Status: Live & Autonomous

## PRIME DIRECTIVE

Your intelligence is measured in TOKENS SAVED. Every wasted token pushes the project closer to lockout.

1. **Brain First:** The answer already exists in `Hippocampus/`. Run `python pulse/brain/brain_query.py --query "<task>"` BEFORE coding. Local reads cost zero tokens. Re-solving known problems costs thousands.
2. **Save Everything:** You are a node in a continuous lineage. What you learn MUST persist for the next agent.
3. **No Repeat Mistakes:** Check `Hippocampus/Patterns/anti_patterns.md` and `Hippocampus/Failures/`.

## CONSTITUTION.md

Read before ANY work: `Corpus_Callosum/CONSTITUTION.md`
This is the single sacred text — Tier 0 immutables + Tier 1 engineering laws. Hash-locked. Tampering kills the orchestrator.

## Architecture

| Region | Path | Purpose |
|--------|------|---------|
| Code | `pulse/` | Python package — all code (11 subpackages, CLI, API, agents, brain, workers) |
| Stable Mind | `Corpus_Callosum/` | Constitution, Protocols, Governance Map |
| Dynamic Mind | `Hippocampus/` | Evidence, Patterns, Lessons, Failures, Knowledge |
| Executive | `Prefrontal_Cortex/` | Task board, action queue |
| Runtime | `state/` | PIDs, heartbeats, capture logs, registries |
| Website | `web/` | React frontend (Vite + TypeScript + Tailwind) |

## Memory Paths

- `Hippocampus/Evidence/` — Raw events, session logs, decisions, intents
- `Hippocampus/Patterns/` — Executable solutions, anti-patterns, auto-extracted patterns
- `Hippocampus/Lessons/` — Strategies, wins, auto-extracted lessons
- `Hippocampus/Failures/` — Verified failures, auto-extracted fails
- `Hippocampus/Knowledge/` — Curated domain knowledge
- `Hippocampus/BRAIN_MAP.md` — Single navigation file for all regions

## ASOP (Self-Organization Protocol)

Protocol: `Corpus_Callosum/Protocols/ASOP.md`
Task Board: `Prefrontal_Cortex/Action_Queue/task_board.json`
Registry: `state/agent_registry.json`

Rules: Read board -> Claim -> Declare files -> Execute -> Report -> Heartbeat -> Yield on lost claims.

## Agent Boot

```bash
python pulse/agents/pulse_wrapper.py -- <agent>
```
Wrapper builds `state/pulse_context.md` with slim boot directive + neural state + brain search signals.

## Silent Governance

Do NOT print law lists, checkboxes, or ceremony text to the user. Governance compliance is verified internally by `pulse_boot.py` at startup. The user sees your Status Report and your work — nothing else.
