Crate totalreclaw_memory

Expand description

TotalReclaw Memory Backend

Rust implementation of the TotalReclaw E2EE memory pipeline. Produces byte-for-byte identical crypto output to the TypeScript MCP server.

§Modules

crypto — Key derivation (BIP-39 + HKDF-SHA256), XChaCha20-Poly1305 encrypt/decrypt
blind — Blind index generation (SHA-256 token hashing + Porter stemming)
fingerprint — Content fingerprint (HMAC-SHA256 with NFC normalization)
lsh — Locality-sensitive hashing (random hyperplane LSH)
embedding — Embedding pipeline (Local ONNX, Ollama, ZeroClaw, LLM provider)
reranker — BM25 + Cosine + RRF fusion reranker
relay — HTTP client for TotalReclaw relay server
protobuf — Minimal protobuf encoder for fact payloads
store — Encrypt → index → encode → submit pipeline (with Phase 2 KG contradiction check)
search — Subgraph query → decrypt → rerank pipeline
backend — ZeroClaw Memory trait implementation
setup — First-use setup wizard (credentials + embedding config)

Claim
Contradiction: A detected contradiction between two claims that share an entity.
DecisionLogEntry: A single row in decisions.jsonl.
EntityRef
MemoryClaimV1: A v1 memory claim per the Memory Taxonomy v1 spec.
MemoryEntityV1: Structured entity reference inside a v1 claim.
ResolutionOutcome: Output of running the resolution formula on a contradiction.
ResolutionWeights: Weights for the resolution formula. Defaults come from P2-3.
ScoreComponents: Per-component breakdown of a claim’s score.

ClaimCategory
ClaimStatus
EntityType
Error: Crate-level error type.
MemoryScope: Life-domain scope for a memory claim. Open-extensible per client, but every v1-compliant client MUST accept all values defined here when reading from a vault written by another client.
MemorySource: Provenance source for a memory claim.
MemoryTypeV1: v1 memory type — closed enum of 6 speech-act-grounded categories.
MemoryVolatility: Temporal stability of a memory claim. Assigned in the comparative rescoring pass, not at single-claim extraction.
ResolutionAction: The action to take after checking pin status and tie-zone guard during contradiction resolution.
SkipReason: Why a new claim was skipped in favour of the existing one.

CONTRADICTION_CANDIDATE_CAP: Soft cap on candidates fetched per entity during contradiction detection.
DECISION_LOG_MAX_LINES: Cap on the decisions.jsonl log — oldest lines are dropped above this.
DEFAULT_LOWER_THRESHOLD: Default contradiction detection band lower bound (below = unrelated).
DEFAULT_UPPER_THRESHOLD: Default contradiction detection band upper bound (at/above = duplicate).
MEMORY_CLAIM_V1_SCHEMA_VERSION: The required schema_version value for all v1 claims.
TIE_ZONE_SCORE_TOLERANCE: Tie-zone score tolerance for contradiction resolution.

append_decision_entry: Append one decision-log entry (as JSON string) to existing JSONL content.
build_feedback_from_decision: Build a FeedbackEntry JSON from a decision-log entry JSON and a pin action.
default_weights: Structurally defensible default weights from P2-3 of the Phase 2 design doc.
detect_contradictions: Detect contradictions between a new claim and existing claims that share at least one entity.
find_decision_for_pin: Walk decisions.jsonl content in reverse and return the first supersede_existing decision where the fact appears as winner or loser.
find_loser_claim_in_decision_log: Walk decisions.jsonl content in reverse and return the loser_claim_json for the most recent supersede_existing decision where existing_claim_id == fact_id.
is_pinned_claim: Check whether a claim has pinned status.
is_pinned_json: Check whether a JSON-serialized claim has pinned status.
resolve_pair: Run the resolution formula on two contradicting claims. Returns winner and loser. Ties (equal weighted totals) favour claim_a deterministically.
resolve_with_candidates: Core orchestration loop for contradiction resolution.
respect_pin_in_resolution: Apply pin-status and tie-zone checks to a resolution outcome.