fix: comprehensive repository audit, CI test failures, and code quality improvements

.github/workflows/ci.yml

@@ -70,6 +70,8 @@ jobs:
           pip install -r requirements.txt
           pip install -r requirements-dev.txt
           pip install -e .
+          # Install optional dependencies for testing
+          pip install -e ".[openai]"
           # Ensure coverage plugin is available for enforcing minimum coverage
           pip install pytest-cov
       - name: Run tests

.gitignore

@@ -71,3 +71,8 @@ coverage/
 
 # Keep ADRs local (contain private references)
 docs/adr/
+# Temporary result files
+audit-results.json
+safety-results.json
+vulnerability_summary.json
+coverage.xml

.pre-commit-config.yaml

@@ -46,10 +46,10 @@ repos:
   #
   # Current Status: Phase 0 (Foundation) - 86 strict mode errors identified
   # Progress Tracking: https://github.com/your-org/ConextForge_memory/issues/TBD
-  # TODO: Update with actual issue URL when created
+  # Progress tracking: https://github.com/VirtualAgentics/ConextForge_memory/issues/7
   # ADR Reference: docs/adr/ADR-0004-mypy-strict-mode-migration.md
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.8.0
+    rev: v1.18.1
     hooks:
       - id: mypy
         additional_dependencies: [types-requests, types-setuptools, types-aiofiles]

CONTRIBUTING.md

@@ -38,14 +38,6 @@ make test        # Full test suite
 **⚠️ CRITICAL**: All Python operations must be performed in the activated
 virtual environment.
 
-### Temporary Dependency Constraints
-
-- **setuptools < 81**: We temporarily pin setuptools to versions below 81 in our
-  CI workflow to avoid deprecation warnings related to the `pkg_resources`
-  module. The `pkg_resources` module is deprecated and scheduled for removal
-  as early as November 30, 2025. This constraint should be removed once
-  setuptools releases a fix or the deprecation is resolved. See:
-  [setuptools documentation](https://setuptools.pypa.io/en/latest/pkg_resources.html)
 
 ## Development Workflow
 

README.md

@@ -34,6 +34,10 @@ multi-repo reuse (Brainstorm, Cursor, and others).
 **ALL Python operations MUST be performed in a virtual environment** to prevent system corruption.
 Never install dependencies directly on the host system.
 
+## Python Version Requirements
+
+**Python 3.12+ Required**: This project requires Python 3.12 or higher. Python 3.11 and earlier are not supported.
+
 ## Features
 
 - Versioned API: `/v0/` with `store`, `search`, `embed`.
@@ -94,6 +98,18 @@ make setup  # Installs both production and development dependencies
 make run    # Start development server
 ```
 
+### Optional Dependencies
+
+For enhanced functionality, install optional dependency groups:
+
+```bash
+# OpenAI integration (embeddings and summarization)
+pip install -e ".[openai]"
+
+# Development tools (linting, testing, formatting)
+pip install -e ".[dev]"
+```
+
 **Prerequisites for type checking:**
 
 - Node.js and npm must be installed for `make type-check` (pyright is Node.js-based)
@@ -344,7 +360,7 @@ See [CI/CD Documentation](docs/ci-cd.md) for detailed workflow information.
 Run the comprehensive example script to see all features in action:
 
 ```bash
-python example_usage.py
+python examples/example_usage.py
 ```
 
 This script demonstrates:

REPOSITORY_IMPROVEMENTS.md → docs/REPOSITORY_IMPROVEMENTS.md

@@ -22,6 +22,18 @@ This document outlines recommended improvements for the ContextForge Memory repo
 - **Description**: Created CHANGELOG.md following Keep a Changelog format
 - **Implementation**: Documented all notable changes with proper versioning
 
+### 3. Repository Structure Cleanup
+
+- **Status**: ✅ Completed
+- **Description**: Reorganized repository structure for better maintainability
+- **Implementation**:
+  - Created `examples/` directory for example scripts
+  - Moved `example_usage.py` from root to `examples/`
+  - Moved 8 test files from root to `tests/` directory
+  - Moved 4 development documentation files to `docs/` directory
+  - Cleaned up temporary files and empty files
+  - Updated all documentation references to reflect new structure
+
 ## 🔄 Recommended Next Steps
 
 ### High Priority (Immediate Action Required)

docs/api-reference.md

@@ -674,7 +674,7 @@ const results = await client.v1Search(
 
 ## Examples
 
-See [example_usage.py](../example_usage.py) for comprehensive usage examples.
+See [examples/example_usage.py](../examples/example_usage.py) for comprehensive usage examples.
 
 ## OpenAPI Specifications
 

docs/configuration.md

@@ -241,31 +241,58 @@ Without OpenAI API key:
 
 ## Dependencies
 
+### Python Version Requirements
+
+**Python 3.12+ Required**: This project requires Python 3.12 or higher. Python 3.11 and earlier are not supported.
+
 ### Production Dependencies (requirements.txt)
 
 Core dependencies for running ContextForge Memory:
 
 ```txt
-aiofiles==24.1.0          # Async file operations
-fastapi==0.119.1          # Web framework
+aiofiles==25.1.0          # Async file operations
+fastapi>=0.118.1          # Web framework
 uvicorn[standard]==0.38.0 # ASGI server
 pydantic==2.12.3         # Data validation
-orjson==3.10.7           # Fast JSON serialization
-numpy==2.1.1             # Numerical operations
-httpx==0.27.2            # HTTP client
-starlette==0.48.0        # ASGI framework
-tenacity==9.0.0          # Retry logic
+tenacity==9.1.2          # Retry logic
+numpy>=1.26.0            # Numerical operations
 ```
 
-Optional dependencies (automatically installed):
+### Optional Dependencies
+
+The project supports optional dependency groups for enhanced functionality:
+
+#### OpenAI Integration (`openai` group)
+
+```bash
+pip install -e ".[openai]"
+```
+
+Includes:
+
+- `openai>=1.0.0,<3.0.0` - OpenAI API client (supports 2.x versions)
+- `tiktoken>=0.5.0,<1.0.0` - Token counting for OpenAI models
+
+#### Development Dependencies (`dev` group)
+
+```bash
+pip install -e ".[dev]"
+```
+
+Includes testing, linting, and development tools.
+
+### Automatic Optional Dependencies
+
+These are installed automatically when needed:
 
 - `sentence-transformers` - For sentence transformer embeddings
-- `openai` - For OpenAI API integration
 
 ### Development Dependencies
 
 The project uses `pip-tools` for reproducible development environments:
 
+> **Note**: For information about dependency resolution and MCP compatibility, see [ADR-0005: MCP Dependency Resolution](adr/ADR-0005-mcp-dependency-resolution.md).
+
 - **requirements-dev.in**: Unpinned development dependencies
 - **requirements-dev.txt**: Pinned versions generated from requirements-dev.in
 

docs/development.md

@@ -563,13 +563,13 @@ logging.basicConfig(level=logging.DEBUG)
 - **API Documentation**: Visit `http://localhost:8085/docs` when server is running
 - **OpenAPI Specs**: Check `openapi/` directory
 - **Rules**: See `.cursor/rules/` for coding standards
-- **Examples**: Run `python example_usage.py` for usage examples
+- **Examples**: Run `python examples/example_usage.py` for usage examples
 - **Issues**: Check GitHub issues for known problems
 
 ## Next Steps
 
 1. **Explore the codebase**: Start with `src/contextforge_memory/main.py`
-2. **Run examples**: Execute `python example_usage.py`
+2. **Run examples**: Execute `python examples/example_usage.py`
 3. **Check API docs**: Visit `http://localhost:8085/docs`
 4. **Read the rules**: Review `.cursor/rules/` for coding standards
 5. **Write tests**: Add tests for any new features

pyproject.toml

@@ -23,7 +23,7 @@ select = ["E", "F", "I", "B", "UP", "C4", "PIE", "SIM", "T20", "ASYNC", "S", "RU
 ignore = []
 fixable = ["I"]
 [tool.ruff.lint.per-file-ignores]
-"example_usage.py" = ["T20"]
+"examples/example_usage.py" = ["T20"]
 ".github/scripts/analyze_vulnerabilities.py" = ["T20"]
 "tests/**/*.py" = ["S101", "T20"]  # Allow assert statements and print in test files
 "**/test_*.py" = ["S101", "T20"]  # Allow assert statements and print in test files