chore(release): promote develop to main

.env.example

@@ -11,12 +11,21 @@ QDRANT_HOST=
 QDRANT_PORT=6333
 QDRANT_URL=
 QDRANT_COLLECTION=memories
-VECTOR_SIZE=1024  # Must match your embedding provider (1024=voyage-4, 3072=text-embedding-3-large, 768=text-embedding-3-small)
+# Recommended embeddings: Voyage is the default when its API key is configured.
+EMBEDDING_PROVIDER=auto
+VOYAGE_API_KEY=
+VOYAGE_MODEL=voyage-4
+VECTOR_SIZE=1024  # voyage-4 and Ollama bge-m3; must match your selected provider
 PORT=8001
+# OpenAI is the automatic API fallback when VOYAGE_API_KEY is unset.
 OPENAI_API_KEY=
 # For OpenAI-compatible providers (OpenRouter, LiteLLM, vLLM, etc.):
 # OPENAI_BASE_URL=https://openrouter.ai/api/v1
 # EMBEDDING_MODEL=openai/text-embedding-3-small
+# For local/self-hosted Ollama embeddings (for example, multilingual BGE-M3):
+# OLLAMA_BASE_URL=http://localhost:11434
+# OLLAMA_MODEL=bge-m3
+# FastEmbed is local/self-hosted only; do not rely on it as a cloud default.
 # --- LLM classification (scripts/reclassify_with_llm.py) ---
 # Optional. Defaults to OpenAI gpt-4o-mini via OPENAI_API_KEY.
 # OPENROUTER_API_KEY=                    # used by --provider openrouter

.github/workflows/mcp-parity.yml

@@ -0,0 +1,69 @@
+name: MCP Transport Parity
+
+# Diffs the remote MCP bridge against the stdio package against one live
+# AutoMem. See docs/MCP_TRANSPORT_PARITY.md for the contract.
+#
+# No scheduled run yet, deliberately. While the harness is intentionally red
+# against the known gaps, `continue-on-error` leaves the workflow successful
+# either way, so a cron job could not distinguish "same known gaps" from "a
+# newly published mcp-automem added drift" — it would be an alarm that cannot
+# alarm. The weekly drift check lands with the change that turns the harness
+# green, where a failure is a real signal.
+
+on:
+  pull_request:
+    paths:
+      - 'mcp-sse-server/**'
+      - 'automem/api/**'
+      - 'app.py'
+  workflow_dispatch:
+
+jobs:
+  parity:
+    runs-on: ubuntu-latest
+    # Phase 1 only. The harness is legitimately red until the bridge is moved
+    # onto the shared MCP surface; this is removed in the same change.
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: mcp-sse-server/package-lock.json
+
+      - name: Start AutoMem stack
+        env:
+          AUTOMEM_API_HOST_PORT: '8011'
+          AUTOMEM_API_TOKEN: test-token
+          ADMIN_API_TOKEN: test-admin-token
+        run: docker compose up -d
+
+      - name: Wait for /health
+        run: |
+          for i in $(seq 1 60); do
+            if curl -fsS http://localhost:8011/health > /dev/null; then
+              echo "AutoMem is up after ${i}s"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "AutoMem did not become healthy within 60s"
+          docker compose logs flask-api
+          exit 1
+
+      - name: Run parity harness
+        working-directory: mcp-sse-server
+        env:
+          AUTOMEM_RUN_PARITY_TESTS: '1'
+          AUTOMEM_PARITY_API_URL: http://localhost:8011
+          AUTOMEM_PARITY_API_TOKEN: test-token
+        run: |
+          npm ci
+          node -p "'stdio package under test: ' + require('@verygoodplugins/mcp-automem/package.json').version"
+          npm test
+
+      - name: Dump service logs on failure
+        if: failure()
+        run: docker compose logs --tail=200

.gitignore

@@ -33,10 +33,8 @@ node_modules/
 # Experiment results (promote notable runs to tests/benchmarks/results/)
 /tests/benchmarks/experiments/results_*/
 
-# Recall Quality Lab data (snapshots, test results)
-/lab/snapshots/
-/lab/results/
-/lab/test_sets/
+# Recall Quality Lab data (generated snapshots, test sets, and results)
+/lab/
 
 # Benchmark overrides and snapshots
 .env.bench
@@ -47,3 +45,5 @@ node_modules/
 benchmarks/baselines/locomo_baseline.json
 data/bm25_index.db
 data/
+/.agents
+/docs/superpowers/

AGENTS.md

@@ -8,7 +8,7 @@
 - `benchmarks/`: Snapshot-based benchmark system. See `EXPERIMENT_LOG.md` for current baselines and results.
 - `scripts/bench/`: Benchmark tooling (ingest, eval, compare, health check).
 - `docs/`: API, testing, deployment, monitoring, and env var references.
-- `scripts/`: Maintenance and ops helpers (backup, reembed, health monitor).
+- `scripts/`: Maintenance and ops helpers (backup, reembed, health monitor). See the canonical [scripts catalog](scripts/README.md) for lifecycle and usage.
 - `mcp-sse-server/`: Optional MCP bridge used in some deployments.
 
 ## Build, Test, and Development
@@ -76,11 +76,12 @@ The benchmark system uses **snapshot-based evaluation**: ingest once, eval many
 - `benchmarks/baselines/` — baseline result JSONs (small files committed, large ones gitignored).
 - `benchmarks/snapshots/` — Qdrant/FalkorDB snapshot data (gitignored, regenerate with `make bench-ingest`).
 - `benchmarks/results/` — per-run result JSONs (gitignored).
-- `scripts/bench/` — shell and Python scripts driving ingest, eval, compare, and health checks.
+- `scripts/bench/` — shell and Python scripts driving ingest, eval, compare, and health checks; see [scripts/README.md](scripts/README.md).
 - `tests/benchmarks/` — legacy benchmark harnesses (LoCoMo, LongMemEval) and historical result markdown files.
 
 ## Commit & Pull Requests
 
+- Feature PRs target `develop` (repo default). Promote `develop` to `main` with a validated release merge; release-please and GHCR `:stable` then run on `main`. Do not open feature work onto `main`.
 - PR titles must use Conventional Commit format because squash merges use the PR title as the release commit title. Do not prefix titles with `[codex]`, `[claude]`, `[copilot]`, `[wip]`, or similar labels; put agent/status context in the PR body.
 - Use Conventional Commit types: `feat`, `fix`, `docs`, `refactor`, `test`, `ci`, `build`, `chore`, `perf`, `revert` (e.g., `feat(api): add /analyze endpoint`).
 - For public API changes, use `feat(api): ...` unless the change is strictly a bug fix with no new public surface. For docs-only changes, use `docs: ...`; for release automation, use `ci(release): ...` or `chore(release): ...`.

CLAUDE.md

@@ -142,11 +142,13 @@ AutoMem uses a provider pattern with multiple embedding backends:
 #### Provider Priority (Auto-Selection)
 
 1. **Voyage AI** (`voyage:voyage-4`) - If `VOYAGE_API_KEY` is set
+   - Recommended provider for new deployments: multilingual quality with a generous free tier; see [Voyage pricing](https://docs.voyageai.com/docs/pricing) for current limits and rates
    - High-quality embeddings with flexible model family (voyage-4, voyage-4-large, voyage-4-lite)
    - Supports output dimensions: 256, 512, 1024, 2048
    - Requires network and API key
 
 2. **OpenAI / OpenAI-compatible** (`openai:text-embedding-3-small`) - If `OPENAI_API_KEY` is set
+   - API fallback when Voyage is not configured
    - Semantic embeddings via API, truncated to `VECTOR_SIZE` via Matryoshka (OpenAI native only)
    - If `VECTOR_SIZE` > 1536, auto-upgrades to `text-embedding-3-large` (set `EMBEDDING_MODEL=text-embedding-3-large` to silence)
    - Supports any OpenAI-compatible endpoint via `OPENAI_BASE_URL` (OpenRouter, LiteLLM, vLLM, Azure, etc.) for both embeddings and classification/enrichment LLM calls
@@ -155,23 +157,25 @@ AutoMem uses a provider pattern with multiple embedding backends:
 3. **Ollama** (`ollama:nomic-embed-text`) - If `OLLAMA_BASE_URL` or `OLLAMA_MODEL` is configured
    - Fully local, easy model swapping
    - Requires running Ollama server
+   - Use `ollama pull bge-m3`, then `OLLAMA_MODEL=bge-m3` with `VECTOR_SIZE=1024` for local/self-hosted multilingual BGE-M3
 
 4. **FastEmbed** (`fastembed:BAAI/bge-base-en-v1.5`) - Local ONNX model
    - Good quality semantic embeddings
    - No API key or internet required (after first download)
    - Downloads ~210MB model to `~/.config/automem/models/` on first use
    - 768 dimensions (default), also supports 384 and 1024 dim models
+   - Local/self-hosted only: its 1024d cloud fallback can consume roughly 4 GB RSS and raise hosting cost substantially
 
 5. **Placeholder** (`placeholder`) - Hash-based fallback
    - Deterministic vectors from content hash
    - No semantic meaning, last resort only
 
-**Upgrade safety:** `VECTOR_SIZE_AUTODETECT=true` (default) automatically adopts your existing collection dimension on startup. No manual action needed when updating. To enforce strict matching, set `VECTOR_SIZE_AUTODETECT=false`.
+**Upgrade safety:** `VECTOR_SIZE_AUTODETECT=true` (default) only adopts an existing collection dimension. It does not make vectors from different models compatible: any provider or model change requires recreating the Qdrant collection and a full re-embed, including a swap between two 1024d models. To enforce strict dimension matching, set `VECTOR_SIZE_AUTODETECT=false`.
 
 #### Provider Configuration
 
 Control via `EMBEDDING_PROVIDER` environment variable:
-- `auto` (default): Try Voyage → OpenAI → Ollama → FastEmbed → Placeholder
+- `auto` (default): Try Voyage → OpenAI → Ollama (only when configured) → FastEmbed → Placeholder
 - `voyage`: Use Voyage only (fail if unavailable)
 - `openai`: Use OpenAI only (fail if unavailable). Also works with OpenAI-compatible providers when `OPENAI_BASE_URL` is set.
 - `ollama`: Use Ollama only (fail if unavailable)
@@ -226,7 +230,7 @@ QDRANT_HOST=                 # OR hostname for self-hosted Qdrant (e.g. "qdrant"
 QDRANT_PORT=6333             # Port for self-hosted Qdrant (used with QDRANT_HOST)
 QDRANT_API_KEY=              # Qdrant Cloud API key (optional, not needed for self-hosted)
 QDRANT_COLLECTION=memories   # Collection name
-VECTOR_SIZE=1024             # Embedding dimensions (1024 for voyage-4, 768 for small, 3072 for large)
+VECTOR_SIZE=1024             # Embedding dimensions (1024 for voyage-4 or Ollama bge-m3, 768 for small, 3072 for large)
 VECTOR_SIZE_AUTODETECT=true  # Adopt existing collection dim on startup (false = fail on mismatch)
 
 # API configuration
@@ -236,8 +240,12 @@ ADMIN_API_TOKEN=             # For admin endpoints
 
 # Embedding configuration
 EMBEDDING_PROVIDER=auto      # auto|voyage|openai|ollama|local|placeholder
+VOYAGE_API_KEY=              # Recommended for new cloud deployments
+VOYAGE_MODEL=voyage-4
 OPENAI_API_KEY=              # For OpenAI or compatible provider (optional)
 OPENAI_BASE_URL=             # Custom endpoint for OpenAI-compatible APIs used by embeddings and classification/enrichment (optional)
+OLLAMA_BASE_URL=             # Intentional local/self-hosted Ollama endpoint
+OLLAMA_MODEL=                # e.g. bge-m3 (requires `ollama pull bge-m3`)
 
 # Consolidation intervals (seconds)
 CONSOLIDATION_DECAY_INTERVAL_SECONDS=86400    # 1 day (default)