Skip to main content

🧩 The Reason Log – Decision Chain Ledger

reasonlog stores Reggie’s chain-of-thought for every material decision.
It explains why an action was chosen, how risky it seemed, and what the agent expected to happen next.
Alongside internalmonologue (raw events) and cognitivealignment (after-the-fact verdicts) it forms a complete audit trail.

1. Purpose​

ObjectiveHow it helps
TransparencyGives humans and downstream models a timestamped record of the agent’s reasoning steps.
Risk-aware operationsStores relevance and risk scores so high-impact decisions can be routed for human review first.
Outcome trackingSaves the predicted outcome so the platform can later compare expectation versus reality.
Continuous learningInaccurate predictions feed the Cognitive-Alignment loop, tuning future risk thresholds and heuristics.

2. Table Schema (PostgreSQL)​

ColumnType / ConstraintNotes
iduuid PKUnique identifier for this reasoning chain.
timestamptimestamptz NOT NULLWhen the step was recorded.
decision_contexttext NOT NULLShort label (e.g. ROSTER_AUTO_REBALANCE).
step_indexint NOT NULL0-based position in a multi-step chain.
thoughttext NOT NULLNatural-language reasoning for this step.
relevancenumeric(3,2) NOT NULL0.00 – 1.00 importance relative to the final action.
risknumeric(3,2) NOT NULL0.00 – 1.00 probability of a negative consequence.
predicted_outcomejsonbStructured object describing the expected result.
vectorvector(768)Embedding of thought for semantic search.
alignment_iduuidFK → cognitivealignment.id once reviewed.
statustext DEFAULT 'PENDING'Mirrors review state: PENDING, APPROVED, REJECTED.

3. Workflow​

  1. Reasoning – While planning an action Reggie appends one or more steps to reasonlog.
  2. Risk gate – If risk ≥ monitoring_threshold the action pauses for human review (see Cognitive Alignment levels).
  3. Execution – Upon approval the action executes; the final outcome is written to internalmonologue.
  4. Post-hoc analysis – A nightly job compares predicted_outcome with reality and writes accuracy stats to context buckets.
  5. Linkage – Reviewer verdict updates alignment_id and status, closing the loop.

4. Query & Recall Examples​

-- Find recent high-risk decisions awaiting review
SELECT * FROM reasonlog
WHERE status = 'PENDING' AND risk > 0.6
ORDER BY timestamp DESC;

-- Retrieve reasoning similar to a new transport situation
SELECT id, decision_context, thought
FROM reasonlog
ORDER BY vector <-> embedding(:new_prompt)        -- pgvector similarity
LIMIT 5;

The vector column enables precedent-based prompting, e.g.
“Show me past reasoning similar to reassigning vehicles after staff sick leave.”

5. Data Retention & Governance​

  • Retention: Full rows kept 180 days, then summarised and archived to cold storage.
  • Privacy: Must not include raw PII; references use internal IDs only.
  • Change control: Edits to this schema/document require Tech-Lead + Security sign-off.
  • Monitoring metrics: reasonlog_high_risk_rate, reasonlog_pending_count, reasonlog_avg_steps.

🔗 Related Docs​