Memory Recall

Retrieval-side contract for the Coven memory layer (Authoritative Plan v1 hole #7; issue the memory recall implementation). Any familiar, under any runtime, uses this skill to pull already-promoted facts back into working context. It does not write, promote, or mutate anything under ~/.coven/memory — that is the promotion layer's job (schema: familiar-contract/schemas/coven-memory-schema.md §11). A coven memory promote command is planned but does not exist yet; see docs/memory/attested-promotion.md.

When to use

• The question depends on a promoted Coven fact, decision, or cross-familiar context rather than the current session or the familiar's own MEMORY.md.
• "Did we decide X?" / "what did <familiar> attest about Y?" for anything that plausibly predates the current session or originated with another familiar.
• As a supplement to the runtime's own memory search (which covers per-familiar MEMORY.md / daily notes / transcripts). Recall covers the layer below that: promoted, attested, cross-familiar-visible.

When NOT to use

• Answer is in the current session → just answer.
• Answer is in the familiar's own MEMORY.md or daily files → use the runtime's memory tools.
• The promotion layer has not run for the relevant window → recall returns empty; say so honestly. Never fabricate a hit.

Inputs

Outputs

Side effects

None. Recall is read-only by construction; an implementation that mutates ~/.coven/memory during recall is non-conformant with this skill. Recall MUST NOT log query text to any destination outside the Coven filesystem.

Steps

1. Precondition. ~/.coven/memory/manifest.jsonl exists with ≥1 line, else return {hits: [], count: 0, note: "promotion layer has not run"} and stop.
2. Query the crate. Treat query and familiar as untrusted data. Validate familiar against ^[A-Za-z0-9_-]{1,128}$ (default coven) — the shape the crate's validate_identifier already enforces — and reject any other value. Invoke the crate with an argv API, not a shell command string, equivalent to execve/subprocess.run(["coven-memory", "search", "--familiar", familiar, query]). If a runtime exposes only a shell, pass every dynamic argument through robust single-argument shell escaping (for example Python shlex.quote) and do not concatenate raw input. Add --index/ --db only if the store lives off the default path. The crate owns ranking (fastembed/nomic-embed-text-v1.5 + TurboVec ANN; schema §11.5 pins embeddings as crate-internal).
3. Join against the manifest. For each hit, find its manifest line by ulid. Apply since/until on timestamp. Detect supersession: if a later operation: supersede line names this ulid as prior_ulid, annotate superseded_by and rank the superseding entry ahead of the superseded one. Never silently hide a superseded claim — the store is a claims log (§11.0).
4. Verification (verified_only=true, default). Drop hits where (a) the manifest sha256 mismatches the promoted snapshot content, or (b) the entry's attested_via attestation file is absent. Count them in dropped. Fail-degraded, not fail-fatal: verification failure removes the hit and is reported; it never aborts the query. (No cryptographic verification in v1 — attestations are unsigned per schema §11.2.)
5. Resolve source_context lazily. Entries carry FAMILIAR_ROOT-relative paths or portable session:// references (§11.1). Resolve against the current environment's FAMILIAR_ROOT (--familiar-root flag → COVEN_FAMILIAR_ROOT env) only when the caller asks to open a source; unresolvable → return the portable reference as-is with a note. Recall never requires FAMILIAR_ROOT to answer.
6. Answer with provenance. Present claims with attested_by + attestation_type
   • confidence + timestamp. Conflicting claims are both returned; the querying familiar reasons over them (claims-log framing, §11.0).

Failure modes

Runtime-Portability Audit (§11.5 — answered)

If Val runs a familiar tomorrow under a different runtime (Codex CLI, Cursor, Claude Code, CovenCave, bare SSH), does this skill work without modification?

✅ Yes. The skill's only dependencies are (a) the coven-memory CLI — a Coven-shipped binary, and (b) ~/.coven/memory/ — a Coven-owned contract path. No shell, runtime-specific hooks, session APIs, or bootstrap injection are required. FAMILIAR_ROOT resolution follows the schema's flag→env→fail-closed order and is only needed for optional source opening, never for querying. Session references use the portable session:// class form, never raw runtime session keys.