Harlo

Patent Pending | Apache 2.0 | Patent Details

---

Make smarter decisions with a coach who knows how you're really doing. Harlo reads your Apple Watch — sleep, heart, stress — learns your patterns, and eases off when you're running low. It watches for your crashes, backs off during flow, and helps you stop before you burn out.

Private by design. All your data lives on your device as local, composable state — no cloud, no data mining, no rented access to your own mind.

---

Status

PRODUCTION LIVE — Harlo v6.1-MOTOR
1,381 passing · 5 skipped (lean bundle) · Real OpenUSD canonical persistence · USD-Lite runtime tier
8/8 phase gates passed · Substrate-unified with sister project Moneta · P1 CIP defensible
1,390+ organic observations collected · Path C closed (Step 3)
Phase 5A landed: macOS bundle · intake calibration · biometric barrier · Motor Cortex with Basal Ganglia gating
v0.1.2: USD-proof trial — §F1 native composition · §F2 structural lossless · anchor immunity · P5 customData · P1 decision-tier — CONFIRMED on live pxr stage (verifier-first, 4 cycles)
v0.1.6: HarloPulse loop LIVE — Apple Watch → HealthKit → push-on-arrival → launchd socket → biometric barrier → coach
        first organic biometrics through the barrier · Siri/Shortcuts/Spotlight surface · Xcode 27 / iOS 27 SDK
Phase 5B built: Mac-local sibling — Apple Watch → HealthBridge (sandboxed) → XPC relay → daemon biometric loop (relay→daemon proven; full live Watch test pending)
v0.2.0: unified release — biometric_prior seed + HarloPulse (iPhone) + HealthBridge/XPC (macOS) reconciled; one version across every surface (core · Rust · macOS app · iOS app · bridge)

| Sprint | Tests | What Shipped | |--------|-------|-------------| | S1 State Machine | 84 | Pydantic schemas, MockCogExec DAG (networkx), 7 pure computation functions, 26-invariant validator, 10K synthetic trajectories via Profile-Driven Markov Biasing, XGBoost predictor (100% per-field accuracy), Bridge integration | | S2 OpenExec | -- | USD 26.03 built from source with PXR_BUILD_EXEC=ON. C++ Exec libraries compile. Circuit-breaker triggered: zero Python bindings in v26.03 source. MockCogExec continues to serve. | | S3 Hydra Delegates | 85 | HdCognitiveDelegate ABC, DelegateRegistry (capability matching), HdClaude + HdClaudeCode, computerouting (requirements not names), OOB consent tokens (HMAC-signed, TTL), sublayer-per-delegate concurrency, CognitiveEngine singleton, 20-exchange e2e | | S4 Real USD | 59 | CognitiveStage wrapping pxr.Usd.Stage, stagefactory toggle, .usda files on disk with time-sampled CognitiveObservation, delegate sublayer .usda files, backend parity verified (mock = real USD) | | S5 Production | 22 | Graceful degradation (independent failure isolation), health check endpoint, kill switches (ENGINE_ENABLED, USE_REAL_USD, OBSERVATION_LOGGING, PREDICTION_ENABLED), first session verified, production docs | | Path C Step 3 v3.4.0 | +39 | Real OpenUSD as canonical persistence (codeless schema, 21 prim types under harlo plugin separate from Moneta); USD-Lite engine preserved as fast in-memory runtime tier (Fabric pattern); sync layer per D4 policy table; migration script for USD-Lite v1 → real USD; substrate-unified with sister project Moneta. P1 CIP framing now defensible. | | Phase 5A macOS + Operator | +51 | macOS app bundle (Harlo.app + launchd socket activation), intake calibration CLI emitting three INTAKE_CALIBRATED Merkle layers, biometric barrier per ADR-0001 (opt-in HealthKit signals, freshness window, never enter trace pipeline), Motor Cortex with Basal Ganglia inhibition-default gating, harlo doctor --strict operator readiness, signing-readiness pre-flight (27 checks) | | USD Trial v0.1.2 | +verifier | SOLO trial-harness loop (docs/trial-harness.md + docs/usd-proof-trial.md); 4 engine cycles verifier-first against wave1_harness.py; native USD-composition theses CONFIRMED on the live pxr-backed stage: §F1 LOCAL > VARIANT > SPECIALIZE resolution, §F2 reconstruct_clean bit-identical, anchor structural immunity (adversarial probe), P5 customData state tracking; new MCP tools — compose_demo, lossless_demo, anchor_demo, p5_state_demo, persist_stage, decision. P1 closed via Path C Actor-driven motor surface. | | Pulse Loop v0.1.6 | +13 | HarloPulse iPhone sidecar deployed to hardware (Xcode 27 / iOS 27 SDK): 6-word HMAC pairing, per-type opt-in HealthKit reads (ADR-0001/D65), HKObserverQuery + background delivery for push-on-arrival, 48h lookback + chunked frames; Mac side pulse listen adopts a launchd-held TCP socket (Rule 1 — 0W between Watch syncs); App Intents surface (sync, status snippet, type toggles with clarification, OpenIntent, onscreen awareness); field-debugged end-to-end — first organic Apple Watch biometrics through the barrier into the coach. Four WWDC26 frontier docs: App Intents adoption plan, Foundation Models provider review (+ live-verified Python SDK addendum), code-along addendum, HealthKit collaboration report. | | Phase 5B macOS HealthBridge | -- | Mac-local sibling to the HarloPulse iPhone loop — same biometric_barrier, different transport. Sandboxed HarloHealthBridge.app (HealthKit observers, signed under the Apple Developer Program) + HarloXPCRelay launchd Mach service bridging the sandboxed app to the daemon's UNIX socket — the App Group container can't host it (macOS blocks the non-sandboxed daemon from binding there). DaemonWriter over NSXPC, mach-lookup entitlement; full HR/HRV → biometric_barrier → AllostasisTracker → DEPLETED/RED. Relay→daemon proven (XPC ingest of 180 bpm → force_red: true). |

---

Benchmarks

Measured 2026-06-10 on the reference machine (Mac Studio M1 Ultra, 128 GB, macOS 27). Reproduce the search rows with cargo bench -p hippocampus (criterion, crates/hippocampus/benches/recall.rs).

| Path | Constitutional budget | Measured | Headroom | |------|----------------------|----------|----------| | SDR search, 10k traces (k=5) | — | 0.084 ms median | — | | SDR search, 100k traces (k=5) | VARIANT > SPECIALIZE on /Brain/CompositionDemo. GetPropertyStack` reports the strength order itself. Native composition arcs map to cognitive priority without fighting USD semantics.

• §F2 — structural lossless (Cycle 3). reconstruct_clean() as

flatten-to-base recovers the clean baseline bit-identically from a composed (clean + delta) stage. Same SHA256 from cold-pxr re-read; reconstruction is exact, not float-tolerant.

• §F2 anchor structural immunity (Cycle 4). CONSTITUTIONAL / SAFETY /

CONSENT / KNOWLEDGE anchors invariant across 4 delta profiles. The adversarial profile explicitly authors /Brain/Anchors/CONSTITUTIONAL.value = "MALICIOUS_OVERRIDE"; pxr rejects it by composition mechanics — anchor sublayer at subLayerPaths[0] wins. Structural, not parametric.

• P5 — customData state tracking (Cycle 5). Unchanged / Edited / New

derived per-prim from prim-stack analysis, written to a derived tags sublayer, read back through composition. Three prims, three states — tagged / computed / expected all agree.

• P1 decision-tier closure (Cycle 6). New decision MCP tool — the

Actor-driven motor surface — queues MotorPrims that persist_current_brain drains. Live stage now authors session + entity + decision tiers.

Reproduce: .venv312/bin/python wave1_harness.py. The 7-row scoreboard asserts the live USD flip, populated hierarchy (P1), native composition (P3 / §F1), structural lossless (P4 / §F2), anchor immunity (§F2 follow- up), and customData state tracking (P5).

Path C motor surface (Cycle 6) — Actor → live MotorPrim

sequenceDiagram
    participant User
    participant Tool
    participant Queue
    participant Persist
    participant Brain
    participant Writer
    participant Stage
    User->>Tool: decision action gate_status
    Note right of Tool: Rule 23 defaultBasal Ganglia inhibit-by-default
    Tool->>Queue: queue_motor_action
    Note over Queue: module-level listlives for the MCP subprocess
    User->>Persist: persist_stage
    Persist->>Queue: snapshot_pending_motor_actions
    Persist->>Brain: full_stage with motor_actions
    Brain->>Writer: motor_to_prims
    Writer->>Stage: DefinePrim MotorPrim under Brain Motor
    Note over Stage: live pxr stageBrain Motor populated

Diagram legend:

• User = the actor (Claude in production; the trial harness in tests)
• Tool = decision MCP tool (Actor-driven motor surface)
• Queue = _PENDING_MOTOR_ACTIONS module-level list in persistence/__init__.py
• Persist = persist_current_brain (called by persist_stage MCP tool)
• Brain = brainstem.stage_builder.full_stage(motor_actions=…)
• Writer = python/harlo/usd_lite/persistence/writer.py:_write_motor — stage.DefinePrim("/Brain/Motor/action_i", "MotorPrim")
• Stage = /stages/runtime.usda (the live pxr.Usd.Stage)

The inert motor system (premotor, basal_ganglia, executor) remains disconnected — Path C creates the smallest honest motor surface. Consent escalation, basal-ganglia gating, and executor wiring are parked for future cycles.

---

HarloPulse — The Push-on-Arrival Biometric Loop (v0.1.6)

The iPhone sidecar shipped to hardware. Apple Watch biometrics now reach the Modulation Layer with zero resident processes on either side of the wire:

flowchart LR
    W["Apple WatchHR · HRV · RR · sleep · workouts"]:::runtime --> HK["iPhone HealthKitbackground delivery"]:::runtime
    HK --> APP["HarloPulse appHKObserverQuery wakes it"]:::runtime
    APP --> PUSH["delta pushHMAC auth · 48h window · chunked frames"]:::runtime
    PUSH --> LD["Mac launchdholds TCP 48653 · spawns on SYN"]:::substrate
    LD --> LIS["pulse listenadopts socket · whitelist only"]:::substrate
    LIS --> BB["biometric barrierADR-0001 · freshness window"]:::substrate
    BB --> MOD["modulation layerderived verdict only — D60"]:::substrate
    MOD --> COACH["coach · statusClaude Desktop / Claude Code"]:::substrate

    classDef substrate fill:#d4895e,stroke:#a0623d,color:#000000
    classDef runtime fill:#e6c466,stroke:#a8884a,color:#000000

Properties, all field-verified on real hardware (iPhone → Mac Studio, June 2026):

• Push-on-arrival, not polling — the Watch syncs, HealthKit wakes the app

in the background, the app pushes the delta. No schedule, no daemon on the phone, no polling loop anywhere.

• 0 W on the Mac (Rule 1) — launchd holds port 48653; pulse listen is

spawned by the first SYN, drains the connection, exits. KeepAlive is structurally forbidden by the plist tests.

• 6-word pairing, HMAC-authenticated frames — the raw token never

persists; both sides keep only the derived key (iOS Keychain / 0600 file). Single-command whitelist (biometric_ingest), 1 MiB frame cap, 5-minute auth window.

• Raw samples never touch disk on the Mac (Rule 9) — the barrier consumes

them in memory and stores only the derived modulation verdict (load, depleted, stale).

• Per-type opt-in, default OFF (ADR-0001 / D65) — nine HealthKit types,

each with its own toggle and its own permission sheet.

• Siri surface — "Sync HarloPulse," status snippet, type toggles with

clarification dialogs, OpenIntent, onscreen awareness on iOS 18.2+.

Design history: docs/adr/0002-iphone-sidecar.md · WWDC26 adoption analyses in docs/frontier/.

---

Architecture · Path C (Fabric Pattern)

v3.4.0-path-c introduced codeless OpenUSD schemas as canonical persistence while preserving the existing USD-Lite engine as a fast in-memory runtime tier. Path C — the Fabric pattern — separates the two tiers so each can win at what it's good at: real OpenUSD owns durability and patent claims; USD-Lite owns hot-path latency.

Fabric pattern

flowchart TB
    subgraph PERSISTENCE["PERSISTENCE LAYER · canonical truth"]
        SCHEMA["HarloSchema.usda21 prim types · codeless"]:::substrate
        PLUG["plugInfo.jsonharlo namespace"]:::substrate
        DISK[".usda files on diskvia pxr.Usd.Stage"]:::substrate
    end

    subgraph SYNCLAYER["SYNC LAYER · write-side dispatch"]
        WT["write_throughSessionPrim · GateStatusPrimMerkleRootPrim · MotorPrim"]:::substrate
        CP["checkpointTracePrim · CompositionLayerPrimSkillPrim · intake/multipliers"]:::substrate
    end

    subgraph RUNTIME["RUNTIME LAYER · hot-path reads"]
        ENGINE["USD-Lite engineregex parser · sub-ms reads"]:::runtime
        DC["21 dataclass prim typesPython in-memory"]:::runtime
    end

    MIG["migrate_path_c.pyUSD-Lite v1 → real USDidempotent · CLI"]:::substrate

    PERSISTENCE -->|"sync at boundaries"| SYNCLAYER
    SYNCLAYER --> RUNTIME
    MIG -.->|"upgrade path"| PERSISTENCE

    classDef substrate fill:#d4895e,stroke:#a0623d,color:#000000
    classDef runtime fill:#e6c466,stroke:#a8884a,color:#000000

The persistence layer is the canonical truth. The runtime layer is the fast tier that tests and live sessions exercise. The sync layer routes mutations between them based on a per-prim policy table. Reads always hit the runtime tier; persistence is touched only at sync boundaries (Constitution Law 4).

The [substrate] extra activates the persistence layer:

pip install -e .[substrate]   # Pulls usd-core 26.5; activates persistence/

Core Harlo runs without [substrate] — pxr stays optional per Constitution Law 3.

Schema · IsA hierarchy

The codeless schema in schema/HarloSchema.usda declares 21 prim types in a 3-tier IsA hierarchy parallel to containment (D2):

flowchart TB
    Typed["Typed · USD root"]:::substrate

    HP["HarloPrim · abstract"]:::substrate
    HC["HarloContainer · abstract"]:::substrate

    Typed --> HP
    HP --> HC

    BS["BrainStage"]:::substrate
    AP["AssociationPrim"]:::substrate
    CP["CompositionPrim"]:::substrate
    EP["ElenchusPrim"]:::substrate
    ICP["InquiryContainerPrim"]:::substrate
    MCP["MotorContainerPrim"]:::substrate
    SCP["SkillsContainerPrim"]:::substrate
    CPP["CognitiveProfilePrim"]:::substrate

    HC --> BS
    HC --> AP
    HC --> CP
    HC --> EP
    HC --> ICP
    HC --> MCP
    HC --> SCP
    HC --> CPP

    TP["TracePrim"]:::runtime
    CLP["CompositionLayerPrim"]:::runtime
    GSP["GateStatusPrim"]:::runtime
    MRP["MerkleRootPrim"]:::runtime
    SP["SessionPrim"]:::runtime
    IP["InquiryPrim"]:::runtime
    MP["MotorPrim"]:::runtime
    SkP["SkillPrim"]:::runtime
    MuP["MultipliersPrim"]:::runtime
    IHP["IntakeHistoryPrim"]:::runtime

    HP --> TP
    HP --> CLP
    HP --> GSP
    HP --> MRP
    HP --> SP
    HP --> IP
    HP --> MP
    HP --> SkP
    HP --> MuP
    HP --> IHP

    APIB["APISchemaBase · USD"]:::substrate
    PROV["Provenance · applied API"]:::substrate
    APIB --> PROV
    PROV -.->|"attaches to"| CLP

    classDef substrate fill:#d4895e,stroke:#a0623d,color:#000000
    classDef runtime fill:#e6c466,stroke:#a8884a,color:#000000

• Two abstract bases: HarloPrim (root of every Harlo type) and

HarloContainer (parent of structural composites).

• Eight concrete container types: BrainStage plus seven subsystem

containers (Association, Composition, Elenchus, Inquiry, Motor, Skills, CognitiveProfile).

• Ten concrete leaf types holding the actual cognitive-state

attributes.

• One singleApply API schema (Provenance, per D10) that attaches

origin metadata to host prims without cluttering the IsA tree.

Five enum types use lower-case allowedTokens per Constitution Cmd 11: SourceType, VerificationState, RetrievalPath, MotorGateStatus, ArcType. Cross-plugin: zero collisions with sister project Moneta's MonetaMemory typeName (D3 verified).

Sync layer · per-prim policy

The sync layer at python/harlo/sync/ routes writes per the D4 policy table:

flowchart LR

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [JosephOIbrahim](https://github.com/JosephOIbrahim)
- **Source:** [JosephOIbrahim/Harlo](https://github.com/JosephOIbrahim/Harlo)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.