Contributing to Memori¶

Thank you for your interest in contributing to Memori! This guide will help you get started.

Quick Start¶

Fork the repository on GitHub
Clone your fork locally
Install development dependencies
Set up test environment with API keys
Make your changes
Test with dual memory modes
Submit a pull request

Development Setup¶

Prerequisites¶

Python 3.8+
Git
OpenAI API key (for testing agents)
Optional: Azure OpenAI, Ollama, or other LLM providers

Installation¶

# Clone your fork
git clone https://github.com/YOUR_USERNAME/memori.git
cd memori

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

Environment Configuration¶

Create a .env file for development:

# Required for agent testing
OPENAI_API_KEY=sk-your-openai-key-here

# Optional: Azure OpenAI
AZURE_OPENAI_API_KEY=your-azure-key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT=gpt-4o
AZURE_API_VERSION=2024-02-01

# Optional: Custom endpoints (Ollama, etc.)
CUSTOM_BASE_URL=http://localhost:11434/v1
CUSTOM_API_KEY=not-required

Development Dependencies¶

The development installation includes: - pytest - Testing framework with async support - pytest-asyncio - Async testing support
- black - Code formatting - ruff - Fast Python linting - isort - Import sorting - mypy - Type checking - pre-commit - Git hooks for code quality - openai - Required for memory agents - litellm - Universal LLM interface

Project Structure¶

memori/
├── memori/              # Main package
│   ├── core/           # Core memory system and providers
│   │   ├── memory.py   # Main Memori class with dual modes
│   │   ├── providers.py # LLM provider configuration system
│   │   └── database.py # Database management
│   ├── config/         # Configuration management with Pydantic
│   ├── agents/         # Memory processing agents
│   │   ├── memory_agent.py      # Structured conversation processing
│   │   ├── conscious_agent.py   # Conscious-info memory transfer
│   │   └── retrieval_agent.py   # Memory Search Engine
│   ├── database/       # Database connectors and queries
│   ├── integrations/   # LLM provider wrappers (OpenAI, Anthropic)
│   ├── tools/          # Memory search tools for function calling
│   └── utils/          # Pydantic models and utilities
├── tests/              # Test suite with memory mode testing
├── docs/               # Documentation (MkDocs)
├── examples/           # Usage examples for features
├── demos/              # Interactive demonstrations
└── scripts/            # Development and maintenance scripts

Development Workflow¶

1. Code Style¶

We use black for code formatting, ruff for linting, and isort for imports:

# Format code
black memori/ tests/ examples/

# Sort imports
isort memori/ tests/ examples/

# Lint code
ruff check memori/ tests/ examples/

# Type checking
mypy memori/

# Run all quality checks
pre-commit run --all-files

2. Testing¶

Core Testing¶

# Run all tests
pytest

# Run with coverage
pytest --cov=memori --cov-report=html

# Run specific test categories
pytest tests/ -m "not integration"  # Unit tests only
pytest tests/ -m "integration"      # Integration tests only

# Test specific memory modes
pytest tests/test_memory_modes.py
pytest tests/test_agent_system.py

Testing Memory Modes¶

Test both conscious_ingest and auto_ingest modes:

# Test conscious ingest mode
pytest tests/test_conscious_ingest.py -v

# Test auto ingest mode  
pytest tests/test_auto_ingest.py -v

# Test combined mode
pytest tests/test_combined_modes.py -v

# Test provider configurations
pytest tests/test_providers.py -v

Manual Testing¶

Test with the examples to verify functionality:

# Test basic functionality
cd examples
python basic_usage.py

# Test dual memory modes
python personal_assistant.py
python personal_assistant_advanced.py

# Test provider configurations
python advanced_config.py

3. Documentation¶

Documentation is built with MkDocs and includes interactive examples:

# Install docs dependencies (if not already installed)
pip install -r docs/requirements.txt

# Serve docs locally (with live reload)
mkdocs serve

# Build docs for production
mkdocs build

# Test documentation examples
python docs/examples/test_examples.py

Contributing Guidelines¶

Code Quality¶

Follow PEP 8 - Use black for formatting and isort for imports
Add type hints - Use Python type annotations throughout
Write docstrings - Use Google-style docstrings with examples
Add tests - Maintain high test coverage, especially for memory modes
Update docs - Keep documentation current with features
Test providers - Verify compatibility with different LLM providers

Memory Mode Testing¶

When contributing features that affect memory modes:

Test Both Modes: Verify functionality with conscious_ingest and auto_ingest
Test Combined Mode: Ensure features work when both modes are enabled
Provider Compatibility: Test with OpenAI, Azure, and custom providers
Performance Impact: Consider token usage and API call implications

Commit Messages¶

Use conventional commit format with memory-specific scopes:

feat(memory): add vector search support for auto-ingest
fix(agents): resolve conscious agent startup issues
docs(modes): update dual memory mode examples
test(providers): add Azure OpenAI integration tests
perf(search): optimize memory retrieval performance

Scopes for Memori: - memory: Core memory functionality - agents: Memory processing agents
- providers: LLM provider system - modes: Conscious/auto ingest modes - config: Configuration management - database: Database operations - tools: Memory search tools - integrations: LLM wrapper integrations

Pull Requests¶

Create a feature branch from main
Make focused changes - One feature per PR
Add comprehensive tests for new functionality:
Unit tests for core logic
Integration tests for memory modes
Provider compatibility tests
Update documentation including:
API documentation
Usage examples
Configuration examples
Ensure CI passes - All tests, linting, and type checks
Test memory modes - Verify both conscious and auto ingest work
Consider backward compatibility - Don't break existing APIs

Documentation Standards¶

When updating documentation:

Include Code Examples: Provide working code snippets
Show Memory Modes: Demonstrate both conscious_ingest and auto_ingest
Provider Examples: Show configuration for different providers
Performance Notes: Include token usage and performance considerations
Update Architecture: Reflect current system design

Example documentation format:

def new_feature(param: str) -> Dict[str, Any]:
    """Brief description of the new feature.

    This feature works with both memory modes and all provider configurations.

    Args:
        param: Description of parameter

    Returns:
        Description of return value

    Examples:
        Basic usage:
        >>> memori = Memori(conscious_ingest=True)
        >>> result = memori.new_feature("example")

        With auto-ingest mode:
        >>> memori = Memori(auto_ingest=True)
        >>> result = memori.new_feature("example")

        With Azure provider:
        >>> config = ProviderConfig.from_azure(...)
        >>> memori = Memori(provider_config=config)
        >>> result = memori.new_feature("example")
    """

Types of Contributions¶

Bug Reports¶

Use the GitHub issue template and include: - Clear description of the bug - Steps to reproduce - Expected vs actual behavior - Memory mode being used (conscious_ingest, auto_ingest, or both) - Provider configuration (OpenAI, Azure, custom) - Environment details (Python version, OS, database) - Code snippet with minimal reproduction - Error messages and stack traces

Feature Requests¶

Before implementing a new feature: 1. Check existing issues - Avoid duplicates 2. Open a discussion - Propose the feature first 3. Consider memory modes - How will it work with both modes? 4. Provider compatibility - Will it work with all providers? 5. Wait for approval - Ensure it aligns with project goals

Documentation¶

Documentation improvements are always welcome: - Fix typos and grammar - Add examples for features - Update configuration guides - Improve dual memory mode explanations - Add provider setup tutorials - Translate to other languages

Testing¶

Help improve test coverage: - Add unit tests for untested code - Create integration tests for memory modes - Add provider compatibility tests - Test edge cases and error conditions - Add performance benchmarks - Test real-world scenarios

Development Areas¶

Priority areas for contribution:

Memory System¶

Vector search integration
Memory relationship analysis
Performance optimizations
Advanced filtering and categorization

Provider Support¶

New LLM provider integrations
Enhanced provider configuration
Custom endpoint support
Authentication improvements

Agent System¶

Custom agent development
Advanced memory processing
Multi-model support
Reasoning capabilities

Database Support¶

New database connectors
Cloud database optimization
Migration utilities
Performance tuning

Development Tips¶

Testing Memory Modes¶

Test your changes with both memory modes:

# Test conscious ingest mode
cd examples
python -c "
from memori import Memori
memori = Memori(conscious_ingest=True, verbose=True)
memori.enable()
print('Conscious ingest mode working')
"

# Test auto ingest mode
python -c "
from memori import Memori
from litellm import completion

memori = Memori(auto_ingest=True, verbose=True)
response = completion(
    model='gpt-4o-mini',
    messages=[{'role': 'user', 'content': 'Hello'}]
)
print('Auto ingest mode working')
"

# Test combined mode
python personal_assistant_advanced.py

Provider Testing¶

Test with different LLM providers:

# OpenAI (default)
export OPENAI_API_KEY="sk-..."
python examples/basic_usage.py

# Azure OpenAI
export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_ENDPOINT="https://..."
python examples/advanced_config.py

# Custom endpoint (Ollama)
python -c "
from memori import Memori
from memori.core.providers import ProviderConfig

config = ProviderConfig.from_custom(
    base_url='http://localhost:11434/v1',
    api_key='not-required',
    model='llama3'
)
memori = Memori(provider_config=config)
print('Custom provider working')
"

Database Testing¶

Test with different databases:

# SQLite (default)
python -c "from memori import Memori; m = Memori(); print('SQLite OK')"

# PostgreSQL (requires setup)
python -c "
from memori import Memori
m = Memori(database_connect='postgresql://user:pass@localhost/memori')
print('PostgreSQL OK')
"

# MySQL (requires setup)  
python -c "
from memori import Memori
m = Memori(database_connect='mysql://user:pass@localhost/memori')
print('MySQL OK')
"

Memory Inspection¶

Debug and inspect memory during development:

from memori import Memori

# Set up with verbose logging
memori = Memori(
    conscious_ingest=True,
    auto_ingest=True,
    verbose=True
)
memori.enable()

# Inspect memories
stats = memori.get_memory_stats()
print(f"Memory statistics: {stats}")

# Check short-term memory (conscious ingest)
short_term = memori.db_manager.get_short_term_memories(
    namespace=memori.namespace
)
print(f"Short-term memories: {len(short_term)}")

# Test auto-ingest context retrieval
context = memori._get_auto_ingest_context("test query")
print(f"Auto-ingest context: {len(context)} memories")

# Search by category
preferences = memori.search_memories_by_category("preference", limit=5)
print(f"Preferences: {len(preferences)}")

# Get all conscious-info labeled memories
conscious_memories = memori.search_memories_by_labels(["conscious-info"])
print(f"Conscious-info memories: {len(conscious_memories)}")

Performance Testing¶

Monitor performance impact of changes:

import time
from memori import Memori

# Measure startup time
start = time.time()
memori = Memori(conscious_ingest=True, auto_ingest=True)
memori.enable()
startup_time = time.time() - start
print(f"Startup time: {startup_time:.2f}s")

# Measure query time
start = time.time()
context = memori._get_auto_ingest_context("What are my preferences?")
query_time = time.time() - start
print(f"Query time: {query_time:.2f}s, Context size: {len(context)}")

# Token usage estimation
total_tokens = sum(len(str(memory)) for memory in context) // 4
print(f"Estimated tokens: {total_tokens}")

Architecture Guidelines¶

Code Organization¶

Separation of concerns - Each module has a clear purpose
Dependency injection - Use ProviderConfig for LLM dependencies
Error handling - Use custom exceptions with detailed context
Type safety - Full type annotations and Pydantic validation
Memory mode agnostic - Features should work with both modes

Memory System Design¶

Dual mode support - All features must work with conscious_ingest and auto_ingest
Provider agnostic - Support OpenAI, Azure, and custom endpoints
Structured data - Use Pydantic models for all memory operations
Categorization - Proper memory categorization (fact, preference, skill, context, rule)
Performance aware - Consider token usage and API call implications

Database Design¶

SQL in query modules - Centralized query management in database/queries/
Connection pooling - Efficient resource usage with SQLAlchemy
Migration support - Schema versioning for database updates
Multi-database - Support SQLite, PostgreSQL, MySQL, and cloud databases
Namespace isolation - Support for multi-tenant memory spaces

API Design¶

Simple interface - Minimal required configuration with sensible defaults
Pydantic validation - Type-safe data structures throughout
Error context - Detailed error information with troubleshooting hints
Backwards compatibility - Careful API evolution with deprecation warnings
Provider flexibility - Easy switching between LLM providers

Agent System Architecture¶

When working with the agent system:

Memory Agent: Focus on structured output processing with Pydantic
Conscious Agent: Simple transfer of conscious-info labeled memories
Memory Search Engine: Intelligent context retrieval for auto-ingest
Provider Integration: Ensure all agents work with configured providers

Testing Architecture¶

Unit tests - Test individual components in isolation
Integration tests - Test memory modes and provider combinations
Performance tests - Monitor token usage and response times
Mock external services - Use mock providers for CI/CD
Real provider tests - Optional tests with actual API keys

Getting Help¶

GitHub Discussions - Ask questions and share ideas about features
GitHub Issues - Report bugs and request features
Discord Community - Join us at https://www.gibsonai.com/discord
Documentation - Check docs for configuration and usage examples
Examples Directory - Working code examples for all major features
Email - Direct contact at noc@gibsonai.com for sensitive issues

Common Questions¶

Q: How do I test both memory modes? A: Use the examples in /examples/ that demonstrate both conscious_ingest and auto_ingest modes.

Q: Which provider should I use for testing? A: OpenAI GPT-4o-mini is recommended for development due to cost-effectiveness and reliability.

Q: How do I set up Azure OpenAI for testing? A: See the provider configuration examples in /examples/advanced_config.py.

Q: Why are my tests failing with "No API key"? A: Set up your .env file with the required API keys as shown in the setup section.

Q: How do I debug memory retrieval issues? A: Use verbose=True in your Memori configuration to see detailed logging.

Recognition¶

Contributors will be: - Listed in the project README and CHANGELOG - Credited in release notes for significant contributions - Invited to join the maintainers team (for ongoing contributors) - Featured in community highlights

Contribution Levels¶

Bug fixes: Listed in CHANGELOG
Feature additions: Featured in release notes
Documentation improvements: Recognized in community updates
Major contributions: Invited to maintainer discussions

Thank you for helping make Memori better! Your contributions help build the future of AI memory systems.