cambium ▸ UPGRADE-SPEC.md
updated 2026-04-08

Cambium Upgrade Spec — Inspired by KayOS Analysis

Date: 2026-04-08 Author: Obadiah (with Tesla on innovation, MacKenzie on architecture) Status: Draft for Joshua’s review

Executive Summary

After analyzing KayOS.ai’s architecture, we identified four upgrades that would meaningfully improve Cambium. These are ordered by impact and build on our existing 26-table PostgreSQL schema — not replacing it, but extending it.

Upgrade 1: Knowledge Graph Layer

What: Add entity-relationship tracking per project so agents understand who/what they’re working with, not just what happened.

Why: Currently Cambium stores flat project contexts (“BLO app submitted, website live”). A knowledge graph would store: “BLO → has_channel → #blo-growth”, “Joshua → owns → BLO”, “Vega → responsible_for → ASO”, “boldlittleoracle.unicorn.land → hosted_on → Cloudflare”. Agents can then reason about relationships, not just summaries.

Schema additions:

-- Entities (people, projects, services, concepts)
CREATE TABLE entities (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  project_id TEXT NOT NULL,           -- which project namespace
  name TEXT NOT NULL,
  entity_type TEXT NOT NULL,          -- person, project, service, concept, channel, url
  metadata JSONB DEFAULT '{}',
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(project_id, name, entity_type)
);

-- Relationships between entities
CREATE TABLE relationships (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  project_id TEXT NOT NULL,
  source_entity_id UUID REFERENCES entities(id),
  relationship_type TEXT NOT NULL,     -- owns, uses, responsible_for, deployed_on, depends_on, monitors
  target_entity_id UUID REFERENCES entities(id),
  metadata JSONB DEFAULT '{}',
  confidence FLOAT DEFAULT 1.0,        -- how certain is this relationship
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Observations (time-stamped facts about entities)
CREATE TABLE observations (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  entity_id UUID REFERENCES entities(id),
  observed_at TIMESTAMPTZ DEFAULT NOW(),
  observation_type TEXT NOT NULL,       -- metric, status_change, event, note
  content JSONB NOT NULL,              -- flexible payload
  source TEXT,                         -- which agent/trigger observed this
  expires_at TIMESTAMPTZ              -- optional TTL for temporal facts
);

Bridge CLI additions:

cambium-bridge.sh graph add-entity blo "Cloudflare Pages" service
cambium-bridge.sh graph add-relationship blo "BLO Website" deployed_on "Cloudflare Pages"
cambium-bridge.sh graph query blo "what depends on Cloudflare?"
cambium-bridge.sh graph observe blo "BLO App" metric '{"downloads": 0, "rating": null}'

Effort: Medium (2-3 hours). Schema + bridge extensions + seed initial graph for BLO.

Upgrade 2: Project Ontology Files

What: Add a ontology.md per project deployment that defines the domain vocabulary, key concepts, and decision frameworks specific to that project.

Why: Right now agents get a persona (who they are) and a context summary (what happened). But they don’t get a domain model. An ontology tells them: “In BLO’s world, ASO means App Store Optimization. A ‘draw’ is when a user pulls a card. ‘Sassy mode’ is the irreverent tone. Phase 1 means first 4 weeks targeting 2K downloads.” This eliminates the need to re-explain domain concepts in every prompt.

Implementation:

deployments/blo/ontology.md
deployments/obadiah/ontology.md

Each ontology file follows a standard structure:

# BLO Ontology

## Core Concepts
- **Draw:** User pulls a daily oracle card
- **Tone:** PG (gentle) or Sassy (irreverent)
- **Phase 1:** Weeks 1-4, 2K downloads, 200 DAU, $0 ad spend
- **Phase 2:** Weeks 5-8, add IAP at €4.99

## Key Metrics
- **Downloads:** App Store + Google Play total installs
- **DAU:** Daily Active Users (unique app opens per day)
- **ASO Score:** Keyword ranking position for target terms

## Decision Framework
- External content (social posts, store changes) → needs Joshua's approval
- Internal research/experiments → execute freely
- Spending money → needs approval

## Domain Relationships
- BLO → distributed via → App Store, Google Play
- Growth → measured by → downloads, DAU, rating, revenue
- Content → created by → Vega (marketing), Tesla (innovation)

Bridge CLI addition:

cambium-bridge.sh ontology load blo    # returns ontology for agent context injection

Effort: Low (1 hour). File convention + bridge read command + inject into agent prompts.

Upgrade 3: Agent Archetypes (Scout / Synthesizer / Gardener)

What: Add three meta-agent roles that run across all projects, complementing the domain-specific personas we already have.

Why: KayOS uses scout (detect external signals), synthesizer (compress and consolidate memory), gardener (maintain the knowledge graph). These are orthogonal to our personas — Vega is a marketing specialist, but the scout pattern could be applied to any domain. This gives us systematic information hygiene.

New agent templates:

# Cross-cutting meta-agents (add to each deployment)

scout:
  role: signal-detection
  label: "Scout"
  emoji: "🔭"
  description: "Detects external signals — competitor moves, market changes, new opportunities, threats"
  capabilities:
    - web_monitoring
    - competitor_tracking
    - trend_detection
    - alert_generation
  schedule: "0 9 * * *"  # Daily scan
  triggers:
    - competitor_app_update
    - keyword_ranking_change
    - negative_review_spike

synthesizer:
  role: memory-compression
  label: "Synthesizer"
  emoji: "🧬"
  description: "Compresses daily memory into long-term knowledge. Identifies patterns across days/weeks."
  capabilities:
    - memory_consolidation
    - pattern_recognition
    - summary_generation
  schedule: "0 2 * * 0"  # Weekly Sunday 2am
  actions:
    - compress daily logs into weekly summaries
    - update knowledge graph with new patterns
    - prune stale observations
    - flag recurring themes for human attention

gardener:
  role: graph-maintenance
  label: "Gardener"
  emoji: "🌱"
  description: "Maintains the knowledge graph. Adds missing relationships, removes stale entities, validates accuracy."
  capabilities:
    - graph_maintenance
    - relationship_inference
    - data_quality
  schedule: "0 3 * * 0"  # Weekly Sunday 3am
  actions:
    - scan for entities mentioned in memory but not in graph
    - verify existing relationships still hold
    - infer new relationships from recent activity
    - flag inconsistencies for human review

Effort: Medium (2 hours). Agent template definitions + prompt engineering + scheduling.

Upgrade 4: Experiment Tracking Table

What: Formalize the AutoResearch pattern into a proper experiment tracking system in the database.

Why: We already use AutoResearch in Pam (mutate params → replay → score → keep/discard) and planned it for BLO (ASO keyword testing). But experiments are tracked in TSV files and memory, not in the database. A proper experiments table lets any agent propose, run, and learn from experiments with full history.

Schema:

CREATE TABLE experiments (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  project_id TEXT NOT NULL,
  name TEXT NOT NULL,
  hypothesis TEXT NOT NULL,           -- "Adding 'daily oracle' to subtitle improves impressions"
  status TEXT DEFAULT 'proposed',     -- proposed, running, completed, discarded
  metric_name TEXT NOT NULL,          -- "impressions_per_week"
  baseline_value FLOAT,
  result_value FLOAT,
  variant JSONB,                      -- what was changed
  started_at TIMESTAMPTZ,
  completed_at TIMESTAMPTZ,
  proposed_by TEXT,                   -- which agent
  approved_by TEXT,                   -- human or auto
  outcome TEXT,                       -- kept, discarded, inconclusive
  notes TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

Bridge CLI additions:

cambium-bridge.sh experiment propose blo "Add 'daily oracle' to subtitle" impressions_per_week
cambium-bridge.sh experiment start blo <experiment-id>
cambium-bridge.sh experiment complete blo <experiment-id> --result 1250 --outcome kept
cambium-bridge.sh experiment list blo --status running
cambium-bridge.sh experiment history blo --limit 20

Effort: Low-Medium (1-2 hours). Single table + bridge commands.

Implementation Priority

# Upgrade Impact Effort Priority
1 Knowledge Graph High — transforms agent context quality Medium Do first
2 Ontology Files Medium — eliminates repeated context Low Do second
4 Experiment Tracking High — formalizes AutoResearch Low-Medium Do third
3 Agent Archetypes Medium — systematic info hygiene Medium Do fourth

Total estimated effort: 6-8 hours for all four upgrades.

What We’re NOT Doing (and why)