08 — Promotion Path

The Canonical Writer

The only canonical writer of organizational memory is services/pipeline/src/memory-promoter.ts.

No other service, workflow, or agent may write to org_memory directly.

Promotion Flow

Approved triage candidate
        |
        v
Memory Consolidator (scheduled)
        |
        v
scoreForPromotion() — 7 Promotion Signals
        |
        v
Governance gate: staging vs approved
        |
   ┌────┴────┐
   |         |
staging   approved
   |         |
   v         v
Human     Direct write
review    to org_memory
   |         |
   v         v
approve   Index to
   |      AI Search
   v
Pipeline
promotion

7 Promotion Signals

Signal	Weight	Meaning
strategic	2	Entity is inherently strategic (account, deal, contract, etc.)
decision	2	Explicit decision provenance
exception	2	Risk, anomaly, breach, blocked, churn
important	1	Material value, financial significance
repeated	1	Multiple occurrences or contributors
behavioral	1	Activity, engagement, interaction
preference	1	Explicit user/customer preference

Strong signals (weight >= 2) can promote alone. Weak signals need company.

Threshold: Score >= 2 to promote.

Governance Gate

const needsApproval =
  !schema.governanceDefaults.autoPromote ||
  schema.governanceDefaults.requiresApproval.includes(category);

const governanceState = needsApproval ? "staging" : "approved";

Sensitive categories (risk, decision, policy) always land in staging — the Twin must not use them until approved.

Deduplication

Promotion deduplicates by lineage_ref (the source Spine entity):

• Existing memory found → update confidence (+0.1), update content
• No existing memory → insert new row
• Audit trail always written

Indexing

After promotion, approved memory is indexed into AI Search:

• Markdown content with full metadata
• Idempotent re-upload (same ID overwrites)
• Batch processing (10 per batch, 100ms delay between batches)

What Promotion Produces

Output	Store	Purpose
org_memory row	D1	Canonical organizational memory
memory_promotion_audit row	D1	Immutable audit trail
AI Search document	Vectorize/AI Search	Searchable memory
Outbox event	Queue	Downstream notifications