Cognitive architecture for Claude Code – triggers, memory, docs

This started as a psychology research project (building a psychoemotional safety scoring model) and turned into something more general: a reusable cognitive architecture for long-running AI agent work.

The core problem: Claude Code sessions lose context. Memory files live outside the repo and can silently disappear. Design decisions made in Session 3 get forgotten by Session 8. Documentation drifts from reality.

Our approach — 12 mechanical triggers that fire at specific moments (before responding, before writing to disk, at phase boundaries, on user pushback). Principles without firing conditions remain aspirations. Principles with triggers become infrastructure.

What's interesting:

- Cognitive trigger system — T1 through T12 govern agent behavior: anti-sycophancy checks, recommend-against scans, process vs. substance classification, 8-order knock-on analysis before decisions. Not prompting tricks — structural firing conditions. - Self-healing memory — Auto-memory lives outside the git repo. A bootstrap script detects missing/corrupt state, restores from committed snapshots with provenance headers, and reports what happened. The agent's T1 (session start) runs the health check before doing anything else. - Documentation propagation chain — 13-step post-session cycle that pushes changes through 10 overlapping documents at different abstraction levels. Content guards prevent overwriting good state with empty files. Versioned archives at every cycle. - Git reconstruction from chat logs — The project existed before its repo. We rebuilt git history by replaying Write/Edit operations from JSONL transcripts, with a weighted drift score measuring documentation completeness. The divergence report became a documentation coverage report. - Structured decision resolution — 8-order knock-on analysis (certain → likely → possible → speculative → structural → horizon) with severity-tiered depth and consensus-or-parsimony binding.

All built on Claude Code with Opus. The cognitive architecture (triggers, skills, memory pattern) transfers to any long-running agent project — the psychology domain is the first application, not a constraint.

Design phase — architecture resolved, implementation of the actual psychology agent hasn't started. The infrastructure for building it is the interesting part.

Code: https://github.com/safety-quotient-lab/psychology-agent

Highlights if you want to skip around: - Trigger system: docs/cognitive-triggers-snapshot.md - Bootstrap script: bootstrap-check.sh - Git reconstruction: reconstruction/reconstruct.py - Documentation chain: .claude/skills/cycle/SKILL.md - Decision resolution: .claude/skills/adjudicate/SKILL.md - Research journal: journal.md (the full narrative, 12 sections)

Happy to discuss the trigger design, the memory recovery pattern, or why we think documentation propagation matters more than people expect for AI-assisted work.