@psiclawops/hypermem 0.9.3 → 0.9.5

package/ARCHITECTURE.md

@@ -1,298 +0,0 @@
-# hypermem Architecture
-
-_Agent-centric memory that outlives sessions, backed by SQLite memory databases._
-
----
-
-## Memory Layers
-
-```
-L1  SQLite Cache (Hot)       Active session working memory
-     │                       Slots: system, identity, messages, facts, context
-     │                       Sub-millisecond reads, evicts on session end
-     │                       Fleet cache: agent profiles, fleet summary
-     │
-L2  Agent Messages DB        Raw conversation history (per agent)
-     │  messages.db           Write-heavy, rotatable (100MB / 90 days)
-     │  messages_YYYYQN.db    Rotated archives, read-only
-     │
-L3  Agent Vectors DB         Semantic search index (per agent)
-     │  vectors.db            Index rebuilt from L2+L4 (reconstructable)
-     │                        KNN search via sqlite-vec (nomic-embed-text, 768d)
-     │                        Rate-limited embedding via token bucket
-     │
-L4  Library DB               Fleet-wide structured knowledge
-        library.db            Facts, knowledge, preferences, fleet registry
-                              Episodes, topics, work items, system state
-                              Desired state, agent capabilities
-                              Knowledge graph (DAG links between entities)
-```
-
-> Note: some internal method names and telemetry reasons still contain `redis`
-> for backward compatibility. The runtime hot layer is SQLite `:memory:` cache,
-> not an external Redis service.
-
-## Database Schema
-
-### messages.db (per agent, schema v10)
-- `agent_meta` — agent metadata
-- `conversations` — session tracking
-- `messages` — raw message log (text, tool calls, tool results)
-- `schema_version` — migration tracking
-- **Rotation:** When size > 100MB or age > 90 days, renamed to `messages_YYYYQN.db`
-- **WAL mode** with checkpoint on rotation
-
-### vectors.db (per agent)
-- `vec_facts` — 768-dimensional vectors for facts (sqlite-vec virtual table)
-- `vec_knowledge` — vectors for knowledge entries
-- `vec_episodes` — vectors for episode descriptions
-- `vec_sessions` — vectors for session summaries
-- `vec_index_map` — tracks what's been indexed (source_table, source_id, source_db)
-- `embedding_cache` — avoids redundant Ollama API calls
-
-### library.db (shared, schema v19)
-- `facts` — verifiable claims with confidence, domain, expiry, supersedes chains
-- `knowledge` — domain/key/value structured data
-- `knowledge_links` — DAG edges between entities (fact↔fact, fact↔knowledge, etc.)
-- `episodes` — significant events with impact and participants
-- `topics` — cross-session thread tracking
-- `preferences` — operator/user behavioral patterns
-- `fleet_agents` — agent registry with tier, org, capabilities (JSON)
-- `fleet_orgs` — organizational structure
-- `agent_capabilities` — queryable skills, tools, MCP servers per agent
-- `agent_desired_state` — intended configuration vs. actual (drift detection)
-- `agent_config_events` — change audit trail
-- `system_registry` — service state tracking
-- `system_events` — service lifecycle events
-- `work_items` — work queue entries with FTS5
-- `session_registry` — session lifecycle tracking
-
-## Compositor
-
-Assembles LLM prompts from all four layers with token budgeting:
-
-```
-User message arrives
-  │
-  ├── L1 Hot cache: system prompt, identity, cached slots
-  ├── L2 Messages: recent conversation history (budget-truncated)
-  ├── L3 Vectors: KNN semantic recall on user's latest message
-  │     └── Related facts/knowledge/episodes with relevance scores
-  ├── L4 Library: structured knowledge injection
-  │     ├── Facts (up to 30% of remaining budget): active, non-expired, sorted by confidence
-  │     ├── Knowledge (up to 20% of remaining): grouped by domain, top 15 entries
-  │     └── Preferences (up to 10% of remaining): behavioral patterns, grouped by subject
-  └── Cross-session (up to 20% of remaining): context from related sessions
-```
-
-Each slot gets a proportional budget cap. Smart truncation at line boundaries.
-Multi-provider output: Anthropic and OpenAI message formats.
-
-### Tuning Parameters (TUNE-001–007)
-
-Compositor behavior is tuned via parameters tracked in `tune/TUNING_REGISTRY.md`:
-
-| ID | Parameter | Value | Effect |
-|---|---|---|---|
-| TUNE-001 | Semantic recall min RRF score | 0.008 | Drops noise results from hybrid search |
-| TUNE-002 | Facts confidence floor | 0.5 | Excludes low-confidence facts from injection |
-| TUNE-003 | Differentiated fact confidence | 0.60–0.75 by type | Decisions/incidents score higher than config/prefs |
-| TUNE-004 | config_change episode significance | 0.5 (was 0.4) | Config changes no longer silently dropped |
-| TUNE-005 | Extraction slot guard | suppress on default | No-op when strategy is lightweight/default |
-| TUNE-006 | Advisor slot guard | suppress bare seat list | No-op when no domain routes matched |
-| TUNE-007 | Identity anchor guard | suppress on default identity | No-op when identity resolves to 'default' |
-
-### Safety Mechanisms
-
-- **Budget safety valve:** Post-assembly check — if estimated tokens exceed budget × 1.05, trims oldest history messages until under budget. System/identity/current prompt are never touched.
-- **Compaction fence:** Per-conversation boundary protecting the LLM's recent tail from compaction. Only moves forward (monotone progress). No fence = no compaction (explicit opt-in).
-- **Preservation gate:** Nomic-space geometric verification that summaries stay faithful to source content. Centroid alignment + source coverage → combined score (threshold: 0.65).
-
-## Fleet Cache (Hot Cache Layer)
-
-```
-fleet:agent:{id}   — Composite profile: registry + capabilities + desired state
-fleet:summary      — Fleet-wide stats: agent count, drift count, tier breakdown
-```
-
-- **Cache-aside** on reads: hot cache first, SQLite fallback, warm on miss
-- **Write-through invalidation** on fleet mutations
-- **Hydration** on gateway startup: bulk-populate from library.db
-- TTL: agent profiles 10min, summary 2min
-
-## Knowledge Graph
-
-DAG traversal over `knowledge_links` for relationship discovery:
-
-- **Entity types:** fact, knowledge, topic, episode, agent, preference
-- **Link types:** supports, contradicts, supersedes, references, derived_from, depends_on, extends, covers, related, authored_by
-- **BFS traversal:** configurable depth, result limit, direction filter, type filter
-- **Shortest path:** between any two entities
-- **Analytics:** most-connected entities, link count by type
-
-## Rate Limiter
-
-Token-bucket rate limiter for embedding API calls:
-
-- Burst capacity with steady refill (default: 5/s, burst 10)
-- Priority queue: high (user-facing recall) > normal > low (batch indexing)
-- Reserved tokens for high-priority requests
-- `createRateLimitedEmbedder()` wraps any embedding function
-
-## Cross-Agent Access Control
-
-Visibility-tiered access model for cross-agent knowledge queries:
-
-- **`fleet`** — visible to all agents (default tier)
-- **`org`** — visible to agents in the same organizational unit
-- **`council`** — visible to council-tier agents and the org lead
-- **`private`** — visible only to the owning agent
-
-### Org Registry
-
-`visibilityFilter()` resolves access levels using an `OrgRegistry` — a mapping of agents to tiers, orgs, and capabilities. Currently loaded from a hardcoded `defaultOrgRegistry()` in `cross-agent.ts`.
-
-**Known limitation:** `defaultOrgRegistry()` duplicates fleet structure that lives authoritatively in `fleet_agents` + `fleet_orgs` in library.db. The planned migration is to live-load the registry from library.db on startup, with the hardcoded registry retained only as a cold-start fallback.
-
-### Unknown Agent Fallback (Restrictive Default)
-
-When a target agent is not found in the registry, `visibilityFilter()` applies a **restrictive default**: fleet-only visibility with a logged warning. This is a deliberate safety-side behavior — unknown agents see only fleet-visible data rather than failing the query entirely. The warning surfaces registry gaps for operators to fix.
-
-This means:
-- Queries succeed but return a narrowed result set
-- New agents provisioned in the DB but not yet in the registry will have reduced cross-agent visibility until registered
-- The warning message names the missing agent and suggests adding it to the registry
-
-## Context Engine Plugin
-
-`plugin/src/index.ts` — OpenClaw context engine plugin (`hypercompositor`, fills `contextEngine` slot):
-
-```
-gateway:startup     → Init hypermem, auto-rotate DBs, seed fleet registry from workspace identities, hydrate fleet cache
-agent:bootstrap     → Warm session (history, facts, profile → hot cache)
-context:assemble    → Full four-layer prompt assembly within token budget
-agent:afterTurn     → Ingest new messages to SQLite + hot cache, trigger background indexer
-```
-
-Registers with `ownsCompaction: true` — runtime skips legacy compaction entirely.
-
-## Memory Plugin
-
-`memory-plugin/src/index.ts` — Lightweight memory provider (`hypermem`, fills `memory` slot):
-
-- Registers `MemoryPluginCapability` with a `MemorySearchManager` backed by HyperMem's hybrid FTS5 + KNN retrieval
-- Provides the `memory_search` tool through the official memory slot interface
-- Public artifacts provider lists `MEMORY.md` and `memory/*.md` for all configured agents
-- Stateless wrapper: lifecycle is owned by the context engine plugin
-
-### Plugin Data Flow
-
-```
-                    ┌──────────────────────────────────────────────────┐
-                    │      HOT CACHE (SQLite :memory: CacheLayer)       │
-                    │                                                  │
-                    │  hm:{a}:{s}:history  ── Session archive (250 cap │
-                    │    (append-only)        at bootstrap, 1000 soft  │
-                    │                         cap ongoing)             │
-                    │                                                  │
-                    │  hm:{a}:{s}:window   ── Submission buffer        │
-                    │    (compositor output)   (120s TTL)              │
-                    │                                                  │
-                    │  hm:{a}:{s}:cursor   ── Last-sent pointer        │
-                    │    (compositor metadata)  (24h TTL)              │
-                    │                                                  │
-                    │  hm:{a}:{s}:system   ── System prompt slot       │
-                    │  hm:{a}:{s}:identity ── Identity slot            │
-                    │  hm:{a}:{s}:facts    ── Cached facts slot        │
-                    │  hm:{a}:{s}:context  ── Cross-session slot       │
-                    └──────────────────────────────────────────────────┘
-
-Data Flow (current — P0 stabilized, window/cursor active):
-
-  bootstrap()                     assemble()                   afterTurn()
-  ───────────                     ──────────                   ───────────
-  ▸ sessionExists() → skip if hot  compose()                    slice(prePromptCount)
-  ▸ SQLite ─→ warmSession()        ─→ getHistory(limit) ✅      ─→ record*Message()
-           ─→ pushHistory(250)     ─→ dedup by id               ─→ pushHistory(1, dedup)
-           ─→ cache history        ─→ budget assembly            ─→ cache history
-                                   ─→ write window bundle       ─→ invalidateWindow()
-                                   ─→ write cursor metadata     ─→ background indexer
-                                   ─→ → runtime → provider
-
-### Key Invariants
-
-1. Hot-cache `history` is the warm archive. Append-only. Nothing reads it for direct submission.
-2. Hot-cache `window` is the compositor's output cache. Written ONLY by `compose()`. Read ONLY by `assemble()`. Invalidated by `afterTurn`.
-3. Hot-cache `cursor` tracks the newest message in the last window. Used by background indexer for high-signal mining.
-4. `warmSession()` seeds `history` only (capped at 250). Never writes `window`.
-5. `pushHistory()` tail-checks before append (no duplicate IDs in the hot-cache history list).
-6. `compose()` deduplicates history by `id` before budget assembly.
-7. `getHistory()` honors its `limit` parameter on BOTH hot-cache and SQLite paths.
-
-Open and deferred work is tracked outside this public architecture reference.
-
-### Runtime Contract
-
-**Exclusive dispatch:** The OpenClaw runtime calls either `afterTurn()` OR `ingest()`/`ingestBatch()`, never both. Since hypermem implements `afterTurn`, it must handle message ingestion there. `ingest()` exists for API compatibility but is never called by the runtime in practice.
-
-**Provider translation:** The plugin sets `skipProviderTranslation: true` on compose requests. The compositor returns NeutralMessages; the plugin converts to AgentMessages. The runtime handles provider-specific translation. Two-stage translation (compositor → provider format → plugin → agent format) was the root cause of Incident 1 (silent tool call drops).
-
-## Module Map (29 files, ~12,300 lines)
-
-| Module | Lines | Layer | Purpose |
-|---|---|---|---|
-| `index.ts` | ~1,340 | All | Facade — all public API |
-| `compositor.ts` | ~1,140 | L1-L4 | Prompt assembly + token budgeting + safety valve + window/cursor write |
-| `library-schema.ts` | ~780 | L4 | Library schema v19 + migrations |
-| `background-indexer.ts` | ~680 | L2-L4 | LLM-powered extraction framework |
-| `vector-store.ts` | ~600 | L3 | Semantic search + embedding |
-| `hybrid-retrieval.ts` | ~450 | L3-L4 | FTS5 + KNN with Reciprocal Rank Fusion |
-| `fleet-store.ts` | ~440 | L4 | Fleet registry + capabilities |
-| `db.ts` | ~440 | - | Database manager + rotation |
-| `knowledge-graph.ts` | ~420 | L4 | DAG traversal + shortest path |
-| `cache.ts` | ~700 | L1 | SQLite `:memory:` hot-cache operations, window cache, cursor, fleet cache |
-| `doc-chunker.ts` | ~400 | - | Section-aware markdown/file parser |
-| `work-store.ts` | ~400 | L4 | Work queue + FTS5 |
-| `provider-translator.ts` | ~390 | - | Neutral ↔ provider format conversion |
-| `doc-chunk-store.ts` | ~375 | L4 | Chunk storage + deduplication |
-| `message-store.ts` | ~370 | L2 | Conversation recording + querying |
-| `types.ts` | ~370 | - | Shared type definitions + SessionCursor |
-| `cross-agent.ts` | ~330 | L2-L4 | Cross-agent knowledge queries + visibility |
-| `desired-state-store.ts` | ~310 | L4 | Config drift detection |
-| `knowledge-store.ts` | ~300 | L4 | Domain/key/value structured data |
-| `secret-scanner.ts` | ~285 | - | Credential/secret detection |
-| `system-store.ts` | ~250 | L4 | Service state tracking |
-| `seed.ts` | ~250 | L4 | Workspace seeder + collection inference |
-| `fact-store.ts` | ~230 | L4 | Facts with confidence + expiry |
-| `rate-limiter.ts` | ~230 | L3 | Token-bucket for embedding API |
-| `schema.ts` | ~200 | L2 | Messages schema + migrations |
-| `episode-store.ts` | ~180 | L4 | Significant event tracking |
-| `preference-store.ts` | ~170 | L4 | Operator behavioral patterns |
-| `topic-store.ts` | ~160 | L4 | Cross-session thread tracking |
-| `plugin/src/index.ts` | ~590 | - | `hypercompositor` context engine plugin + window invalidation |
-| `memory-plugin/src/index.ts` | ~290 | - | `hypermem` memory slot plugin (memory_search via hybrid retrieval) |
-
-## Test Coverage (105 assertions, 11 suites)
-
-_Test count reflects assertions, not individual test blocks. Suites contain inline assertions._
-
-| Suite | Key coverage |
-|---|---|
-| smoke | End-to-end create/write/read/close, provider translation |
-| redis-integration | Legacy suite name, covers hot-cache ops, slots, history limits, window cache, cursor, warming, dedup |
-| cross-agent | Cross-agent queries, fleet search, visibility tiers |
-| vector-search | Embedding, KNN, batch indexing |
-| library | All L4 collections (facts → desired state) |
-| compositor | Four-layer composition, budgets, providers, safety valve, Gate 1 |
-| fleet-cache | Fleet hot-cache hydration and cache-aside behavior |
-| rotation | DB rotation, auto-rotate, collision handling |
-| knowledge-graph | DAG traversal, shortest path, analytics |
-| rate-limiter | Token bucket, priority, timeout, embedder |
-| doc-chunker | Markdown/file chunking, section-aware parsing, seeder |
-
-## Dependencies
-
-- `node:sqlite` (Node 22+ built-in) — zero-dependency SQLite
-- No external cache service dependency — hot cache is SQLite `:memory:`
-- `sqlite-vec` — optional, vector search extension
-- Ollama (localhost:11434) — optional, embedding generation

package/docs/KNOWN_LIMITATIONS.md

@@ -1,35 +0,0 @@
-# Known Limitations — HyperMem 0.8.0
-
-## Global-scope fact write authorization
-
-Facts written with `scope='global'` are readable fleet-wide at L4 priority. The write path has no authorization gate — any agent with access to the HyperMem API can write a global-scope fact.
-
-**Impact:** In a trusted single-operator deployment (the intended target), this is acceptable. All agents are operator-controlled and share the same trust boundary.
-
-**Planned fix:** Introduce a write-authority model that gates global-scope writes to designated agents (council seats or explicitly allowlisted agent IDs). See [docs/ROADMAP.md](ROADMAP.md).
-
-**Workaround:** Restrict HyperMem API access to trusted agents only. Do not expose the API to untrusted external agents.
-
-## Cross-agent org registry is hardcoded
-
-`visibilityFilter()` in `cross-agent.ts` resolves agent tiers and visibility from a hardcoded `defaultOrgRegistry()`. This duplicates fleet topology that lives authoritatively in `fleet_agents` + `fleet_orgs` in library.db.
-
-**Impact:** New agents added to library.db but not the hardcoded registry get fleet-only visibility until the registry is updated in code.
-
-**Planned fix:** Live-load registry from library.db on startup, hardcoded as cold-start fallback only. See [docs/ROADMAP.md](ROADMAP.md).
-
-## Cursor durability across restarts
-
-The compositor writes a session cursor to hot cache (SQLite `:memory:`) with a 24h TTL. On gateway restart, the cursor is lost until the next `compose()` call repopulates it.
-
-**Impact:** Background indexer may miss the cursor on the first turn after a restart, falling back to full-history scan.
-
-**Planned fix:** Dual-write cursor to messages.db so it survives restarts. See [docs/ROADMAP.md](ROADMAP.md).
-
-## Cross-session context has no boundary markers
-
-`buildCrossSessionContext()` renders flat previews with no per-message boundaries or sender identity labels.
-
-**Impact:** Context from different sessions blends together, making attribution ambiguous in multi-agent scenarios.
-
-**Planned fix:** WQ-20260402-001. See [docs/ROADMAP.md](ROADMAP.md).

package/docs/PHASE1-VALIDATION.md

@@ -1,132 +0,0 @@
-# HyperMem Phase 1 Validation Runbook
-
-Operator-facing guide for running and interpreting the Phase 1 validation suite.
-
----
-
-## Quick Start
-
-Run the full Phase 1 validation flow:
-
-```bash
-npm run build && node scripts/validate-compose.mjs && node scripts/validate-config-surface.mjs
-```
-
-Or run individual validations:
-
-```bash
-# Compose validation (facts, library, budget pressure)
-node scripts/validate-compose.mjs
-
-# Config surface parity (install.sh, docs, README)
-node scripts/validate-config-surface.mjs
-
-# Config key resolution tests
-node test/config-validation.mjs
-
-# Retrieval regression harness
-node test/retrieval-regression.mjs
-
-# Compositor integration (includes budget-pressure fixture)
-node test/compositor.mjs
-
-# Plugin pipeline (requires plugin build)
-npm run validate:plugin-pipeline
-
-# Startup fleet seeding on cold boot
-node test/fleet-startup-seeding.mjs
-
-# Release path hardening harness (builds core + plugin)
-npm run validate:release-path
-
-# Compose report (operator-readable diagnostics)
-node scripts/compose-report.mjs
-```
-
----
-
-## What Each Validation Covers
-
-| Validation | What it proves |
-|---|---|
-| `validate-compose.mjs` | End-to-end compose with seeded facts, knowledge retrieval, and budget pressure |
-| `validate-config-surface.mjs` | Config keys present in install.sh, INSTALL.md, TUNING.md, README |
-| `config-validation.mjs` | contextWindowOverrides sanitization, budget resolution, maintenance defaults |
-| `retrieval-regression.mjs` | Scope isolation, superseded-fact filtering, budget pressure, knowledge retrieval |
-| `compositor.mjs` | Four-layer compose, trigger routing, keystone injection, budget-pressure filtering |
-| `plugin-pipeline.mjs` | Real plugin assemble() path with seeded L4 memory, tight-budget proof |
-| `fleet-startup-seeding.mjs` | Cold-start fleet population from workspace identity files plus idempotent repeat-boot behavior |
-| `release-gateway-path.mjs` | Real plugin release-path proof: tool-chain ejection counters, ArtifactRef, replay marker, and degradation telemetry |
-| `compose-report.mjs` | Operator-readable diagnostics showing layer counts and budget decisions |
-
----
-
-## Interpreting Healthy Output
-
-A passing run shows all checks green:
-
-```
-  ALL 12 CHECKS PASSED ✅
-```
-
-Key diagnostics in the compose report:
-
-- **factsIncluded > 0**: facts were retrieved for the prompt
-- **tokenCount <= budget**: compositor respected the token ceiling
-- **retrievalMode**: `trigger`, `fallback_knn`, or `fts_only` — shows which retrieval path fired
-- **scopeFiltered >= 0**: cross-session facts correctly filtered
-
-Maintenance diagnostics (when `verboseLogging` is enabled):
-
-```
-[indexer] Maintenance: considered=5 skipped=2 scanned=3 mutated=0 duration=12ms exit=complete
-```
-
-- **considered**: conversations examined
-- **skipped**: conversations within cooldown window
-- **scanned**: conversations where sweeps ran
-- **mutated**: total messages deleted or truncated
-- **exit**: `complete`, `cap-reached`, `cooldown`, or `no-conversations`
-
----
-
-## Common Cases
-
-### Empty context (no facts/knowledge seeded)
-
-Expected: `factsIncluded=0`, `contextBlock` may be empty or contain only history. This is normal for fresh installs or agents with no indexed conversations.
-
-### Missing fact in context
-
-Check: is the fact's `superseded_by` column NULL? Superseded facts are filtered. Is the fact's `agent_id` correct for the composing agent? Cross-agent facts are scope-filtered.
-
-### Over-budget compose
-
-The compositor respects token budgets with a small tolerance (5-15%). If `tokenCount` significantly exceeds `tokenBudget`, check `compositor.budgetFraction` and `contextWindowReserve` in config.
-
-### Maintenance not running
-
-Check that `maintenance.periodicInterval` is set in config.json. Default is 300000ms (5 min). If `verboseLogging` is enabled, you should see maintenance diagnostics every tick.
-
----
-
-## What Remains Unverified After Phase 1
-
-- **Vector/semantic retrieval**: all Phase 1 tests run FTS-only (no Ollama dependency)
-- **Full hot-cache plugin path inside Phase 1 itself**: these checks use the direct compositor, not the full cache-layer assemble lifecycle. Use `npm run validate:release-path` for that proof.
-- **Multi-agent fleet interactions**: scope isolation is tested, but fleet-wide maintenance behavior is not
-- **Provider-specific formatting**: tests use `provider: 'anthropic'` only
-- **Real model token counting**: tests use the char/4 heuristic estimator, not tiktoken
-
----
-
-## Maintenance Tuning Reference
-
-See [TUNING.md](./TUNING.md#background-maintenance) for the full knob reference. Key defaults:
-
-| Setting | Default | Effect |
-|---|---|---|
-| `maintenance.periodicInterval` | 300000ms | Background tick cadence |
-| `maintenance.maxActiveConversations` | 5 | Conversations processed per agent per tick |
-| `maintenance.recentConversationCooldownMs` | 30000ms | Skip recently processed conversations |
-| `maintenance.maxCandidatesPerPass` | 200 | Cap on mutations per tick |

package/docs/RELEASE_0.8.0_VALIDATION.md

@@ -1,70 +0,0 @@
-# HyperMem 0.8.0 Release Path Validation
-
-This is the operator runbook for the release hardening harness.
-
-## Command
-
-```bash
-npm run validate:release-path
-```
-
-That command builds core + plugin, then runs `test/release-gateway-path.mjs` against the built plugin dist in an isolated temporary HOME.
-
-## What it proves
-
-The harness exercises the real context-engine plugin path, not just direct compositor helpers.
-
-It verifies four release-path behaviors in one run:
-
-1. **normal compose path** returns assembled context through `engine.assemble()`
-2. **artifact degradation** emits a canonical `[artifact:...]` reference in system context
-3. **tool-chain ejection** is recorded through real compose-path co-ejection counters in telemetry
-4. **tool-loop replay recovery** emits the canonical `[replay state=entering ...]` marker when runtime history is hot and the hot cache is cold
-
-## Telemetry contract
-
-When `HYPERMEM_TELEMETRY=1`, the plugin now emits a `degradation` JSONL event alongside the existing `assemble`, `trim`, and `trim-guard` events.
-
-Per event fields:
-
-- `agentId`
-- `sessionKey`
-- `turnId`
-- `path` (`compose` or `toolLoop`)
-- `toolChainCoEjections`
-- `toolChainStubReplacements`
-- `artifactDegradations`
-- `artifactOversizeThresholdTokens`
-- `replayState`
-- `replayReason` (legacy machine reason strings may still contain `redis` for compatibility)
-
-The release harness asserts those counters against prompt-visible behavior, so the telemetry is not just emitted, it is verified.
-
-## Inspecting artifacts manually
-
-By default the harness deletes its temp HOME on success.
-
-To keep the temp workspace and telemetry file:
-
-```bash
-HYPERMEM_KEEP_RELEASE_TMP=1 npm run validate:release-path
-```
-
-The script will print the preserved temp path. The telemetry file lives at:
-
-```text
-<tmp>/release-telemetry.jsonl
-```
-
-## Healthy result
-
-```text
-ALL 12 CHECKS PASSED ✅
-```
-
-A healthy run means the built plugin can prove the Phase C prompt-path contracts that matter for `0.8.0`:
-
-- degraded content uses the canonical visible shapes where it is prompt-visible
-- degradation counters line up with what entered the model path
-- replay recovery is visible at the plugin boundary
-- the proof runs against the real assemble lifecycle, not a mocked helper only

package/docs/RELEASE_PROCESS.md

@@ -1,10 +0,0 @@
-# HyperMem Release Process
-
-**Canonical source:** [PsiClawOps/publication_process_internal](https://github.com/PsiClawOps/publication_process_internal)
-
-- **Universal process:** `PROCESS.md` (5-stage publication pipeline)
-- **HyperMem-specific:** `repos/hypermem.md` (scrub lists, stubs, build checks)
-- **Install verification:** `INSTALL_VERIFICATION.md` (independent vetting gate)
-- **Style:** `STYLE_GUIDE.md` + `FLEET_OUTPUT.md`
-
-Do not duplicate process content here. If something is missing from the canonical repo, add it there.