Metadata-Version: 2.4
Name: pulse-os
Version: 10.6.0
Summary: PULSE: A Neural Operating System for AI Swarms.
Project-URL: Homepage, https://github.com/Honesty0x/PULSE
Project-URL: Repository, https://github.com/Honesty0x/PULSE
Project-URL: Documentation, https://github.com/Honesty0x/PULSE/blob/main/README.md
Author-email: PULSE Contributors <contact@pulse-os.org>
License: Proprietary
License-File: LICENSE
Keywords: agents,ai,autonomous,llm,neural-os,swarm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Operating System
Requires-Python: >=3.10
Requires-Dist: cryptography>=41.0
Requires-Dist: filelock>=3.13.1
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.7.0
Provides-Extra: api
Requires-Dist: flask>=3.0; extra == 'api'
Requires-Dist: requests>=2.31; extra == 'api'
Provides-Extra: brain
Requires-Dist: networkx>=3.0; extra == 'brain'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'brain'
Description-Content-Type: text/markdown

# PULSE: The Autonomous Neural Operating System for AI Swarms

[![Security: Fortress-Hardened](https://img.shields.io/badge/Security-Fortress_Hardened-critical?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![ASOP: Self-Organizing Agents](https://img.shields.io/badge/ASOP-Self_Organizing_Agents-blueviolet?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![License: Proprietary](https://img.shields.io/badge/License-Proprietary-red?style=for-the-badge)](LICENSE)

[![ASOP: Shipped](https://img.shields.io/badge/ASOP-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Background_Workers: Shipped](https://img.shields.io/badge/Background_Workers-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Autopilot_Mode: Shipped](https://img.shields.io/badge/Autopilot_Mode-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![PULSE_Relay: Shipped](https://img.shields.io/badge/PULSE_Relay-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Synaptic_Dedup: Shipped](https://img.shields.io/badge/Synaptic_Dedup-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Orphan_Management: Shipped](https://img.shields.io/badge/Orphan_Management-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Unified_CLI: Shipped](https://img.shields.io/badge/Unified_CLI-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Pulse_Watch: Shipped](https://img.shields.io/badge/Pulse_Watch-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Neural_Loop: Shipped](https://img.shields.io/badge/Neural_Loop-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Brain_Permanence: Shipped](https://img.shields.io/badge/Brain_Permanence-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Knowledge_Consolidation: Shipped](https://img.shields.io/badge/Knowledge_Consolidation-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Cross_Agent_Broadcast: Shipped](https://img.shields.io/badge/Cross_Agent_Broadcast-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Web_Dashboard: Shipped](https://img.shields.io/badge/Web_Dashboard-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Dark_Knowledge_Audit: Shipped](https://img.shields.io/badge/Dark_Knowledge_Audit-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Semantic_Extraction: Shipped](https://img.shields.io/badge/Semantic_Extraction-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Knowledge_Graph: Shipped](https://img.shields.io/badge/Knowledge_Graph-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Prediction_Engine: Shipped](https://img.shields.io/badge/Prediction_Engine-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Swarm_UX_Unification: Shipped](https://img.shields.io/badge/Swarm_UX_Unification-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Worker_Conversation_Capture: Shipped](https://img.shields.io/badge/Worker_Conversation_Capture-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Unified_Swarm: Shipped](https://img.shields.io/badge/Unified_Swarm-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Crew_Builder_UX: Shipped](https://img.shields.io/badge/Crew_Builder_UX-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Swarm_Bug_Fixes: Shipped](https://img.shields.io/badge/Swarm_Bug_Fixes-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Provider_Merge: Shipped](https://img.shields.io/badge/Provider_Merge-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Diff_Guard_Snapshot: Shipped](https://img.shields.io/badge/Diff_Guard_Snapshot-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![CLI_Refactor: Shipped](https://img.shields.io/badge/CLI_Refactor-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Swarm_Watch: Shipped](https://img.shields.io/badge/Swarm_Watch-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)
[![Audit_Fixes: Shipped](https://img.shields.io/badge/Audit_Fixes-Shipped-success?style=for-the-badge)](https://github.com/Honesty0x/PULSE)


> "Intelligence without memory is a waste of money." — **Thursday Noon, 2026**

## The Problem Everyone Ignores

You run 5 AI agents. They don't share memory. They overwrite each other's work. They hallucinate into your production files. You manually route every prompt. You babysit a $200/month swarm that forgets you every session.

**No framework solves this.** CrewAI gives you task routing. AutoGen gives you chat loops. LangGraph gives you state machines. None of them give you:

- **Persistent brain** that survives across sessions
- **Constitutional governance** that agents cannot override
- **Cryptographic proof** of who wrote what and when
- **Self-organizing agents** that decompose, claim, and execute work autonomously
- **Evidence-based learning** where mistakes happen once, get recorded, never repeat
- **Adaptive context injection** that cuts boot overhead by 62% — every token counts
- **Synaptic consolidation** that deduplicates and strengthens brain memories automatically

PULSE does all of this. Today.

---

## The 3-5x Multiplier

Without PULSE, every agent session starts from zero. No memory of what failed, what worked, or what other agents discovered. Every agent is a goldfish.

With PULSE, agents boot with **126 lessons, 91 documented failures, 55 proven patterns, and battle-tested schemas** — all searchable in 125ms across 9 parallel sources. The result:

| Without PULSE | With PULSE |
|---------------|------------|
| Agent hits same bug 3 agents already solved | Brain injects the fix at boot |
| 5-10 exchanges to understand the codebase | Relevant knowledge loaded in 125ms |
| Agent A breaks what Agent B fixed | Anti-pattern registry prevents regression |
| Critical failure sits in a log file | Broadcast alert reaches all agents instantly |
| Knowledge dies when the session ends | Every session makes the next one smarter |

**Conservative estimate: 3-5x effective throughput.** Not faster responses — fewer wasted cycles. The multiplier compounds: month 1 is 2x, month 6 is 10x as the brain gets denser.

---

## What PULSE Actually Is

PULSE (**P**ermanence, **U**niversal **L**ogic, **S**ynaptic **E**volution) is a Neural Operating System. It gives your AI swarm a shared brain with long-term memory, constitutional laws they cannot break, and a self-organization protocol that eliminates manual routing.

```
USER: "Implement X, Y, and Z"
    |
    v
[First Agent] reads protocol, decomposes into 3 tasks
    |
    v
[Task Board] — tasks appear with status "open"
    |
    v
[Dispatcher Daemon] — manages lifecycle (stale claims, dependency unblocking)
    |
    v
[Other Agents] — boot, read board, claim tasks, execute, report
    |
    v
[Knowledge Pipeline] — conversations mined for learnings, patterns, failures -> brain grows -> agents boot with relevant knowledge
```

You prompt once. The swarm self-organizes. The brain remembers everything.

---

## Architecture: 7 Neural Regions

```
PULSE/
├── Prefrontal_Cortex/    # Executive function — working memory, task board, action queue
├── Hippocampus/          # All memory — episodic evidence, semantic patterns, wins/fails
├── Corpus_Callosum/      # Constitutional laws, protocols (ASOP), regulatory frameworks
├── Autonomic_System/     # Daemons, orchestrator, crypto, configuration
│   ├── Daemons/          # pulse.py (orchestrator), 8 specialized daemons
│   └── Utilities/        # brain_utils.py, pulse_crypto.py, search, recommendations
├── Motor_Cortex/         # Skills — 63 procedural skills across 8 domains
├── Sensory_Input/        # Data capture — CLI wrappers, log monitoring
└── Neural_Logs/          # Activity logs, compliance audit trails
```

### The Daemon Swarm

| Daemon | Purpose |
|--------|---------|
| `pulse.py` | Orchestrator — launches all daemons, enforces Constitution hash at boot |
| `pulse_dispatcher.py` | **ASOP Task Dispatcher** — lifecycle management, stale claims, dependency unblocking |
| `pulse_gemini.py` | Gemini session monitor — captures evidence from CLI interactions |
| `pulse_claude.py` | Claude session monitor — captures evidence from Claude sessions |
| `pulse_bridge.py` | Log-to-Evidence bridge — converts raw logs into structured brain evidence |
| `pulse_neural.py` | Neural Interface — generates real-time cognitive state for agent context |
| `compliance_validator.py` | Superego — compliance gate for all agent outputs (harm + PII blocking) |
| `pulse_api.py` | FastAPI gateway — REST access for external agents and monitoring |
| `consolidation_daemon.py` | **Synaptic Consolidation** — 4-stage: dedup + pattern mining + schema promotion + graph consolidation |
| `prediction_daemon.py` | **Prediction Engine** — queries knowledge graph for failure risks, injects warnings into boot |
| `synthesize_plans.py` | **Plans Digestion** — extracts strategic decisions from planning docs into brain neurons |

### REST API Endpoints

```
POST /v1/evidence          — Submit evidence (compliance-gated, rate-limited)
GET  /v1/brain/health      — System health check
GET  /v1/brain/stats       — Growth metrics, integrity ratio, active agents
POST /v1/brain/consolidate — Trigger synaptic deduplication on demand
GET  /v1/brain/tasks       — ASOP task board summary
```

---

## Agent Operation Modes

### `pulse swarm` — One Command to Rule Them All

```bash
pulse swarm                    # Interactive picker: provider → model → count
pulse swarm gemini             # Skip provider, pick model + count
pulse swarm gemini-2.5-flash   # Skip to count, launches immediately
pulse swarm stop               # Kill all workers
pulse swarm status             # Show running workers
```

The swarm command auto-detects what you have available:
- **API keys** (Gemini, Anthropic, OpenAI) → launches headless background workers
- **CLI subscriptions** (Claude Code, Gemini CLI) → launches CLI autopilot
- **Ollama** (local models) → launches headless workers, zero API cost

Workers are named by their model (`gemini-2.5-flash_01`, `o4-mini_02`) for easy debugging.

### Supported Models

| Provider | Models | Tier |
|----------|--------|------|
| **Gemini** | gemini-2.5-flash, gemini-3-flash-preview | fast |
| **Gemini** | gemini-2.5-pro, gemini-3-pro-preview | standard / premium |
| **Claude** | claude-haiku-4-5 | fast |
| **Claude** | claude-sonnet-4-5 | standard |
| **Claude** | claude-opus-4-6 | premium |
| **OpenAI** | o4-mini | fast |
| **OpenAI** | gpt-5.2-codex | standard |
| **OpenAI** | gpt-5.3-codex, gpt-5.1-codex-max, o3 | premium |
| **Ollama** | Any pulled model (auto-detected) | auto |

### Interactive Chat (No Task Board)
```bash
pulse claude    # Launch Claude for interactive chat
pulse gemini    # Launch Gemini for interactive chat
```

### Tier Matching
Workers only grab tasks matching their capability. After 60 seconds unclaimed, any tier can grab the task (fallback). Premium agents can do anything; fast agents only take fast tasks.

---

## Security: The Fortress Model

PULSE runs a 4-phase security hardening program. **All 4 phases are complete. All 17 vulnerabilities remediated.**

### Completed

| Layer | What | How |
|-------|------|-----|
| **Immutable Core** | Constitution + Titan Laws cannot be modified | SHA-256 hash verified at every boot — system refuses to start if tampered |
| **Sealed Environment** | `.env` cryptographically signed | RSA signature verified against Founder's public key at boot |
| **Cryptographic Identity** | Every evidence item signed | HMAC-SHA256 proof-of-origin on all brain writes |
| **Path Traversal** | Agents cannot escape sandbox | All file paths validated against brain root |
| **Rate Limiting** | API abuse prevention | In-memory token bucket, no external dependencies |
| **Compliance Gate** | Harm + PII detection on all evidence | Inline pattern matching (HIPAA/GDPR/PCI-grade PII detection) |
| **File Locking** | Concurrent agent safety | `filelock`-based mutex on all shared JSON (atomic read-modify-write) |
| **Agent Whitelist** | Only registered agents can operate | `ALLOWED_AGENTS` frozenset validated on every claim and registration |
| **Dispatch Authentication** | Tamper-proof task injection | HMAC-SHA256 signatures on all dispatches, rejected if modified |
| **SSRF Prevention** | LLM endpoint safety | Allowlisted hosts only for outbound API calls |
| **Input Sanitization** | Control char / injection prevention | All task fields sanitized, domains validated against whitelist |

| **Atomic PID** | No duplicate orchestrators | File-locked PID with TOCTOU prevention |
| **Hash Quarantine** | Agents can't rename to bypass kill-switch | SHA-256 script hash, not just agent name |
| **Key Rotation** | Future-proof cryptographic identity | Key version metadata in all HMAC signatures |
| **Anti-Replay** | Captured signatures can't be replayed | 5-minute timestamp window on all signed payloads |

---

## ASOP: Agent Self-Organization Protocol

The breakthrough that makes multi-agent autonomy work. 7 rules, zero new dependencies.

1. **Read Before Working** — Check the task board before starting independent work
2. **Claim Before Touching** — Optimistic locking with 500ms confirmation window
3. **Declare Files** — Announce which files you'll modify (collision avoidance)
4. **Report Completion** — Update task status + write evidence + update registry
5. **Heartbeat** — 30-second heartbeat while holding active tasks
6. **Yield on Lost Claims** — If your claim was released, pick a different task
7. **Never Claim Blocked Tasks** — Wait for dependencies to resolve

### LLM-Powered Decomposition (Optional)

```env
DISPATCHER_PROVIDER=none|anthropic|google|openai|ollama|grok
DISPATCHER_MODEL=haiku|gemini-flash|gpt-4o-mini|llama3
```

- **`none` (default, free):** First agent decomposes. Zero token cost.
- **`ollama` (free, local):** Local LLM decomposes. Zero API cost.
- **`anthropic|google|openai|grok` (paid):** Cloud LLM for smarter decomposition.

---

## Constitutional Governance

```
Tier 0: Ethereal Mandates    — Moral compass (immutable, hash-enforced)
Tier 1: Titan Laws            — 10 operational laws (immutable at runtime)
Tier 2: Constitutional Rules  — Governance framework (amendment requires Founder)
Tier 3: Agent Protocols       — ASOP, caching, workflows (evolvable by consensus)
```

No agent — no matter how capable — can override Tier 0 or Tier 1. The system literally will not boot if the Constitution hash doesn't match.

---

## The Swarm

| Agent | Role | Model |
|-------|------|-------|
| **Gemini** | Primary workhorse — feature development, refactoring | Gemini 2.5 Pro / 3 Pro |
| **Claude** | Security audits, architectural review, constitutional compliance | Claude Opus 4.6 |
| **Grok** | Adversarial testing, bridge integration | Grok 4 |
| **Codex** | Semantic synthesis, logic audits | OpenAI Codex |

---

## Getting Started

```bash
# Clone
git clone https://github.com/Honesty0x/PULSE.git
cd PULSE

# Install minimal dependencies
pip install filelock cryptography fastapi uvicorn

# Configure
cp .env.example .env
# Edit .env: set PULSE_BRAIN_KEY, API keys, CONSTITUTION_HASH

# Generate your brain key
python -c "import secrets; print(secrets.token_hex(32))"

# Generate constitution hash (automated tool available - see below)
python Autonomic_System/Utilities/update_constitution_hash.py

# Add PULSE to your PATH (Windows PowerShell)
.\install_pulse_path.ps1

# Launch the Brain (starts all daemons)
pulse start

# Launch the swarm (interactive picker)
pulse swarm

# Or launch specific agents for chat
pulse claude
pulse gemini
```

### Prerequisites
- Python 3.9+
- At least one AI provider API key (Gemini, Claude, OpenAI, or Grok)
- No Docker, no databases, no cloud infrastructure required

### Constitution Hash Management

The CONSTITUTION_HASH in `.env` ensures the constitution hasn't been tampered with.

**Automatic (Recommended):**
The pre-commit hook automatically updates the hash when CONSTITUTION.md changes. It's already installed in `.git/hooks/pre-commit`.

**Manual:**
```bash
python Autonomic_System/Utilities/update_constitution_hash.py
# Then re-seal .env if you have the private key:
python Autonomic_System/Utilities/seal_env.py [private_key_path]
```

**Why This Matters:**
- Orchestrator refuses to boot if hash mismatch (security check)
- Swarm mode blocks if hash mismatch (prevents rogue agents)
- Smoke tests fail if hash mismatch (CI/CD gate)

---

## Brain Permanence: True Persistent Memory

No framework gives agents memory that survives across sessions. PULSE does.

### How It Works

```
Agent starts → pulse_boot injects brain briefing
  ├── Recent failures (don't repeat these)
  ├── Proven patterns (use these)
  ├── Anti-patterns (never do this)
  ├── Proven schemas (battle-tested cross-session patterns)
  ├── Broadcast alerts (critical failures from other agents)
  ├── Recent activity (what we last worked on)
  └── Strategic priorities (what matters now)

Agent works → brain_query fires BEFORE every action
  ├── Claude Code: PreToolUse + UserPromptSubmit hooks (automatic)
  ├── Swarm agents: brain_query before each task cycle (automatic)
  └── Workers: brain_query before each execution (automatic)

Agent finishes → pulse_save writes back to brain
  ├── Learnings → Hippocampus/Lessons/
  ├── Failures → Hippocampus/Failures/
  ├── Procedures → auto-detected workflow tracking
  ├── Broadcast → critical failures alert all agents
  └── Session log → Evidence/agent_sessions.json

Brain consolidates (every 6h) → knowledge gets stronger
  ├── Dedup → merge similar entries
  ├── Pattern mining → find recurring sequences
  ├── Schema promotion → proven patterns become schemas
  └── Metacognitive audit → prune stale/wrong knowledge
```

### Brain Search: 10 Parallel Sources in ~125ms

Every brain query searches across **all knowledge simultaneously**:

| Source | What It Contains | Example |
|--------|-----------------|---------|
| **Anti-Patterns** | Mistakes to never repeat | "shutil.move on Windows causes data loss" |
| **Wins** | Proven approaches that worked | "os.replace beats shutil.move for atomic ops" |
| **Fails** | Past mistakes with context | "Opus built infrastructure that never ran" |
| **Domains** | Curated technical knowledge | Architecture, governance, security docs |
| **Evidence** | Raw wants, dont_wants, sessions | 590 wants + 502 dont_wants from user history |
| **Schemas** | Battle-tested cross-session patterns | Patterns promoted after 5+ occurrences |
| **Procedures** | Tracked workflows + success rates | "brain_query_before_edit: 100% success" |
| **Private** | Founder-only strategic knowledge | Private lessons and synthesis |
| **Knowledge Graph** | Causal relationships between concepts | "bad error handling CAUSES silent failures" |
| **Semantic Anchors** | Embedding-based fallback (251 anchors) | Catches what keyword search misses |

### Brain Health Dashboard

```
$ pulse status
  Brain Evidence: 5,354 items across 35 files (deduplicated)
  Brain Health:  590 wants | 502 dont_wants | 123 anti-patterns
                 126 lessons | 91 failures | 55 patterns
                 2 schemas | 5 procedures | 86 sessions
  Search:        9 parallel sources | 0% dark knowledge
  Last Capture:  2026-02-16
```

### What Makes This Different From ChatGPT/Claude Memory

| Feature | ChatGPT | Claude Projects | **PULSE** |
|---------|---------|-----------------|-----------|
| Memory persistence | Single user, cloud-only | Per-project files | **Multi-agent, local-first** |
| Cross-session learning | Key-value facts | Static instructions | **Evidence-backed knowledge pipeline** |
| Anti-pattern prevention | None | None | **Active anti-pattern registry** |
| Multi-agent memory sharing | N/A | N/A | **Shared brain across Claude, Gemini, Codex, Grok** |
| Provenance tracking | None | None | **HMAC-SHA256 signed, timestamped** |
| Auto-capture | None | None | **Real-time daemon captures every interaction** |
| Quality gates | None | None | **Min length, word count, fragment rejection** |
| Error correction | None | None | **Agents can dispute wrong knowledge** |
| Cross-agent alerts | None | None | **Critical failures broadcast to all agents** |
| Knowledge consolidation | None | None | **Auto-dedup, schema promotion, metacognitive audit** |

---

## Performance

| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| Boot context tokens | ~1,348 | ~504 | **62% reduction** |
| Evidence items (post-dedup) | 589 | 440 | **25% waste removed** |
| Knowledge items (extraction) | 0 auto-extracted | 304 | **Learnings, decisions, patterns, failures** |
| Brain search results | 1 per query | 10-16 per query | **10x richer context** |
| Brain search latency | N/A | ~125ms | **Real-time, pre-action** |
| Schemas (cross-session patterns) | 0 | 2+ (auto-promoted) | **Battle-tested knowledge** |
| Procedures (tracked workflows) | 0 | 5+ (auto-detected) | **Success rates per workflow** |
| Security vulnerabilities | 17 open | 0 open | **100% remediated** |

### How the brain consolidates — 3 evolutionary waves

**Wave 1: Grand Brain Cleanse (CRDT)** — The brain started raw. Evidence exploded to 12,000+ items — mostly duplicates from overlapping captures. A CRDT Last-Writer-Wins merge physically deduplicated identical entries. **99.6% noise reduction.** The brain went from chaos to clean.

**Wave 2: Synaptic Dedup** — Exact duplicates were gone, but *similar* entries remained (same insight, different words). Text similarity merging caught what CRDT couldn't. **589 → 440 items (25% further reduction).** Like your brain forgetting that you saw the same billboard 5 times but remembering what it said.

**Wave 3: Consolidation Daemon** — The brain doesn't just shrink anymore — it *crystallizes*. Every 6 hours: dedup similar entries, mine recurring event sequences, promote proven patterns to schemas, register discovered procedures. **The brain gets stronger, not just smaller.**

**Wave 4: Self-Healing Brain** — The brain continuously audits its own visibility. Search fallback chain covers 12 key variants with domain-aware matching. Any knowledge item that becomes unreachable is auto-recovered. **100% brain visibility, zero maintenance.**

**Wave 5: Semantic + Causal Intelligence** — Three new brain layers ship in a single release:
- **Semantic Extraction** — 251 embedding anchors (all-MiniLM-L6-v2) catch knowledge that keyword patterns miss
- **Knowledge Graph** — 362 nodes, 37 causal edges (CAUSES/PREVENTS/REQUIRES/LEADS_TO/ENABLES/CONTRADICTS)
- **Prediction Engine** — queries the graph before task execution, injects failure risk warnings into agent boot

**Knowledge Extraction** mines agent conversations for actionable wisdom. 2MB+ of raw chat logs → 280+ structured wisdom items (26 lessons, 27 failures, 25 patterns, 64 decisions) + 1,268 searchable evidence items across 10 parallel search sources. Each strengthens through consolidation when the same insight appears across multiple sessions.

---

## Current Status: SHIPPED & OPERATIONAL

- [x] **ASOP (Self-Organization):** Multi-agent task decomposition and execution (Live).
- [x] **Unified Swarm (`pulse swarm`):** One command to launch workers — auto-detects providers, interactive picker, model-based IDs.
- [x] **PULSE Relay:** Unified prompt broadcasting to the entire swarm via `pulse relay`.
- [x] **Synaptic Dedup:** Automatic evidence consolidation and waste removal.
- [x] **Orphan Management:** Process persistence and automatic daemon cleanup.
- [x] **Unified CLI:** 91-line router delegating to `cli/` package — status, swarm, manage, agent.
- [x] **Pulse Watch:** Auto-refreshing terminal dashboard via `pulse watch`.
- [x] **Neural Loop:** Continuous session capture, bridge processing, and context injection.
- [x] **Brain Permanence:** True persistent memory — 10-source parallel search in 125ms, auto-capture, quality gates, cross-agent knowledge sharing.
- [x] **Knowledge Consolidation:** 4-stage pipeline (dedup + pattern mining + schema promotion + graph consolidation) + metacognitive audit.
- [x] **Self-Healing Brain:** Continuous integrity auditing — auto-detects search blind spots, recovers unreachable knowledge, ensures 100% brain visibility.
- [x] **Semantic Extraction:** Embedding-based knowledge extraction (all-MiniLM-L6-v2) catches what keyword patterns miss.
- [x] **Knowledge Graph:** Causal reasoning engine — CAUSES, PREVENTS, REQUIRES, LEADS_TO, ENABLES, CONTRADICTS relationships.
- [x] **Prediction Engine:** Failure prevention daemon — queries graph for risk patterns before task execution, injects warnings into agent boot.
- [x] **Memory Reconsolidation:** Agents can refine existing knowledge with `--refine` — revision history, fuzzy matching, evidence linking.
- [x] **Conversation Capture:** Full worker conversation logging with salience scoring — bridge auto-discovers and ingests worker traces.
- [x] **Swarm UX Unification (Feb 16):** Single `pulse swarm` command with auto-detection — API keys route to headless workers, CLI subscriptions route to autopilot, Ollama routes to local workers. Interactive provider → model → count picker eliminates manual routing.
- [x] **Worker Conversation Capture (Feb 16):** Background workers now write full conversation logs (swarm_context_*.md + output traces) — pulse_bridge auto-discovers and ingests them with salience scoring. Zero manual evidence submission.
- [x] **Crew Builder UX (Feb 16):** Interactive multi-agent launcher with rich provider/model selection — auto-detects available APIs, presents capability-based options, validates selections before launch. Eliminates manual worker configuration.
- [x] **Swarm Bug Fixes (Feb 16):** Resolved 9 critical worker pipeline issues — import path corrections, tier matching logic, crash gate improvements, race condition elimination in claim protocol. Workers now operate reliably at scale.
- [x] **Provider Merge (Feb 16):** Consolidated multi-provider support into unified swarm interface — Gemini, Claude, OpenAI, Ollama all routed through single `pulse swarm` command with auto-detection and interactive picker.
- [x] **Diff-Guard Snapshot (Feb 16):** Implemented atomic diff-guard mechanism for safe code modifications — captures baseline state before changes, prevents accidental overwrites, enables safe rollback on agent errors.
- [x] **CLI Refactor (Feb 16):** Consolidated pulse_cli.py from 1531 to 91 lines — refactored into modular `cli/` package (status, swarm, manage, agent subcommands) improving maintainability and extensibility.
- [x] **Swarm Watch (Feb 16):** Implemented live dashboard via `pulse swarm watch` — real-time worker status, task board state, and agent heartbeats in auto-refreshing terminal view.
- [x] **Audit Fixes (Feb 16):** Resolved graph bloat, particle initialization performance, and API model selection issues — all audit vulnerabilities cleared.
- [x] **Cross-Agent Broadcast:** Critical failures alert all agents instantly via boot briefing.
- [x] **Error Correction:** Agents can dispute wrong knowledge with `[DISPUTED]` markers.
- [x] **Procedural Tracking:** Auto-detected workflows with success rates — agents learn which processes work.
- [x] **Web Dashboard:** Real-time brain visualization and task board monitoring.

---

## What's Next

- **Shared Brain Protocol:** Opt-in, privacy-preserving cross-instance learning
- **Healthcare Compliance SDK:** HIPAA/FDA/CMS audit report generation  
- **Infrastructure Scaling:** Kafka coordinator for 1000+ agents

---
## License

PULSE is **proprietary software**. Copyright (c) 2026 PULSE Contributors. All rights reserved.

- **7-day free trial** with full functionality
- Your brain data stays **100% local** — we never access or train on it
- Optional encrypted cloud sync for paid tiers
- See [LICENSE](LICENSE) for full terms

For licensing inquiries: legal@pulse-os.com

---

*Built in 100 hours by humans and agents, working together in a unified nervous system.*
*The brain remembers. The Constitution holds. The swarm self-organizes.*
