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

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

@@ -82,7 +82,7 @@ jobs:
         run: ruff check src tests hermes/hooks
       - name: Run pgvector integration tests
         env:
-          LUMINARY_PG_DSN: postgresql://luminary:luminary@localhost:5432/luminary
+          PG_DSN: postgresql://luminary:luminary@localhost:5432/luminary
         run: >-
           python -m coverage run --source=src/luminary_memory/backends
           -m pytest -q tests/test_backend_pgvector.py

{luminary_memory-0.3.2 → luminary_memory-0.3.3}/.github/workflows/publish.yml

@@ -45,7 +45,9 @@ jobs:
           node-version: "22"
           check-latest: true
       - run: npm ci --ignore-scripts
-      - run: npm run build:plugins
+      - run: npm run build
+      - run: npm run check:opencode
+      - run: npm run test:ui-contracts
       - run: npm run test:plugins
       - run: npm run pack:plugins
       - name: Check complete, version-matched release tarballs
@@ -78,6 +80,53 @@ jobs:
           name: native-plugin-packages
           path: artifacts/plugins/*.tgz
           if-no-files-found: error
+      - name: Upload complete wheel resources
+        uses: actions/upload-artifact@v4
+        with:
+          name: inspector-resources
+          path: |
+            src/luminary_memory/integrations/assets/compiled/
+            src/luminary_memory/inspector/assets/browser/
+          if-no-files-found: error
+
+  python-native-contracts:
+    name: Test Python against the official Hermes SDK
+    needs: [native-packages]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          repository: NousResearch/hermes-agent
+          ref: v0.22.5
+          path: .native-sdk/hermes-agent
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Install test and native HTTP dependencies
+        # Hermes 0.22.5 imports hermes_yaml, which requires ruamel.yaml.
+        run: python -m pip install -e ".[dev]" fastapi httpx python-multipart "ruamel.yaml==0.18.16"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          check-latest: true
+      - name: Install the consumer-test build toolchain
+        run: npm ci --ignore-scripts
+      - name: Download validated native and UI resources
+        uses: actions/download-artifact@v4
+        with:
+          name: inspector-resources
+          path: src/luminary_memory
+      - name: Build and install a separate inspector consumer wheel
+        run: |
+          python -m build --wheel --outdir "$RUNNER_TEMP/inspector-wheel"
+          python -m venv "$RUNNER_TEMP/inspector-wheel-env"
+          "$RUNNER_TEMP/inspector-wheel-env/bin/python" -m pip install "$RUNNER_TEMP/inspector-wheel/"*.whl
+      - name: Require the real SDK and run the Python suite
+        env:
+          INSPECTOR_INSTALLED_PYTHON: ${{ runner.temp }}/inspector-wheel-env/bin/python
+        run: python scripts/test-hermes-sdk.py .native-sdk/hermes-agent -q
 
   real-model:
     # Release gate. Runs public strict recall against the real default
@@ -108,7 +157,7 @@ jobs:
           if-no-files-found: ignore
 
   pypi:
-    needs: [real-model, native-packages]
+    needs: [real-model, native-packages, python-native-contracts]
     runs-on: ubuntu-latest
     environment:
       name: pypi
@@ -122,6 +171,11 @@ jobs:
         with:
           python-version: "3.11"
           cache: pip
+      - name: Download validated native and UI resources
+        uses: actions/download-artifact@v4
+        with:
+          name: inspector-resources
+          path: src/luminary_memory
       - name: Build sdist and wheel
         run: |
           python -m pip install --upgrade pip

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

@@ -117,3 +117,6 @@ website/*.png
 
 # ---- Internal plan files ----
 website/plan.md
+
+# Private implementation plans, runtime probes and acceptance captures
+.superpowers/

luminary_memory-0.3.3/AGENTS.md

@@ -0,0 +1,6 @@
+# Repository instructions
+
+## GitHub releases
+
+Write structured, human-readable release notes. Before creating or editing a
+GitHub release, follow **Release notes style** in `CONTRIBUTING.md`.

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

@@ -1,6 +1,225 @@
 # Changelog
 
-## [Unreleased]
+## [0.3.3] - 2026-11-10
+
+Interactive memory inspection, explicit owner controls and safer native recall.
+This version includes only the verified native surfaces and the opt-in loopback
+companion; the interactive UI roadmap is incomplete.
+
+### Compatibility
+
+- Native OpenCode Web GUI discovery remains unsupported. Server tools remain
+  separate from a client-native inspector; the companion is not a Web plugin.
+- Hermes CLI/TUI inspector rendering remains blocked on authenticated native
+  context and scope lifecycle. Existing provider and command integrations remain
+  separate from that unfinished visual target.
+
+### Added
+
+- Optional operator config file (`~/.luminary/luminary.env`) shared by native
+  integrations and the CLI. Env-style `LUMINARY_*` settings load before
+  `Settings` is constructed; process environment wins, `LUMINARY_CONFIG_FILE`
+  overrides the path or disables loading with `none`/`off`, and edits apply on
+  the next bridge call without restarting the host.
+- Portable OpenCode agent skill (`opencode/SKILL.md`) covering scoped recall,
+  user-approved durable writes, ID-scoped retraction, result semantics,
+  configuration, and bridge troubleshooting. Install it under
+  `~/.config/opencode/skills/luminary-memory/` or a project's `.opencode/skills/`.
+- Authorized memory inspector service with bounded browse/detail/history,
+  explicit project bindings and independent sharing capabilities. Confirmed
+  corrections preserve ownership and create successor versions; stale revisions
+  and revoked proposals fail closed instead of overwriting newer content.
+- Explicit optional loopback inspector with nine views, deterministic Summary,
+  separate owner confirmations, one-use sign-in, session cookies and same-origin
+  CSRF protection. Installing or opening a UI does not enable saving or call AI.
+- Complete compiled native-package installation instead of copying an orphaned
+  TypeScript entry. Unapproved local changes are preserved, and owned legacy
+  hooks require an explicit cutover to prevent duplicate loading.
+- Keyboard-accessible entity neighborhoods and supporting-memory inspection.
+  Recall Activity records actual retrieval rank/score separately from returned
+  context order; unrelated core rows cannot turn native recall abstention into success.
+- Summary includes authorized lifecycle counts and stored created/updated
+  timestamp bounds in UTC, including offset-aware ordering and microseconds.
+  Missing or invalid timestamp coverage is explicit; refresh remains offline.
+
+### Fixed
+
+- Inspector dispatch resolves storage and other settings from the same supplied
+  launcher environment and config as the authorized context, without mutating
+  the process environment. Config files cannot provide trusted inspector channels.
+  A conflicting launcher home or unavailable selected config fails closed, and
+  `~` SQLite paths resolve before the store is opened.
+- The companion treats non-object JSON from the inspector process as a bounded,
+  redacted failure, distinguishing read failures from unknown mutation outcomes.
+- The release workflow installs the YAML dependency required to import the
+  official Hermes SDK in a clean environment.
+- OpenCode's compact inspector shows bounded, server-reported record permissions;
+  native session, policy and explicit-project changes discard stale snapshots.
+  Read-only shared projects no longer display the previous project's edit rights.
+  Native sharing cards identify the granting agent, recipient and capabilities.
+- The opt-in browser companion includes scoped record permissions in compact
+  mode, limits activity rendering to five events and clears the overview when
+  its project selection changes.
+- Hermes UI installation ignores generated Python bytecode without replacing
+  profile-owned caches or activating a provider. Wheels include only required
+  native/UI resources, so incidental `__pycache__` files cannot break installation.
+- Hermes panels inherit native text colors and use documented host border
+  tokens; dashboard themes can no longer turn the whole inspector transparent.
+- Hermes tab navigation and refresh select the requested backend projection.
+  Sharing displays grants instead of memory rows; memory filters stay limited
+  to the views that actually support them.
+- Hermes session admission loads the selected view immediately, including the
+  native plugin settings page, rather than presenting browse rows as settings.
+- Hermes REST inspectors preserve their bound scope through socket reconnects;
+  only native session, profile and gateway activation changes invalidate it.
+- Hermes compact views now show read-only context, server-reported record
+  permissions, up to five activity events, and a full-inspector entry instead
+  of squeezing all tabs and mutation forms into a sidebar.
+- The dashboard overview uses the rendered native `pre-main` slot, behind an
+  explicit open/close control, rather than the unmounted `sidebar` slot.
+- omp headless RPC returns the scoped inspector state instead of silently
+  discarding it through unavailable dialogs. UI-enabled RPC keeps its native
+  dialogs; neither mode constructs terminal components. Acceptance was
+  re-verified on the currently installed omp **18.18.5** with a copy-installed
+  extension: `/luminary full` JSON state over a seeded store, headless RPC state
+  delivery, and UI-enabled RPC opening all nine native dialogs.
+- Native OpenCode Summary keeps authorized lifecycle totals and UTC time bounds
+  visible even when recent changes are present. Activity and Relations now use
+  the same operational and supporting-memory labels as the pi/omp inspector.
+- Sharing now lists the native actor's incoming/outgoing grants rather than
+  unrelated memory rows. Project, user and actor filtering happens before SQL
+  pagination; capability lists remain independent and browsing grants no access.
+- Inspector headers expose secret-safe native agent/profile/store/host labels,
+  not frontend-selected identity or the native bearer. Long pi/omp terminal
+  proposals use a scrollable review and a separate Cancel-first confirmation;
+  narrow terminals no longer hide the decision below a long proposal.
+- Terminal memory rows identify lifecycle state and revision, including deleted
+  and superseded records explicitly requested through status filters. Memory
+  search controls appear only on supported views; shared-resource selection
+  does not offer native-own-project policy mutations.
+- Concurrent store startup now keeps inspector schema inspection and migration
+  under the existing cross-process writer transaction. Independent SQLite
+  workers no longer race to add the same audit-ownership column.
+- Native recall preserves the engine's abstention and returns only relevant,
+  current rows, including core-tagged rows only when retrieval selects them.
+  Reference data stays outside system instructions, is request-local, and is
+  serialized once as complete records. Empty recall adds no model message or
+  transcript entry in OpenCode, pi, or omp.
+- Native model writes require a bounded quote verified against current user
+  input by the adapter, not self-evidence or a model-supplied confirmation flag.
+  Per-call launcher provenance cannot be restored from an operator config file.
+  User-grounded paraphrases retain their original quote without invented full
+  confidence; owner-typed commands remain explicit assertions. Core/rule
+  promotion uses the owner-confirmed inspector. Existing records are not
+  retroactively re-certified or rewritten.
+- Structural transcript-noise filtering now runs in shared API/CLI/bridge
+  retrieval as well as Hermes. Short legitimate facts remain eligible.
+  Destructive-verb suppression is not reinstated; no language keyword list
+  decides whether a live user request may recall.
+- Precompiled OpenCode TUI binds Solid/OpenTUI imports to the host's shared
+  runtime instead of creating an independent reactive owner and a blank panel.
+  Native review dialogs keep the decision visible while complete proposals
+  scroll; cancellation is the default.
+- OpenCode copy installation now explicitly tells the operator to install its
+  declared Node dependencies before restart. It does not silently run npm or
+  download memory models.
+
+- Denied inspector responses now refresh their reference time and context
+  metadata while clearing inaccessible content, rather than retaining the
+  preceding successful read's timestamp.
+- Direct npm packaging keeps compiler diagnostics on stderr, preserving valid
+  machine-readable `npm pack --json` output without hiding build warnings.
+- Native Hermes settings include backend/model configuration and separate
+  readiness information without exposing profile credentials. Profile-local
+  changes survive restart; unrelated settings do not implicitly enable saving
+  or modify sibling profiles.
+- Optional explanation requires a nonblank model selection before disclosure;
+  a configured URL alone is not reported as a configured explanation.
+
+- Inspector graph reads stay in the selected PostgreSQL schema. A missing graph
+  table now reports unavailable instead of silently reading a fallback table.
+- Hermes pagination preserves the original operation, project and filters.
+  Context/project changes discard the cursor rather than replaying an old page.
+
+- Hermes provider Activity now separates durable saves, duplicate suppression,
+  skipped curation, session episodes and recall. Duplicate writes no longer
+  claim a new save; replaying an episode does not claim another insertion.
+  Queued retention keeps its original session. Prepared context is not reported
+  as confirmed model delivery, and operational events do not inflate Summary
+  changes or copy raw prompts into Activity.
+
+- PostgreSQL entity expansion now groups unique authorized neighbor names and
+  ranks their strongest edges. The previous `DISTINCT`/`ORDER BY` combination
+  was rejected by PostgreSQL and silently left the query unexpanded; duplicate
+  edges no longer make ranking ambiguous.
+- Native bridge recalls now append scoped start/result/error/cancellation events
+  without storing raw queries or exception text. Activity replay preserves the
+  same source/session/reference metadata; recall never claims a saved memory or
+  confirmed injection, and Summary excludes recall events before pagination.
+- Activity checkpoints bind replay to the native session, project and current
+  access policy. Missing witnessed history raises a visible gap instead of a
+  healthy empty result. “Check new activity” loads only unseen events; Refresh
+  resets to a recent snapshot without replaying writes.
+- Memory-record exports retain source IDs, and imports remap predecessor links
+  instead of treating source IDs as destination IDs. Invalid/cyclic lineage is
+  rejected; lineage imports roll back on incompatible duplicates or audit
+  failure. Independent owners and sessions are no longer collapsed by import
+  deduplication, and inspector receipts separate actual saves from duplicates.
+  Re-importing an unchanged version chain reuses its original ancestors;
+  historical source IDs and creation timestamps prevent merging distinct
+  observations.
+- Export/native-settings failures after external persistence starts now report
+  an unknown outcome, including lost commit acknowledgements. SQL rollback is
+  not presented as proof that a selected file or profile stayed unchanged.
+- SQLite keyword indexes now update only when content or tags change. This
+  prevents nested content-revision updates from deleting FTS entries twice;
+  existing update triggers and derived indexes migrate on the next store open.
+- Confirmed inspector creation preserves the verified native session in both
+  the record and durable audit, and distinguishes saved records from duplicates.
+  Corrections attribute the new observation to the verified current session
+  and a distinct inspector source ID without changing the original ownership.
+  Explicit cross-session versioning updates the predecessor and keeps stale
+  editor protection; session-bound clients still cannot cross that boundary.
+- Optional AI explanations consume disclosure consent before sending, reject
+  redirects, and release database locks during provider calls. Revocation or
+  changed facts discard stale responses; model text has no tool/write authority.
+- Telegram activity no longer treats global new memory IDs as this turn's
+  writes. Routing, profile-local secrets, exact ownership/session cursors,
+  expiry/validity filtering, evidence/ID visibility, and acknowledgement of
+  displayed rows prevent cross-chat disclosure and silent backlog loss.
+- Telegram cursor locking now works on Windows and POSIX, fails closed, and
+  never yields a contextmanager body twice after a delivery/state failure.
+- **Query expansion no longer decides what answers a question.** Expanded text
+  appends entity names harvested from the graph neighbourhood of a shared
+  entity, and those names usually belong to the neighbour memory itself, so
+  scoring against them let a memory supply its own evidence: one shared entity
+  lifted an unrelated memory from `0.5436` to `0.8024` and made "what is the
+  cluster fingerprint?" return a memory about load tests. Expansion now only
+  selects candidates; every candidate is scored against the question as asked.
+  The reported documentation-URL answer for "where will Luminary go live now?"
+  is gone, and `tests/test_query_expansion.py` pins it through public
+  `MemoryClient.recall`.
+- **Dense similarity decides support, not the loudest signal.** Keyword and
+  graph scores saturate (an FTS `bm25` of 2.6 and a graph weight of 8.0 both
+  normalise to 1.0), so `max(...)` let one shared word outrank the question.
+  They now stand in only for rows without a usable embedding. Combined with the
+  scoring change this takes micro recall@10 from `0.70` to `0.85` at
+  `wrong_hit_rate` `0.00`, and lifts extended-fixture abstention from `0.33` to
+  `1.00`.
+- **The support floor is re-measured, not re-tuned.** `0.74` was chosen while
+  expansion could raise a score; on the raw-query scale the highest confident
+  wrong answer is `0.5991` and the lowest correct answer `0.6439`, so the floor
+  is their midpoint, `0.635`. Nothing outside that gap could be correct.
+- **Tokenisation no longer swallows sentence-final punctuation.** `_token_set`
+  keeps `.` `:` `/` inside a token so identifiers such as `gpt-4o` and URLs
+  survive, but the same pattern absorbed the last word of every memory
+  (`production.`, `cluster.`), which could never match a query token
+  (`production`, `cluster`). Matching bug only; no benchmark metric moves.
+- **A weakly-grounded row no longer pads a well-grounded answer.** When a
+  candidate covers at least half the question's tokens, rows that cover almost
+  none are dropped instead of being returned alongside it.
+
+## [0.3.2] - 2026-10-25
 
 ### Added
 
@@ -181,6 +400,13 @@ Cloudflare-protected gateways.
   provider/runtime boundary, hook cursor resolution, and the current `505`
   regression baseline.
 
+### Removed
+
+- **Destructive-imperative recall suppression** was removed in `f303511`.
+  The old Hermes query-word heuristic introduced in 0.2.18 did not remain
+  active in 0.3.0. This entry corrects the missing removal history; it does
+  not claim an unrecorded rationale or restore that heuristic.
+
 ### Tests & documentation
 
 - Added scope, lifecycle, hash-repair, claim-rollback, inactive-hook, and
@@ -211,12 +437,13 @@ Cloudflare-protected gateways.
 
 ### Added
 
-- **Recall noise filter** — shell/terminal artifacts (`&&`, `===`, `echo `,
-  etc.) and near-empty content are dropped before they can pollute context.
-- **Destructive-imperative suppression** — a query that is a destructive
-  instruction (`hapus`, `delete`, `remove`, `stop`, `disable`, ...) suppresses
-  the recall block so the agent follows the instruction instead of re-anchoring
-  on the stored topic.
+- **Hermes recall noise filter** — shell/terminal artifacts (`&&`, `===`,
+  `echo `, etc.) and near-empty content were dropped by the provider formatter.
+  This was not yet filtering on the shared API/CLI retrieval path.
+- **Destructive-imperative suppression (historical)** — Hermes suppressed
+  recall for destructive instructions (`hapus`, `delete`, `remove`, `stop`,
+  `disable`, ...). This query-word heuristic was removed in 0.3.0; see Removed
+  above. It is not the current recall policy.
 - **Scoped claim/evidence schema** — ownership fields, episodes, claims,
   claim evidence, memory evidence, conflict/supersession status, and
   `needs_reindex` repair state are migrated idempotently for existing SQLite

{luminary_memory-0.3.2 → luminary_memory-0.3.3}/CONTRIBUTING.md

@@ -76,8 +76,9 @@ separate from the package tests.
 
 ## Release gate
 
-Tagging `v*` publishes to PyPI through `.github/workflows/publish.yml`, and
-`pypi` has a hard prerequisite: the `real-model` job. It runs
+Tagging `v*` publishes to PyPI through `.github/workflows/publish.yml`.
+`pypi` requires the `real-model`, `native-packages`, and
+`python-native-contracts` jobs. The real-model gate runs:
 
 ```bash
 python scripts/smoke-real-model.py --report real-model-gate.json
@@ -119,8 +120,8 @@ 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
+also match `v<version>`. The package, real-model, and official Hermes SDK
+contract gates 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.
 
@@ -129,6 +130,20 @@ 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.
 
+### Release notes style
+
+Write structured, human-readable notes for the actual release: a descriptive
+version title, a short summary, and readable `##` feature sections with normal
+prose and focused bullets. These formatting rules are version-independent.
+
+Never leave a published release empty or asset-only. Do not use small/subscript
+HTML, wrap the whole description in a code block, or substitute a raw commit
+dump for release notes. Reserve code blocks for short installation commands.
+State only shipped behavior and verified registry availability.
+
+The workflow attaching assets does not finish the release. Fill in the release
+notes and inspect the actual GitHub rendering before reporting completion.
+
 ### Optional npm trusted publishing
 
 npm publication is **disabled unless** the repository Actions variable
@@ -193,10 +208,11 @@ publication must continue to use the validated release tarballs.
 - 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.
+  evidence-backed baseline (`83%`, 5,092 statements, 876 missed). 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
 
@@ -247,7 +263,7 @@ contributor communication; keep it concise and in your own voice.
 Run the full suite (SQLite + unit tests) locally:
 
 ```bash
-python -m pytest          # 505 passed, 3 skipped at the current baseline
+python -m pytest
 python -m ruff check src tests hermes/hooks
 ```
 
@@ -257,17 +273,58 @@ Coverage (full-source baseline):
 python -m pytest --cov=luminary_memory --cov-report=term
 ```
 
-The current local baseline is `83%` (`5,037` statements, `881` missed). The
+The current local baseline is `541 passed, 3 skipped` at `83%` (`5,092`
+statements, `876` 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`.
 
+### Official Hermes SDK contracts
+
+Standalone tests skip native schema cases when Hermes is not installed; they
+never install a production SDK substitute. To exercise those cases, use an
+official source checkout matching the supported host:
+
+```bash
+git clone --depth 1 --branch v0.22.5 https://github.com/NousResearch/hermes-agent.git ../hermes-agent-sdk
+python -m pip install -e ".[dev]" fastapi httpx python-multipart
+python scripts/test-hermes-sdk.py ../hermes-agent-sdk -q
+```
+
+The runner imports the real provider/config SDK before pytest, verifies that
+both modules came from that checkout, and uses a temporary Hermes home. Missing
+or incompatible SDK modules fail the run before native cases can be skipped.
+The release workflow runs this mode as a mandatory publication prerequisite.
+
+### Installed inspector consumer
+
+After `npm ci --ignore-scripts && npm run build`, build a wheel and install it
+into a separate Python virtual environment. Run its real subprocess/controller
+contract from the checkout:
+
+```bash
+INSPECTOR_INSTALLED_PYTHON=/absolute/path/to/wheel-env/bin/python \
+  python -m pytest tests/inspector/test_transport.py -q
+```
+
+On Windows, point the environment variable at `wheel-env/Scripts/python.exe`.
+The runner bundles the controller/transport sources shipped in that installed
+wheel, then runs outside the checkout with repository import paths removed.
+It checks real scoped SQLite reads, permissions, confirmed edits, stale-editor
+conflicts and denied-result metadata. No retrieval/model-quality claim is made.
+A missing optional interpreter skips only this case locally; a configured but
+broken installation fails. The release SDK job always supplies a clean installed
+wheel, making this contract a publication prerequisite.
+
+
 ### 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:
+**skipped unless an isolated `PG_DSN` is set**. `LUMINARY_*` operator settings
+are cleared by test isolation; do not point tests at a production store. CI
+provides a disposable Postgres service (see `.github/workflows/ci.yml`).
+To run these checks locally:
 
 ```bash
 # spin up a throwaway Postgres with the pgvector extension
@@ -276,6 +333,6 @@ docker run -d --name luminary-pg -p 5432:5432 \
   pgvector/pgvector:pg16
 
 # point the tests at it
-export LUMINARY_PG_DSN=postgresql://luminary:***@localhost:5432/luminary
+export PG_DSN=postgresql://luminary:***@localhost:5432/luminary
 python -m pytest tests/test_backend_pgvector.py -v
 ```

{luminary_memory-0.3.2 → luminary_memory-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: luminary-memory
-Version: 0.3.2
+Version: 0.3.3
 Summary: A lightweight, self-hosted memory layer for AI agents
 Project-URL: Homepage, https://github.com/alertxsto/luminary-memory
 Project-URL: Repository, https://github.com/alertxsto/luminary-memory
@@ -41,8 +41,6 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/pypi/pyversions/luminary-memory?color=8ab4e8)](https://pypi.org/project/luminary-memory)
 [![License](https://img.shields.io/github/license/alertxsto/luminary-memory?color=8ab4e8)](LICENSE)
 [![CI](https://github.com/alertxsto/luminary-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/alertxsto/luminary-memory/actions)
-[![Tests](https://img.shields.io/badge/tests-505%2B%20passing-8ab4e8)](https://github.com/alertxsto/luminary-memory/actions)
-[![Coverage](https://img.shields.io/badge/coverage-83%25-8ab4e8)](https://github.com/alertxsto/luminary-memory)
 [![Stars](https://img.shields.io/github/stars/alertxsto/luminary-memory?color=8ab4e8)](https://github.com/alertxsto/luminary-memory)
 
 **Self-hosted · Private · Budget-aware · Self-maintaining**
@@ -63,7 +61,7 @@ Agents are only as good as what they remember. A stateless agent re-learns the s
 
 Strategies fuse via **weighted RRF (semantic 0.4, keyword 0.3, graph 0.2, temporal 0.1)** → **scope/status/time filtering** → **conservative confidence and abstention** → **adaptive cutoff** → **Jaccard deduplication** → **token budget**. Short queries may be expanded with graph entities or stored content tokens before embedding; there is no language-specific alias classifier.
 
-**Important rules always in context.** Durable rules tagged `core` are auto-loaded into the system prompt every session (the DB-backed `MEMORY.md`). All other durable memories are surfaced through query retrieval: relevant facts are recalled on demand (ranked by query relevance) and merged with the core block under anti-duplication. When durable recall abstains, the Hermes provider can also expose a bounded exact-session continuity block so an ambiguous follow-up stays attached to its active task without turning raw conversation into durable memory.
+**Core and recall are different surfaces.** The Hermes provider separately loads owner-designated `core` rules (the DB-backed `MEMORY.md`) and deduplicates them against query retrieval. Native OpenCode, pi, and omp adapters return only relevant, evidence-bearing recall; a core tag cannot turn abstention into success. Their historical reference stays outside system instructions and the persistent transcript. Hermes can also expose bounded exact-session continuity without turning raw conversation into durable memory.
 
 ---
 
@@ -103,8 +101,8 @@ luminary-memory stats
 ## Native hooks for supported harnesses
 
 The harness-neutral JSON bridge supports native adapters without coupling the
-memory engine to one runner. Shipped adapters cover OpenCode V2's
-`@opencode/plugin` 2.1.4 API, pi, and omp; Hermes keeps its provider integration.
+memory engine to one runner. The current source targets OpenCode V2's
+`@opencode/plugin` 2.2.0 API, pi, and omp; Hermes keeps its provider integration.
 
 ```bash
 luminary-memory hook install opencode  # or pi / omp; project-local by default
@@ -114,7 +112,19 @@ Automatic scoped recall, opt-in user-grounded curation, explicit memory tools,
 and accurate stored/duplicate/skipped/error results. pi/omp also expose
 `/luminary` commands and native UI dialogs. Server tool results/custom messages
 are available to compatible desktop/web clients; no universal frontend plugin
-API or standalone desktop app is assumed.
+API or standalone desktop app is assumed. A portable OpenCode agent skill lives
+at [`opencode/SKILL.md`](opencode/SKILL.md); install it under
+`~/.config/opencode/skills/luminary-memory/` or a project's `.opencode/skills/`.
+
+The `0.3.3` source includes native interactive inspectors for the verified
+surfaces: OpenCode CLI/Desktop, pi and omp, Hermes Desktop/dashboard and an
+explicitly launched loopback companion. The `0.3.2` registry packages do not
+include the inspector; see the installation guide for current availability.
+Two native targets remain blocked on upstream
+contracts and are recorded in the roadmap: OpenCode Web GUI contribution
+discovery and Hermes terminal/TUI authority plus scope lifecycle. See
+[development setup and explicit companion launch](docs/agent-integrations.md#interactive-inspectors)
+and the [native support/acceptance roadmap](docs/ROADMAP.md).
 
 ### Luminary-maintained plugin packages
 
@@ -136,7 +146,8 @@ The three installable tarballs are written to `artifacts/plugins/`. Set
 Choose the native package **or** the copied hook, never both.
 
 Registry names are `luminary-memory-pi`, `luminary-memory-opencode`, and
-`luminary-memory-omp`. They are not claimed published by this source change.
+`luminary-memory-omp`. All three npm packages and the Python bridge are
+published at `0.3.2`; npm `latest` points to that version.
 The pi manifest includes `pi-package` for eligibility in the
 [official package catalog](https://pi.dev/packages). OpenCode's existing
 Ecosystem PR targets legacy V1 docs, not a verified V2 listing; no V2 website
@@ -307,7 +318,7 @@ after, and a background lifecycle keeps the store lean.
 | **Abstention** | Strict provider/CLI paths can return `abstain` when support is weak or ambiguous |
 | **Evidence** | Stored claims retain evidence quote, source, validity time, and audit provenance |
 | **Conflict safety** | Conflicting claim keys remain versioned/conflicted until explicit supersession or resolution |
-| **Core memory** | Rules tagged `core` are auto-loaded into the system prompt every session (the DB-backed MEMORY.md), independent of query match |
+| **Core memory** | Hermes separately loads designated `core` rows; native adapters require core-tagged rows to pass ordinary retrieval |
 | **Weighted fusion** | Each strategy carries a tunable weight (semantic 0.4, keyword 0.3, graph 0.2, temporal 0.1), so high-signal strategies dominate the ranking |
 | **Query expansion** | Short queries are expanded with co-occurring graph entities before embedding; when the graph is empty, content tokens from a topically related important memory may be appended (v0.2.15). No language-specific alias list is used. |
 | **Importance boost** | Memories at importance ≥ 0.8 get a ranking bonus, lifting durable rules above weak-but-recent noise |