1  # CREATURE Project Intelligence
  2  
  3  This file captures important patterns, preferences, and project intelligence for the CREATURE project. It serves as a learning journal to document key insights that aren't obvious from the code alone.
  4  
  5  ## Go Language Conventions
  6  
  7  1. **Package Organization**
  8     - Follow standard Go package organization with `cmd`, `pkg`, and `internal` directories
  9     - Keep package names simple and descriptive
 10     - Use lowercase package names without underscores
 11  
 12  2. **Naming Conventions**
 13     - Use camelCase for variable names
 14     - Use PascalCase for exported functions, types, and variables
 15     - Use acronyms consistently (e.g., API, HTTP, JSON) and capitalize them properly (e.g., `apiClient` not `aPIClient`)
 16  
 17  3. **Error Handling**
 18     - Always check errors and handle them appropriately
 19     - Return errors rather than using panic
 20     - Use custom error types for specific error conditions
 21     - Consider using the `errors.Is` and `errors.As` functions for error checking
 22  
 23  4. **Concurrency Patterns**
 24     - Use goroutines judiciously
 25     - Prefer channels for communication between goroutines
 26     - Use sync.WaitGroup for waiting for goroutines to complete
 27     - Consider using context for cancellation and timeouts
 28  
 29  5. **Code Organization**
 30     - Keep functions small and focused
 31     - Group related functions together
 32     - Use interfaces to define behavior
 33     - Follow the principle of least privilege
 34  
 35  6. **Testing**
 36     - Write tests for all exported functions
 37     - Use table-driven tests where appropriate
 38     - Use testify for assertions if needed
 39     - Consider using subtests for related test cases
 40  
 41  ## Fish Shell Usage
 42  
 43  1. **Environment Variables**
 44     - Set environment variables using `set -x VARIABLE_NAME value`
 45     - Export variables using `set -gx VARIABLE_NAME value`
 46     - Access environment variables using `$VARIABLE_NAME`
 47  
 48  2. **Command Execution**
 49     - Use `and` and `or` for conditional execution
 50     - Use command substitution with `(command)`
 51     - Use process substitution with `<(command)`
 52  
 53  3. **Script Organization**
 54     - Use functions for reusable code
 55     - Use `function name` to define functions
 56     - Use `end` to close blocks
 57  
 58  4. **Error Handling**
 59     - Check exit status with `if test $status -eq 0`
 60     - Use `or` for fallback commands
 61  
 62  5. **Common Commands**
 63     - Build: `go build -o creature ./cmd/creature`
 64     - Run: `./creature`
 65     - Test: `go test ./...`
 66     - Clean: `go clean`
 67     - Get dependencies: `go mod tidy`
 68  
 69  ## Project-Specific Patterns
 70  
 71  1. **Thought DNA Model**
 72     - Six dimensions: Emergence, Coherence, Resilience, Intelligence, Efficiency, Integration
 73     - Each dimension ranges from -100 to 100
 74     - Dimensions are interconnected and influence each other
 75     - Balance across dimensions is key to successful emergence
 76  
 77  2. **Memory Management**
 78     - Each cell has a memory limit (default: 50,000 bytes)
 79     - Older memories are compressed when the limit is reached
 80     - Compression preserves essential information while reducing storage
 81     - Historical context influences future decisions
 82  
 83  3. **API Interaction**
 84     - OpenRouter API is used for language model capabilities
 85     - API key is required and stored in environment variable
 86     - Rate limiting must be respected
 87     - Implement backoff strategies for API failures
 88  
 89  4. **Data Persistence**
 90     - Colony state is stored in `eca_state.json`
 91     - Individual thoughts are stored in `data/thoughts/`
 92     - Plans are stored in `data/plans/`
 93     - Use consistent JSON structure for all stored data
 94  
 95  5. **Configuration Management**
 96     - Configuration is defined in `pkg/models/config.go`
 97     - Command-line flags override default values
 98     - Environment variables provide API credentials
 99     - Configuration is validated at startup
100  
101  ## Known Challenges
102  
103  1. **API Dependency**
104     - The system relies on OpenRouter API for core functionality
105     - API outages or rate limiting can disrupt simulation
106     - Consider implementing fallback mechanisms or caching
107  
108  2. **Performance Optimization**
109     - Batch processing helps manage computational load
110     - JSON serialization/deserialization can be expensive
111     - Memory compression algorithms need to balance preservation with efficiency
112     - Consider profiling to identify bottlenecks
113  
114  3. **Visualization Complexity**
115     - Terminal-based visualization has limitations
116     - Representing six dimensions visually is challenging
117     - Consider using color, symbols, and positioning to convey information
118     - Explore alternative visualization approaches for complex data
119  
120  ## Evolution of Project Decisions
121  
122  As the project evolves, document significant decisions and their rationale here:
123  
124  1. **Initial Architecture**: Cellular automata approach with six-dimensional Thought DNA model to explore emergent intelligence through simple, interacting cells.
125  
126  2. **JSON Storage**: Chose JSON for data persistence due to simplicity, human-readability, and ease of implementation, despite potential performance limitations for large datasets.
127  
128  3. **Terminal Visualization**: Initial visualization will be terminal-based for simplicity, with potential for more sophisticated visualization tools in the future.
129  
130  ## Tool Usage Patterns
131  
132  1. **Development Workflow**
133     - Edit code in VSCode or preferred editor
134     - Build with `go build -o creature ./cmd/creature`
135     - Run with `./creature [flags]`
136     - Monitor output in terminal
137     - Analyze data using `jq` for JSON processing
138  
139  2. **Debugging Approaches**
140     - Use logging for runtime information
141     - Inspect JSON files for state analysis
142     - Use Go's built-in debugging tools
143     - Consider adding debug flags for verbose output
144  
145  3. **Performance Analysis**
146     - Use Go's profiling tools
147     - Monitor memory usage during simulation
148     - Track API call frequency and duration
149     - Measure simulation cycles per second