Contributing Overview

memori/              # SDK source code
  ├── llm/               # LLM provider integrations
  │   ├── clients/       # OpenAI, Anthropic, Google, etc.
  │   └── frameworks/    # LangChain, Agno, etc.
  ├── memory/            # Memory system and augmentation
  │   ├── augmentation/  # Advanced Augmentation (facts, preferences, etc.)
  │   └── recall/        # Memory recall logic
  ├── storage/           # Storage adapters
  │   ├── adapters/      # DB-API, Django, SQLAlchemy, MongoDB
  │   └── drivers/       # PostgreSQL, MySQL, SQLite, MongoDB, Oracle
  ├── api/               # API client for Memori Cloud
  └── __init__.py        # Main Memori class

tests/               # Test files
  ├── llm/               # LLM provider tests
  ├── memory/            # Memory system tests
  ├── storage/           # Storage adapter tests
  └── integration/       # Integration tests (requires API keys)

examples/            # Example projects
  ├── postgres/          # PostgreSQL example
  ├── mongodb/           # MongoDB example
  ├── cockroachdb/       # CockroachDB example
  └── agno/              # Agno framework example

docs/                # Documentation
pyproject.toml       # Project metadata and dependencies
CONTRIBUTING.md      # This guide
CHANGELOG.md         # Version history

# Good: Simple and clear
def get_entity_id(config):
    return config.entity_id

# Avoid: Unnecessary complexity
def get_entity_id(config):
    return config.entity_id if hasattr(config, 'entity_id') and \
           config.entity_id is not None else None

# Good: Clear and self-documenting
def calculate_cosine_similarity(embedding_a: np.ndarray, embedding_b: np.ndarray) -> float:
    return np.dot(embedding_a, embedding_b) / (
        np.linalg.norm(embedding_a) * np.linalg.norm(embedding_b)
    )

# Avoid: Requires comments to understand
def calc(a, b):  # calculates cosine similarity
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

from typing import Optional

def recall_memories(
    entity_id: str,
    process_id: str,
    limit: int = 10,
    threshold: float = 0.1
) -> list[dict]:
    ...

# Format code
uv run ruff format .

# Check linting
uv run ruff check .

# Auto-fix issues
uv run ruff check --fix .

# Run security scans
uv run bandit -r memori -ll -ii
uv run pip-audit --require-hashes --disable-pip || true

uv run pytest

# Set required API keys in .env
cp .env.example .env

# Initialize database
make init-postgres  # or init-mysql, init-mongodb, etc.

# Run integration tests
MEMORI_TEST_MODE=1 uv run pytest tests/integration/

# Run with coverage report
uv run pytest --cov=memori

# View HTML report
open htmlcov/index.html