feat: Initial project setup and implementation

.dockerignore

@@ -0,0 +1,79 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# Environment
+.env
+.env.local
+
+# Documentation
+*.md
+docs/
+
+# Git
+.git/
+.gitignore
+
+# Docker
+Dockerfile
+docker-compose.yml
+.dockerignore
+
+# Logs and data
+logs/
+*.log
+.vgm/
+
+# Database storage
+qdrant_storage/
+janusgraph_storage/
+mongodb_storage/
+
+# Scripts
+start_api.sh
+scripts/
+
+# JanusGraph config
+janusgraph-config.properties
+janusgraph-init.groovy

.env.example

@@ -0,0 +1,68 @@
+# Vector Graph Memory - Environment Configuration
+
+# === Database Configuration ===
+# NOTE: When running API via Docker, these are overridden in docker-compose.yml
+#       to use container names (qdrant, janusgraph) instead of localhost.
+#       These localhost values are for local development only.
+QDRANT_HOST=localhost
+QDRANT_HTTP_PORT=6333
+QDRANT_GRPC_PORT=6334
+JANUSGRAPH_HOST=localhost
+JANUSGRAPH_PORT=8182
+
+# === LLM Configuration ===
+# OpenAI API Key (required)
+OPENAI_API_KEY=your_openai_api_key_here
+
+# LLM Model (supports PydanticAI format: openai:gpt-4o-mini, anthropic:claude-3-5-sonnet-20241022, etc.)
+LLM_MODEL=openai:gpt-4o-mini
+
+# === Memory Configuration ===
+# Project identifier (unique namespace for memory storage)
+PROJECT_ID=default
+
+# Use case description (guides the agent's memory behavior)
+MEMORY_USE_CASE=General purpose conversational memory
+
+# Memory threshold description (what should be stored)
+MEMORY_THRESHOLD=Store important facts, decisions, and context from conversations
+
+# Similarity threshold for duplicate detection (0.0-1.0)
+SIMILARITY_THRESHOLD=0.85
+
+# === Memory Trigger Configuration ===
+# Trigger mode: 'ai_determined', 'phrase', or 'interval'
+TRIGGER_MODE=ai_determined
+
+# Trigger phrase (only used if TRIGGER_MODE=phrase)
+# TRIGGER_PHRASE=save this to memory
+
+# Trigger interval in messages (only used if TRIGGER_MODE=interval)
+# TRIGGER_INTERVAL=5
+
+# === System Prompt ===
+SYSTEM_PROMPT=You are a helpful AI assistant with persistent memory capabilities.
+
+# === Audit Configuration ===
+# Audit backend: 'jsonl' or 'mongodb'
+AUDIT_BACKEND=jsonl
+
+# Audit log directory (for JSONL backend)
+AUDIT_LOG_DIR=~/.vgm/logs
+
+# MongoDB connection (only if AUDIT_BACKEND=mongodb)
+# AUDIT_MONGODB_URI=mongodb://localhost:27017
+# AUDIT_MONGODB_DATABASE=vgm_audit
+# AUDIT_MONGODB_COLLECTION=logs
+
+# === API Configuration ===
+# API server host and port
+API_HOST=0.0.0.0
+API_PORT=8000
+
+# === Docker Configuration ===
+# Qdrant version
+QDRANT_VERSION=v1.12.5
+
+# JanusGraph version
+JANUSGRAPH_VERSION=latest

.github/workflows/cd.yml

@@ -0,0 +1,115 @@
+name: CD
+
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+      - opened
+      - synchronize
+      - reopened
+  push:
+    branches:
+      - main
+
+jobs:
+  check-branch:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request' || github.event_name == 'push'
+    outputs:
+      is_release_or_hotfix: ${{ steps.check.outputs.is_release_or_hotfix }}
+    steps:
+      - name: Check if PR is from release or hotfix branch
+        id: check
+        run: |
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            SOURCE_BRANCH="${{ github.head_ref }}"
+          else
+            # For push events, check the commit message or use a different strategy
+            # This assumes the branch name is preserved in merge commits
+            SOURCE_BRANCH="${{ github.ref_name }}"
+          fi
+
+          if [[ "$SOURCE_BRANCH" == release/* ]] || [[ "$SOURCE_BRANCH" == hotfix/* ]]; then
+            echo "is_release_or_hotfix=true" >> $GITHUB_OUTPUT
+          else
+            echo "is_release_or_hotfix=false" >> $GITHUB_OUTPUT
+          fi
+
+  dry-run:
+    needs: check-branch
+    if: github.event_name == 'pull_request' && needs.check-branch.outputs.is_release_or_hotfix == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: |
+          uv sync
+
+      - name: Build package
+        run: |
+          uv build
+
+      - name: Check package metadata
+        run: |
+          uv run twine check dist/*
+
+      - name: Dry-run publish
+        run: |
+          echo "Dry-run: Would publish to PyPI"
+          ls -lh dist/
+
+  publish:
+    needs: check-branch
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main' && needs.check-branch.outputs.is_release_or_hotfix == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: |
+          uv sync
+
+      - name: Build package
+        run: |
+          uv build
+
+      - name: Get version from pyproject.toml
+        id: get_version
+        run: |
+          VERSION=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.get_version.outputs.version }}
+          name: Release v${{ steps.get_version.outputs.version }}
+          draft: false
+          prerelease: false
+          generate_release_notes: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - dev
+      - main
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras
+
+      - name: Run ruff check
+        run: |
+          uv run ruff check .
+
+      - name: Run ruff format check
+        run: |
+          uv run ruff format --check .
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras
+
+      - name: Run mypy
+        run: |
+          uv run mypy .

.gitignore

@@ -173,7 +173,7 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
 
 # Abstra
 # Abstra is an AI-powered process automation framework.
@@ -205,3 +205,7 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+
+
+## Custom Ignores
+uv.lock