super-memori（超级记忆）

Super Memori — v4.0.23 Project Skill

Release line: v4.0.23 unpublished current candidate line for the current-generation local-only memory runtime, advanced from the previously-published v4.0.22 baseline with an enforceable per-session startup self-check hook for OpenClaw session start.

Release-line truth boundary: the release line identifies the packaged skill artifact, not the live freshness state of whatever host runs it later. Current host freshness, semantic readiness, degraded state, and authority limits must be read from live command outputs such as ./health-check.sh --json and ./query-memory.sh ... --json at use time, not inferred from the release label alone.

Runtime prerequisites: Semantic / hybrid retrieval is now implemented in the runtime, but it only becomes active on hosts where local semantic prerequisites are actually present: sentence-transformers, numpy, a locally available embedding model, local Qdrant, and vectors built from canonical files. Without them, the skill remains operational in lexical/degraded mode and surfaces that state explicitly.

Status: v4 local-only memory runtime with real lexical, semantic, hybrid, temporal-relational, audit, and change-memory machinery in code, plus maintenance-only learning improvement / pattern-mining surfaces. Host state still matters: a host can run this release in lexical-only/degraded mode if semantic prerequisites or vector build state are missing.

Current Release & Host State

Artifact invariants (v4.0.23)

• Lexical retrieval: active.
• Change-memory: implemented and live.
• Change-audit integration: implemented and live.
• Minimal hot-change-buffer: implemented, internal, recovery-only, non-canonical, non-durable.
• Semantic / hybrid / temporal-relational runtime: implemented in code, host-dependent activation.
• Destructive auto-actions: disabled by default.
• Overall release state: unpublished 4.0.23 built on top of the previously published baseline 4.0.22.

Host-state guidance

• Do not infer live host state from this document. Read ./health-check.sh --json and ./query-memory.sh ... --json at use time.
• Known host-scoped caveat: system_hygiene may surface as stale or partial-visibility on some hosts; treat that as host-scoped degraded evidence, not a clean-health signal and not an artifact-wide invariant.
• Blocking issues for the active 4.0.23 line: none currently known after the enforceable per-session startup-hook hardening pass on this host.
• Publish-readiness qualification: a host reporting WARN is still within the qualified v4.0.23 baseline and does not by itself indicate artifact instability, setup failure, or a publication blocker; it only activates the degraded-mode routing contract defined below.

Host profiles

• current-degraded-host — safe-first, degraded-aware, no destructive auto-actions by default.
• equipped-stable-host — stronger semantic / audit / index verification allowed, but still truth-tracked and rollback-aware.

OpenClaw quickstart for weak models

If you need the shortest safe operating path under OpenClaw, use this order and do not improvise extra steps:

1. cd ~/.openclaw/workspace/skills/super_memori
2. ./health-check.sh --json
3. Read the JSON status field first. If status is FAIL → stop (emit D-FAIL).
4. If status is WARN → continue only in degraded mode, applying the matching D-WARN-* catalog row from the JSON-qualified state rather than from exit code alone.
5. Treat the bash exit code from health-check.sh only as a hard-stop gate: exit 3, 4, or 5 = immediate stop/escalate; otherwise continue to JSON parsing.
6. For first query: ./query-memory.sh "<your query>" --mode auto --json
7. Trust the exact field set defined in Operating Rule 2 below. Do not infer stronger capability than the payload states.
8. Use ./memorize.sh only for reusable lessons.
9. Use ./index-memory.sh only when the contract below tells you to refresh or repair freshness.

This quickstart does not guarantee semantic-ready operation on every host. It gives the strongest safe first path on OpenClaw while keeping degraded truth explicit.

Weak-Model Decision Matrix

Use this matrix when a weak model needs one-pass routing instead of hopping between quickstart prose, degraded-state catalog rows, and multiple exit-code tables.

Priority rules:

1. health-check.sh --json status is the primary gate; bash exit code is only a hard-stop override.
2. For degraded routing, D-WARN-COMBINED beats D-WARN-INDEX-STALE-ONLY, which beats D-WARN-GENERIC.
3. D-LOW-AUTHORITY can apply on top of OK or WARN whenever the returned authority fields require it.
4. Never describe a degraded lexical fallback as semantic or hybrid retrieval.

Execution

OpenClaw host setup (weak-model executable)

Use this only when preparing super-memori on an OpenClaw host for first use or when rebuilding local prerequisites. Execute the steps in order.

1. Enter the skill directory

cd ~/.openclaw/workspace/skills/super_memori

2. Confirm Python is available

python3 --version

Expected: Python is installed and callable as python3.

3. Optional: install semantic prerequisites for fuller local capability

pip3 install --user sentence-transformers numpy qdrant-client

Note: this installs only the Python client library; it does not install or start the Qdrant database service. Vector search will remain inactive until a reachable local Qdrant service is running and accessible. If this step fails, the skill can still run in degraded lexical-only mode and will report that state honestly.

4. Build or refresh local indexes

./index-memory.sh --full --json

If semantic prerequisites are still unavailable, this may complete in degraded mode. Report that honestly; do not pretend semantic readiness.

5. Verify host health

./health-check.sh --json

Expected result:

• OK = normal operation
• WARN = degraded but usable operation
• FAIL = stop and escalate to maintenance

6. Run a first real query

./query-memory.sh "test query" --mode auto --json --limit 3

Confirm that the output includes at least mode_used, degraded, warnings, and results.

7. Return to the normal operating contract

After setup, follow only the four public commands and the FOR ALL MODELS — REQUIRED OPERATING CONTRACT below.

Change-Memory Authority & Scope

• Change-memory records are operational truth about agent-made changes. Structured records distinguish applied, failed, reverted, and unverified states, and support current-known-state + recall-bundle retrieval. reverted or unverified records must not be presented as active current state.
• A minimal internal hot-change-buffer may hold very recent recovery-only state for recent agent-made changes. It is internal-only (no public command), RAM-resident, circular, non-canonical, non-durable, and aggressively noise-filtered.
• Neither durable change-memory nor the hot-change-buffer replaces direct live filesystem / service / package inspection when exact current machine state is required.
• Destructive auto-actions remain disabled by default.

Change-Memory Noise Policy

• Do not log harmless reads as change-memory.
• Log only state-changing actions, failed writes, risky cleanup, package/service/config/runtime changes, and rollback events.

Truth precedence

For current machine state

1. Canonical files and direct live inspection
2. Lexical index
3. Semantic / vector index when healthy
4. Learning memory
5. Inferred recall last

For agent-made change history

1. Change-memory records
2. Change-audit integration
3. Canonical files that directly confirm the current result
4. Inferred recall last

Decision rule for live inspection

Live filesystem / service / package inspection is mandatory before writes, config changes, service restarts, or any action that depends on exact current machine state, and whenever ./health-check.sh returns WARN or FAIL. Memory-tool outputs are sufficient on their own only for read-only queries when status=OK and the returned payload has degraded=false.

Never let inferred, stale, degraded, or retrieval-only surfaces override canonical truth.

RUNTIME CAPABILITY MATRIX

IMPLEMENTED VS OPTIONAL VS HOST-STATE TRUTH

• Implemented now in code: lexical search, semantic search, hybrid fusion, temporal-relational rerank, integrity audit, relation-aware write metadata, block-level pattern mining, change-memory capture, change-audit integration, and a minimal internal recovery-only non-canonical non-durable hot-change-buffer.
• Optional host state: semantic embeddings, vector search, and hybrid selection only activate when local semantic dependencies/model/vector state are actually ready.
• Not implemented / not claimed: cloud backends, remote embeddings endpoints, remote vector DB, auto-promotion into durable memory, internet-dependent memory runtime, destructive auto-actions by default.

Design Boundaries / Intentional Exclusions

This skill is intentionally strong-by-constraint rather than feature-maximal.

• It keeps a four-command public surface because weak OpenClaw models are more reliable when command choice, degraded routing, and rollback expectations fit in one short loop.
• It rejects background auto-indexing and always-on memory daemons as public operating requirements because they hide freshness state, blur operator intent, and make degraded/rollback truth harder to surface cleanly on local hosts.
• It rejects LLM-driven auto-consolidation or automatic promotion into durable memory because reusable lessons must remain operator-auditable and reversible.
• It rejects cloud sync, hosted embeddings, and remote vector backends because this artifact is optimized for local-first OpenClaw deployment, local privacy, and host-truthful failure handling.
• It prefers explicit host-state checks over ambient automation: current freshness, semantic readiness, and authority must come from live payloads, not from assumptions that a background subsystem stayed healthy.

FOR ALL MODELS — REQUIRED OPERATING CONTRACT

Public commands

• ./query-memory.sh
• ./memorize.sh
• ./index-memory.sh
• ./health-check.sh

Maintenance-only entrypoints

These are maintenance-only surfaces. Do not add them to the normal weak-model command loop unless maintenance is explicitly requested.

• ./audit-memory.sh — human/maintenance integrity audit surface.
• ./repair-memory.sh — human/maintenance repair planner/executor surface for controlled memory repair work.
• ./list-promotion-candidates.sh — human/maintenance review surface for candidate promotion workflow.
• ./validate-release.sh — human/maintenance release-surface verification gate; not a normal runtime memory command.
• ./startup-self-check.sh — startup-only health gate and safe self-heal surface for OpenClaw bootstrap/BOOT.md flows.
• hooks/super-memori-session-start/ — enforceable per-session startup hook surface for OpenClaw agent:bootstrap runs.

Weak-model operating rules

1. Default to ./query-memory.sh --mode auto. The script will choose the strongest available local path and will report what actually ran via mode_used.
2. Trust the returned mode_used, degraded, warnings[], semantic_ready, semantic_fresh, index_fresh, authoritative_result_present, low_authority_only, and each result's match_authority fields when they are present. Do not infer stronger capability than the payload states.
3. --mode semantic and --mode hybrid are now real implemented runtime modes. They are no longer compatibility stubs. Weak models still should prefer auto unless the task clearly requires a forced semantic/hybrid retrieval query.
4. If --mode semantic or --mode hybrid is requested on a host where the runtime reports semantic_ready=false or otherwise returns degraded=true, do not pretend semantic execution succeeded. Trust the returned mode_used and warnings: the request may honestly degrade to the strongest available local lexical path on this host. In that case, report the degraded lexical outcome as such and do not describe the result as semantic or hybrid retrieval. Precedence: if the payload also reports index_fresh=false (or index_stale=true) together with semantic unavailability, D-WARN-COMBINED applies and lexical fallback authority is revoked; otherwise apply D-WARN-GENERIC and present the degraded lexical result honestly.
5. For the lowest-friction safe path, weak models should think in this order: health-check -> query(auto) -> read returned fields -> only then decide whether memorize or index is needed.
6. --mode learning remains a learning-memory-oriented retrieval lane, but it now sits on top of the stronger v4 retrieval stack and still reports its true mode_used honestly.
7. Use memorize.sh only for reusable lessons that should influence future behavior. Positive test: memorize only if the lesson encodes a reusable decision rule, parameter set, or failure pattern that will predictably recur across ≥2 sessions or contexts. Do not log expected misses, one-off noise, duplicate lessons, or checked, nothing relevant.
8. Relation targets in memorize.sh are canonical, not freeform. Use only learn:<signature>, chunk:<chunk_id>, or path:<canonical_path> relation targets.
9. Do not execute internal helper scripts or reason about backend selection manually during normal use. The runtime owns retrieval choice; you consume the structured output.

Canonical action routing

Use this compact routing map first when choosing what to do next; the detailed gates and exit-code tables below remain authoritative for script-specific interpretation.

Degraded-State Response Catalog (single source of truth)

All mandatory user-visible degraded strings live here. Some rows are exact output strings; behavioral-rule rows are marked as such. Other sections reference this catalog by ID; do not restate inline elsewhere.

JSON-capable outputs: mandatory degraded notices must live inside structured warning fields rather than outside the payload.

Health & Safety Gate

For one-pass weak-model routing, prefer the Weak-Model Decision Matrix above first; this section remains the detailed degraded-state authority. See Canonical action routing above for the shortest precedence map; this section remains the detailed degraded-state authority.

• OK → proceed normally.
• WARN → emit the matching catalog row (D-WARN-COMBINED takes precedence over D-WARN-INDEX-STALE-ONLY, which takes precedence over D-WARN-GENERIC). For writes/maintenance also append D-WARN-WRITE-ROLLBACK. For read-only degraded queries, state the degradation and fallback scope without requiring a rollback path.
• In the D-WARN-COMBINED state, lexical authority is revoked: do not present results as lexical truth or as the best available answer; do not invent manual retrieval steps outside the four public commands.
• Under D-WARN-INDEX-STALE-ONLY, indexed results remain usable but freshness-limited; do not present them as fully current. Under semantic-only unavailability (lexical freshness OK), lexical/index-backed results remain authoritative for exact/path/time-style matches, but do not describe them as semantic or meaning-based retrieval.
• D-LOW-AUTHORITY applies regardless of warn/ok surface whenever those fields are set.
• Do not treat every warnings[] note as a degraded retrieval result. Informational notes may appear even when the current request was satisfied exactly as designed; rely on the script's degraded field and exit code, not on the mere presence of warning text.
• Queue/backlog WARN states do not by themselves disable read/query authority, but they do require reporting that recent learnings or pending index work may not yet be reflected. Negative results under that WARN should be treated as potentially incomplete, not definitive absence.
• FAIL → emit D-FAIL.

Interpreting query-memory.sh exit codes

After running ./query-memory.sh, you MUST check the exit code and act accordingly:

CRITICAL: Do not confuse exit code 1 (clean miss) with exit code 3 (broken retrieval stack). The former is normal operation; the latter requires immediate escalation.

Interpreting memorize.sh exit codes

After running ./memorize.sh, you MUST check the exit code and act accordingly:

If you need machine-readable confirmation, prefer ./memorize.sh --json ... and inspect its status field (written vs duplicate) instead of inventing extra exit-code meanings.

Interpreting health-check.sh exit codes

After running ./health-check.sh, you MUST check the exit code and act accordingly:

Precedence rule: for normal degraded-mode routing, always execute ./health-check.sh --json and decide OK vs WARN vs FAIL from the parsed JSON status field plus payload details. Treat the bash exit code only as a hard-stop gate: exit 3, 4, or 5 means immediate stop/escalate; other non-fatal paths still require JSON parsing before selecting a D-WARN-* row.

If you need machine-readable status decisions, prefer ./health-check.sh --json and inspect structured status, warnings, and checks[] fields rather than guessing from free text.

Interpreting index-memory.sh exit codes

After running ./index-memory.sh, you MUST check the exit code and act accordingly:

If you need machine-readable details, prefer ./index-memory.sh --json and inspect actions[], warnings[], and any mode-specific fields returned by the script.

Pre-action gate

Applies when: the next action is a script/policy/index edit that modifies files, OR a ./memorize.sh call meant to durably record a high-value lesson. For the short routing form, see Canonical action routing above.

Execute in order, do not skip:

1. Run ./health-check.sh directly (not via bash <script>).
2. Apply the Health & Safety Gate result:

- OK → continue to step 3. - WARN → emit the matching catalog row (plus D-WARN-WRITE-ROLLBACK) and continue to step 3 only if the rollback path is concrete. - FAIL → emit D-FAIL and STOP.

1. Verify rollback exists: git status, a backup directory, or untouched canonical files. If rollback is unclear, abort and escalate to human maintenance.
2. If live inspection contradicts a change-memory record marked applied, trust live inspection, abort the write/maintenance action, and treat the host as degraded until reconciled.
3. Do not ingest references/maintenance.md during normal operation; open it only for human-led maintenance or when this skill explicitly tells you to.

Deterministic fallback

• If a request does not clearly map to the four public commands or the explicit maintenance path, reply: Out of scope for super-memori v4 local-only runtime. Please specify which command to run or escalate to human maintenance. After running a public command, follow the exit-code interpretation rules above exactly.
• If you are unsure whether information qualifies for memorize.sh, default to not memorizing.

Maintenance Reference

For retrieval pipeline contracts, write/learning contracts, promotion rules, maintenance entrypoints, release gates, and anti-patterns, see references/maintenance.md.