brycewang-stanford/diverga-memory

Diverga Memory System v7.0

Overview

Human-centered research context persistence with:

• 3-Layer Context System
• Checkpoint Auto-Trigger
• Cross-Session Continuity
• Decision Audit Trail
• Research Documentation Automation

Quick Reference

Context Loading Keywords

English: "my research", "research status", "where was I", "continue research", "what stage"

Korean: "내 연구", "연구 진행", "연구 상태", "어디까지", "지금 단계"

Commands

| Command | Description | |---------|-------------| | /diverga:memory status | Show project status | | /diverga:memory context | Display full context | | /diverga:memory init | Initialize project | | /diverga:memory decision list | List decisions | | /diverga:memory archive [STAGE] | Archive stage | | /diverga:memory migrate | Run migration |

Priority Context (v8.2 — Compression Resilience)

MCP Tools for Priority Context

| Command | MCP Tool | Description | |---------|----------|-------------| | Read priority | diverga_priority_read() | Read 500-char context summary | | Write priority | diverga_priority_write(context) | Update context summary | | Full status | diverga_project_status() | Project state + checkpoints + decisions | | Check prereqs | diverga_check_prerequisites(agent_id) | Verify agent can proceed | | Record decision | diverga_mark_checkpoint(cp_id, decision, rationale) | Record and auto-update priority |

Auto-Update Behavior

Priority context is automatically updated when:

• A checkpoint is marked via diverga_mark_checkpoint()
• Format: Project: {name} | Paradigm: {paradigm} | RQ: {question} | ✅/❌ checkpoints | Last: {decision}
• Maximum 500 characters, stored at .research/priority-context.md

Compression Recovery

When context window is compressed:

1. Call diverga_priority_read() to recover essential project context
2. Call diverga_checkpoint_status() to see checkpoint state
3. Call diverga_project_status() for full project details

3-Layer Context System

Layer 1: Keyword-Triggered (자연어 감지)

When researcher asks "내 연구 진행 상황은?" or "What's my research status?", automatically load and display context.

Auto-Detection Keywords:

• "my research", "연구", "research", "progress", "진행"
• "where was I", "continue", "다시", "어디까지"
• "what stage", "현재 단계", "stage", "지금"

Response Pattern:

1. Detect keyword match
2. Load .research/project-state.yaml
3. Display current stage and progress
4. Show pending checkpoints
5. List available next actions

Layer 2: Task Interceptor (에이전트 호출)

When Task(subagent_type="diverga:*") is called, automatically inject full research context and checkpoint instructions.

Injection Process:

1. Detect diverga: prefix in subagent_type
2. Read .research/project-state.yaml
3. Read .research/checkpoints.yaml
4. Inject context into agent prompt
5. Add checkpoint validation wrapper
6. Execute with full research awareness

Context Injected:

# Automatically included in agent prompt
research_context:
  project_name: "[from project-state.yaml]"
  current_stage: "[from checkpoints.yaml]"
  research_question: "[from project-state.yaml]"
  methodology: "[from project-state.yaml]"
  decisions: "[from decision-log.yaml, last 10]"
  pending_checkpoints: "[from checkpoints.yaml]"

Layer 3: CLI (명시적 요청)

Run /diverga:memory context --verbose for full detailed state.

Available Flags:

• --verbose - Show full decision audit trail
• --archive - Include archived stages
• --decisions - Show decision log only
• --checkpoints - Show checkpoint status only
• --format json|yaml|text - Output format

Checkpoint System

Checkpoint Levels

| Level | Icon | Behavior | Example | |-------|------|----------|---------| | REQUIRED | 🔴 | Must complete before proceeding | CP_RESEARCH_DIRECTION | | RECOMMENDED | 🟠 | Strongly suggested | CP_PARADIGM_SELECTION | | OPTIONAL | 🟡 | Can skip with defaults | CP_METHODOLOGY_APPROVAL |

Standard Checkpoints (Research Workflow)

Foundation Stage (0-2 hours)

• CP_RESEARCH_DIRECTION 🔴 - Research question finalized and validated
• CP_PARADIGM_SELECTION 🟠 - Quantitative/qualitative/mixed selected with rationale
• CP_SCOPE_DEFINITION 🔴 - Scope constraints documented (years, populations, outcomes)

Design Stage (2-4 hours)

• CP_THEORY_SELECTION 🟠 - Theoretical framework chosen and justified
• CP_VARIABLE_DEFINITION 🔴 - All variables operationalized (IV, DV, mediators, moderators)
• CP_METHODOLOGY_APPROVAL 🟠 - Research design validated (RCT, meta-analysis, qualitative, etc.)

Planning Stage (4-6 hours)

• CP_DATABASE_SELECTION 🔴 - Data sources identified with inclusion/exclusion criteria
• CP_SEARCH_STRATEGY 🔴 - Search terms, filters, and retrieval approach documented
• CP_SAMPLE_PLANNING 🟠 - Sample size, power analysis (if quantitative), or saturation plan (if qualitative)

Execution Stage (6+ hours)

• CP_SCREENING_CRITERIA 🔴 - Inclusion/exclusion criteria operationalized for systematic review
• CP_RAG_READINESS 🟠 - Vector database and retrieval system configured
• CP_DATA_EXTRACTION 🟠 - Data extraction protocol finalized and tested
• CP_ANALYSIS_PLAN 🔴 - Analysis approach documented with reproducible steps

Validation Stage (Final)

• CP_QUALITY_GATES 🔴 - PRISMA/CONSORT compliance verified
• CP_PEER_REVIEW 🟠 - Methodology reviewed by co-investigators
• CP_PUBLICATION_READY 🔴 - Manuscript format and ethics approved

Checkpoint Enforcement Rules

REQUIRED (🔴) Checkpoints:

• Cannot skip
• Must have evidence of completion
• Blocks advancement to next stage
• Tracked in decision-log.yaml with timestamp

RECOMMENDED (🟠) Checkpoints:

• Can skip with documented rationale
• Requires explicit user acknowledgment
• Added to issues.log if skipped
• Tracked as amendment to decision-log

OPTIONAL (🟡) Checkpoints:

• Can skip without confirmation
• Tracked for audit trail only
• May be auto-populated with defaults

Checkpoint Validation

When checkpoint is reached:

# In checkpoints.yaml
- checkpoint_id: CP_RESEARCH_DIRECTION
  level: REQUIRED
  status: pending
  triggered_at: 2025-02-03T10:30:00Z
  stage: foundation

# User completes checkpoint
- checkpoint_id: CP_RESEARCH_DIRECTION
  level: REQUIRED
  status: completed
  completed_at: 2025-02-03T10:45:00Z
  completed_by: researcher
  decision_id: DEV_001
  evidence: "Research question: How does AI improve learning outcomes?"

# Moving to next stage
- checkpoint_id: CP_PARADIGM_SELECTION
  level: RECOMMENDED
  status: pending
  triggered_at: 2025-02-03T10:46:00Z

Decision Audit Trail

All decisions are:

• Immutable: Never modified after creation
• Versioned: Amendments create new entries with amends reference
• Contextual: Capture research question and prior decisions
• Timestamped: ISO 8601 format with timezone

Decision Structure

decisions:
  - decision_id: DEV_001
    checkpoint_id: CP_RESEARCH_DIRECTION
    timestamp: 2025-02-03T10:30:00Z
    researcher_name: "Dr. Park"

    # What was decided
    decision_type: "research_question"
    selected: "How does AI-assisted instruction affect student engagement in STEM?"
    alternatives_considered:
      - "How does AI personalization improve learning outcomes?"
      - "What are barriers to AI adoption in classrooms?"

    # Why this decision
    rationale: |
      Engagement is measurable and significant to existing literature.
      Aligns with team expertise in behavioral psychology.
      Scope is feasible within 6-month timeline.

    # Context at time of decision
    prior_decisions: []
    research_constraints:
      - timeline: "6 months"
      - budget: "$50,000"
      - team_size: 3

    # Amendment tracking
    amends: null  # Only non-null for amendments
    version: 1

  - decision_id: DEV_002
    checkpoint_id: CP_PARADIGM_SELECTION
    timestamp: 2025-02-03T10:45:00Z
    researcher_name: "Dr. Park"
    decision_type: "paradigm"
    selected: "Quantitative: Meta-analysis"
    rationale: "Sufficient RCTs exist. Need synthesis of effect sizes."
    prior_decisions: ["DEV_001"]
    version: 1

  # Amendment example
  - decision_id: DEV_002_A1
    checkpoint_id: CP_PARADIGM_SELECTION
    timestamp: 2025-02-03T14:30:00Z
    researcher_name: "Dr. Park"
    decision_type: "paradigm_amendment"
    selected: "Mixed-methods: Meta-analysis + qualitative synthesis"
    rationale: "Expanded to include implementation barriers (qualitative)"
    amends: "DEV_002"
    version: 2

Decision Amendment Process

When researcher changes mind or refines decision:

1. View current decision: /diverga:memory decision show DEV_002
2. Amend decision: /diverga:memory decision amend DEV_002 --reason "New data suggests..."
3. System action:
   • Creates new entry: DEV_002_A1 with amends: DEV_002
   • Links to previous decision
   • Records amendment rationale
   • Updates version: 2
   • Marks original as "amended" (not deleted)

Directory Structure

.research/
├── baselines/
│   ├── literature/
│   │   └── key_studies.yaml
│   ├── methodology/
│   │   └── frameworks.yaml
│   └── framework/
│       └── theories.yaml
│
├── changes/
│   ├── current/
│   │   ├── research_question.md
│   │   ├── methodology_plan.md
│   │   └── data_extraction.yaml
│   └── archive/
│       ├── foundation_20250203.yaml
│       ├── design_20250210.yaml
│       └── planning_20250217.yaml
│
├── sessions/
│   ├── 2025_02_03_session_001.yaml
│   ├── 2025_02_03_session_002.yaml
│   └── 2025_02_10_session_001.yaml
│
├── project-state.yaml
├── decision-log.yaml
├── checkpoints.yaml
├── issues.log
└── README.md

File Specifications

project-state.yaml

project:
  name: "AI in STEM Education"
  description: "Meta-analysis of AI-assisted instruction effects"
  created_at: 2025-02-03T10:00:00Z
  updated_at: 2025-02-03T14:30:00Z

research:
  question: "How does AI-assisted instruction affect student engagement in STEM?"
  paradigm: "Quantitative"
  methodology: "Meta-analysis"
  timeline:
    start_date: 2025-02-03
    estimated_completion: 2025-08-03
    current_stage: "foundation"
    stage_progress: "50%"  # % of expected work for this stage

team:
    lead: "Dr. Park"
    members: ["Dr. Park", "Ms. Kim", "Mr. Lee"]

constraints:
  budget: 50000
  budget_used: 5000
  team_capacity_hours_per_week: 40
  database_access: ["Semantic Scholar", "OpenAlex", "arXiv"]

last_session:
  session_id: "2025_02_03_session_002"
  duration_minutes: 45
  checkpoint_reached: "CP_PARADIGM_SELECTION"

decision-log.yaml

See Decision Audit Trail section above.

checkpoints.yaml

checkpoints:
  foundation:
    - checkpoint_id: CP_RESEARCH_DIRECTION
      level: REQUIRED
      status: completed
      completed_at: 2025-02-03T10:30:00Z
      decision_id: DEV_001

    - checkpoint_id: CP_PARADIGM_SELECTION
      level: RECOMMENDED
      status: completed
      completed_at: 2025-02-03T10:45:00Z
      decision_id: DEV_002_A1

    - checkpoint_id: CP_SCOPE_DEFINITION
      level: REQUIRED
      status: pending
      triggered_at: 2025-02-03T10:46:00Z

  design:
    - checkpoint_id: CP_THEORY_SELECTION
      level: RECOMMENDED
      status: pending
      expected_completion: 2025-02-10T12:00:00Z

current_stage: "foundation"
completed_stages: []

issues.log

issues:
  - issue_id: ISS_001
    date: 2025-02-03T11:00:00Z
    severity: medium
    category: "checkpoint_skipped"
    checkpoint_id: "CP_SCOPE_DEFINITION"
    message: "User requested to skip scope definition checkpoint"
    resolution: "Documented in decision-log as DEV_003"

  - issue_id: ISS_002
    date: 2025-02-03T13:15:00Z
    severity: low
    category: "api_access_warning"
    message: "OpenAlex API rate limit approaching (890/1000 requests)"
    resolution: "Will reduce request frequency next session"

Usage Examples

Initialize Project

# Interactive initialization
/diverga:memory init

# Or with CLI arguments
/diverga:memory init \
  --name "AI in STEM Education" \
  --question "How does AI-assisted instruction affect student engagement?" \
  --paradigm quantitative \
  --methodology "meta-analysis" \
  --timeline 6 \
  --team-lead "Dr. Park"

Output:

✓ Project initialized: AI in STEM Education
✓ Created .research/ directory structure
✓ Set checkpoint: CP_RESEARCH_DIRECTION (REQUIRED)
✓ Next action: Define research scope

Start with: /diverga:memory status

Record Decision

# At checkpoint completion
/diverga:memory decision add \
  --checkpoint CP_RESEARCH_DIRECTION \
  --selected "How does AI-assisted instruction affect student engagement in STEM?" \
  --rationale "Engagement is measurable and aligns with team expertise"

Output:

✓ Decision recorded: DEV_001
✓ Checkpoint CP_RESEARCH_DIRECTION marked COMPLETED
✓ Next checkpoint: CP_PARADIGM_SELECTION (RECOMMENDED)
✓ Session time: 15 minutes

Next: /diverga:memory checkpoint next

View Project Status

/diverga:memory status

Output:

╔════════════════════════════════════════╗
║      AI in STEM Education              ║
║      Meta-Analysis Research Project    ║
╚════════════════════════════════════════╝

📊 PROGRESS
├─ Current Stage: Foundation [50% complete]
├─ Sessions: 2 (90 minutes total)
├─ Decisions: 2 completed
└─ Next Milestone: CP_SCOPE_DEFINITION (REQUIRED)

🎯 RESEARCH QUESTION
   "How does AI-assisted instruction affect student engagement in STEM?"

📋 PARADIGM & METHODOLOGY
   Quantitative | Meta-Analysis

⏱️ TIMELINE
   Started: Feb 3, 2025
   Target: Aug 3, 2025
   Elapsed: 45 minutes
   Est. Remaining: 24+ hours

👥 TEAM
   Lead: Dr. Park
   Members: 3

✅ COMPLETED CHECKPOINTS
   ✓ CP_RESEARCH_DIRECTION (Feb 3, 10:30)
   ✓ CP_PARADIGM_SELECTION (Feb 3, 10:45)

⏳ PENDING CHECKPOINTS
   🔴 CP_SCOPE_DEFINITION (REQUIRED)
   🟠 CP_THEORY_SELECTION (RECOMMENDED)

🔗 LAST SESSION
   Duration: 45 minutes
   Ended: Feb 3, 14:30
   Next: CP_SCOPE_DEFINITION discussion

Archive Completed Stage

# Archive foundation stage after completing all checkpoints
/diverga:memory archive foundation \
  --summary "Research direction and paradigm finalized" \
  --learnings "Team consensus on meta-analysis approach strengthens methodology"

Creates:

.research/changes/archive/foundation_20250203.yaml

foundation_archive:
  archived_at: 2025-02-03T15:00:00Z
  stage_name: "Foundation"
  duration_hours: 2.5

  checkpoints_completed: 2
  checkpoints_skipped: 0
  decisions_made: 2

  summary: "Research direction and paradigm finalized"
  learnings: |
    Team consensus on meta-analysis approach strengthens methodology.
    Early consideration of scope constraints prevented later conflicts.

  next_stage: "Design"
  notes: "Team ready to proceed to theory selection"

List Decisions

# Show all decisions
/diverga:memory decision list

# Filter by checkpoint
/diverga:memory decision list --checkpoint CP_PARADIGM_SELECTION

# Show with full rationale
/diverga:memory decision list --verbose

Output:

DECISION AUDIT TRAIL
═════════════════════════════════════

DEV_001 | CP_RESEARCH_DIRECTION | ✓ ACTIVE
  Date: Feb 3, 2025 10:30
  Decision: How does AI-assisted instruction affect student engagement in STEM?
  Rationale: Engagement is measurable and significant to existing literature.
  Version: 1

DEV_002_A1 | CP_PARADIGM_SELECTION | ✓ ACTIVE (amended)
  Date: Feb 3, 2025 10:45 [amended 14:30]
  Original (DEV_002): Quantitative: Meta-analysis
  Amendment: Mixed-methods: Meta-analysis + qualitative synthesis
  Amendment Rationale: Expanded to include implementation barriers
  Version: 2

Total Decisions: 2
Total Amendments: 1

Show Full Context

/diverga:memory context --verbose --format yaml

Output (excerpt):

research_context:
  project_name: "AI in STEM Education"
  current_stage: "foundation"
  research_question: "How does AI-assisted instruction affect student engagement in STEM?"
  paradigm: "Quantitative"
  methodology: "Meta-analysis"

  decisions:
    - DEV_001: "Research question finalized"
    - DEV_002_A1: "Mixed-methods approach approved"

  completed_checkpoints:
    - CP_RESEARCH_DIRECTION (Feb 3 10:30)
    - CP_PARADIGM_SELECTION (Feb 3 10:45)

  pending_checkpoints:
    - CP_SCOPE_DEFINITION (REQUIRED)
    - CP_THEORY_SELECTION (RECOMMENDED)

session_history:
  - session_001: 45 minutes (Feb 3 10:00-10:45)
  - session_002: 45 minutes (Feb 3 13:45-14:30)

issues:
  - ISS_001: Checkpoint skipped (documented)

Migration from v6.8

Automatic Migration Detection

When accessing v6.8 project with v7.0 system:

/diverga:memory migrate --dry-run

Output:

MIGRATION CHECK: v6.8 → v7.0
═════════════════════════════════════

Found v6.8 project structure detected:
├─ old_decisions.log (47 entries)
├─ old_checkpoints.txt (basic format)
└─ old_sessions/ (8 files)

MIGRATION PLAN
├─ ✓ Convert decisions to YAML format
├─ ✓ Upgrade checkpoint structure (add levels)
├─ ✓ Import session history
├─ ✓ Create missing metadata fields
└─ ✓ Generate amendment chain analysis

Ready to migrate. Use: /diverga:memory migrate

Execute Migration

/diverga:memory migrate

Output:

MIGRATION IN PROGRESS
═════════════════════════════════════

✓ Imported 47 decisions
✓ Upgraded checkpoint structure
✓ Analyzed amendment history
✓ Imported 8 session records
✓ Generated project-state.yaml
✓ Validated checkpoint linkage
✓ Created archive/baseline/ structure
✓ Backed up original files to .backup/

MIGRATION COMPLETE
═════════════════════════════════════
Project upgraded to v7.0
Old files backed up in: .research/.backup/v6.8/
Ready to continue research workflow.

Backward Compatibility

v7.0 maintains read-only compatibility with v6.8 files:

• Can read old decision logs
• Can display old checkpoint format
• Cannot write to old format
• Must run migration for full functionality

Integration with Research Coordinator

Memory system integrates with all Diverga agents (A1-H2) to provide:

Auto-Context Injection for Agents

When delegating to research agents:

# Without explicit context injection (system does it automatically)
Task(
    subagent_type="diverga:A2-HypothesisArchitect",
    prompt="Help me develop hypotheses for my research"
)

# Memory system automatically:
# 1. Loads .research/project-state.yaml
# 2. Loads .research/decision-log.yaml
# 3. Injects into agent system prompt:
#    - Current research question
#    - Methodology selection
#    - Prior decisions made
#    - Pending checkpoints
# 4. Executes with full context

Checkpoint Enforcement in Agent Execution

Agents automatically:

• Check pending REQUIRED checkpoints before starting
• Validate checkpoint prerequisites
• Record new checkpoints when appropriate
• Update session context
• Log decisions with audit trail

Session Continuity

When researcher returns later:

User: "Let's continue my research on AI in education"

Memory System:
1. Detects keyword trigger
2. Loads last_session from project-state.yaml
3. Displays: "Welcome back! Last session: Feb 3, 14:30"
4. Shows: "Next checkpoint: CP_SCOPE_DEFINITION"
5. Suggests: "Continue with scope definition discussion?"

Advanced Features

Dependency Chain Tracking

Memory system automatically detects and validates checkpoint dependencies:

dependencies:
  CP_PARADIGM_SELECTION:
    requires:
      - CP_RESEARCH_DIRECTION  # Must be completed first
    unlocks:
      - CP_THEORY_SELECTION
      - CP_VARIABLE_DEFINITION
      - CP_METHODOLOGY_APPROVAL

  CP_DATABASE_SELECTION:
    requires:
      - CP_METHODOLOGY_APPROVAL
    unlocks:
      - CP_SEARCH_STRATEGY
      - CP_SCREENING_CRITERIA

Baseline Preservation

Research baselines (literature reviews, theoretical frameworks) are immutable:

.research/baselines/
├── literature/
│   └── key_studies.yaml        # Immutable snapshot
├── methodology/
│   └── frameworks.yaml         # Immutable reference
└── framework/
    └── theories.yaml           # Immutable collection

Changes are tracked in changes/current/ while baselines remain stable.

Cross-Project Learning

After project completion, memory system extracts learnings:

/diverga:memory extract-learnings

Creates shareable artifact for future projects:

• Common decision patterns
• Checkpoint shortcut sequences
• Timeline estimates
• Lessons learned

Performance and Limits

| Metric | Limit | Notes | |--------|-------|-------| | Max decisions per project | 1000 | Archive older decisions if needed | | Max sessions per project | 500 | Session history available via archive | | Context injection latency | <100ms | Cached for performance | | Maximum project lifespan | 10 years | Can archive and restore old projects |

Privacy and Security

• All project data stored locally in .research/
• No cloud sync unless explicitly configured
• Decision audit trail is non-repudiation certified
• Checkpoint timestamps are tamper-evident
• All modifications tracked in git history (if repo enabled)

---

Summary

Diverga Memory System v7.0 enables researchers to:

✓ Persist research context across sessions without manual setup ✓ Track all decisions with immutable audit trail and amendment support ✓ Enforce research rigor through checkpoint system with dependency validation ✓ Integrate with agents automatically for context-aware research support ✓ Maintain research quality through baseline preservation and change tracking ✓ Scale research projects from single-investigator to multi-year team efforts

---

Version 7.0.0 | Global Deployment Ready | Last Updated: 2025-02-03