chore: add project documentation and config updates

- Add CLAUDE.md with project guidance
- Add .env.example for environment variables
- Update config.py with new helper functions
- Update dependencies in uv.lock

Author: zircote

.env.example

@@ -0,0 +1,44 @@
+# Git Notes Memory Plugin - Environment Configuration
+# Copy this file to .env and modify as needed
+# All variables are optional - defaults are shown
+
+# =============================================================================
+# Storage Configuration
+# =============================================================================
+
+# Override the XDG-compliant data directory
+# Default: ~/.local/share/memory-plugin/
+# MEMORY_PLUGIN_DATA_DIR=~/.local/share/memory-plugin
+
+# =============================================================================
+# Git Notes Configuration
+# =============================================================================
+
+# Override the git notes namespace (ref prefix)
+# Default: refs/notes/mem
+# MEMORY_PLUGIN_GIT_NAMESPACE=refs/notes/mem
+
+# =============================================================================
+# Embedding Model Configuration
+# =============================================================================
+
+# Override the sentence-transformers embedding model
+# Default: all-MiniLM-L6-v2
+# MEMORY_PLUGIN_EMBEDDING_MODEL=all-MiniLM-L6-v2
+
+# =============================================================================
+# Feature Flags
+# =============================================================================
+
+# Enable auto-capture of memories during Claude sessions
+# Accepts: 1, true, yes, on (case-insensitive)
+# Default: disabled
+# MEMORY_PLUGIN_AUTO_CAPTURE=false
+
+# =============================================================================
+# XDG Base Directory (System)
+# =============================================================================
+
+# Override XDG data home (affects default data directory)
+# Default: ~/.local/share
+# XDG_DATA_HOME=~/.local/share

CLAUDE.md

@@ -0,0 +1,147 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`git-notes-memory` is a Python library and Claude Code plugin that provides git-native, semantically-searchable memory storage. Memories are stored as git notes with YAML front matter and indexed in SQLite with sqlite-vec for vector similarity search.
+
+## Development Commands
+
+```bash
+# Install with dev dependencies
+uv sync
+
+# Run all tests
+make test
+
+# Run tests with coverage (80% minimum required)
+make coverage
+
+# Run a specific test file
+uv run pytest tests/test_capture.py -v
+
+# Run a single test
+uv run pytest tests/test_capture.py::TestCaptureService::test_capture_basic -v
+
+# Skip slow tests
+uv run pytest -m "not slow"
+
+# Run all quality checks (format, lint, typecheck, security, tests)
+make quality
+
+# Individual quality checks
+make format     # Auto-fix formatting
+make lint       # Ruff linting
+make typecheck  # mypy strict mode
+make security   # bandit security scan
+```
+
+## Architecture
+
+### Service Layer Pattern
+
+The codebase uses a singleton service factory pattern with lazy initialization:
+
+```
+__init__.py          # Lazy imports via __getattr__ to avoid loading embedding model at import
+    └── get_capture_service()  → CaptureService
+    └── get_recall_service()   → RecallService
+    └── get_sync_service()     → SyncService
+```
+
+Services are exposed through factory functions (`get_*_service()`) that return singleton instances. Internal modules use `get_default_service()` naming.
+
+### Core Data Flow
+
+```
+Capture:
+  CaptureService.capture()
+      → validate (namespace, summary ≤100 chars, content ≤100KB)
+      → serialize_note() (YAML front matter + body)
+      → GitOps.append_note() (atomic append to refs/notes/mem/{namespace})
+      → EmbeddingService.embed() (sentence-transformers, graceful degradation)
+      → IndexService.insert() (SQLite + sqlite-vec)
+
+Recall:
+  RecallService.search()
+      → EmbeddingService.embed(query)
+      → IndexService.search_vector() (KNN via sqlite-vec)
+      → Memory objects with distance scores
+```
+
+### Git Notes Storage
+
+Memories are stored under `refs/notes/mem/{namespace}` where namespace is one of:
+`inception`, `elicitation`, `research`, `decisions`, `progress`, `blockers`, `reviews`, `learnings`, `retrospective`, `patterns`
+
+Each note has YAML front matter:
+```yaml
+---
+type: decisions
+timestamp: 2024-01-15T10:30:00Z
+summary: Use PostgreSQL for persistence
+spec: my-project
+tags: [database, architecture]
+---
+## Context
+...
+```
+
+### Key Modules
+
+| Module | Responsibility |
+|--------|---------------|
+| `capture.py` | Memory capture with file locking (`fcntl`) for concurrency |
+| `recall.py` | Search and retrieval with progressive hydration |
+| `index.py` | SQLite + sqlite-vec for metadata and vector search |
+| `embedding.py` | Sentence-transformer embeddings (all-MiniLM-L6-v2) |
+| `git_ops.py` | Git notes operations with security validation |
+| `note_parser.py` | YAML front matter parsing/serialization |
+| `models.py` | Frozen dataclasses for all domain objects |
+| `sync.py` | Index synchronization with git notes |
+
+### Models
+
+All models are immutable (`@dataclass(frozen=True)`):
+- `Memory` - Core entity with id format `{namespace}:{commit_sha}:{index}`
+- `MemoryResult` - Memory + distance score from vector search
+- `CaptureResult` - Operation result with success/warning status
+- `HydrationLevel` - SUMMARY → FULL → FILES progressive loading
+
+### Claude Code Plugin Integration
+
+The `.claude-plugin/` directory defines:
+- Commands: `/capture`, `/recall`, `/search`, `/sync`, `/status`
+- Hooks: `Stop` (sync index on session end)
+- Skills: `memory-recall` for semantic search
+
+## Code Conventions
+
+- Python 3.11+ with full type annotations (mypy strict)
+- Google-style docstrings
+- Frozen dataclasses for all models (immutability)
+- Tuple over list for immutable collections in models
+- Factory functions expose services; internal modules use `get_default_service()`
+- Graceful degradation: embedding failures don't block capture
+
+## Testing
+
+The test suite uses pytest with automatic singleton reset via `conftest.py`. Each test gets isolated service instances to prevent cross-test pollution.
+
+```python
+# Tests automatically reset singletons via autouse fixture
+# For manual isolation, use tmp_path and monkeypatch:
+@pytest.fixture
+def capture_service(tmp_path, monkeypatch):
+    monkeypatch.setenv("MEMORY_PLUGIN_DATA_DIR", str(tmp_path))
+    return get_capture_service(repo_path=tmp_path)
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MEMORY_PLUGIN_DATA_DIR` | Data/index directory | `~/.local/share/memory-plugin/` |
+| `MEMORY_PLUGIN_GIT_NAMESPACE` | Git notes ref prefix | `refs/notes/mem` |
+| `MEMORY_PLUGIN_EMBEDDING_MODEL` | Embedding model | `all-MiniLM-L6-v2` |

Makefile

@@ -32,7 +32,7 @@ test:  ## Run tests
 	uv run pytest
 
 test-cov:  ## Run tests with coverage
-	uv run pytest --cov=git_notes_memory_manager --cov-report=html --cov-report=term-missing
+	uv run pytest --cov=git_notes_memory --cov-report=html --cov-report=term-missing
 
 lint:  ## Run linter (ruff)
 	uv run ruff check src/ tests/
@@ -52,7 +52,7 @@ format-check:  ## Check formatting
 	uv run ruff check src/ tests/
 
 coverage:  ## Run tests with coverage threshold
-	uv run pytest --cov=git_notes_memory_manager --cov-report=term-missing --cov-fail-under=80
+	uv run pytest --cov=git_notes_memory --cov-report=term-missing --cov-fail-under=80
 
 quality:  ## Run all quality checks
 	@echo "Running quality checks..."
@@ -75,7 +75,7 @@ quality:  ## Run all quality checks
 	@echo "Security: PASS"
 	@echo ""
 	@echo "5. Tests with coverage..."
-	@uv run pytest --cov=git_notes_memory_manager --cov-report=term-missing --cov-fail-under=80 -q
+	@uv run pytest --cov=git_notes_memory --cov-report=term-missing --cov-fail-under=80 -q
 	@echo ""
 	@echo "ALL QUALITY CHECKS PASSED"
 

pyproject.toml

@@ -24,6 +24,7 @@ classifiers = [
 requires-python = ">=3.11"
 dependencies = [
     "pyyaml>=6.0",
+    "python-dotenv>=1.0.0",
     "sentence-transformers>=2.2.0",
     "sqlite-vec>=0.1.1",
 ]

src/git_notes_memory/config.py

@@ -12,13 +12,23 @@
 XDG Compliance:
     By default, data is stored in $XDG_DATA_HOME/memory-plugin/ which
     defaults to ~/.local/share/memory-plugin/ if XDG_DATA_HOME is not set.
+
+.env File Support:
+    Place a .env file in the project root or working directory to set
+    environment variables. See .env.example for available options.
 """
 
 from __future__ import annotations
 
 import os
 from pathlib import Path
 
+from dotenv import load_dotenv
+
+# Load .env file early, before any environment variable access
+# This looks for .env in the current directory and parent directories
+load_dotenv()
+
 __all__ = [
     # Namespaces
     "NAMESPACES",