rexdivakar · rexdivakar · Oct 19, 2025 · Oct 19, 2025 · Oct 19, 2025 · Oct 19, 2025
diff --git a/.github/workflows/dependency-health.yml b/.github/workflows/dependency-health.yml
@@ -0,0 +1,34 @@
+name: Dependency Health
+
+on:
+  schedule:
+    - cron: '0 6 * * 1'
+  pull_request:
+    paths:
+      - 'pyproject.toml'
+      - 'requirements.txt'
+      - '.github/workflows/dependency-health.yml'
+  workflow_dispatch:
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install project with tooling extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[core,dev,test,docs]
+
+      - name: Run vulnerability scan
+        run: pip-audit
+
+      - name: Check license compliance
+        run: liccheck -s liccheck.ini
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,44 @@
+# Contributing to HippocampAI
+
+Thanks for helping improve HippocampAI! This guide keeps contributions smooth and reviewable.
+
+## Getting Started
+
+1. **Clone & install** (use a virtual environment):
+   ```bash
+   git clone https://github.com/rexdivakar/HippocampAI.git
+   cd HippocampAI
+   python -m venv .venv && source .venv/bin/activate
+   pip install -e .[core,dev,test]
+   ```
+2. **Bootstrap the project** (optional, for running demos):
+   ```bash
+   python setup_initial.py
+   ```
+3. **Configure providers** by copying `.env.example` to `.env` and filling in API keys as needed.
+
+## Coding Standards
+
+- Keep imports sorted with `ruff check --select I --fix .`.
+- Run `ruff check` and `./scripts/run-tests.sh` before each commit; add targeted tests for new behaviour.
+- Use type hints throughout and prefer dataclasses or Pydantic models where possible.
+- Log meaningful context (`logger.info/debug`) rather than printing directly.
+- All timestamps must be timezone-aware UTC. Use helpers in `hippocampai.utils.time` (`now_utc()`, `isoformat_utc()`, etc.) instead of `datetime.utcnow()`.
+
+## Pull Requests
+
+- Create feature or bugfix branches off `main`.
+- Squash commits sensibly; commit messages should describe _why_ a change is needed.
+- Provide a concise summary of the change in the PR description, including testing performed.
+- Update documentation (`docs/` and `README.md`) when you add or modify features or commands.
+- Ensure CI (lint, tests, dependency checks) passes; the `dependency-health` workflow runs `pip-audit` and `liccheck`.
+
+## Reporting Issues
+
+When filing an issue, include:
+
+- What happened vs. what you expected.
+- Steps to reproduce (commands, config, snippets).
+- Environment details (OS, Python version, optional: vector DB / provider info).
+
+We appreciate your time and contributions—thank you for making HippocampAI better!
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -8,6 +8,7 @@ include .env.example
 
 # Include all source code
 recursive-include src *.py
+recursive-include src *.html
 
 # Include type stubs if any
 recursive-include src *.pyi

diff --git a/README.md b/README.md
@@ -44,8 +44,8 @@ LLM_MODEL=qwen2.5:7b-instruct
 Start the chat clients:
 
 ```bash
-python cli_chat.py alice
-python web_chat.py        # open http://localhost:5000
+python -m hippocampai.cli_chat alice
+python -m hippocampai.web_chat        # open http://localhost:5000
 ```
 
 Run the interactive example suite:
@@ -110,6 +110,31 @@ Full API and architecture references live under `docs/`.
 
 ---
 
+## Dependency Management
+
+- We follow a "latest minor" pinning strategy: each requirement is constrained with `>=` and `<` to stay current without taking untested major releases.
+- Install optional groups with extras, e.g. `pip install .[core]` for provider SDKs, `pip install .[test]` for the pytest stack, and `pip install .[docs]` for MkDocs authoring.
+- Run `pip install .[dev]` to pull in tooling such as Ruff, MyPy, `pip-audit`, and `liccheck`.
+- The `dependency-health` GitHub workflow runs weekly (and on relevant PRs) to audit vulnerabilities via `pip-audit` and enforce license compatibility with `liccheck`.
+
+---
+
+## Testing
+
+- Execute the unit suite with `./scripts/run-tests.sh`; pass extra pytest arguments as needed (for example `./scripts/run-tests.sh -k retrieval`).
+- The helper script exports `PYTHONPATH=src` automatically, so no additional environment tweaks are required.
+- CI runs the same command; please mirror it locally before opening a PR.
+
+---
+
+## Contributing
+
+- Start with [CONTRIBUTING.md](CONTRIBUTING.md) for environment setup, coding conventions, and pull request expectations.
+- Run `ruff check` and `pytest` locally before opening a PR; add tests for any behavior changes.
+- All timestamps are stored as timezone-aware UTC (`+00:00`); please normalize new datetime fields via `hippocampai.utils.time` helpers.
+
+---
+
 ## HippocampAI vs Mem0 and Others
 
 | Capability                | HippocampAI                                         | Mem0 / hosted memory APIs                    |

diff --git a/config.yaml → config/config.yaml b/config.yaml → config/config.yaml
diff --git a/logging_config.yaml → config/logging_config.yaml b/logging_config.yaml → config/logging_config.yaml
@@ -50,52 +50,52 @@ handlers:
 
 loggers:
   # Application loggers
-  src.qdrant_client:
+  hippocampai.qdrant_client:
     level: INFO
     handlers: [console, file]
     propagate: false
 
-  src.embedding_service:
+  hippocampai.embedding_service:
     level: INFO
     handlers: [console, file]
     propagate: false
 
-  src.memory_store:
+  hippocampai.memory_store:
     level: INFO
     handlers: [console, file]
     propagate: false
 
-  src.memory_retriever:
+  hippocampai.memory_retriever:
     level: INFO
     handlers: [console, file]
     propagate: false
 
-  src.memory_extractor:
+  hippocampai.memory_extractor:
     level: INFO
     handlers: [console, file]
     propagate: false
 
-  src.memory_deduplicator:
+  hippocampai.memory_deduplicator:
     level: INFO
     handlers: [console, file]
     propagate: false
 
-  src.memory_updater:
+  hippocampai.memory_updater:
     level: INFO
     handlers: [console, file]
     propagate: false
 
-  src.importance_scorer:
+  hippocampai.importance_scorer:
     level: INFO
     handlers: [console, file]
     propagate: false
 
-  src.session_manager:
+  hippocampai.session_manager:
     level: INFO
     handlers: [console, file]
     propagate: false
 
-  src.memory_consolidator:
+  hippocampai.memory_consolidator:
     level: INFO
     handlers: [console, file]
     propagate: false

diff --git a/docs/CHAT_INTEGRATION.md b/docs/CHAT_INTEGRATION.md
@@ -70,19 +70,19 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 ### 3. Run CLI Chat
 
 ```bash
-python cli_chat.py
+python -m hippocampai.cli_chat
 ```
 
 Or specify a user ID:
 
 ```bash
-python cli_chat.py alice
+python -m hippocampai.cli_chat alice
 ```
 
 ### 4. Run Web Chat
 
 ```bash
-python web_chat.py
+python -m hippocampai.web_chat
 ```
 
 Then open: http://localhost:5000
@@ -95,10 +95,10 @@ Then open: http://localhost:5000
 
 ```bash
 # Default user (cli_user)
-python cli_chat.py
+python -m hippocampai.cli_chat
 
 # Specific user
-python cli_chat.py john_doe
+python -m hippocampai.cli_chat john_doe
 ```
 
 ### Available Commands
@@ -164,7 +164,7 @@ You: /quit
 ### Starting Web Server
 
 ```bash
-python web_chat.py
+python -m hippocampai.web_chat
 ```
 
 Output:
@@ -179,7 +179,7 @@ Server starting at: http://localhost:5000
 
 Endpoints:
   - Web Interface: http://localhost:5000/
-  - API Docs: See web_chat.py docstrings
+  - API Docs: See src/hippocampai/web_chat.py docstrings
 
 Press Ctrl+C to stop
 ============================================================
@@ -241,7 +241,7 @@ Press Ctrl+C to stop
 ### Basic Usage
 
 ```python
-from src.ai_chat import MemoryEnhancedChat
+from hippocampai.ai_chat import MemoryEnhancedChat
 
 # Create chat instance
 chat = MemoryEnhancedChat(
@@ -266,7 +266,7 @@ chat.end_conversation()
 ### Advanced Usage
 
 ```python
-from src.ai_chat import MemoryEnhancedChat
+from hippocampai.ai_chat import MemoryEnhancedChat
 
 # Initialize with custom settings
 chat = MemoryEnhancedChat(
@@ -771,7 +771,7 @@ preferences = chat.retriever.search_memories(
 
 ### Web Server Configuration
 
-Edit `web_chat.py`:
+Edit `src/hippocampai/web_chat.py`:
 
 ```python
 # Change host/port
@@ -784,7 +784,7 @@ app.run(
 
 ### Web UI Customization
 
-Edit `web/chat.html`:
+Edit `src/hippocampai/web/chat.html`:
 
 - Change colors in `<style>` section
 - Modify layout (sidebar width, chat area)
@@ -800,7 +800,7 @@ For production, replace in-memory sessions with Redis:
 
 ```python
 import redis
-from src.ai_chat import MemoryEnhancedChat
+from hippocampai.ai_chat import MemoryEnhancedChat
 
 redis_client = redis.Redis(host='localhost', port=6379)
 
@@ -848,7 +848,7 @@ COPY . .
 
 EXPOSE 5000
 
-CMD ["python", "web_chat.py"]
+CMD ["python", "-m", "hippocampai.web_chat"]
 ```
 
 ### NGINX Reverse Proxy
@@ -886,7 +886,7 @@ grep API_KEY .env
 **Solution:** Set PYTHONPATH:
 ```bash
 export PYTHONPATH=/path/to/HippocampAI:$PYTHONPATH
-python cli_chat.py
+python -m hippocampai.cli_chat
 ```
 
 ### Issue: Web server won't start
@@ -918,7 +918,7 @@ pip install flask flask-cors
 
 **Solution:** Run manual consolidation:
 ```python
-from src.memory_consolidator import MemoryConsolidator
+from hippocampai.memory_consolidator import MemoryConsolidator
 
 consolidator = MemoryConsolidator(retriever, updater, embeddings)
 clusters = consolidator.find_similar_clusters(user_id="alice")
@@ -933,7 +933,7 @@ for cluster in clusters:
 ### Example 1: Personal Assistant
 
 ```python
-from src.ai_chat import MemoryEnhancedChat
+from hippocampai.ai_chat import MemoryEnhancedChat
 
 chat = MemoryEnhancedChat(
     user_id="john",
@@ -984,9 +984,9 @@ support.send_message("My order still hasn't arrived")
 
 ## Next Steps
 
-1. **Try CLI Chat**: `python cli_chat.py`
-2. **Launch Web Interface**: `python web_chat.py`
-3. **Read API Docs**: See docstrings in `src/ai_chat.py`
+1. **Try CLI Chat**: `python -m hippocampai.cli_chat`
+2. **Launch Web Interface**: `python -m hippocampai.web_chat`
+3. **Read API Docs**: See docstrings in `src/hippocampai/ai_chat.py`
 4. **Customize**: Modify system prompts, retrieval limits
 5. **Deploy**: Use Docker or cloud platforms
 

diff --git a/docs/CHAT_README.md b/docs/CHAT_README.md
@@ -4,7 +4,7 @@
 
 ### 1. CLI Chat (Command Line)
 ```bash
-python cli_chat.py
+python -m hippocampai.cli_chat
 ```
 
 **Features:**
@@ -15,7 +15,7 @@ python cli_chat.py
 
 ### 2. Web Chat (Browser)
 ```bash
-python web_chat.py
+python -m hippocampai.web_chat
 ```
 Then open: **http://localhost:5000**
 
@@ -28,7 +28,7 @@ Then open: **http://localhost:5000**
 
 ### 3. Python API
 ```python
-from src.ai_chat import MemoryEnhancedChat
+from hippocampai.ai_chat import MemoryEnhancedChat
 
 chat = MemoryEnhancedChat(user_id="alice")
 response = chat.send_message("Hello!")
@@ -117,10 +117,10 @@ support.send_message("My order hasn't arrived")
 
 | File | Purpose |
 |------|---------|
-| `src/ai_chat.py` | Core memory-enhanced chat class (650+ lines) |
-| `web_chat.py` | Flask web server with REST API |
-| `web/chat.html` | Beautiful web UI with gradient design |
-| `cli_chat.py` | Command-line chat interface |
+| `src/hippocampai/ai_chat.py` | Core memory-enhanced chat class (650+ lines) |
+| `src/hippocampai/web_chat.py` | Flask web server with REST API |
+| `src/hippocampai/web/chat.html` | Beautiful web UI with gradient design |
+| `src/hippocampai/cli_chat.py` | Command-line chat interface |
 | `docs/CHAT_INTEGRATION.md` | Complete documentation (900+ lines) |
 
 ---
@@ -228,9 +228,9 @@ echo "ANTHROPIC_API_KEY=sk-ant-your-key" >> .env
 python setup_initial.py
 
 # 4. Start chatting!
-python cli_chat.py
+python -m hippocampai.cli_chat
 # or
-python web_chat.py
+python -m hippocampai.web_chat
 ```
 
 ---