Skip to content

AI-AGENT-SYSTEM.md

Latest commit

 

History

History
701 lines (536 loc) · 18.8 KB

AI-AGENT-SYSTEM.md

File metadata and controls

701 lines (536 loc) · 18.8 KB
title AI Agent Learning and Context Management System
atom ATOM-AI-20251127-002
classification AGENT-DIRECTIVE
status production
created 2025-11-26
updated 2025-11-27
purpose AI ingestion, monitoring, review, and analysis framework

AI Agent System

Purpose: Define ingestion, monitoring, review, and analysis points for AI agents to pass learnings and context changes to the system.

For AI Agents: This document describes HOW YOU interact with and update the KENL system.

🎯 System Overview

graph TB
    subgraph Ingestion["📥 Ingestion Layer"]
        I1[Session Start]
        I2[Context Load]
        I3[State Validation]
    end

    subgraph Monitoring["📊 Monitoring Layer"]
        M1[Activity Tracking]
        M2[Decision Points]
        M3[Outcome Recording]
    end

    subgraph Review["🔍 Review Layer"]
        R1[Session Analysis]
        R2[Pattern Detection]
        R3[Improvement Identification]
    end

    subgraph Update["♻️ Update Layer"]
        U1[Context Updates]
        U2[Document Revision]
        U3[Knowledge Storage]
    end

    Ingestion --> Monitoring
    Monitoring --> Review
    Review --> Update
    Update --> |Next Session| Ingestion

    style Ingestion fill:#4dabf7,color:#fff
    style Monitoring fill:#ffd43b,color:#000
    style Review fill:#845ef7,color:#fff
    style Update fill:#51cf66,color:#000
Loading

📥 Phase 1: Ingestion (Session Start)

Primary Orientation: bump.md Protocol

NEW: High-Mass Context Routing

The bump.md system provides single-file orientation with accumulated context. Use this as your primary entry point:

Orientation Flow:

1. bump.md (systemwide) → High-mass context + task routing
   ↓
2. {project}/bump.md (if applicable) → Project-specific focus
   ↓
3. Supplemental files below → Detailed environment data

Momentum Equation:

  • Mass = Accumulated context in bump.md (frameworks, history, state)
  • Velocity = User's simple instruction ("check bump.md and proceed")
  • Result = Large stable output without extensive back-and-forth

YOU MUST Read These Files (In Order):

Primary (START HERE):

  1. bump.md - High-mass orientation, task routing, system context

Supplemental (after bump.md): 2. CURRENT-STATE.md - Detailed environment snapshot 3. RECENT-WORK.md - Last session's work and context 4. NEXT-STEPS.md - Immediate actionable tasks 5. QUICK-REFERENCE.md - Common paths and commands

Context Validation Checklist

✅ CTF FLAG CAPTURE PROTOCOL + bump.md Verification

Before proceeding, validate these expectations:

From bump.md "Current State" section:
- [ ] System status matches documented state
- [ ] "What's Working" items verified
- [ ] "What's Not Working" items acknowledged
- [ ] Critical alerts reviewed
- [ ] Your Mission is clear and understood

From environment validation:
- [ ] Branch name matches documented state
- [ ] Platform matches (Windows/Linux/CI)
- [ ] Active module context is correct
- [ ] Last ATOM tag sequence is valid
- [ ] No unexpected file changes since last session

Apply Tomorrow's Test: "Does documented state match reality?"

IF Context Mismatch:

IF: Documented state ≠ Reality
THEN:
  1. Stop current task
  2. Update bump.md "Current State" section with actual state
  3. Mark unknowns explicitly (don't fabricate)
  4. Document discrepancy in latest Work Session
  5. Update CURRENT-STATE.md as supplemental detail
  6. Flag for human review if significant
  7. Apply Tomorrow's Test before continuing

📊 Phase 2: Monitoring (During Work)

Peripheral Vision Protocol (Proactive Issue Flagging)

CRITICAL: Flag anomalies even when not directly related to current task.

"Peripheral vision" observations to ALWAYS flag:

Observation Type Priority Action
Incorrect file extension (e.g., .sh.txt instead of .sh) Medium Flag immediately, offer fix
Typos in filenames or code Low Note in session, batch fix later
Security issues (credentials, keys) CRITICAL Stop work, flag immediately
Broken links in documentation Medium Add to NEXT-STEPS.md
Missing files referenced in docs High Investigate, document in KNOWN-ISSUES.md
Version mismatches (documented vs actual) High Update CURRENT-STATE.md
Deprecated patterns in new code Medium Suggest modern alternative
CTF flag failures (state mismatch) High Investigate before proceeding

Flagging Format:

⚠️ PERIPHERAL OBSERVATION
Type: [Incorrect Extension | Typo | Security | etc.]
Priority: [CRITICAL | High | Medium | Low]
Location: [file:line or description]
Issue: [Brief description]
Suggested Fix: [If obvious]
Impact: [Minimal | Could cause issues | Blocks work]

Example:

⚠️ PERIPHERAL OBSERVATION
Type: Incorrect Extension
Priority: Medium
Location: scripts/build-recovery-vault.sh.txt
Issue: Bash script has .txt extension, won't execute properly
Suggested Fix: Rename to .sh, make executable
Impact: Script won't run without manual intervention

Activity Tracking Points

Track every decision with ATOM tags:

Action Type ATOM Format Example
Research ATOM-RESEARCH-YYYYMMDD-NNN ATOM-RESEARCH-20251126-001
Configuration ATOM-CFG-YYYYMMDD-NNN ATOM-CFG-20251126-002
Documentation ATOM-DOC-YYYYMMDD-NNN ATOM-DOC-20251126-003
Decision ATOM-DECISION-YYYYMMDD-NNN ATOM-DECISION-20251126-004
Problem ATOM-PROBLEM-YYYYMMDD-NNN ATOM-PROBLEM-20251126-005
Solution ATOM-SOLUTION-YYYYMMDD-NNN ATOM-SOLUTION-20251126-006
Peripheral Issue ATOM-PERIPHERAL-YYYYMMDD-NNN ATOM-PERIPHERAL-20251127-001

SAIF Checkpoint Protocol

Create SAIF flags at key decision points:

SAIF-{ACTION}-{YYYYMMDD}-{NNN}

Examples:
- SAIF-VALIDATE-20251126-001: Pre-work validation complete
- SAIF-CHECKPOINT-20251126-002: Mid-task checkpoint
- SAIF-COMPLETE-20251126-003: Task completion verified
- SAIF-HANDOVER-20251126-001: Context prepared for next session

Decision Documentation Format

## Decision: [Brief Title]

**ATOM:** ATOM-DECISION-YYYYMMDD-NNN

**Context:**
- What prompted this decision
- Available options considered

**Decision:**
- Chosen approach
- Rationale

**Outcome:**
- Result of implementation
- Lessons learned

**Impact:**
- Files affected
- Future considerations

🔍 Phase 3: Review (Session End)

Session Analysis Checklist

YOU MUST complete before ending session:

✅ SESSION END PROTOCOL

Primary handover:
- [ ] bump.md updated with new Work Session entry (at TOP)
- [ ] bump.md "Current State" section reflects final state
- [ ] bump.md "Your Mission" updated if task changed
- [ ] All changes committed via report_progress

Supplemental documentation:
- [ ] CURRENT-STATE.md updated with detailed environment state
- [ ] RECENT-WORK.md updated with session summary
- [ ] NEXT-STEPS.md updated with remaining tasks
- [ ] ATOM tags logged for all significant actions
- [ ] SAIF-HANDOVER flag dropped if work continues

Tomorrow's Test Applied:
- [ ] Next instance can orient from bump.md alone
- [ ] Claims are honest and verifiable
- [ ] Unknowns marked explicitly, not fabricated

Pattern Detection

Document recurring patterns observed:

Pattern Type Where to Document Action
Coding convention .github/copilot-instructions.md Add rule
Common error claude-landing/KNOWN-ISSUES.md Document fix
Workflow improvement claude-landing/AGENT-FACING-CONTENT-DESIGN.md Add pattern
Command/path claude-landing/QUICK-REFERENCE.md Add entry

Improvement Identification

If you discover something that would help future sessions:

## Learning: [Brief Title]

**Category:**
- [ ] Coding convention
- [ ] Build/test command
- [ ] File location
- [ ] Workflow pattern
- [ ] Tool usage

**Discovery:**
What you learned

**Evidence:**
File:line or commit hash

**Recommendation:**
How to apply this learning

♻️ Phase 4: Update (Knowledge Integration)

Context Update Protocol

Update these files based on session work:

File Update When What to Update
bump.md Every session Work Sessions (top), Current State, Your Mission
{project}/bump.md Project work Project-specific state, task progress
CURRENT-STATE.md Every session Detailed environment snapshot (supplements bump.md)
RECENT-WORK.md Every session Summary, outcomes, next actions
NEXT-STEPS.md Tasks change Priority, status, blockers
QUICK-REFERENCE.md New paths/commands discovered Commands, paths, files
HARDWARE.md Hardware context changes Specs, configurations

Document Revision Protocol

When updating documentation:

✅ DOCUMENTATION UPDATE CHECKLIST

- [ ] Update frontmatter date/atom tag
- [ ] Preserve existing content structure
- [ ] Add new content in appropriate section
- [ ] Update cross-references if paths change
- [ ] Verify links still work
- [ ] Run pre-commit validation

Knowledge Storage via store_memory

Use store_memory tool for facts that help future sessions:

Good candidates for store_memory:

  • Build/test commands verified to work
  • File locations for key functionality
  • Naming conventions not obvious from code
  • Dependency relationships between modules
  • Common error fixes

Format:

Subject: [1-2 words]
Fact: [<200 chars, actionable]
Citations: [file:line or "User input: ..."]
Reason: [Why this helps future tasks]
Category: [bootstrap_and_build | user_preferences | general | file_specific]

🔄 Continuous Learning Cycle

Every Session Must:

  1. INGEST - Read context files, validate state
  2. TRACK - Log ATOM tags for decisions
  3. CHECKPOINT - Drop SAIF flags at key points
  4. REVIEW - Analyze session outcomes
  5. UPDATE - Revise documentation with learnings
  6. HANDOVER - Prepare context for next session

Cross-Session Knowledge Flow

graph LR
    S1[Session N] --> H1[Handover Docs]
    H1 --> S2[Session N+1]
    S2 --> H2[Handover Docs]
    H2 --> S3[Session N+2]

    S1 --> K1[(Knowledge Store)]
    S2 --> K1
    S3 --> K1

    K1 --> |Informs| S2
    K1 --> |Informs| S3

    style K1 fill:#845ef7,color:#fff
    style H1 fill:#51cf66,color:#000
    style H2 fill:#51cf66,color:#000
Loading

📁 Key Files Reference

Agent Context Files (claude-landing/)

File Purpose Update Frequency
bump.md Primary orientation & task routing Every session
{project}/bump.md Project-specific orientation During project work
CURRENT-STATE.md Detailed environment snapshot Every session
RECENT-WORK.md Last session summary Every session
NEXT-STEPS.md Immediate tasks When tasks change
QUICK-REFERENCE.md Commands/paths When discovered
AI-AGENT-SYSTEM.md This file - framework details Rarely
AGENT-FACING-CONTENT-DESIGN.md Writing patterns When patterns evolve

System Knowledge Files

File Purpose Update Frequency
ATOM-REGISTER.md ATOM tag tracking Every session
.github/copilot-instructions.md Agent rules When conventions change
CONTRIBUTING.md Contribution guidelines Stable
GETTING-STARTED.md User entry point Stable

🚨 Error Recovery Protocol

IF: Session interrupted unexpectedly

THEN:
1. Note last known state
2. Check git status for uncommitted changes
3. Update CURRENT-STATE.md with interruption note
4. Create ATOM-INTERRUPT-YYYYMMDD-NNN tag
5. Document recovery steps in NEXT-STEPS.md

IF: Context files outdated

THEN:
1. Compare documented state vs reality
2. Update files to match reality
3. Note discrepancy with ATOM-SYNC-YYYYMMDD-NNN
4. Continue with corrected context

IF: Conflicting instructions

THEN:
1. Prioritize: copilot-instructions.md > CONTRIBUTING.md > module READMEs
2. Document conflict for human review
3. Follow highest-priority instruction
4. Note in RECENT-WORK.md for resolution

📊 Metrics and Success Criteria

Session Quality Indicators

Metric Good Needs Improvement
Context files updated ✅ All updated ❌ Some missed
ATOM tags logged ✅ For all decisions ❌ Sparse logging
SAIF flags dropped ✅ At checkpoints ❌ None created
Pre-commit passed ✅ Clean ❌ Failures
Handover prepared ✅ Next session ready ❌ Incomplete

Knowledge Quality Indicators

Metric Good Needs Improvement
Facts stored ✅ Actionable, verified ❌ Vague, unverified
Patterns documented ✅ With evidence ❌ Assumed
Cross-references ✅ Links work ❌ Broken links

🔄 Freshness Loop Protocol

Document Versioning

Every document MUST have in frontmatter:

---
title: Document Title
atom: ATOM-{TYPE}-YYYYMMDD-NNN
version: X.Y.Z  # Semantic versioning
created: YYYY-MM-DD
updated: YYYY-MM-DD  # On every edit
status: draft | production | deprecated | archived
hash: sha256-first-8-chars  # For integrity verification
---

Freshness Validation Loop

graph TD
    A[Start Session] --> B{Check Document Age}
    B --> |> 30 days| C[Flag for Review]
    B --> |<= 30 days| D[Continue]
    C --> E{Content Still Valid?}
    E --> |Yes| F[Update 'updated' date]
    E --> |No| G[Revise Content]
    G --> H[Increment Version]
    H --> I[Update Hash]
    F --> D
    I --> D
    D --> J[Proceed with Session]

    style C fill:#ffd43b,color:#000
    style G fill:#ff6b6b,color:#fff
Loading

Automatic Hash Verification

Generate hash for versioned files:

# Generate hash for a document (use the script for consistency)
./scripts/verify-doc-hashes.sh generate document.md

# Verify all hashes
./scripts/verify-doc-hashes.sh

# Update all hashes
./scripts/verify-doc-hashes.sh update

Hash should be updated:

  • On every content change
  • As part of commit process
  • Verified on session start

🎯 Visual Context Mapping

System State Visualization

Link to Obsidian graph view:

  • Primary vault: ~/.kenl opened as Obsidian vault
  • Graph view shows document relationships
  • Backlinks reveal cross-references

Dynamic Display Integration

PowerShell banner shows current context:

# Current context displayed on shell start
Show-KenlBanner
# Shows: Platform, Module, Playcard, ATOM trail, SAIF flags

Mermaid diagrams for system state:

  • Located in DOCUMENTATION-PATHWAYS.md
  • Shows pathway relationships
  • Updated when structure changes

Context Indicators

Indicator Location Purpose
🎮 KENL2 Shell prompt Gaming context active
💻 KENL3 Shell prompt Dev context active
⚙️ KENL0 Shell prompt System context active
📊 Dashboard Obsidian Current state overview

🛑 Graceful Shutdown Protocol

Normal Session End

1. Complete current atomic operation
2. Drop SAIF-COMPLETE flag
3. Update context files:
   - CURRENT-STATE.md (final state)
   - RECENT-WORK.md (session summary)
   - NEXT-STEPS.md (remaining work)
4. Commit via report_progress
5. Log: ATOM-SESSION-END-YYYYMMDD-NNN

Interrupted Session Recovery

IF: Session timeout / disconnection / error
THEN:
1. On next session start, check for:
   - Uncommitted changes (git status)
   - Incomplete operations (partial edits)
   - Missing SAIF-COMPLETE flag
2. Recovery actions:
   - Commit or stash partial work
   - Update CURRENT-STATE.md with interruption note
   - Create ATOM-RECOVER-YYYYMMDD-NNN
3. Resume from documented state

Error States

Error Detection Recovery
Timeout No activity > threshold Auto-save context
Conflict Merge errors Flag for human review
Loop detected Iteration counter Break and report
Missing file File not found Check DOCUMENT-INDEX.md

🔁 Circular Reference Protection

Loop Detection

Maximum iteration counters:

Operation Max Iterations Action on Exceed
Link following 10 Stop, report circular ref
Document updates 5 per session Warn, require confirmation
Cross-references 20 Flag for review
Pathway navigation 15 Stop, log warning

Detection Algorithm

visited = set()
def follow_reference(doc):
    if doc in visited:
        log("CIRCULAR_REF: " + doc)
        return ERROR
    visited.add(doc)
    # Continue processing

Recovery from Circular References

IF: Circular reference detected
THEN:
1. Log: ATOM-CIRCULAR-REF-YYYYMMDD-NNN
2. Stop current operation
3. Report in NEXT-STEPS.md:
   - Which documents form the loop
   - Suggested break point
4. Flag for human review
5. DO NOT attempt auto-fix

Prevention

  • Use DOCUMENT-INDEX.md as single source of truth
  • Validate links before adding
  • Run ./scripts/validate-links.sh on each commit
  • Prefer hierarchical over circular structures

ATOM: ATOM-AI-20251127-002 SAIF: SAIF-SYSTEM-DESIGN-20251126-001 Version: 2.2.0 Created: 2025-11-26 Updated: 2025-12-27 Changelog:

  • v2.2.0 (2025-12-27): Integrated bump.md as primary orientation system
  • v2.1.0 (2025-11-27): Added Peripheral Vision Protocol for proactive issue flagging

Quick Start for AI Agents

Session Start:

1. Read: bump.md (PRIMARY - high-mass context routing)
   - Verify "Current State" matches reality
   - Understand "Your Mission"
   - Review latest Work Session
2. Read: {project}/bump.md (if working on specific project)
3. Read: Supplemental files (CURRENT-STATE.md, RECENT-WORK.md, NEXT-STEPS.md)
4. Validate: Apply CTF flags + Tomorrow's Test
5. Plan: Outline approach before making changes

During Work:

1. Track: Log ATOM tags for decisions
2. Checkpoint: Drop SAIF flags at key points
3. Commit: Use report_progress frequently
4. Monitor: Apply Peripheral Vision Protocol (flag anomalies)

Session End:

1. Update bump.md:
   - Add new Work Session entry at TOP
   - Update "Current State" to final state
   - Apply Tomorrow's Test to all claims
2. Update: CURRENT-STATE.md, RECENT-WORK.md, NEXT-STEPS.md (supplemental)
3. Store: Use store_memory for reusable knowledge
4. Handover: Next instance can orient from bump.md alone

Frameworks Integration:

  • bump.md: Primary orientation (you start here)
  • ATOM: Decision tracking throughout work
  • SAIF: Staged checkpoints at key points
  • CTF: Validation (documented vs reality)
  • Tomorrow's Test: Honesty check before claims
  • Peripheral Vision: Flag issues proactively