Agent Logs Starter Kit

A universal, cross-platform logging system for AI agents.

Overview

This starter kit provides a robust and universal logging scaffold for AI agents. Capturing AI interactions is crucial for traceability, auditability, and continuity. This system is designed to be simple, machine-readable, and extensible.

Logs are stored as Markdown files with YAML front matter, making them easy to parse for both humans and AIs.

Features

• Cross-Platform: Supports macOS, Linux, and Windows (with PowerShell 7+).
• Structured Logging: Uses Markdown with YAML front matter for easy parsing.
• Log Categories: Organizes logs into incidents, changes, successes, notes, and daily summaries.
• Automation: Includes Makefiles and a PowerShell script for common tasks.
• Backup and Restore: Built-in commands for backing up and restoring logs.

Documentation

For detailed documentation on the PowerShell scripts and Makefiles, please see the guides below:

• PowerShell Guide: A comprehensive guide for the AgentLogs.ps1 script.
• Makefile Guide: A detailed guide for the Makefile.linux and Makefile.macos files.

Getting Started

Prerequisites

• macOS/Linux: make
• Windows: PowerShell 7+

Installation

1. Clone the repository:

   git clone https://github.com/your-username/agent-logs-starter-kit-v3.git
   cd agent-logs-starter-kit-v3

2. Initialize the log directories for your platform:
   • macOS: make -f Makefile.macos create_log_dirs
   • Linux: make -f Makefile.linux create_log_dirs
   • Windows: pwsh -File .\AgentLogs.ps1 New-LogDirs

Usage

Commands are run using make on macOS/Linux and pwsh on Windows.

Creating Logs

• Daily Log:
  • macOS: make -f Makefile.macos create_daily_log
  • Linux: make -f Makefile.linux create_daily_log
  • Windows: pwsh -File .\AgentLogs.ps1 New-DailyLog
• Incident Log:
  • macOS: make -f Makefile.macos create_incident_log
  • Linux: make -f Makefile.linux create_incident_log
  • Windows: pwsh -File .\AgentLogs.ps1 New-IncidentLog
• Change Log:
  • macOS: make -f Makefile.macos create_change_log
  • Linux: make -f Makefile.linux create_change_log
  • Windows: pwsh -File .\AgentLogs.ps1 New-ChangeLog
• Success Log:
  • macOS: make -f Makefile.macos create_success_log
  • Linux: make -f Makefile.linux create_success_log
  • Windows: pwsh -File .\AgentLogs.ps1 New-SuccessLog
• Note Log:
  • macOS: make -f Makefile.macos create_note_log
  • Linux: make -f Makefile.linux create_note_log
  • Windows: pwsh -File .\AgentLogs.ps1 New-NoteLog

Managing Logs

• List Logs:
  • macOS: make -f Makefile.macos list_logs
  • Linux: make -f Makefile.linux list_logs
  • Windows: pwsh -File .\AgentLogs.ps1 Get-Logs
• Backup Logs:
  • macOS: make -f Makefile.macos backup_logs
  • Linux: make -f Makefile.linux backup_logs
  • Windows: pwsh -File .\AgentLogs.ps1 Backup-Logs
• Clean Old Logs (Dry Run):
  • macOS: make -f Makefile.macos clean_old_logs
  • Linux: make -f Makefile.linux clean_old_logs
  • Windows: pwsh -File .\AgentLogs.ps1 Remove-OldLogs -DryRun
• Clean Old Logs (Execute):
  • macOS: make -f Makefile.macos clean_old_logs_execute
  • Linux: make -f Makefile.linux clean_old_logs_execute
  • Windows: pwsh -File .\AgentLogs.ps1 Remove-OldLogs

For AI Agents

This repository includes two key resources for AI agents:

1. A Natural Language Guide for AI Agents: A comprehensive, conversational guide that explains the "why" behind the logging system and provides a conceptual framework for its use. It is highly recommended that you read this guide first to gain a deeper understanding of the repository's purpose.
2. ai_instructions.yml: A machine-readable instruction file that provides the specific, structured commands for all available actions.

To get started, we recommend reading the guide and then using the ai_instructions.yml file for automated setup and operation.

Testing

This project includes a test suite for the Makefile.linux file. To run the tests, execute the following command:

./tests/test_makefile.sh

Integrations

See the integrations directory for agent-specific guidance.

Contributing

Contributions are welcome! Please read our CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

License

This project is licensed under the MIT License - see the LICENSE file for details.