Skip to content

Development Guide

Welcome to the HTM development documentation! This guide will help you contribute to HTM, whether you're fixing bugs, adding features, or improving documentation.

About HTM Development

HTM (Hierarchical Temporal Memory) is an open-source Ruby gem that provides intelligent memory management for LLM-based applications. The project is built with modern Ruby practices, comprehensive testing, and a focus on developer experience.

Project Values

  • Quality First: We prioritize correctness, performance, and maintainability
  • Test-Driven: All features must have comprehensive test coverage
  • Documentation Matters: Code is read more than it's written
  • Community-Driven: We welcome contributions from everyone
  • Never Forget: Like our memory philosophy, we preserve development history and context

Development Documentation

This development guide is organized into several sections:

Setup Guide

Learn how to set up your development environment, clone the repository, install dependencies, configure the database, and run the test suite.

Topics covered:

  • Cloning the repository
  • Installing Ruby and dependencies
  • Setting up TimescaleDB for development
  • Configuring Ollama for embeddings
  • Running tests and examples
  • Development tools and rake tasks
  • Troubleshooting common setup issues

Testing Guide

Understand HTM's testing philosophy, learn how to write tests, and discover best practices for maintaining test quality.

Topics covered:

  • Test suite organization
  • Running tests (unit, integration, all)
  • Writing new tests
  • Test helpers and fixtures
  • Mocking and stubbing strategies
  • Test coverage expectations
  • CI/CD integration
  • Testing best practices

Contributing Guide

Everything you need to know about contributing code, documentation, or bug reports to HTM.

Topics covered:

  • How to contribute (code, docs, bugs)
  • Finding issues to work on
  • Development workflow (fork, branch, commit, PR)
  • Code style guidelines
  • Commit message conventions
  • Pull request process
  • Code review expectations
  • Documentation requirements

Rake Tasks Reference

Complete reference for all 44 HTM rake tasks covering database management, documentation, file loading, background jobs, and tag management.

Topics covered:

  • Database tasks (htm:db:*) - setup, migrations, maintenance
  • Documentation tasks (htm:doc:*) - YARD, MkDocs, diagrams
  • File loading tasks (htm:files:*) - load, sync, unload files
  • Job tasks (htm:jobs:*) - process embeddings, tags, propositions
  • Tag tasks (htm:tags:*) - visualization and management
  • Common workflows and examples
  • Troubleshooting guide

Database Schema

Deep dive into HTM's database architecture, tables, indexes, and TimescaleDB optimization strategies.

Topics covered:

  • Complete schema reference
  • Entity-Relationship diagrams
  • Table definitions and column details
  • Indexes and constraints
  • Views and functions
  • TimescaleDB hypertables
  • Compression policies
  • Migration strategies

Quick Start for Contributors

Want to jump right in? Here's the fastest path to contributing:

1. Set Up Your Environment

# Clone the repository
git clone https://github.com/madbomber/htm.git
cd htm

# Install dependencies
bundle install

# Configure database (see setup guide)
source ~/.bashrc__tiger

# Verify setup
rake db_test

2. Run the Tests

# Run all tests
rake test

# Run specific test file
ruby test/htm_test.rb

# Run integration tests
ruby test/integration_test.rb

3. Make Your Changes

# Create a feature branch
git checkout -b feature/your-feature-name

# Make your changes
# ... edit files ...

# Run tests to verify
rake test

# Commit with descriptive message
git commit -m "Add feature: your feature description"

4. Submit a Pull Request

# Push to your fork
git push origin feature/your-feature-name

# Open a pull request on GitHub
# Include description of changes and any related issues

See the Contributing Guide for detailed instructions.

Development Workflow

HTM follows a streamlined development workflow:

Branch Strategy

  • main: Stable, production-ready code
  • Feature branches: feature/description for new features
  • Bug fix branches: fix/description for bug fixes
  • Documentation branches: docs/description for documentation updates

Pull Request Process

  1. Fork and clone the repository
  2. Create a branch from main
  3. Make your changes with tests
  4. Run the test suite to verify
  5. Push to your fork and create a PR
  6. Respond to review feedback and iterate
  7. Merge after approval

Code Review Standards

All pull requests must:

  • Pass the test suite (100% pass rate)
  • Maintain or improve test coverage
  • Follow Ruby style guidelines
  • Include documentation updates
  • Have clear commit messages
  • Be reviewed by at least one maintainer

Getting Help

Documentation

Community Resources

Common Questions

Q: Where do I start if I'm new to the project?

A: Check out issues labeled good-first-issue on GitHub. These are specifically chosen to be approachable for new contributors.

Q: How do I run tests without a database?

A: Unit tests (like test/htm_test.rb) don't require a database. Integration tests require TimescaleDB. See the Testing Guide for details.

Q: What's the preferred debugging approach?

A: HTM uses the debug_me gem for debugging. See examples in the codebase and avoid using puts for debugging.

Q: How do I add new database columns or tables?

A: See the Database Schema guide for migration strategies and best practices.

Code of Conduct

HTM is committed to providing a welcoming and inclusive environment for all contributors. We expect all participants to:

  • Be respectful: Treat everyone with respect and kindness
  • Be inclusive: Welcome diverse perspectives and backgrounds
  • Be collaborative: Work together toward common goals
  • Be professional: Keep discussions focused and constructive
  • Be patient: Remember that everyone was a beginner once

Unacceptable behavior includes harassment, discrimination, or any conduct that creates an unsafe or unwelcoming environment.

Development Philosophy

HTM's development is guided by several key principles:

Never Forget (But Evolve)

Just like HTM's memory philosophy, we preserve development history and context. However, we're not afraid to evolve and improve:

  • Git history is sacred - no force pushes to main
  • Deprecate before removing - give users time to adapt
  • Document breaking changes clearly
  • Maintain backward compatibility when possible

Test Everything

Every feature must have comprehensive tests:

  • Unit tests: Test individual methods in isolation
  • Integration tests: Test full workflows with real database
  • Edge cases: Test error conditions and boundaries
  • Performance: Monitor memory usage and query performance

Document as You Go

Documentation is part of the feature:

  • Add inline comments for complex logic
  • Update API docs for public methods
  • Include examples in documentation
  • Update guides when behavior changes

Iterate and Improve

We value continuous improvement:

  • Refactor for clarity and performance
  • Review and update old code
  • Learn from mistakes and share lessons
  • Celebrate improvements, no matter how small

Project Structure

Understanding the codebase structure:

HTM Project Structure

Tools and Technologies

HTM is built with modern Ruby tools:

Core Technologies

  • Ruby 3.0+: Modern Ruby with pattern matching and better performance
  • PostgreSQL 17: Robust relational database
  • TimescaleDB: Time-series optimization for PostgreSQL
  • pgvector: Vector similarity search
  • RubyLLM: LLM client library for embeddings
  • Ollama: Local embedding generation

Development Tools

  • Minitest: Testing framework
  • Minitest Reporters: Beautiful test output
  • Rake: Task automation
  • Bundler: Dependency management
  • debug_me: Debugging utility
  • MkDocs: Documentation generation

Optional Tools

  • VSCode: Popular editor with Ruby extensions
  • RuboCop: Ruby style checker (future)
  • SimpleCov: Code coverage (future)
  • YARD: Documentation generator (future)

Next Steps

Ready to contribute? Here's where to go next:

  1. Setup Your Environment: Clone the repo and get everything running
  2. Understand the Tests: Learn how to write and run tests
  3. Read Contributing Guidelines: Learn our workflow and standards
  4. Explore the Schema: Understand the database architecture

Thank You

Thank you for your interest in contributing to HTM! Every contribution, whether it's code, documentation, bug reports, or ideas, helps make HTM better for everyone.

We look forward to working with you!

Maintained by: Dewayne VanHoozer

License: MIT License