Stage 0 Research Brief: Spore Intelligence Architecture

Stage 0 Research Brief: Spore Intelligence Architecture

> Integrating Real Infrastructure (EW, KARL, Cortex, Graph Kernel, RAG++, Pulse) as Spore's Backend Brain
> Researched: 2026-03-11 | Agent: Meta-Recursive Explorer (Opus 4.6)

---

1. Spore's Current Architecture (Complete Map)

1.1 Data Model

File: `[home]/Desktop/Spore/Spore/Models/Spore.swift`

The `Spore` model is a SwiftData `@Model` with these fields:

@Model final class Spore {
    var id: UUID
    var text: String                // The raw idea text
    var keywords: [String]          // Extracted/evolved keyword tags
    var strength: Double            // 0-100 growth meter
    var statusRaw: String           // SporeStatus enum raw
    var tendrilIDs: [UUID]          // Bidirectional connections to other spores
    var parentIDs: [UUID]           // Graft parents
    var plantedAt: Date
    var bloomedAt: Date?
    var harvestedAt: Date?
    var lastGrowthAt: Date
    var guidanceCount: Int          // User interactions (watering)
    var harvestNotes: String?
    var lineageData: Data?          // JSON-encoded EvolutionLineage
    var mutationCount: Int          // Denormalized for queries
    var lastMutationAt: Date?
    var evolutionStyleRaw: String?  // EvolutionStyle enum raw
    var keywordCapacity: Int = 12   // Grows every 5 mutations
}

Status lifecycle: `spore -> germinating -> growing -> budding -> blooming -> fruiting`
- Branch: `withering` (neglect, recoverable) and `composted` (terminal)
- Thresholds: 0/10/30/55/80/95

SwiftData schema (from `SporeApp.swift`):

Schema([Spore.self, Garden.self, InteractionEvent.self, GrowthSnapshot.self, LearnedPattern.self])

1.2 Evolution System (On-Device)

File: `[home]/Desktop/Spore/Spore/Services/EvolutionEngine.swift`

The on-device `EvolutionEngine` uses Apple's `NLEmbedding` (word-level English embeddings) to drive 5 mutation strategies:

Mutation probability is computed per growth cycle:
- Base: 15
- Modifiers: season (spring 1.5x, winter 0.4x), tendril count (+3
- Diminishing returns after 10 mutations

Key limitation: The on-device engine only uses Apple's pre-trained word embeddings. No semantic understanding of the idea itself. No cross-idea intelligence. No learning from user behavior patterns across the garden.

1.3 Server-Side Evolution (Current: Dumb Gemini Wrapper)

File: `[home]/Desktop/Spore/supabase/functions/evolve-spore/index.ts`

The current server-side evolution is a Supabase Edge Function that:

1. Receives: `{ spore: { name, keywords, strength, description }, technique: "G01" }`
2. Calls Gemini 2.0 Flash with a TIE technique prompt
3. Returns: `{ mutated_keywords, strength_delta, changelog_entry, new_description, technique_used }`

12 TIE techniques are defined (6 generative, 6 reductive):
- Generative: G01 Random Word Catalyst, G04 SCAMPER, G07 Oblique Strategy, G10 Biomimicry, G15 Contradiction Embrace, G18 Time Shift
- Reductive: R01 Essence Distillation, R04 Constraint Injection, R07 Compression, R10 Perspective Flip, R14 Analogy Bridge, R18 Edge Case Explorer

Friction points:
- Zero feedback loop. The technique choice is random or user-selected. No learning from which techniques worked best for which types of ideas.
- No context from the rest of the garden. Each spore is evolved in isolation.
- No semantic search. The engine can't find related ideas across the user's history.
- No trajectory intelligence. No record of what mutations led to successful blooms.
- Hardcoded API key in the edge function (needs env var migration).

1.4 Background Task Architecture

File: `[home]/Desktop/Spore/Spore/App/SporeApp.swift` (lines 146-366)

Two `BGProcessingTask` identifiers:
- `garden.spore.growth` — runs at 4 AM, applies on-device growth algorithm
- `garden.spore.evolution` — tier-gated (Free: skip, Sprout: weekly, Garden: daily), calls server-side `evolve-spore`

Tier model (StoreKit 2):
- Free: on-device evolution only
- Sprout: server evolution weekly, 2 spores per cycle
- Garden: server evolution daily, 5 spores per cycle

1.5 Memory and Learning System

File: `[home]/Desktop/Spore/Spore/Services/GardenMemoryService.swift`

`GardenMemoryService` already implements on-device behavioral learning:
- Records `InteractionEvent` (plant, water, harvest, season change, etc.)
- Takes `GrowthSnapshot` per growth cycle (strength, status, keyword count)
- Runs 6 learning algorithms: planting rhythm, care frequency, topic affinity, bloom success factors, season preference, neglect risk
- Persists `LearnedPattern` to SwiftData

This is the hook point. The existing memory service provides the behavioral signal data that Cortex can consume and that KARL can use for trajectory evaluation.

1.6 EvolutionStyle (TIE Technique Picker)

File: `[home]/Desktop/Spore/Spore/Models/EvolutionStyle.swift`

12 `EvolutionStyle` enum cases (G01-G18, R01-R18) with:
- `displayName`, `subtitle`, `icon`, `family` (generative/reductive)
- `strengthMultiplier` (1.1x to 1.6x)

Users can assign an evolution style to a spore. The style is passed to the server as the `technique` parameter.

---

2. Evolution World — The Adaptive Engine

2.1 Architecture

File: `[home]/projects/evolution_world/engine.py`

Evolution World is a 3-layer recursive evolution engine:

L3 (Meta-Meta-Evolution): Evolves L2's own constants every 30 L1 steps
L2 (Meta-Evolution): The evolution process itself adapts based on L1 outcomes
L1 (App Evolution): Genomes mutate toward milestones via TIE techniques

Key class: `EvolutionWorld`
- `register_app(genome: AppGenome)` — register an app for evolution
- `evolve_step(app_name)` — one full evolution cycle
- `evolve_all(max_steps)` — evolve all active apps with rotation
- `get_world_status()` — current state of all genomes

2.2 The 4+1 Non-Halting Invariants

File: `[home]/projects/evolution_world/invariants.py`

Config defaults: `epsilon=0.01`, `max_divergence=2.0`, `l1_stall_threshold=3`, `l2_stall_threshold=5`

2.3 Data Model: AppGenome

The `AppGenome` dataclass has:
- `app_name`, `id`, `project_path`
- `fitness` (0.0-1.0), `generation`, `status`
- `milestones` (list of Milestone with progress tracking)
- `mutation_operators` (list of MutationOperator with weights)
- `capabilities` (dict of features), `technique_weights`

2.4 Persistence (Supabase)

File: `[home]/projects/evolution_world/state.py`

Supabase tables used:
- `ew_app_genomes` — app genome state
- `ew_l1_steps` — L1 evolution step records
- `ew_l2_steps` — L2 meta-evolution steps
- `ew_invariant_checks` — invariant check results
- `ew_forcing_events` — cross-layer forcing events
- `ew_pulse_sessions` — Pulse autonomous dev sessions
- `ew_feedback_snapshots` — feedback channel snapshots
- `ew_l3_state` — L3 meta-meta state (singleton)
- `ew_config` — active EW config

2.5 Feedback Metabolism

File: `[home]/projects/evolution_world/feedback.py`

5-channel real fitness with temporal decay:
1. Build health (0.25) — xcodebuild pass rate
2. Crash rate (0.20) — TestFlight/App Store
3. Engagement (0.25) — EventTracker signals
4. Store presence (0.15) — App Store review/ratings
5. Design health (0.15) — DHS anti-gravity scores

`FeedbackState.compute_grounded_fitness()` returns a single weighted score. `compute_metabolism()` drives heartbeat interval (high metabolism = faster cycles, 30s-600s range).

2.6 Integration Surface for Spore

What would need to change:
- Register Spore as an AppGenome with custom milestones (bloom rate, mutation diversity, user engagement)
- Create a Spore-specific `FeedbackCollector` that pulls engagement signals from the app
- Map TIE techniques (G01-R18) to EW mutation operators
- Create a new Supabase Edge Function (`evolve-spore-v2`) that calls the EW engine instead of raw Gemini
- Use invariants to prevent stale evolution: if a spore's mutations aren't producing novelty, switch technique automatically

---

3. KARL — Trajectory Intelligence

3.1 Core Architecture

Files: `[home]/.claude/karl/` (21 Python files)

KARL records and scores agent tool-use trajectories to learn which approaches work best.

4 Tap Points (from `trajectory_tap.py`):
- Tap A: Init session buffer on skill injection (SessionStart)
- Tap B: Append tool event after each tool use (PostToolUse)
- Tap C: Flush buffer to `trajectories.jsonl` (SessionEnd/Stop)
- Tap D: Annotate previous record with cross-turn signals (next UserPromptSubmit)

3.2 Reward Engine (5-Signal)

File: `[home]/.claude/karl/reward_engine.py`

Composite reward = weighted blend of 5 signals:

Z-score advantage: `A = (reward - domain_baseline) / max(domain_std, beta)`

3.3 Flow Sampler (FlowRL)

File: `[home]/.claude/karl/flow_sampler.py`

4 sampling strategies:
- `uniform` — plain random
- `balanced` — equal samples per domain (FlowRL distribution matching)
- `advantage` — softmax-weighted by advantage score
- `top_k` — highest reward only

3.4 Skill Patterns (Spore Already Tracked)

From `trajectory_tap.py` line 43:

(r"Desktop/Spore/", "spore", "ios"),

KARL already categorizes Spore-related work as skill `"spore"` in domain `"ios"`. Any trajectory that touches Spore files gets labeled and scored.

3.5 Integration Surface for Spore

What would need to change:
- Create a Spore-specific trajectory format: each evolution cycle becomes a "trajectory" with the spore state as context, technique choice as tool, and outcome (keyword novelty, strength delta, bloom progress) as signals
- Build a Spore reward engine that measures: Did the mutation produce novel keywords? Did the spore grow toward bloom? Did the user engage with the result?
- Use the flow sampler to select which technique to apply: if G01 consistently produces high-reward mutations for "technology" spores but R01 works better for "philosophy" spores, learn that
- Feed spore evolution histories into KARL's trajectory store so the advantage-weighted sampler can recommend techniques

---

4. Cortex — Behavioral Intelligence

4.1 Core Architecture

Files: `[home]/.claude/cortex/` (19 Python files)

Cortex detects behavioral patterns and corrections, forges operational skills, and propagates rules.

Entry types (from `models.py`):
- `skill_candidate` — extracted from prompt log analysis
- `routing_decision` — skill routing/claim/machine decisions
- `correction` — detected user behavioral correction
- `rule` — promoted correction (in CLAUDE.md)
- `decay_flag` — skill/rule flagged for staleness
- `invocation_record` — skill was injected into a session

4.2 Correction Detector

File: `[home]/.claude/cortex/adaptation/correction_detector.py`

Detects user behavioral corrections via regex patterns:
- "don't use/do/add/include..."
- "never use/do/add..."
- "always use/do/add..."
- "stop doing/using..."
- Confidence threshold: 0.45

Feeds KARL Tap D when correction detected:

from karl.trajectory_tap import annotate_previous
annotate_previous(session_id, correction_detected=True)

4.3 Forge Generator

File: `[home]/.claude/cortex/forge/generator.py`

Generates operational SKILL.md files from behavioral patterns. Maps domains to tools, machines, and auto-trigger regex patterns.

4.4 Integration Surface for Spore

What would need to change:
- Create a Spore-specific Cortex domain that tracks in-app behavioral patterns: which spores get watered most, which techniques users select, which ideas get grafted vs composted
- The correction detector pattern can be adapted for Spore: if a user undoes an evolution or compostes a recently-mutated spore, that's a correction signal
- Cortex's frequency tracking can identify recurring user gardening patterns (e.g., "user always plants technology ideas in spring, compostes them in winter")
- Use the `LearnedPattern` data from `GardenMemoryService` as a Cortex signal source

---

5. Graph Kernel — Entity Relationships

5.1 API Interface

File: `[home]/projects/dream-weaver-engine/memory/graph_kernel_client.py`

REST API on `http://localhost:8001` (Rust binary on cloud-vm, SSH tunnel to Mac1):

Knowledge Triple format:

KnowledgeTriple(
    subject="spore",          # Entity name (bare lowercase)
    predicate="has_feature",  # Relation type
    object="voice_capture",   # Target entity
    confidence=0.8,
    source="spore-evolution"
)

Entity naming convention: Bare lowercase names (`spore`, `evolution`), NOT prefixed. Multi-word: try exact then first-word fallback.

HIGH_SIGNAL_PREDICATES: `works_on`, `built_with`, `has_feature`, `uses`, `evolved_from`, `is_a`, `belongs_to`, `tagged`, `deployed_on`

5.2 Integration Surface for Spore

What would need to change:
- Register spore entities in the knowledge graph: each spore becomes a node, tendrils become edges, keywords become `tagged` predicates
- Use GK to find semantic relationships between spores beyond keyword overlap: if spore A "climate solutions" and spore B "ocean acidification" share a GK edge via `relates_to`, suggest a tendril
- Query GK for cross-pollination: "what concepts are adjacent to this spore's keywords in the knowledge graph?"
- Create a Spore slice policy that filters context by spore domain/keywords

---

6. RAG++ — Semantic Search

6.1 API Interface

File: `[home]/projects/agent-intelligence/agent_intelligence/executors/rag_executor.py`

RAG++ is a hybrid search system on `http://localhost:8000` (Docker on cloud-vm, SSH tunnel to Mac1):

Search payload:

{
  "query": "string",
  "k": 10,
  "embedding": [0.1, 0.2, ...],  // Optional: Gemini embedding vector
  "hmac_ticket": "string"         // Optional: GK HMAC ticket
}

Embedding generation: Uses Gemini Embedding API (`gemini-embedding-001`):

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent

Data sources: Searches across `claude_prompts` and `rag_embeddings` Supabase tables. These contain 112K+ conversational turns from Claude sessions.

6.2 Integration Surface for Spore

What would need to change:
- Index spore ideas into `rag_embeddings`: when a spore is planted, generate an embedding and store it
- Use RAG++ search when evolving: "find similar ideas in my history that evolved successfully"
- Use RAG++ to suggest tendrils: search for spores with semantically similar content
- Create a Spore-specific RAG collection so searches can be scoped
- The search results can inform technique selection: if similar ideas bloomed after G07 (Oblique Strategy), recommend that technique

---

7. Daemon/Pulse — Autonomous Development

7.1 Architecture

File: `[home]/projects/evolution_world/daemon.py`

The EW daemon runs a 5-phase heartbeat:

sense -> select -> mutate -> check -> adapt

• Heartbeat interval: 30s-600s (driven by metabolism)
• Communicates via NUMU bus (JSON lines)
• Integrates with Pulse Bridge for autonomous code changes
• Budget gate prevents runaway spending

7.2 Integration Surface for Spore

The daemon already manages multiple apps. Spore would be registered as another genome. The daemon would:
- Sense: pull engagement metrics from the app (via Supabase)
- Select: choose which spore to evolve (using L2's selection strategy)
- Mutate: apply the chosen TIE technique via the edge function
- Check: verify invariants (did the mutation produce novelty?)
- Adapt: if stalling, switch technique; if diverging, dampen mutations

---

8. The Integration Architecture (Proposed)

8.1 Data Flow

User plants idea (voice/text)
    |
    v
[iOS App] -- SwiftData local store
    |
    | (Background task / foreground trigger)
    v
[Supabase Edge Function: evolve-spore-v2]
    |
    +---> [RAG++] "Find similar successful evolutions"
    |         |
    |         +---> Returns: similar spores, successful techniques, bloom histories
    |
    +---> [Graph Kernel] "What's adjacent to these keywords?"
    |         |
    |         +---> Returns: related entities, cross-domain connections
    |
    +---> [EW Engine] "Evolve this spore with invariant enforcement"
    |         |
    |         +---> Selects technique via L2 (not random!)
    |         +---> Applies mutation via Gemini Flash
    |         +---> Checks 4 invariants
    |         +---> Persists to Supabase
    |
    +---> [KARL] "Record this evolution as a trajectory"
              |
              +---> Scores outcome, computes advantage
              +---> Feeds back into EW's technique selection

8.2 New Supabase Tables Needed

8.3 New/Modified Edge Functions

8.4 iOS App Changes

---

9. Integration Friction Points

### 9.1 Network Dependency
- Current app works fully offline. Intelligence features need network.
- Mitigation: Keep on-device EvolutionEngine as fallback. Queue intelligence requests and batch when online.

### 9.2 Latency Budget
- iOS background tasks have a 30-second execution budget.
- RAG++ search + GK query + Gemini call could exceed this.
- Mitigation: Pre-compute intelligence at plant time (embed + GK register). Background evolution only calls the pre-enriched edge function.

### 9.3 Port Accessibility
- RAG++ (`:8000`) and GK (`:8001`) are on cloud-vm, accessed via SSH tunnel on Mac1.
- Supabase Edge Functions run on Supabase's infrastructure, not Mac1.
- Mitigation: Edge functions should call RAG++ and GK via the Tailscale IP (`[ip]`) or expose them via a reverse proxy with auth.

### 9.4 Authentication
- Current edge function uses anon key (exposed in Swift source).
- Intelligence features need service-role access for writing to new tables.
- Mitigation: Edge functions already have `SUPABASE_SERVICE_ROLE_KEY` in their env. iOS app continues to use anon key for reads + calling edge functions.

### 9.5 Cost
- Gemini Flash is cheap but RAG++ embedding generation adds API calls.
- Every spore plant = 1 embedding call. Every evolution = 1 RAG search + 1 Gemini Flash.
- Mitigation: Cache embeddings. Only re-embed on significant keyword changes. Rate-limit free tier to on-device only (current behavior).

### 9.6 Data Volume
- 112K+ turns in RAG++ already. Spore data is tiny in comparison.
- But each spore evolution generates a trajectory record, embedding, and GK triples.
- Mitigation: Prune old evolution trajectories after 90 days. Compact GK triples.

---

10. Priority Ranking for Implementation

### Phase 1: Foundation (Critical Path)
1. `evolve-spore-v2` Edge Function — Replace Gemini wrapper with EW-orchestrated evolution
2. `spore-embed` Edge Function — Embedding generation on plant
3. `IntelligenceClient.swift` — iOS client for new endpoints
4. Register Spore as EW AppGenome — Custom milestones (bloom rate, mutation diversity)

### Phase 2: Intelligence Loop
5. RAG++ integration — "Find similar successful evolutions" before mutating
6. GK entity registration — Spore -> knowledge triple on plant
7. KARL trajectory recording — Record each evolution cycle as a trajectory
8. Technique selection via KARL advantage — Stop random technique, use learned preferences

### Phase 3: Behavioral Learning
9. Cortex integration — Push GardenMemoryService patterns to Cortex
10. User engagement feedback — Water/graft/compost as Cortex correction signals
11. EW Feedback Metabolism — Spore-specific feedback channels
12. Tendril suggestion engine — RAG++ + GK powered "connect these ideas"

### Phase 4: Autonomous Evolution
13. EW daemon integration — Spore as a managed genome in the heartbeat loop
14. Invariant enforcement — Prevent stale evolution with EW invariants
15. L2 meta-evolution — The evolution process for Spore itself adapts
16. Cross-pollination — EW population manager enables cross-app technique sharing

---

11. Key API Contracts

evolve-spore-v2 (Proposed)

Request:

{
  "spore": {
    "id": "uuid",
    "name": "string",
    "keywords": ["string"],
    "strength": 0-100,
    "description": "string",
    "tendril_keywords": [["keyword1", "keyword2"]],
    "mutation_count": 0,
    "generation": 0
  },
  "garden_context": {
    "season": "spring|summer|autumn|winter",
    "total_spores": 12,
    "bloom_rate": 0.25,
    "user_engagement_score": 0.7
  },
  "technique_override": "G01|null"
}

Response:

{
  "mutated_keywords": ["string"],
  "strength_delta": 2.5,
  "changelog_entry": "string",
  "new_description": "string",
  "technique_used": "G07 Oblique Strategy",
  "technique_reason": "RAG++ found 3 similar ideas that bloomed with lateral techniques",
  "related_spores": [{"id": "uuid", "similarity": 0.82}],
  "invariant_check": {
    "min_entropy": {"passed": true, "novelty": 0.045},
    "bounded_divergence": {"passed": true, "rate": 0.8}
  },
  "ew_generation": 14,
  "karl_trajectory_id": "traj_abc123"
}

spore-feedback (Proposed)

Request:

{
  "spore_id": "uuid",
  "event_type": "water|graft|compost|view|evolve_undo|tendril_create",
  "metadata": {
    "duration_seconds": 12,
    "previous_strength": 45.0,
    "technique_applied": "G01"
  }
}

spore-suggest-tendril (Proposed)

Request:

{
  "spore_id": "uuid",
  "keywords": ["climate", "solutions", "renewable"],
  "exclude_ids": ["uuid1", "uuid2"],
  "limit": 5
}

Response:

{
  "suggestions": [
    {
      "spore_id": "uuid",
      "spore_name": "Ocean Carbon Capture",
      "similarity_score": 0.78,
      "shared_keywords": ["climate"],
      "gk_path": ["climate -> environmental_science -> ocean_acidification"],
      "reason": "Connected via Graph Kernel: both address carbon cycle"
    }
  ]
}

---

12. Existing Assets That Accelerate This

---

13. Open Questions for Stage 1

1. Should the EW daemon directly manage Spore, or should Spore have its own lighter heartbeat? The EW daemon is designed for iOS app genomes, but Spore's "genome" is individual ideas, not the app itself. We might want a Spore-specific "garden daemon" that runs evolution cycles for all spores in a user's garden.

2. How do we handle multi-user? Currently Spore is single-user with CloudKit sync. The intelligence backend is single-tenant. If we want multiple users' spores in the same EW population, we need user-scoped namespacing.

3. Where does the embedding model run? Gemini Embedding API is cloud-only. For offline/low-latency, we could use Apple's `NLEmbedding` (already in EvolutionEngine) as a local fallback and Gemini for the high-quality server-side path.

4. What's the privacy boundary? Spore ideas are personal. RAG++ currently indexes all Claude session data. Should spore embeddings live in a separate, user-owned collection?

5. How do we measure success? The ultimate metric is bloom rate and user retention. We need to define what "successful evolution" means in Spore terms: Does the user engage with the mutated idea? Do they create tendrils to it? Do they water it more?

---

Research complete. Ready for Stage 1: Architecture Design.