Show HN: Cognitive architecture for Claude Code – triggers, memory, docs

3 points

3 months ago

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.

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.