luminary-memory 0.3.0__tar.gz → 0.3.2__tar.gz

{luminary_memory-0.3.0 → luminary_memory-0.3.2}/.github/workflows/ci.yml

@@ -24,7 +24,34 @@ jobs:
       - name: Test and coverage
         run: |
           python -m coverage run --source=src/luminary_memory -m pytest -q
-          python -m coverage report --fail-under=83
+          python -m coverage report --fail-under=82
+
+  native-packages:
+    name: Native plugin packages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Install the actual Python bridge
+        run: python -m pip install -e ".[dev]"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          check-latest: true
+          cache: npm
+      - run: npm ci --ignore-scripts
+      - run: npm run build:plugins
+      - run: npm run test:plugins
+      - run: npm run pack:plugins
+      - name: Upload installable plugin tarballs
+        uses: actions/upload-artifact@v4
+        with:
+          name: native-plugin-packages
+          path: artifacts/plugins/*.tgz
+          if-no-files-found: error
 
   pgvector-integration:
     name: PostgreSQL pgvector integration

luminary_memory-0.3.2/.github/workflows/publish.yml

@@ -0,0 +1,191 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  native-packages:
+    name: Build release plugin tarballs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Check Python, plugin and tag versions
+        env:
+          RELEASE_TAG: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || '' }}
+        run: |
+          python - <<'PY'
+          import json
+          import os
+          from pathlib import Path
+          import tomllib
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          for agent in ("pi", "opencode", "omp"):
+              path = Path("plugins") / agent / "package.json"
+              manifest = json.loads(path.read_text())
+              if manifest["name"] != f"luminary-memory-{agent}" or manifest["version"] != version:
+                  raise SystemExit(f"{path}: package name/version does not match Python {version}")
+          tag = os.environ["RELEASE_TAG"]
+          if tag and tag != f"v{version}":
+              raise SystemExit(f"Tag {tag!r} does not match Python/plugin version v{version}")
+          PY
+      - name: Install the actual Python bridge
+        run: python -m pip install -e ".[dev]"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          check-latest: true
+      - run: npm ci --ignore-scripts
+      - run: npm run build:plugins
+      - run: npm run test:plugins
+      - run: npm run pack:plugins
+      - name: Check complete, version-matched release tarballs
+        run: |
+          python - <<'PY'
+          import json
+          from pathlib import Path
+          import tarfile
+          import tomllib
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          expected = {f"luminary-memory-{agent}-{version}.tgz" for agent in ("pi", "opencode", "omp")}
+          directory = Path("artifacts/plugins")
+          actual = {path.name for path in directory.glob("*.tgz")}
+          if actual != expected:
+              raise SystemExit(f"Expected tarballs {sorted(expected)}, got {sorted(actual)}")
+          for filename in sorted(expected):
+              with tarfile.open(directory / filename, "r:gz") as archive:
+                  manifest = json.load(archive.extractfile("package/package.json"))
+                  if filename != f'{manifest["name"]}-{manifest["version"]}.tgz' or manifest["version"] != version:
+                      raise SystemExit(f"{filename}: packed manifest name/version mismatch")
+                  for member in ("package/dist/index.js", "package/README.md", "package/LICENSE"):
+                      entry = archive.getmember(member)
+                      if not entry.isfile() or entry.size == 0:
+                          raise SystemExit(f"{filename}: missing or empty {member}")
+          PY
+      - name: Upload validated plugin tarballs
+        uses: actions/upload-artifact@v4
+        with:
+          name: native-plugin-packages
+          path: artifacts/plugins/*.tgz
+          if-no-files-found: error
+
+  real-model:
+    # Release gate. Runs public strict recall against the real default
+    # embedding model on an isolated SQLite store and asserts which facts come
+    # back: the current scoped fact must be retrieved, an off-topic but
+    # graph-linked row must not be, cross-scope and expired rows stay out, and
+    # unanswerable queries abstain. This fails closed: if the model cannot be
+    # downloaded or run, the release does not happen.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Install package with the real embedding engine
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Gate on public strict recall with the default model
+        run: python scripts/smoke-real-model.py --report real-model-gate.json
+      - name: Upload gate report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: real-model-gate
+          path: real-model-gate.json
+          if-no-files-found: ignore
+
+  pypi:
+    needs: [real-model, native-packages]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/luminary-memory
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+          python -m build
+      - name: Download validated plugin tarballs
+        uses: actions/download-artifact@v4
+        with:
+          name: native-plugin-packages
+          path: artifacts/plugins
+      - name: Build Hermes skill artifact
+        run: |
+          mkdir -p skill_asset
+          zip -j skill_asset/luminary-memory-skill.zip hermes/SKILL.md hermes/README.md
+          ls -lh skill_asset/luminary-memory-skill.zip
+      - name: Publish to PyPI (trusted publishing / OIDC)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Trusted Publisher only — no API token. Configured at
+        # https://pypi.org/manage/account/publishing/. Never fall back to twine:
+        # an API token upload alongside Trusted Publishing triggers a PyPI alert.
+      - name: Attach skill and native plugin assets to GitHub Release
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            skill_asset/luminary-memory-skill.zip
+            artifacts/plugins/*.tgz
+          fail_on_unmatched_files: true
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+  npm:
+    name: Publish configured npm plugins
+    needs: [pypi, native-packages]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/') && vars.PUBLISH_NPM_PLUGINS == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: npm
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          check-latest: true
+      - name: Install an npm CLI with trusted publishing support
+        run: npm install --global 'npm@^11.5.1' --ignore-scripts
+      - name: Download the exact validated release tarballs
+        uses: actions/download-artifact@v4
+        with:
+          name: native-plugin-packages
+          path: artifacts/plugins
+      - name: Publish built tarballs using npm trusted publishing
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          version="${RELEASE_TAG#v}"
+          for agent in pi opencode omp; do
+            archive="artifacts/plugins/luminary-memory-${agent}-${version}.tgz"
+            test -s "$archive"
+          done
+          for agent in pi opencode omp; do
+            archive="artifacts/plugins/luminary-memory-${agent}-${version}.tgz"
+            npm publish "$archive" --access public --ignore-scripts --registry https://registry.npmjs.org
+          done

{luminary_memory-0.3.0 → luminary_memory-0.3.2}/.gitignore

@@ -23,6 +23,11 @@ sdist/
 var/
 wheels/
 
+# ---- Native plugin packages ----
+node_modules/
+artifacts/plugins/
+plugins/*/LICENSE
+
 # ---- Virtual environments ----
 .venv/
 venv/
@@ -97,6 +102,7 @@ REPORT-*.md
 
 # ---- Local documentation and planning (keep out of source) ----
 docs/*
+!docs/agent-integrations.md
 
 # ---- Generated API docs (regenerate via pdoc) ----
 docs/api/

{luminary_memory-0.3.0 → luminary_memory-0.3.2}/CHANGELOG.md

@@ -1,5 +1,114 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+
+- Harness-neutral UTF-8 JSON memory bridge with exact user/workspace/agent
+  ownership, strict recall, synchronous explicit writes, ID-scoped retraction,
+  current activity snapshots, and opt-in user-evidenced automatic curation.
+- Packaged native OpenCode V2 2.1.4, pi and omp adapters, installed with
+  `luminary-memory hook install`. Native tools plus pi/omp `/luminary` commands
+  support terminal interaction and serializable results for compatible clients.
+  Existing config and unrelated dependencies are preserved.
+- Supported-harness capability/setup guide, generic subprocess contract and
+  explicit desktop/web/Telegram interaction limits.
+- Luminary-maintained native npm package sources for pi, OpenCode and omp, built
+  from the canonical adapters with a locked Node/esbuild workspace. Installable
+  tarballs contain compiled ESM and native discovery metadata without bundling
+  host frameworks or embedding a maintainer's Python path.
+- Plugin build/consumer checks, version-synchronized release artifacts and
+  explicitly opt-in npm trusted publishing after the Python release gates.
+- Published initial `0.3.1` npm packages for pi, OpenCode and omp with verified
+  registry checksums and native installation/loading. Python bridge setup uses
+  a pinned public source commit until the next coordinated Python release.
+- Submitted OpenCode Ecosystem PR #58823 and pi's release-gated `pi-package`
+  discovery metadata. Catalog indexing and upstream approval remain separate
+  from successful npm publication.
+- Migrated the OpenCode `0.3.2` adapter to the actual V2 CLI/SDK namespace,
+  `@opencode/cli` and `@opencode/plugin` 2.1.4: default `Plugin.define`,
+  Promise domain APIs, plural `plugins`, native tools/progress/context hooks,
+  and successful-execution retention with per-session workspace ownership.
+  Real V2 sessions and SQLite verified memory operations, cross-workspace
+  isolation, automatic recall, user-grounded curation, rejection of
+  assistant-only claims, and removal cleanup. The old V1-only listing patch
+  was removed; the legacy Ecosystem PR is not a verified V2 listing.
+
+## [0.3.1] - 2026-10-25
+
+Measurement and recall-calibration release. No public API breaks; the default
+embedding model answers more paraphrases without loosening the abstention guard,
+and releases are now gated on real-model recall instead of a green unit suite
+alone.
+
+### Added
+
+- **Release gate on public strict recall** — `.github/workflows/publish.yml` had
+  no real-model job, so a release could ship while strict recall returned a
+  confident wrong answer. `scripts/smoke-real-model.py` drives
+  `MemoryClient.recall` end to end with the real default model on an isolated
+  store and asserts which facts come back, including abstention, scope isolation
+  and expiry. `pypi` requires it and fails closed.
+- **`--engine real|fake` for gold evaluation** — accuracy runs can use the real
+  embedding model while the latency smoke keeps its deterministic engine.
+  Reports record engine, model, Python/NumPy/Fastembed versions, the evaluation
+  clock, and per-case returned/excluded ids.
+- **Recorded baseline** — `benchmarks/baselines/gold-real-v1.json`.
+- **Extended gold fixture** — `benchmarks/gold_extended.jsonl` (28 memories, 15
+  cases) plus `build_gold_extended.py`. Kept out of CI while it is red; it is the
+  instrument for the remaining retrieval defects.
+- **Long-run soak harness** — `scripts/soak-test.py` drives ingest, recall and
+  lifecycle through hundreds of cycles on one store and fails on a lost control
+  fact, a no-answer query that starts answering, or recall p50 growing more than
+  3x across the run. A bounded version runs in the normal suite.
+- **Validity-window regression tests** — past-`valid_to` and future-`valid_from`
+  rows were already excluded in both strict and permissive mode, but nothing
+  pinned it. Four tests now do, verified to fail when the comparison is removed.
+
+### Changed
+
+- **Semantic-evidence floor is model-scoped and re-measured** — a single global
+  `0.78` cosine constant threw away correct paraphrases whose lexical coverage
+  was also low. `config.semantic_support_floor()` now returns a floor measured
+  per embedding model, `0.74` for `BAAI/bge-small-en-v1.5`, and keeps the
+  conservative `0.78` for any unmeasured model so an unmeasured model can only
+  abstain more.
+
+  The value comes from a sweep over two fixtures plus the release gate. It is
+  deliberately the lowest floor that stops a grounded but off-topic row from
+  being returned: that row's cosine is `0.7098`, which a `0.70` floor admitted.
+  On the controlled micro fixture the result is recall@10 `0.70` with
+  **`wrong_hit_rate` 0.00** and abstention 1.00; the extended fixture improves
+  from 0.25 to 0.08 wrong-hit. Some recall is given up on purpose — for a memory
+  layer a wrong answer is worse than an abstention.
+
+### Fixed
+
+- **Gold evaluation is date-invariant** — fixture timestamps are rebased so the
+  newest `observed_at` equals run time, preserving relative ages and validity
+  windows. The same commit now scores the same on any date.
+- **Grounding is no longer reported as relevance** — `evidence_support_precision`
+  counted a fully sourced but off-topic row as supported. It is replaced by
+  `wrong_hit_rate` / `wrong_hit_rows` / per-case `wrong_hit_ids` for relevance
+  and `source_grounded_rate` for stored-source grounding.
+
+### Documented
+
+- **Consolidation converges, it is not idempotent** — clustering is greedy and
+  single-pass, so a row similar to several others can be claimed by one cluster
+  and never compared against the rest. On a 25-memory store the observed shape is
+  `25 → 14 → 13 → 13`; schedule more than one pass after a bulk import.
+- **Unbounded ledger growth** — `episodes`, `memory_events` and
+  `memory_evidence` are append-only and untouched by `run_lifecycle()`. A direct
+  `ingest()` stores a verbatim episode copy of content already in `memories`, so
+  a long-lived store holds two copies of every fact with no retention bound.
+- **Query expansion can worsen ranking** — keeping the original query tokens does
+  not bound the result. Measured on the default model: the correct deploy fact
+  ranks `0.6495` against an unrelated docs URL at `0.6255`, but after expansion
+  the docs URL rises to `0.8084` and the deploy fact to `0.7074`. Documented as
+  an open defect with the measured values.
+
+
 ## [0.3.0] - 2026-08-24
 
 ### Summary

luminary_memory-0.3.2/CONTRIBUTING.md

@@ -0,0 +1,281 @@
+# Contributing
+
+Thanks for helping build luminary-memory.
+
+## Setup
+
+```bash
+git clone <repo> && cd luminary-memory
+pip install -e ".[dev]"
+```
+
+## Development workflow
+
+1. Create a branch from `develop`: `git checkout develop && git checkout -b feat/your-change`.
+2. Write a failing test first (`tests/`).
+3. Implement the minimal change.
+4. Update the tracked guide that owns the changed contract and the matching
+   static website guide in `website/js/docs-guides.js`. Keep ignored planning
+   notes under `docs/` out of the public source.
+5. Run the checks:
+
+```bash
+python -m pytest
+python -m ruff check src tests hermes/hooks
+node --check website/js/docs-guides.js
+```
+
+5. Commit with a conventional message.
+
+### Native plugin packages
+
+Use the latest Node.js 22 patch (at least 22.22.2) and Python 3.11+ from the
+repository root:
+
+```bash
+python -m pip install -e ".[dev]"
+npm ci --ignore-scripts
+npm run build:plugins
+npm run test:plugins
+npm run pack:plugins
+```
+
+The private root npm workspace is build tooling, not a publishable package.
+The three Luminary-maintained packages are `luminary-memory-pi`,
+`luminary-memory-opencode`, and `luminary-memory-omp`. "Maintained" does not
+imply endorsement by pi, OpenCode or omp, ownership of an npm name, or that an
+npm release already exists.
+
+Edit the canonical adapters under
+`src/luminary_memory/integrations/assets/`, not generated bundles. The build
+produces each `plugins/<agent>/dist/index.js` and copies the root license into
+the package. **A source checkout of `plugins/<agent>` without a build has no
+`dist` entry point and is not an installable plugin.** Packaging writes local
+installable tarballs to `artifacts/plugins/*.tgz`; it does not publish them.
+Use the instructions in each package README to install a built local directory
+or tarball into its host.
+
+The Node tests must be able to start the real Python bridge. Keep the editable
+Python installation available on `PATH`, or set `LUMINARY_PYTHON` to its Python
+executable. Package installation never installs Python dependencies, downloads
+models or runs an automatic pip/postinstall script. The existing Python-wheel
+copy installer is a separate installation path; remove copied hooks before
+enabling a native package so memory events are not registered twice.
+
+CI runs these same npm commands on the latest Node 22 patch with Python 3.11
+and an editable Python installation, then uploads the tarballs as the
+`native-plugin-packages` artifact. The real-model release gate below remains
+separate from the package tests.
+
+
+## Branch model
+
+- **`develop`**, integration branch. **All pull requests target `develop`.**
+- **`main`**, stable release branch, protected. Only maintainers merge release
+  commits into it (feature → develop → main → tag).
+
+## Release gate
+
+Tagging `v*` publishes to PyPI through `.github/workflows/publish.yml`, and
+`pypi` has a hard prerequisite: the `real-model` job. It runs
+
+```bash
+python scripts/smoke-real-model.py --report real-model-gate.json
+```
+
+which drives public `MemoryClient.recall` end to end on an isolated SQLite store
+with the real default embedding model and asserts **which facts come back**:
+
+- the current scoped deploy fact for both an exact and a paraphrased question;
+- an off-topic but graph-linked documentation row is not returned;
+- an expired row, another tenant's row and a scoped query stay inside their
+  boundaries;
+- unanswerable queries abstain.
+
+It fails closed — a wrong model, a failed download or a failed inference aborts
+the job — and the JSON report is uploaded as an artifact even when it fails.
+Run it locally before tagging; it is not part of the unit suite because it needs
+the real ONNX model.
+
+A gate that passes on a confident wrong answer is worse than no gate. When the
+gate fails, fix the retrieval defect; never relax the gate or swap in a stub
+embedder.
+
+### Versioning and release assets
+
+Before a release, use the existing version synchronizer from the repository
+root, for example:
+
+```bash
+bash scripts/bump-version.sh 0.3.2
+```
+
+It synchronizes the Python version, all three plugin manifest versions and the
+workspace versions in `package-lock.json`, preserving other JSON metadata.
+The private root `package.json` has no version. Review the generated changelog
+entry, then run the Python checks, native package commands and real-model gate
+before committing the release changes and creating the matching `vX.Y.Z` tag.
+
+The publish workflow builds, tests and packs native plugins, checks that every
+manifest matches `pyproject.toml`, and verifies the exact three nonempty
+tarballs contain a built entry point, README and license. Tag releases must
+also match `v<version>`. Both this package job and the existing real-model gate
+must pass before PyPI publication. After PyPI succeeds, tag pushes attach the
+Hermes skill zip and those exact `.tgz` files to the GitHub release, even when
+npm publication is disabled. Missing or mismatched packages fail closed.
+
+Manual `workflow_dispatch` keeps the Python publication path: it performs the
+same gates and builds, but does not create GitHub release assets or publish to
+npm, even if dispatched from a tag. A tag push, not a manual dispatch, is
+required for those external release actions.
+
+### Optional npm trusted publishing
+
+npm publication is **disabled unless** the repository Actions variable
+`PUBLISH_NPM_PLUGINS` is exactly `true`. Leave it unset while establishing
+package ownership and registry configuration. Local builds and downloadable
+release tarballs do not require npm publishing access.
+
+Before enabling it:
+
+1. Establish maintainer-controlled ownership of all three exact npm names:
+   `luminary-memory-pi`, `luminary-memory-opencode`, and `luminary-memory-omp`.
+   Availability is not ownership. Complete any initial package creation or
+   authenticated bootstrap required by npm separately; this workflow does not
+   reserve names or pretend to bootstrap trusted publishing.
+2. Configure an npm **trusted publisher for each package** for the correct
+   GitHub owner/repository, workflow filename `publish.yml`, and environment
+   name `npm`. Allow direct `npm publish` (a stage-only publisher cannot run
+   this workflow). Each manifest's `repository.url` must match that GitHub
+   repository. See [npm's trusted publishing requirements](https://docs.npmjs.com/trusted-publishers/).
+3. Configure the GitHub `npm` deployment environment and its protection rules;
+   keep the existing `pypi` environment and PyPI trusted publisher configured
+   independently. Protect release tags and restrict who can change the opt-in
+   variable or approve deployments.
+4. Only after all three package publishers are ready, set the repository
+   variable `PUBLISH_NPM_PLUGINS=true` and push a new, version-matched tag.
+
+The npm job runs on a GitHub-hosted runner with the latest Node 22 patch and
+npm `^11.5.1` (trusted publishing requires npm 11.5.1+ and Node 22.14+).
+It requests `id-token: write`, downloads the already validated tarballs from
+the same workflow run, and publishes each exact tarball only after the
+real-model gate and PyPI job succeed. It never rebuilds a package at publish
+time. Publishing uses `--access public --ignore-scripts` against
+`https://registry.npmjs.org`; no npm token secret, credential logging or
+token-based fallback is configured.
+
+The workflow's default permission is `contents: read`. The PyPI job requests
+`id-token: write` for its existing trusted publishing and `contents: write` to
+attach GitHub release assets; the optional npm job requests only
+`contents: read` and `id-token: write`. Neither local development commands nor
+manual Python releases force npm publication.
+
+The three npm uploads are sequential, not transactional. If registry
+authorization or an upload fails, the job fails; it does not mask the error,
+republish an existing immutable version or fall back to credentials. Inspect
+which versions actually reached npm before planning recovery. Fix npm
+configuration without rerunning a successful PyPI upload blindly; npm
+publication must continue to use the validated release tarballs.
+
+
+## Commit conventions
+
+- `feat:`, new feature
+- `fix:`, bug fix
+- `docs:`, documentation only
+- `improve:`, refactor or enhancement without behavior change
+- `chore:`, build/tooling
+
+## Coding standards
+
+- Python 3.11+, type-hinted.
+- `ruff` clean, `pytest` green.
+- TDD where feasible, test first, then implement.
+- Keep the public API (`MemoryClient`) stable; add rather than break.
+- Full-source coverage is reported and must not regress from the current
+  evidence-backed baseline (`83%`, 5,037 statements). Every changed behavior
+  needs a targeted regression or invariant test; do not inflate coverage with
+  tests that only execute lines without checking outcomes. PostgreSQL-only
+  branches are verified separately by the pgvector integration job.
+
+### Long-run checks
+
+Changes to ingest, recall, lifecycle or retention must also survive a soak run,
+because those defects only appear across cycles:
+
+```bash
+python scripts/soak-test.py --cycles 400 --per-cycle 5 --report /tmp/soak.json
+```
+
+It fails on a lost control fact, a no-answer query that starts returning rows,
+or recall p50 growing more than `3x` between the first and last fifth of the
+run. See [Lifecycle](docs/lifecycle.md#long-run-behaviour) for what it measures
+and the current observed numbers.
+
+## AI assistance notice
+
+If you use **any kind of AI assistance** to contribute to luminary-memory, please
+disclose it in the pull request together with the extent of the usage. For
+example:
+
+> This PR was written primarily by Claude Code.
+>
+> I consulted ChatGPT to understand the codebase, but the solution was fully
+> authored manually.
+
+This helps reviewers apply the right level of scrutiny. AI assistance isn't
+always perfect, even when used with the utmost care, a quick disclosure goes a
+long way. Please don't use AI to write the pull request description or
+contributor communication; keep it concise and in your own voice.
+
+## Pull requests
+
+- One logical change per PR.
+- Target the **`develop`** branch.
+- Link the issue if applicable.
+- CI must pass before merge.
+- Automated checks run on every PR:
+  - **CI**, unit tests (Python 3.11 & 3.12) + lint.
+  - **pgvector integration**, real Postgres round-trips (HNSW, JSONB, rollback).
+  - **Native plugin packages**, Node 22 build/tests/local pack with the actual
+    Python bridge available; uploads all three installable `.tgz` artifacts.
+  - **Triage**, auto-labels the PR and welcomes first-time contributors.
+  - **Contributor check**, a soft account/language triage hint for maintainers.
+
+## Testing
+
+Run the full suite (SQLite + unit tests) locally:
+
+```bash
+python -m pytest          # 505 passed, 3 skipped at the current baseline
+python -m ruff check src tests hermes/hooks
+```
+
+Coverage (full-source baseline):
+
+```bash
+python -m pytest --cov=luminary_memory --cov-report=term
+```
+
+The current local baseline is `83%` (`5,037` statements, `881` missed). The
+number is intentionally reported honestly while the defensive PostgreSQL and
+failure branches continue to receive integration coverage; the quality gate
+is the invariant-focused test suite plus the CI/verification coverage gate
+`--fail-under=82`.
+
+### Postgres / pgvector integration tests
+
+`tests/test_backend_pgvector.py` contains real-Postgres round-trips that are
+**skipped unless `LUMINARY_PG_DSN` is set**. CI provides a Postgres service for
+these (see `.github/workflows/ci.yml`). To run them locally:
+
+```bash
+# spin up a throwaway Postgres with the pgvector extension
+docker run -d --name luminary-pg -p 5432:5432 \
+  -e POSTGRES_USER=luminary -e POSTGRES_PASSWORD=luminary -e POSTGRES_DB=luminary \
+  pgvector/pgvector:pg16
+
+# point the tests at it
+export LUMINARY_PG_DSN=postgresql://luminary:***@localhost:5432/luminary
+python -m pytest tests/test_backend_pgvector.py -v
+```