Skip to content

🤖 Agent Context: KotaDB Standalone Project

⚠️ IMPORTANT: This is a Standalone Project

KotaDB is a complete, independent project within the broader kota_md workspace.

When working on KotaDB: - Treat this as a separate repository with its own lifecycle - All work should be contained within this directory - This project has its own documentation, tests, and deployment - Use the standalone execution tools: ./run_standalone.sh

🎯 Project Status: Storage Engine Complete

✅ All 6 Risk Reduction Stages Complete - Stage 1: Test-Driven Development (-5.0 risk) - Stage 2: Contract-First Design (-5.0 risk) - Stage 3: Pure Function Modularization (-3.5 risk) - Stage 4: Comprehensive Observability (-4.5 risk) - Stage 5: Adversarial Testing (-0.5 risk) - Stage 6: Component Library (-1.0 risk)

✅ FileStorage Implementation Complete - Production-ready file-based storage engine - Full Stage 6 wrapper composition applied - Integration tests and documentation complete

Total Risk Reduction: -19.5 points (99% success rate) Current Phase: Ready for index implementation

📁 Project Structure

kota-db/
├── AGENT_CONTEXT.md     ← You are here
├── README.md            ← Project overview
├── STANDALONE.md        ← Standalone usage guide
├── run_standalone.sh    ← Primary execution tool
├── Cargo.toml          ← Rust project configuration
├── .gitignore          ← Git ignore rules
├── src/                ← Source code
├── tests/              ← Test suites
├── docs/               ← Comprehensive documentation
├── examples/           ← Usage examples
├── benches/            ← Performance benchmarks
└── handoffs/           ← Development history

🚀 Quick Start for Agents

# Get project status
./run_standalone.sh status

# Run tests
./run_standalone.sh test

# See Stage 6 demo
./run_standalone.sh demo

# Build project
./run_standalone.sh build

🏗️ Architecture Principles

1. Component Library Approach

  • Validated Types: Compile-time safety
  • Builder Patterns: Fluent APIs
  • Wrapper Components: Automatic best practices

2. Risk Reduction First

  • Every component designed to prevent failures
  • Comprehensive testing at all levels
  • Observable, debuggable, maintainable

3. Pure Functions + Contracts

  • Clear interfaces with pre/post conditions
  • Immutable data structures where possible
  • Predictable, testable behavior

📋 Current Implementation Status

✅ Foundation Complete - All core traits and contracts defined - Validation layer implemented - Observability infrastructure ready - Component library functional

✅ FileStorage Implementation Complete - src/file_storage.rs - Production-ready storage engine - create_file_storage() - Factory with all Stage 6 wrappers - tests/file_storage_integration_test.rs - Comprehensive tests - examples/file_storage_demo.rs - Usage demonstration

🔄 Ready for Next Phase - Index implementations (using Stage 6 metered wrappers) - Query engine (leveraging pure functions) - CLI integration (builder patterns)

🎯 For New Agents: Essential Reading

  1. Read handoffs/README.md - Understand project history
  2. Read docs/architecture/stage6_component_library.md - Core architecture
  3. Run ./run_standalone.sh demo - See components in action
  4. Check docs/api/quick_reference.md - Development patterns

🚨 Critical Guidelines

DO:

  • Use the component library (builders, wrappers, validated types)
  • Follow the 6-stage methodology principles
  • Add comprehensive tests for new features
  • Use the standalone execution tools
  • Maintain observability and validation

DON'T:

  • Break the risk reduction achievements
  • Bypass validation or safety mechanisms
  • Add dependencies without careful consideration
  • Ignore the existing architectural patterns
  • Work outside this directory structure

💡 Development Philosophy

"Prevention is better than detection. The component library approach means bugs are caught at compile time, not runtime."

This project prioritizes: 1. Safety - Prevent invalid states 2. Reliability - 99% success rate through risk reduction 3. Maintainability - Clear contracts and pure functions 4. Performance - When safety is ensured 5. Usability - Builder patterns and fluent APIs

Remember: KotaDB is designed to be a production-ready database for distributed human-AI cognition. Every design decision prioritizes safety, reliability, and maintainability.