@psiclawops/hypermem 0.8.2 → 0.8.3

package/INSTALL.md

@@ -3,7 +3,7 @@
 ## Prerequisites
 
 - **Node.js 22+** (uses built-in `node:sqlite`)
-- **OpenClaw** must already be installed, onboarded, and running. The plugin install assumes a working OpenClaw home with a valid `openclaw.json` and a gateway that can restart.
+- **OpenClaw** must already be installed, onboarded, and running. HyperMem is a plugin for an existing OpenClaw deployment -- it does not bootstrap OpenClaw itself. If you have never run `openclaw gateway start` or completed OpenClaw onboarding, do that first. The HyperMem install guide picks up after OpenClaw is operational.
 - **Disk space:** allow at least 2 GB free. Plugin builds pull OpenClaw as a dev dependency.
 
 **Verify before starting:**
@@ -17,21 +17,20 @@ If `gateway status` shows "disabled" or "not configured", complete OpenClaw onbo
 
 ## Quick Start
 
-> **Disk space:** plugin installs pull OpenClaw as a dev dependency. Allow at least 2 GB free before starting.
->
-> **Prerequisites:** OpenClaw must be installed and onboarded before this step. Run `openclaw gateway status` to confirm. If the gateway is not configured, complete OpenClaw setup first.
->
-> **Production runtime path:** install the built runtime payload into `~/.openclaw/plugins/hypermem`. Do not point production at `/tmp` or at your development repo clone.
+```bash
+npm install @psiclawops/hypermem
+npx hypermem-install
+```
+
+`hypermem-install` stages the plugin runtime into `~/.openclaw/plugins/hypermem`. It does **not** modify your OpenClaw config and does **not** restart the gateway.
+
+> **Prerequisites:** OpenClaw must be installed and onboarded. Run `openclaw gateway status` to confirm. If the gateway is not configured, complete OpenClaw setup first.
 >
-> **Config merge warning:** if you already have values in `plugins.load.paths` or `plugins.allow`, merge them instead of overwriting them blindly.
+> **Config merge warning:** if you already have values in `plugins.load.paths` or `plugins.allow`, merge them instead of overwriting blindly.
+
+Create the config directory and set the embedding provider:
 
 ```bash
-git clone https://github.com/PsiClawOps/hypermem.git
-cd hypermem
-npm install && npm run build
-npm --prefix plugin install && npm --prefix plugin run build   # ~1 min on a clean machine
-npm --prefix memory-plugin install && npm --prefix memory-plugin run build
-npm run install:runtime
 mkdir -p ~/.openclaw/hypermem
 cat > ~/.openclaw/hypermem/config.json <<'JSON'
 {
@@ -42,19 +41,41 @@ cat > ~/.openclaw/hypermem/config.json <<'JSON'
 JSON
 ```
 
-`install:runtime` stages the built plugin files into `~/.openclaw/plugins/hypermem`. It does **not** modify your OpenClaw config. The commands below wire the plugins manually.
-
 Wire both plugins into OpenClaw:
 
+**Step 1: Check your existing config (mandatory — do this before wiring).**
+
+```bash
+openclaw config get plugins.load.paths
+openclaw config get plugins.allow
+```
+
+Note any existing values. You must include them in the commands below.
+
+**Step 2: Wire plugins.**
+
 ```bash
-openclaw config set plugins.load.paths "[\"$HOME/.openclaw/plugins/hypermem/plugin\",\"$HOME/.openclaw/plugins/hypermem/memory-plugin\"]" --strict-json
+# Wire plugin load paths — merge with any existing paths from Step 1:
+openclaw config set plugins.load.paths "[\"${HOME}/.openclaw/plugins/hypermem/plugin\",\"${HOME}/.openclaw/plugins/hypermem/memory-plugin\"]" --strict-json
+
+# Set the context engine and memory slots:
 openclaw config set plugins.slots.contextEngine hypercompositor
 openclaw config set plugins.slots.memory hypermem
-openclaw config set plugins.allow '["hypercompositor","hypermem"]' --strict-json
+
+# Allow both plugins — merge with any existing allowed plugins from Step 1.
+# Example (if "my-plugin" was already allowed):
+ocplatform config set plugins.allow '["my-plugin","hypercompositor","hypermem"]' --strict-json
+```
+
+> **⚠️  Merge, don't replace.** The command above sets `plugins.allow` to whatever you specify. If `plugins.allow` was non-empty in Step 1, include those entries in the array. Replacing it drops existing plugins (including bundled OpenClaw CLI surfaces and channel plugins).
+
+**Step 3: Restart.**
+
+```bash
 openclaw gateway restart
 ```
 
-The repo clone is for build and release work. OpenClaw should load the installed runtime payload from `~/.openclaw/plugins/hypermem/`.
+OpenClaw loads the plugin runtime from `~/.openclaw/plugins/hypermem/`.
 
 ### Verification checkpoints
 
@@ -342,7 +363,9 @@ Then:
 
 ## Installation Steps
 
-### Step 1 — Clone and build
+### Step 1 — Source Build (contributors)
+
+> **Most users should use the npm Quick Start above.** This section is for contributors or users who need to modify HyperMem source.
 
 ```bash
 git clone https://github.com/PsiClawOps/hypermem.git
@@ -351,7 +374,7 @@ npm install
 npm run build
 ```
 
-Build both plugins, then install the runtime payload into OpenClaw's durable plugin directory:
+Build both plugins, then install the runtime payload into OCPlatform's durable plugin directory:
 
 ```bash
 npm --prefix plugin install && npm --prefix plugin run build
@@ -365,32 +388,29 @@ Verify:
 npm test
 ```
 
-The full suite takes 30–60 seconds. When complete, output ends with `ALL N TESTS PASSED ✅`. If you see `ENOSPC`, free up disk space and retry.
+The full suite takes 30–60 seconds. When complete, output ends with `N passed, 0 failed`. If you see `ENOSPC`, free up disk space and retry.
 
 ### Step 2 — Wire the plugins
 
 Use the OpenClaw CLI. **Do not edit `openclaw.json` directly.**
 
 ```bash
-# Add plugin load paths
-openclaw config set plugins.load.paths "[\"$HOME/.openclaw/plugins/hypermem/plugin\",\"$HOME/.openclaw/plugins/hypermem/memory-plugin\"]" --strict-json
+# Check existing values first — merge if non-empty:
+ocplatform config get plugins.load.paths
+openclaw config get plugins.allow
 
-# Set the context engine slot
-openclaw config set plugins.slots.contextEngine hypercompositor
+# Wire plugin load paths (merge with any existing paths):
+openclaw config set plugins.load.paths "[\"${HOME}/.openclaw/plugins/hypermem/plugin\",\"${HOME}/.openclaw/plugins/hypermem/memory-plugin\"]" --strict-json
 
-# Set the memory slot
+# Set the context engine and memory slots:
+openclaw config set plugins.slots.contextEngine hypercompositor
 openclaw config set plugins.slots.memory hypermem
 
-# Allow both plugins
-openclaw config set plugins.allow '["hypercompositor","hypermem"]' --strict-json
+# Allow both plugins — merge with any existing allowed plugins (example includes "my-plugin"):
+ocplatform config set plugins.allow '["my-plugin","hypercompositor","hypermem"]' --strict-json
 ```
 
-If you already have entries in `plugins.allow` or `plugins.load.paths`, merge rather than replace. Check current values:
-
-```bash
-openclaw config get plugins.allow
-openclaw config get plugins.load.paths
-```
+> **⚠️  Merge, don't replace.** Check `openclaw config get plugins.allow` before running this command and include all existing entries in the array.
 
 ### Step 3 — Choose embedding provider
 
@@ -422,7 +442,7 @@ Expected:
 [hypermem:compose] agent=main triggers=0 fallback=true facts=3 semantic=2 ...
 ```
 
-Full health check (run from the repo clone directory):
+Full health check (run from the repo clone directory — `bin/` is a relative path):
 
 ```bash
 node bin/hypermem-status.mjs              # full dashboard
@@ -430,6 +450,8 @@ node bin/hypermem-status.mjs --health     # health checks only (exit 1 on failur
 ```
 
 > **Note:** The health check requires the data directory to exist. It is created on first gateway restart with the plugin active. Run the `openclaw logs` check first to confirm initialization, then run the health check.
+>
+> **Empty results on fresh installs are normal.** If the health check shows `facts=0`, `episodes=0`, or `no agent messages.db found`, that means the install worked but no conversations have happened yet. Data populates after real agent sessions.
 
 If the plugin didn't load:
 
@@ -549,23 +571,66 @@ npm --prefix memory-plugin run build
 
 ---
 
-## OpenClaw Settings (Optional Tuning)
+## OpenClaw Platform Settings
+
+HyperMem manages its own context pressure, memory injection, and compaction. Several OpenClaw defaults conflict with this or are too conservative for memory-augmented agents. Apply these after plugin installation, before the gateway restart.
+
+### Disable OpenClaw context pruning (required)
+
+OpenClaw has a built-in context pruning system (`cache-ttl` mode) that independently truncates and clears tool results from the message history based on time and context-window ratio thresholds. When HyperMem is active, these two systems fight each other: OpenClaw prunes tool results to free space, then HyperMem injects context that refills it, triggering aggressive compaction on the next turn. The result is unpredictable amnesia.
+
+Disable OpenClaw's pruning and let HyperMem handle context pressure exclusively:
+
+```bash
+openclaw config set agents.defaults.contextPruning.mode off
+```
+
+### Startup context (recommended)
 
-These are optional. hypermem works with OpenClaw defaults, but these changes reduce unnecessary overhead.
+Controls how much daily memory context agents receive on session start. The defaults are very conservative (2 days, 2800 chars total). For memory-augmented agents, increase these so agents wake up with meaningful context:
+
+```bash
+openclaw config set agents.defaults.startupContext.dailyMemoryDays 4 --strict-json
+openclaw config set agents.defaults.startupContext.maxFileChars 4000 --strict-json
+openclaw config set agents.defaults.startupContext.maxTotalChars 12000 --strict-json
+openclaw config set agents.defaults.startupContext.maxFileBytes 32768 --strict-json
+```
+
+This gives agents 4 days of working memory at startup (~12k chars total). Still under 10% of a 128k context window.
+
+### Bootstrap max chars (recommended)
+
+Controls the maximum size of bootstrap files (AGENTS.md, SOUL.md, etc.) injected on session start. The default (12000) is tight for agents with governance rules, tool references, and identity docs:
+
+```bash
+ocplatform config set agents.defaults.bootstrapMaxChars 20000 --strict-json
+```
 
-### Lower OpenClaw's compaction threshold
+### Compaction safety net
 
-hypermem owns compaction. OpenClaw's default fires at 24K reserved tokens, which races hypermem's budget management:
+OpenClaw's built-in compaction (`safeguard` mode) serves as a last-resort safety net. Keep it enabled but tuned so it only fires when HyperMem's own pressure management is insufficient:
 
 ```bash
-openclaw config set agents.defaults.compaction.reserveTokens 1000 --strict-json
+ocplatform config set agents.defaults.compaction.mode safeguard
+openclaw config set agents.defaults.compaction.reserveTokens 16384 --strict-json
+ocplatform config set agents.defaults.compaction.keepRecentTokens 6000 --strict-json
+ocplatform config set agents.defaults.compaction.reserveTokensFloor 15000 --strict-json
+openclaw config set agents.defaults.compaction.maxHistoryShare 0.65 --strict-json
 ```
 
-This makes OpenClaw's compaction a last-resort safety net that never fires in normal operation.
+This reserves 16k tokens for reply generation. HyperMem's own pressure system (afterTurn at 80%, nuclear at 85%) fires first in normal operation. OpenClaw's safeguard catches edge cases.
+
+### LLM idle timeout
+
+Tool-heavy sessions with large outputs can stall during streaming. Raise the idle timeout from the default (120s):
+
+```bash
+openclaw config set agents.defaults.llm.idleTimeoutSeconds 300 --strict-json
+```
 
 ### Tighter session store retention
 
-With hypermem active, SQLite is the durable record. JSONL transcripts provide no memory benefit:
+With HyperMem active, SQLite is the durable record. JSONL transcripts provide no memory benefit:
 
 ```bash
 openclaw config set sessions.maintenance.pruneAfter "14d"
@@ -744,6 +809,10 @@ The background indexer runs on a 5-minute interval. After the first cycle, check
 
 Expected on fresh installs. Facts and episodes accumulate over real conversations. After a few sessions these numbers grow. Workspace files can be seeded manually via the seeder API.
 
+**Lost bundled plugins after setting `plugins.allow`**
+
+If you set `plugins.allow` to only `["hypercompositor","hypermem"]` without including your pre-existing allowed plugins, OpenClaw will stop loading everything else (including built-in CLI surfaces and bundled channel plugins). Fix: re-read your OpenClaw defaults (`openclaw config get plugins.allow`), merge hypermem entries back into the full list, and `openclaw gateway restart`.
+
 **Plugin not found**
 
 Confirm the installed runtime artifacts exist:
@@ -797,4 +866,22 @@ Data in `~/.openclaw/hypermem/` is untouched. Re-enable by switching back.
 
 ---
 
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `HYPERMEM_DATA_DIR` | `~/.openclaw/hypermem` | Override the data directory where hypermem stores `library.db`, per-agent `messages.db` files, and `vectors.db`. Useful when you want data on a separate volume, need isolated test data dirs, or run multiple hypermem instances. The directory is created automatically if it does not exist. |
+
+Example:
+
+```bash
+# Point hypermem at a different data location:
+export HYPERMEM_DATA_DIR=/mnt/data/hypermem
+openclaw gateway restart
+```
+
+> The config file path (`~/.openclaw/hypermem/config.json`) is separate from the data directory. Moving `HYPERMEM_DATA_DIR` does not move the config file.
+
+---
+
 _Questions or issues: file against [the repo](https://github.com/PsiClawOps/hypermem) or ask in `#hypermem`._

package/README.md

@@ -8,10 +8,20 @@
 
 hypermem is a SQLite-backed runtime context engine for OpenClaw agents.
 
+**Quick install** (interactive, detects hardware, writes config):
+
+```bash
+npm install @psiclawops/hypermem && npx hypermem-install
+```
+
+Or via the shell installer:
+
 ```bash
 curl -fsSL https://raw.githubusercontent.com/PsiClawOps/hypermem/main/install.sh | bash
 ```
 
+Or install manually via `npm install @psiclawops/hypermem` — see [Installation](#installation) for plugin wiring, embedding setup, and step-by-step paths.
+
 
 ---
 
@@ -376,7 +386,7 @@ Slot-level budget allocation is shown in the [hypercompositor diagram](#what-the
 
 ## Requirements
 
-**Current release: hypermem 0.8.1.** Changelog: [CHANGELOG.md](./CHANGELOG.md)
+**Current release: hypermem 0.8.2.** Changelog: [CHANGELOG.md](./CHANGELOG.md)
 
 | Requirement | Version | Notes |
 |---|---|---|
@@ -389,7 +399,7 @@ SQLite is a library, not a service. All four layers run in-process with no exter
 **Runtime version constants** (importable from the package):
 ```typescript
 import {
-  ENGINE_VERSION,        // '0.8.1'
+  ENGINE_VERSION,        // '0.8.2'
   MIN_NODE_VERSION,      // '22.0.0'
   SQLITE_VEC_VERSION,    // '0.1.9'
   MAIN_SCHEMA_VERSION,   // 10 (messages.db)
@@ -465,15 +475,30 @@ This sets lightweight mode (FTS5 keyword search, no embedding provider needed).
 
 Wire the plugins into OpenClaw:
 
+> **⚠️  Merge, don't overwrite.** If you already have values in `plugins.load.paths` or `plugins.allow`, check them first and include your existing entries alongside the new ones. Replacing the list drops whatever was there before.
+>
+> ```bash
+> openclaw config get plugins.allow
+> openclaw config get plugins.load.paths
+> ```
+
 ```bash
-openclaw config set plugins.load.paths "[\"$HOME/.openclaw/plugins/hypermem/plugin\",\"$HOME/.openclaw/plugins/hypermem/memory-plugin\"]" --strict-json
+# Use a variable to avoid shell quote-escaping issues with $HOME:
+HYPERMEM_PATHS="[\"${HOME}/.openclaw/plugins/hypermem/plugin\",\"${HOME}/.openclaw/plugins/hypermem/memory-plugin\"]"
+openclaw config set plugins.load.paths "$HYPERMEM_PATHS" --strict-json
+# If you have existing load paths, merge them into the array in HYPERMEM_PATHS.
+
 openclaw config set plugins.slots.contextEngine hypercompositor
 openclaw config set plugins.slots.memory hypermem
+
+# ⚠️  Add to your existing plugins.allow — do not replace your current list.
+# Edit the array below to include any plugins you already have allowed:
 openclaw config set plugins.allow '["hypercompositor","hypermem"]' --strict-json
+
 openclaw gateway restart
 ```
 
-Verify (run from the repo clone directory):
+Verify (run these commands from the repo clone directory — `bin/` is a relative path):
 
 ```bash
 openclaw plugins list                    # hypercompositor and hypermem should show as loaded

package/docs/API_STABILITY.md

@@ -0,0 +1,33 @@
+# API Stability — hypermem
+
+## Public API (frozen at 0.5.0)
+
+The following four methods are the stable public surface of hypermem. They are
+frozen as of 0.5.0. Breaking changes require a 1.0.0 semver bump — no exceptions.
+
+| Method | Signature | Description |
+|---|---|---|
+| `create` | `create(config: HypermemConfig): HypermemInstance` | Initialize a hypermem instance |
+| `record` | `record(agentId, sessionKey, message): Promise<void>` | Store a message in the session store |
+| `compose` | `compose(agentId, sessionKey, opts?): Promise<ComposedContext>` | Assemble context for a prompt |
+| `close` | `close(): Promise<void>` | Gracefully shut down, flush, close DB connections |
+
+## What "frozen" means
+
+- No argument removal or rename
+- No return type narrowing that breaks existing consumers
+- No behavior change that breaks existing consumers without a deprecation cycle
+- Additive changes (new optional args, new fields in return type) are allowed
+
+## Internal APIs
+
+Everything else — `FactStore`, `CacheLayer`, `Compositor`, `HybridRetrieval`,
+`DreamingPromoter`, etc. — is internal and may change between minor versions.
+These are exported for advanced use but carry no stability guarantee until 1.0.
+
+## Versioning policy
+
+| Version range | Policy |
+|---|---|
+| `0.x.y` | Public API frozen, internal APIs may change on minor bumps |
+| `1.0.0+` | Full semver — breaking changes require major bump |

package/docs/KNOWN_LIMITATIONS.md

@@ -0,0 +1,35 @@
+# 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/MEMORY_MD_AUTHORING.md

@@ -0,0 +1,243 @@
+# MEMORY.md authoring
+
+`MEMORY.md` is an index, not a dump.
+
+Use it to preserve durable signal the agent should keep noticing across sessions: decisions, operating rules, important architecture facts, stable paths, active plans, and search pointers into deeper history.
+
+Do not use it as a transcript, changelog, or a second database. hypermem already stores the raw history. `MEMORY.md` should make the right things easy to find again.
+
+## What belongs in MEMORY.md
+
+Keep items that are still likely to matter after the current session ends:
+
+- stable architectural facts
+- standing rules and constraints
+- current project plans worth reloading next session
+- important decisions with enough context to recover why they happened
+- durable paths, repo locations, and operational references
+- search pointers for deeper recall
+
+Good rule: if losing the item would make the next session slower, riskier, or more error-prone, it probably belongs.
+
+## What does not belong
+
+Do not put these in `MEMORY.md`:
+
+- full conversation summaries
+- test logs and build output
+- one-off debugging notes with no ongoing value
+- temporary status that belongs in a daily checkpoint
+- long implementation detail blocks copied from code or specs
+- duplicate facts already obvious from repo structure
+
+If the value is only "this happened today," it usually belongs in the daily file, not the index.
+
+## Authoring style
+
+Write pointer-first entries. One line should stand on its own, and one search pointer should reopen the deeper context.
+
+Preferred format:
+
+```md
+- TUNE-011: indexer quality gate, 33% fact noise removed (2527→1707 facts)
+  → memory_search("TUNE-011 indexer quality")
+```
+
+Avoid this:
+
+```md
+- TUNE-011
+  - changed isQualityFact()
+  - added guards for code blocks
+  - adjusted token thresholds
+  - updated tests
+  - shipped at 11:42 PM
+```
+
+The first format reloads context fast. The second turns `MEMORY.md` into a bad replica of history.
+
+## Recommended sections
+
+Most agents do well with some version of these:
+
+- Identity
+- Domain priming
+- Key specs and plans
+- Standing rules
+- Key decisions
+- Recent actions or active facts, if they are still durable enough to matter
+
+Use only the sections that actually carry signal.
+
+## Recency checking
+
+Some facts are true now but should not be treated like permanent law.
+
+Examples:
+
+- current default model provider
+- active fallback model
+- temporary deployment workarounds
+- known incidents, freezes, or suspensions
+- "current release" statements
+- performance numbers tied to a recent benchmark
+
+For these, add recency cues and review them on a cadence.
+
+### Mark temporal facts clearly
+
+When a fact is time-bound, include one or more of:
+
+- an explicit date, such as `as of 2026-04-18`
+- a condition, such as `until Copilot is restored`
+- a review trigger, such as `recheck after next deploy`
+- a search pointer to the deeper event history
+
+Example:
+
+```md
+- Fleet model drift checks suspended as of 2026-04-14, until Copilot is restored
+  → memory_search("model drift suspension Copilot restored")
+```
+
+### Use a stale-question test
+
+Before adding an item, ask:
+
+1. Will this still be true in 30 days?
+2. If it changed silently, would stale memory cause a bad decision?
+3. Does the entry tell the next session how to verify freshness?
+
+If the answer pattern is `no / yes / no`, the item needs recency metadata or it belongs somewhere else.
+
+### Review cadence
+
+A simple operating rule works well:
+
+- review "current state" lines every 7 to 14 days
+- review release, benchmark, and provider facts after each upgrade or deployment change
+- remove or rewrite any entry whose time condition no longer holds
+
+### Prefer ranges over false permanence
+
+Bad:
+
+```md
+- Forge runs copilot-local/claude-sonnet-4.6
+```
+
+Better:
+
+```md
+- Forge standard model was copilot-local/claude-sonnet-4.6 as of 2026-04-11; recheck after provider routing changes
+  → memory_search("Forge standard model 2026-04-11 provider routing")
+```
+
+## Relationship to daily memory files
+
+Use daily files for checkpoint logging: what changed, what blocked, what to resume.
+
+Use `MEMORY.md` for the compact map of durable context.
+
+A good daily file helps you resume tomorrow. A good `MEMORY.md` helps you resume next month.
+
+## Maintenance rule
+
+If an entry no longer earns its place, delete it.
+
+A shorter `MEMORY.md` with current signal beats a larger one full of expired truth.
+
+## Static index vs runtime tail (compositor contract)
+
+`MEMORY.md` has two regions. The contract between them is enforced by the
+compositor and must be preserved by anyone editing the file.
+
+```
+┌─────────────────────────────────────────────┐
+│  Static curated index (human-authored)      │
+│  • identity, pointers, durable facts        │
+│  • edit this region by hand                 │
+├─────────────────────────────────────────────┤
+│  <!-- OPENCLAW_CACHE_BOUNDARY -->           │
+├─────────────────────────────────────────────┤
+│  Runtime tail (compositor-generated)        │
+│  • Active Facts                             │
+│  • Temporal Context                         │
+│  • Other Active Sessions                    │
+│  • Recent Actions                           │
+│  • Dynamic Project Context                  │
+└─────────────────────────────────────────────┘
+```
+
+### Rules
+
+1. **On-disk `MEMORY.md` is the curated static index.** It holds identity
+   anchors, pointer entries with `memory_search()` hints, and durable facts
+   that earn their place long-term.
+
+2. **Everything below `<!-- OPENCLAW_CACHE_BOUNDARY -->` is the compositor's
+   runtime tail.** It is regenerated on session warm from live stores: the
+   fact table, contradiction audits, topic activity, recent tool actions,
+   and dynamic project context. Treat the text below the boundary as a
+   snapshot, not a source of truth.
+
+3. **Do not hand-edit the runtime tail.** Anything you write there will be
+   overwritten on the next compositor pass.
+
+4. **Do not copy runtime tail content back up into the static index.**
+   Facts in the runtime tail originate from the fact store. Copying them
+   into the static region:
+   - duplicates the content between two layers,
+   - hardens a temporary state into a durable record,
+   - and bypasses the promoter's quality filters and temporal-marker screen.
+
+   If a runtime fact genuinely belongs in the durable index, let the
+   dreaming promoter handle it, or re-author the claim manually with the
+   durability rules above.
+
+5. **The compositor owns the boundary marker.** Do not delete, move, or
+   relabel `<!-- OPENCLAW_CACHE_BOUNDARY -->`. Deleting it makes the entire
+   file look static to the compositor and breaks the runtime tail rebuild.
+
+### Why this matters
+
+The runtime tail exists to surface what is live right now: active facts,
+recent actions, other sessions, current project context. The static index
+exists to hold what will still be true next month. Conflating the two
+produces the exact failure mode the temporal-marker screen guards against:
+temporary state hardens into durable memory, and the agent loses the
+ability to tell "fresh right now" from "true forever."
+
+## Promoter temporal-marker screen
+
+The dreaming promoter (`src/dreaming-promoter.ts`) uses a second line of
+defense to keep time-bound facts out of durable memory: the
+temporal-marker screen.
+
+**How it works.** When `isPromotable()` evaluates a candidate fact, it
+checks the content against a centralized list of temporal markers:
+
+- explicit time bounds: `as of`, `until`, `currently`, `for now`
+- transitional states: `suspended`, `pending`, `paused`, `blocked`, `frozen`
+- rollout language: `rollout`, `phase`, `migration ongoing`, `pre-release`
+- experimental language: `temporary`, `trial`, `experiment(al)`, `exploratory period`, `override`, `hotfix`, `workaround`, `recheck`
+- conditional scope: `in effect during`, `active while … continues/ongoing/rolling out`
+
+If any marker matches, the fact must carry structured recency metadata
+(`validFrom` or `invalidAt` on the facts row) to be eligible for durable
+promotion. Plain ISO dates in the content text are **not** a bypass: a
+sentence like `suspended pending X as of 2026-04-18` still contains the
+temporal markers `suspended` and `pending`, and the date only confirms
+that the claim is time-bound.
+
+**Extending the marker list.** The list is exported from
+`src/dreaming-promoter.ts` as `TEMPORAL_MARKERS`. Keep it centralized.
+Tests in `test/dreaming-promoter-temporal.mjs` exercise coverage on both
+direct and disguised phrasing; add new fixtures there when adding markers.
+
+**Implications for hand-written `MEMORY.md` entries.** The same
+discipline applies at the authoring layer. If you find yourself writing
+"currently," "for now," "pending X," or "in effect during Y" in the
+static index, add an explicit date-stamped condition or move the note to
+a daily file. The promoter's screen is a safety net, not a substitute
+for good authoring.