compass-integrity

name	compass-integrity
description	Use when the user is about to rely on prior session memory for a non-trivial decision, or when something feels off about a recall hit — runs the Merkle chain check, drift summary, and daemon liveness in one pass and surfaces any tampering, drift bursts, or daemon-down state before the user acts on stale or corrupted memory.

Compass Integrity Check

Overview

Compass writes a Merkle hash chain over project memory and a per-session drift signal. Both can be silently broken — a chain mismatch means a memory file was edited outside the writer; a drift-red session means the past assistant output diverged from intent. A recall hit on tampered or red-drift memory is worse than no recall.

This skill runs the integrity checks before the user commits to acting on memory.

When to invoke

Trigger conditions (any one):

1. User says "do we remember", "did we discuss", "based on past sessions" — they're about to lean on memory.
2. User points at a specific memory file or session ID — verify the chain covers it cleanly.
3. Drift incident already suspected ("why did the assistant flip on X?", "this looks like a regression") — pull recent drift history.
4. Session start in a project with memory/, before any recall fires — preflight.
5. After a crash, conflict resolution, or merge — chain may have been broken by a non-writer edit.

Skip when:

• The work is purely procedural (no memory dependency).
• The user explicitly said "ignore memory" / "don't use prior context".

How it works

The skill is a one-pass orchestrator over four already-shipped CLIs in this plugin:

Check	Tool	What it tells you
Daemon liveness	nc 127.0.0.1 9876 ping	Is BGE-m3 up? If not, recall is metadata-only.
Chain integrity	compass_verify.py	Are any memory files tampered/missing?
Drift trend	drift_history.py 7	What is the green/yellow/red split for the last 7 days?
Memory size	recall.find_active_project_memory_dir	How many entries exist for the current project?

The fastest path is the /compass-status slash command, which bundles all four. Use that as the primary entry; only call the individual CLIs if you need finer control (e.g. /compass-drift 30 for a longer window after a yellow signal).

Decision rules

Run the bundle, then apply this triage:

State	Action
All ✓, drift mostly green	Proceed with recall. One-line greenlight to user.
Daemon DOWN	Tell user; recall falls back to keyword/metadata mode (lower recall@k); offer to start daemon.
Chain TAMPERED	Stop. Surface tampered file list verbatim. Do not recall those files. Ask user whether to audit diff or regenerate chain. Document in session notes.
Drift red ≥ 5% in window	Pull /compass-drift 30 --top 10. Surface most recent red incidents. Warn user that prior assistant outputs in those sessions may have been off-intent.
Memory empty	Tell user — no recall hits available. Don't pretend to find them.

Two failure modes can stack (daemon down AND red drift). Surface both, don't pick one.

Examples

Greenlight path

User: "Did we already pick a logging format?"
Assistant: [runs /compass-status]
  daemon  : ✓ pong
  chain   : ✓ C--Users-chunx-Projects-foo
  drift   : G:91% Y:8% R:1% (7d)
  memory  : foo · 23 entries
[runs /compass-recall "logging format"]
"Yes — 2 hits. Decision in feedback_logging.md from 2026-04-22: structured JSON + level filtering ..."

Tampered path

User: "What were our deploy criteria?"
Assistant: [runs /compass-status]
  chain   : ✗ TAMPERED · 1 file (deploy_criteria.md)
"Memory chain mismatch on deploy_criteria.md — it was edited outside the writer. I won't recall from it
until we audit. `git log --diff-filter=M deploy_criteria.md` should show what changed; want me to run that?"

Daemon-down path

User: "Search prior sessions for the Postgres pool size we settled on."
Assistant: [runs /compass-status]
  daemon  : DOWN (timed out)
  chain   : ✓
  drift   : G:84% Y:13% R:2% (7d)
"BGE daemon is down — falling back to keyword search. Hits will miss paraphrases. Start it with
`bash ~/.claude/plugins/nautilus-compass/daemon_start.sh`. Want me to keyword-search now or wait?"

Anti-patterns

• ❌ Recalling silently on a tampered chain. The user should see the tamper alert before any hit lands in the response.
• ❌ Treating yellow drift as failure. Yellow = "small drift, recovered" — historically benign.
• ❌ Reading every memory file to "verify" — the chain is the verification. Don't reinvent it by content-diffing.
• ❌ Auto-regenerating the chain on tamper detection. Always ask the user — regenerating without auditing buries the evidence.

Failure & escalation

If /compass-status itself errors (e.g. ImportError, missing CLI):

1. Note the failure in plain text.
2. Fall back to letting the user proceed without memory (don't pretend to verify).
3. Open a follow-up to fix the broken check — never "best-effort silent skip".