Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
77 lines (57 loc) · 2.3 KB

CONTRIBUTING.md

File metadata and controls

77 lines (57 loc) · 2.3 KB

Contributing to Synaptic Memory

Thanks for your interest in contributing! This guide will help you get started.

Prerequisites

  • Python 3.12+
  • uv — fast Python package manager

Setup

git clone https://github.com/PlateerLab/synaptic-memory.git
cd synaptic-memory
uv sync --extra dev --extra sqlite --extra neo4j --extra qdrant --extra minio

Running Tests

# All tests (requires external services: Neo4j, Qdrant, MinIO)
uv run pytest tests/ -v

# Skip external backends (recommended for most contributors)
uv run pytest tests/ --ignore=tests/test_backend_postgresql.py --ignore=tests/benchmark --ignore=tests/qa -v

Linting

We use Ruff for linting and formatting:

uv run ruff check --fix
uv run ruff format

Both checks must pass before merging. CI runs ruff check and ruff format --check automatically.

Code Style

  • Ruff handles all formatting and linting — no additional tools needed.
  • Type hints are required for all function signatures.
  • Keep imports sorted (Ruff handles this via isort rules).

Pull Request Guidelines

  1. Create a feature branch from main — do not push directly to main.
  2. All tests must pass before requesting review.
  3. Use conventional commit messages:
    • feat: new feature
    • fix: bug fix
    • docs: documentation only
    • refactor: code restructuring without behavior change
    • test: adding or updating tests
    • chore: maintenance tasks
  4. Keep PRs focused — one feature or fix per PR.
  5. Add tests for new functionality.

Project Structure

src/synaptic/
├── graph.py           # Main facade (SynapticGraph)
├── search.py          # Hybrid search engine
├── agent_search.py    # Intent-based agent search
├── resonance.py       # Multi-axis scoring
├── hebbian.py         # Co-activation learning
├── consolidation.py   # Memory consolidation cascade
├── ontology.py        # Type hierarchy & constraints
├── activity.py        # Agent activity tracking
├── models.py          # Core data models
└── backends/          # Storage backends (Memory, SQLite, PostgreSQL, Neo4j, Qdrant, MinIO)

Questions?

Open an issue on GitHub — we're happy to help.