yvgude--lean-ctx/docs/contracts/knowledge-policy-contract-v1.md

Knowledge Policy Contract v1

GitLab: #2317

Ziel

Ein versionierter Governance-Vertrag für Project Knowledge (Facts/Patterns/History + Relations), der:

• bounded ist (keine unkontrollierte Growth/Outputs),
• deterministisch ist (stable ordering + stable semantics),
• replayable ist (Timeline/History bleibt interpretierbar),
• sicher ist (kein secret leakage, policy-gated surfaces),
• auditable ist (Writes emit events).

Version (SSOT)

• leanctx.contract.knowledge_policy_v1.schema_version=1
  • SSOT: CONTRACTS.md
  • Runtime: rust/src/core/contracts.rs

Policy Surface

Config (global/project)

Policy wird über Config.memory geladen und validiert:

• Runtime: rust/src/core/config.rs (memory_policy_effective)
• Structs: rust/src/core/memory_policy.rs

Minimaler TOML-Ausschnitt:

[memory.knowledge]
max_facts = 200
max_patterns = 50
max_history = 100
contradiction_threshold = 0.5

# Retrieval budgets (bounded outputs)
recall_facts_limit = 10
rooms_limit = 25
timeline_limit = 25
relations_limit = 40

[memory.lifecycle]
decay_rate = 0.01
low_confidence_threshold = 0.3
stale_days = 30
similarity_threshold = 0.85

# Verlustfreie Kapazitäts-Reclaim (#995)
reclaim_headroom_pct = 0.25   # voller Store siedelt sich bei 1 - pct (= 75%) an
reclaim_enabled = true        # false ⇒ nur Overflow kappen (Escape Hatch)

Env Overrides (optional)

Die Runtime akzeptiert env overrides für zentrale Felder (siehe memory_policy.rs).

Semantik (MUST)

Facts

• Facts sind logisch durch (category, key) adressiert.
• Current vs archived:
  • current: valid_until == None
  • archived: valid_until != None
• Updates dürfen den vorherigen Zustand nicht “vergessen”: Timeline muss eine nachvollziehbare Folge liefern (archived versions + current).

Contradictions

• Contradiction detection:
  • Case-insensitive equality ⇒ kein Widerspruch.
  • Word-similarity über Schwelle ⇒ kein Widerspruch (verhindert false positives bei semantisch gleichen Werten).
• Severity semantics (stabil):
  • High: existing.confidence >= 0.9 und existing.confirmation_count >= 2
  • Medium: existing.confidence >= contradiction_threshold
  • Low: sonst

Retrieval Budgets (bounded, deterministisch)

• recall_facts_limit: max facts in Recall Outputs
• rooms_limit: max rooms in ctx_knowledge action=rooms
• timeline_limit: max entries in ctx_knowledge action=timeline
• relations_limit: max edges in ctx_knowledge action=relations|relations_diagram

Ordering ist deterministisch (stable sort tie-breaks), danach erfolgt Truncation.

Lifecycle

• Confidence decay + consolidation + compaction laufen deterministisch und bounded:
  • Runtime: rust/src/core/memory_lifecycle.rs
  • Parameter: decay_rate, low_confidence_threshold, stale_days, similarity_threshold, max_facts

Verlustfreie Eviction (MUST, #995)

• Kein Hard-Drop. Jeder Store (facts/history/procedures/patterns) evictet ausschließlich über den einen Kapazitäts-Manager (rust/src/core/memory_capacity.rs::reclaim_store). Der entfernte Tail wird vor dem Löschen nach memory/archive/<store>/ archiviert und ist wiederherstellbar.
• Eine Formel + Hysterese. reclaim_target(max, reclaim_headroom_pct) ist die einzige Zielgrößen-Berechnung. Ein Reclaim triggert nur bei len >= max und siedelt den Store dann bei reclaim_target an (kein Churn pro Write).
• Default-on, gated. reclaim_enabled = true ist Standard; false kappt nur den Overflow (Daten bleiben in beiden Fällen verlustfrei).
• Retention-Ranking je Store ist deterministisch (stable sort tie-breaks): facts nach is_current + Output-Ranking, history/patterns nach Recency, procedures nach procedural_memory::retention_cmp.
• Archive-Erreichbarkeit. rehydrate_reach ist an max_files gekoppelt (ArchiveConfig), sodass jedes retainte Archiv für Recall/Restore erreichbar ist.

Tool Surface

• ctx_knowledge (MCP): rust/src/tools/ctx_knowledge/
  • action=policy + value=show|validate (policy visibility + range validation)
  • action=consolidate (+ dry_run=true ⇒ Preview ohne Writes), action=consolidate_preview
  • action=restore (store, query, limit) ⇒ verlustfreies Undo aus dem Archiv
  • Writes (remember, pattern, feedback, relations) emit audit events
• CLI-Parität: lean-ctx knowledge consolidate [--all] [--dry-run] und lean-ctx knowledge restore [--store …] [--query …] [--limit N]
• Relations: rust/src/tools/ctx_knowledge_relations.rs (bounded + deterministic outputs)

Security & Privacy

• Keine Secrets in Knowledge/Artifacts/Logs; Redaction + path boundaries gelten auch für Memory I/O.
• Outputs sind bounded; Policies müssen nicht zu Token-Burn führen.