🤖 Session ID Quick Reference for AI Agents

🚀 Quick Start

Read Current Session (Fastest Way)

// Read the JSON file - fastest for AI agents
const sessionData = JSON.parse(readFile('docs/data/sessionID.json'));
const currentID = sessionData.current.sessionID;  // "11.25.1.1"

JSON Structure:

{
  "current": {
    "sessionID": "11.25.1.1",
    "month": 11,
    "year": 25,
    "mainSession": 1,
    "subSession": 1,
    "date": "November 18, 2025",
    "time": "11:00 AM EST",
    "description": "Session ID system implementation"
  }
}

📝 When to Increment

Increment subSession (Same Day Work)

// When to do: Same day, different task/break
const newSessionID = `${month}.${year}.${mainSession}.${subSession + 1}`;
// Example: 11.25.1.1 → 11.25.1.2

Triggers:

• Starting new conversation thread
• Moving to different major task
• After significant break (> 2 hours)
• Creating new batch of related docs

Increment mainSession (New Day/Milestone)

// When to do: New day or major milestone
const newSessionID = `${month}.${year}.${mainSession + 1}.1`;
// Example: 11.25.1.5 → 11.25.2.1

Triggers:

• Starting new day of work
• Beginning new major phase/milestone
• Completing major feature set

Reset (New Month)

// When to do: New month starts
const newSessionID = `${newMonth}.${year}.1.1`;
// Example: 11.25.5.3 → 12.25.1.1

🔄 Update Workflow

Step 1: Read Current Session

const sessionData = JSON.parse(readFile('docs/data/sessionID.json'));
const { month, year, mainSession, subSession } = sessionData.current;

Step 2: Determine New Session ID

const currentDate = new Date();
let newSessionID;

if (currentDate.getMonth() + 1 !== month) {
  // New month - reset
  newSessionID = `${currentDate.getMonth() + 1}.${year}.1.1`;
} else if (isNewDay() || isMajorMilestone()) {
  // New day or milestone - increment main
  newSessionID = `${month}.${year}.${mainSession + 1}.1`;
} else {
  // Same day continuation - increment sub
  newSessionID = `${month}.${year}.${mainSession}.${subSession + 1}`;
}

Step 3: Update Both Files

Update sessionID.json:

sessionData.current = {
  sessionID: newSessionID,
  month: newMonth,
  year: newYear,
  mainSession: newMain,
  subSession: newSub,
  date: formatDate(new Date()),
  time: formatTime(new Date()),
  description: "Your session description"
};

// Add to history
sessionData.history.unshift({
  sessionID: newSessionID,
  date: formatDate(new Date()),
  description: "Your session description",
  filesCreated: []
});

writeFile('docs/data/sessionID.json', JSON.stringify(sessionData, null, 2));

Update sessionID.md:

• Update "Current Session" section
• Update session history table
• Update "Last Updated" timestamp

💡 Best Practices

✅ DO:

• Read sessionID.json first (fastest)
• Update both JSON and MD files
• Add description to session history
• Use session ID in all doc frontmatter
• Check rules in sessionID.md if unsure

❌ DON'T:

• Skip reading session ID at start
• Update only one file
• Forget to increment when appropriate
• Use session ID without understanding context

📋 Usage Example

Complete Session Start Flow

// 1. Read current session
const sessionData = JSON.parse(readFile('docs/data/sessionID.json'));
console.log(`Current Session: ${sessionData.current.sessionID}`);

// 2. Check if increment needed
const shouldIncrement = checkIncrementRules();

// 3. Update if needed
if (shouldIncrement) {
  const newID = calculateNewSessionID(sessionData.current);
  updateSessionFiles(newID, "Description of this session");
}

// 4. Use in documentation
const docFrontmatter = `---
title: My New Documentation
sessionID: ${sessionData.current.sessionID}
created: ${new Date().toLocaleString()}
---`;

🔍 Quick Commands

# View current session (JSON)
cat docs/data/sessionID.json | jq '.current'

# View current session ID only
cat docs/data/sessionID.json | jq -r '.current.sessionID'

# View session history
cat docs/data/sessionID.json | jq '.history'

# View increment rules
cat docs/data/sessionID.json | jq '.rules'

# Read comprehensive docs
cat docs/sessionID.md

📚 Related Files

• docs/data/sessionID.json - Machine-readable current session (read this first!)
• docs/sessionID.md - Comprehensive documentation and rules
• docs/AGENTS.md - Full documentation system guide
• AGENTS.md - Root agent instructions

Last Updated: November 18, 2025 - 11:30 AM EST
Session ID: 11.25.1.1
For: AI Agents working with documentation system