Contributing to CortexGraph¶

Thank you for your interest in contributing to CortexGraph! This guide will help you get started with development on Windows, Linux, or macOS.

Table of Contents¶

🚨 Help Needed: Windows & Linux Testers
Prerequisites
Platform-Specific Setup
Windows
Linux
macOS
Development Workflow
Testing
Code Style
Submitting Changes
Reporting Issues

🚨 Help Needed: Windows & Linux Testers¶

I develop CortexGraph on macOS and need help testing on Windows and Linux!

Why This Matters¶

While I've written platform-specific instructions based on best practices, I can't personally test: - Windows installation and setup - Windows path handling and environment variables - Linux distributions (Ubuntu, Fedora, Arch, etc.) - Platform-specific edge cases and bugs

What I Need Help With¶

High Priority 🔥¶

Installation Testing
Does uv tool install work smoothly?
Are the setup instructions clear and accurate?
Do the paths work correctly (~/.config/cortexgraph/ on Linux, C:/Users/.../ on Windows)?
Running the Server
Does cortexgraph command work after installation?
Do all 7 CLI commands work (cortexgraph-search, cortexgraph-maintenance, etc.)?
Can you connect via Claude Desktop or other MCP clients?
Testing Suite
Do all tests pass? (uv run python -m pytest)
Does coverage reporting work?
Are there any platform-specific test failures?
File Operations
Does JSONL storage work correctly?
Do file paths with spaces or special characters work?
Does the maintenance CLI (cortexgraph-maintenance) work?

Medium Priority¶

Development Workflow
Can you clone and set up for development?
Do ruff and mypy work correctly?
Can you run tests in your IDE/editor?
Edge Cases
Long file paths (Windows issue)
Non-ASCII characters in paths
Different filesystem types
Permission issues

How to Help¶

Quick Testing (30 minutes):

# Install and verify
uv tool install git+https://github.com/prefrontal-systems/cortexgraph.git
cortexgraph --version

# Run basic tests
cd $(mktemp -d)
cortexgraph-maintenance stats
cortexgraph-search "test" --verbose

Then report: - ✅ What worked - ❌ What failed (with error messages) - ⚠️ Any warnings or unexpected behavior - 💡 Suggestions for improving the docs

Full Testing (1-2 hours):

Follow the platform-specific setup guide in this file, then:

Install from source
Run the full test suite
Try creating memories and searching
Test consolidation feature
Report your findings

Where to Report¶

Open an issue with:

**Platform:** [Windows 11 / Ubuntu 22.04 / etc.]
**Test Type:** [Quick / Full]

**What I Tested:**
- [ ] Installation
- [ ] Running server
- [ ] CLI commands
- [ ] Test suite
- [ ] File operations

**Results:**
✅ Working: [list what worked]
❌ Failed: [list failures with errors]
⚠️ Issues: [list concerns or warnings]

**Logs:**

[paste relevant error messages or logs]

**Suggestions:**
[any improvements to docs or setup]

Current Status¶

Platform	Installation	Tests	CLI Tools	File Ops	Status
macOS	✅ Tested	✅ Passing	✅ Working	✅ Working	Fully tested
Windows	❓ Untested	❓ Unknown	❓ Unknown	❓ Unknown	Need testers!
Linux (Ubuntu)	❓ Untested	❓ Unknown	❓ Unknown	❓ Unknown	Need testers!
Linux (Fedora)	❓ Untested	❓ Unknown	❓ Unknown	❓ Unknown	Need testers!
Linux (Arch)	❓ Untested	❓ Unknown	❓ Unknown	❓ Unknown	Need testers!

Thank you for helping make CortexGraph work reliably across all platforms! 🙏

Prerequisites¶

Before you begin, ensure you have:

Python 3.10 or higher
Git
UV package manager (recommended) or pip

Platform-Specific Setup¶

Windows¶

1. Install Python¶

Download and install Python from python.org:

# Verify installation
python --version
# Should show Python 3.10 or higher

Important: During installation, check "Add Python to PATH"

2. Install Git¶

Download and install from git-scm.com

# Verify installation
git --version

3. Install UV Package Manager¶

# Using PowerShell (recommended)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or using pip
pip install uv

# Verify installation
uv --version

4. Clone the Repository¶

# Using Command Prompt or PowerShell
git clone https://github.com/prefrontal-systems/cortexgraph.git
cd cortexgraph

5. Set Up Development Environment¶

# Install dependencies (including dev dependencies)
uv sync --all-extras

# Verify installation
uv run python -c "import cortexgraph; print('CortexGraph installed successfully!')"

6. Configure Environment¶

# Copy example config
copy .env.example .env

# Edit .env with your preferred text editor
notepad .env

Windows-specific config (~/.config/cortexgraph/.env or project .env):

# Use Windows paths with forward slashes or escaped backslashes
CORTEXGRAPH_STORAGE_PATH=C:/Users/YourUsername/.config/cortexgraph/jsonl
# Or with escaped backslashes
# CORTEXGRAPH_STORAGE_PATH=C:\\Users\\YourUsername\\.config\\cortexgraph\\jsonl

# Optional: LTM vault path
LTM_VAULT_PATH=C:/Users/YourUsername/Documents/Obsidian/Vault

7. Running Tests on Windows¶

# Run all tests
uv run python -m pytest

# Run with coverage
uv run python -m pytest --cov=cortexgraph --cov-report=html

# Open coverage report
start htmlcov\index.html

# Run specific test file
uv run python -m pytest tests/test_consolidation.py -v

# Run tests matching a pattern
uv run python -m pytest -k "test_merge" -v

Common Windows Issues¶

Issue: ModuleNotFoundError

# Ensure you're in the project directory
cd path\to\cortexgraph

# Reinstall dependencies
uv sync --all-extras

Issue: Path too long errors

# Enable long paths in Windows 10/11
# Run as Administrator:
reg add HKLM\SYSTEM\CurrentControlSet\Control\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1 /f

Issue: Permission errors

# Run PowerShell as Administrator or use:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Linux¶

1. Install Python¶

Ubuntu/Debian:

sudo apt update
sudo apt install python3.10 python3.10-venv python3-pip git

# Verify installation
python3 --version

Fedora/RHEL:

sudo dnf install python3.10 python3-pip git

# Verify installation
python3 --version

Arch Linux:

sudo pacman -S python python-pip git

# Verify installation
python --version

2. Install UV Package Manager¶

# Using curl (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv

# Add to PATH (if needed)
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify installation
uv --version

3. Clone the Repository¶

git clone https://github.com/prefrontal-systems/cortexgraph.git
cd cortexgraph

4. Set Up Development Environment¶

# Install dependencies (including dev dependencies)
uv sync --all-extras

# Verify installation
uv run python -c "import cortexgraph; print('CortexGraph installed successfully!')"

5. Configure Environment¶

# Copy example config
cp .env.example .env

# Edit with your preferred editor
nano .env
# or
vim .env
# or
code .env  # VS Code

Linux-specific config (~/.config/cortexgraph/.env or project .env):

# Standard XDG paths
CORTEXGRAPH_STORAGE_PATH=~/.config/cortexgraph/jsonl

# Optional: LTM vault path
LTM_VAULT_PATH=~/Documents/Obsidian/Vault

# Decay parameters
CORTEXGRAPH_DECAY_MODEL=power_law
CORTEXGRAPH_PL_ALPHA=1.1
CORTEXGRAPH_PL_HALFLIFE_DAYS=3.0
CORTEXGRAPH_DECAY_BETA=0.6

# Thresholds
CORTEXGRAPH_FORGET_THRESHOLD=0.05
CORTEXGRAPH_PROMOTE_THRESHOLD=0.65

6. Running Tests on Linux¶

# Run all tests
uv run python -m pytest

# Run with coverage
uv run python -m pytest --cov=cortexgraph --cov-report=html

# Open coverage report
xdg-open htmlcov/index.html

# Run specific test file
uv run python -m pytest tests/test_consolidation.py -v

# Run tests matching a pattern
uv run python -m pytest -k "test_merge" -v

# Run tests in parallel (faster for large test suites)
uv run python -m pytest -n auto

Common Linux Issues¶

Issue: Permission denied

# Make sure scripts are executable
chmod +x .venv/bin/*

# Or use uv run instead
uv run cortexgraph --help

Issue: ModuleNotFoundError

# Ensure you're in the project directory
cd /path/to/cortexgraph

# Reinstall dependencies
uv sync --all-extras

Issue: Can't find Python 3.10+

# Ubuntu: Use deadsnakes PPA
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.10 python3.10-venv

# Or use pyenv
curl https://pyenv.run | bash
pyenv install 3.10.13
pyenv local 3.10.13

macOS¶

1. Install Homebrew (if not installed)¶

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Python and Git¶

brew install python@3.10 git

# Verify installation
python3 --version
git --version

3. Install UV Package Manager¶

# Using curl (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using Homebrew
brew install uv

# Verify installation
uv --version

4. Clone the Repository¶

git clone https://github.com/prefrontal-systems/cortexgraph.git
cd cortexgraph

5. Set Up Development Environment¶

# Install dependencies (including dev dependencies)
uv sync --all-extras

# Verify installation
uv run python -c "import cortexgraph; print('CortexGraph installed successfully!')"

6. Configure Environment¶

# Copy example config
cp .env.example .env

# Edit with your preferred editor
nano .env
# or
open -e .env  # TextEdit

macOS-specific config (~/.config/cortexgraph/.env or project .env):

# Standard macOS paths
CORTEXGRAPH_STORAGE_PATH=~/.config/cortexgraph/jsonl

# Optional: LTM vault path
LTM_VAULT_PATH=~/Documents/Obsidian/Vault

7. Running Tests on macOS¶

# Run all tests
uv run python -m pytest

# Run with coverage
uv run python -m pytest --cov=cortexgraph --cov-report=html

# Open coverage report
open htmlcov/index.html

# Run specific test file
uv run python -m pytest tests/test_consolidation.py -v

Development Workflow¶

Making Changes¶

Create a new branch:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

Make your changes following the code style guidelines below
Run tests to ensure nothing broke:

# All tests
uv run python -m pytest

# With coverage
uv run python -m pytest --cov=cortexgraph

Run linters:

# Check code style
uv run ruff check src/cortexgraph tests

# Format code
uv run ruff format src/cortexgraph tests

# Type checking
uv run mypy src/cortexgraph

Commit your changes:

git add .
git commit -m "feat: add new feature"
# or
git commit -m "fix: resolve bug in consolidation"

Commit Message Format¶

Use conventional commits:

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
test: - Adding or updating tests
refactor: - Code refactoring
chore: - Maintenance tasks
perf: - Performance improvements

Examples:

feat: add spaced repetition scheduling
fix: handle empty cluster in consolidation
docs: update installation guide for Windows
test: add tests for decay calculation edge cases

Project Structure (v1.2.0+)¶

The source code is organized into focused modules:

src/cortexgraph/
├── core/                       # Foundational algorithms
│   ├── __init__.py             # Exports all core functions
│   ├── decay.py                # Decay calculations
│   ├── similarity.py           # Similarity metrics (NEW)
│   ├── clustering.py           # Clustering logic
│   ├── consolidation.py        # Memory merging
│   ├── search_common.py        # Search validation (NEW)
│   ├── text_utils.py           # Text utilities (NEW)
│   ├── pagination.py           # Pagination helpers
│   └── scoring.py              # Score decisions
├── agents/                     # Multi-agent consolidation
│   ├── __init__.py             # Exports agents + get_storage
│   ├── storage_utils.py        # Storage access utility (NEW)
│   ├── base.py                 # Base agent class
│   ├── decay_analyzer.py       # Find at-risk memories
│   ├── cluster_detector.py     # Group similar memories
│   ├── semantic_merge.py       # Combine memory groups
│   ├── ltm_promoter.py         # Promote to LTM
│   └── relationship_discovery.py # Find cross-domain links
├── storage/                    # Storage backends
│   ├── jsonl_storage.py        # JSONL with batch operations
│   ├── sqlite_storage.py       # SQLite backend
│   ├── ltm_index.py            # LTM indexing
│   └── models.py               # Data models
├── tools/                      # MCP tool implementations
│   ├── search.py               # search_memory tool
│   ├── search_unified.py       # search_unified tool
│   └── ...                     # Other MCP tools
└── cli/                        # Command-line interfaces
    └── ...

Key Modules Added in v1.2.0¶

Module	Location	Purpose
`similarity.py`	`core/similarity.py`	Similarity metrics (`cosine_similarity`, `jaccard_similarity`, etc.)
`search_common.py`	`core/search_common.py`	Search validation (`SearchParams`, `validate_search_params`)
`text_utils.py`	`core/text_utils.py`	Text utilities (`truncate_content`)
`storage_utils.py`	`agents/storage_utils.py`	Storage access (`get_storage`)

Testing¶

Test Structure¶

Tests are organized in the tests/ directory:

tests/
├── test_consolidation.py    # Consolidation logic tests
├── test_decay.py             # Decay algorithm tests
├── test_decay_models.py      # Decay model tests
├── test_ltm_index.py         # LTM index tests
├── test_search_unified.py    # Unified search tests
└── test_storage.py           # Storage layer tests

Writing Tests¶

Follow these guidelines when writing tests:

Use descriptive names:

def test_merge_content_preserves_unique_information():
    """Test that content merging keeps unique info from all memories."""
    # Test implementation

Use fixtures for common setup:

@pytest.fixture
def sample_memories():
    """Create sample memories for testing."""
    return [
        Memory(id="mem-1", content="Test content 1"),
        Memory(id="mem-2", content="Test content 2"),
    ]

def test_something(sample_memories):
    # Use the fixture
    assert len(sample_memories) == 2

Test edge cases:

def test_merge_content_empty():
    """Test merging with empty list."""
    result = merge_content_smart([])
    assert result == ""

def test_merge_content_single():
    """Test merging with single memory."""
    memories = [Memory(id="1", content="Single")]
    result = merge_content_smart(memories)
    assert result == "Single"

Use parametrize for multiple cases:

@pytest.mark.parametrize("use_count,expected", [
    (1, 1.0),
    (5, 2.6),
    (10, 4.0),
])
def test_use_count_boost(use_count, expected):
    boost = calculate_boost(use_count)
    assert abs(boost - expected) < 0.1

Running Specific Tests¶

# Run a specific test file
uv run python -m pytest tests/test_consolidation.py

# Run a specific test
uv run python -m pytest tests/test_consolidation.py::test_merge_tags

# Run tests matching a pattern
uv run python -m pytest -k "consolidation"

# Run with verbose output
uv run python -m pytest -v

# Run with detailed output on failures
uv run python -m pytest -vv

# Stop on first failure
uv run python -m pytest -x

# Show local variables on failure
uv run python -m pytest -l

# Run tests in parallel (requires pytest-xdist)
uv run python -m pytest -n auto

Coverage Requirements¶

Aim for 80%+ code coverage for new features
Critical paths (decay, storage, consolidation) should have 95%+ coverage
Check coverage with:

uv run python -m pytest --cov=cortexgraph --cov-report=term-missing

Code Style¶

Python Style Guidelines¶

We use Ruff for linting and formatting (no Black):

# Check for style issues
uv run ruff check src/cortexgraph tests

# Auto-fix issues
uv run ruff check --fix src/cortexgraph tests

# Format code
uv run ruff format src/cortexgraph tests

Type Hints¶

All functions must have type hints:

# Good ✓
def calculate_score(use_count: int, last_used: int, strength: float) -> float:
    """Calculate memory score."""
    return (use_count ** 0.6) * math.exp(-0.0001 * time.time()) * strength

# Bad ✗
def calculate_score(use_count, last_used, strength):
    return (use_count ** 0.6) * math.exp(-0.0001 * time.time()) * strength

Run type checker:

uv run mypy src/cortexgraph

Docstrings¶

Use Google-style docstrings:

def merge_content_smart(memories: list[Memory]) -> str:
    """
    Intelligently merge content from multiple memories.

    Strategy:
    - If very similar (duplicates), keep the longest/most detailed version
    - If related but distinct, combine with clear separation
    - Preserve unique information from each memory

    Args:
        memories: List of memories to merge

    Returns:
        Merged content string

    Example:
        >>> memories = [Memory(id="1", content="Python is great")]
        >>> merge_content_smart(memories)
        'Python is great'
    """
    # Implementation

Code Organization¶

4-space indentation (no tabs)
Line length: 100 characters max

Module organization:

# Standard library imports
import time
from pathlib import Path

# Third-party imports
from pydantic import BaseModel

# Local imports
from ..storage.models import Memory
from ..config import get_config

Submitting Changes¶

Before Submitting¶

Ensure all tests pass:
```
uv run python -m pytest
```

Check code style:

uv run ruff check src/cortexgraph tests
uv run ruff format src/cortexgraph tests
uv run mypy src/cortexgraph

Update documentation if you:
Added a new feature
Changed an API
Modified configuration options
Add tests for new functionality

Creating a Pull Request¶

Push your branch:

git push origin feature/your-feature-name

Create PR on GitHub
PR Description should include:
What changed
Why the change was needed
How to test it
Any breaking changes

Example PR template:

## Description
Implement spaced repetition scheduling for memory review.

## Motivation
Users requested a way to get reminders for reviewing important memories
before they decay too much.

## Changes
- Add `calculate_next_review()` function to core/scheduling.py
- Add `get_review_queue()` MCP tool
- Add tests in tests/test_scheduling.py (100% coverage)
- Update README.md with usage examples

## Testing
- All existing tests pass
- Added 12 new tests for scheduling logic
- Tested manually with 100+ memories

## Breaking Changes
None - this is a new feature with no API changes.

Code Review Process¶

Maintainers will review your PR
Address any feedback
Once approved, your PR will be merged

Reporting Issues¶

Before Opening an Issue¶

Search existing issues to avoid duplicates
Try the latest version - your issue might be fixed
Gather information:
CortexGraph version (cortexgraph --version or check pyproject.toml)
Python version (python --version)
Operating system and version
Steps to reproduce

Bug Report Template¶

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce:
1. Install CortexGraph with `uv tool install...`
2. Configure with these settings: ...
3. Run command `...`
4. See error

**Expected behavior**
What you expected to happen.

**Actual behavior**
What actually happened.

**Environment:**
- OS: [e.g., Windows 11, Ubuntu 22.04, macOS 14]
- Python version: [e.g., 3.10.13]
- CortexGraph version: [e.g., 1.0.0]
- Installation method: [uv tool install / editable]

**Logs/Screenshots**

[Paste any error messages or logs here]

**Additional context**
Any other information that might help.

Feature Requests¶

**Feature description**
A clear description of the feature you'd like.

**Use case**
Why would this feature be useful? What problem does it solve?

**Proposed solution**
If you have ideas on how to implement it.

**Alternatives considered**
Other approaches you've thought about.

Getting Help¶

Documentation: docs/ directory
Issues: GitHub Issues
Roadmap: future_roadmap.md

License¶

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to CortexGraph! 🎉