yvgude--lean-ctx/docs/cognition-interface.md

Cognition Interface (v1)

LeanCTX cannot modify proprietary model weights. Instead, it ships a Cognition Interface: a deterministic control surface that shapes the model’s effective reasoning by controlling what it sees, how it is budgeted, what is remembered, and what must be verified.

This is production-realistic for API LLMs and becomes even stronger when paired with open-weights models in an optional Cognition Lab track.

What “Cognition Interface” means in practice

1) Context I/O (signal in)

• Deterministic reads/search/shell output with explicit tool calls.
• Bounded outputs (size caps, truncation markers).
• Sandboxed file access (PathJail / allowed roots).

Evidence:

• rust/src/core/pathjail.rs
• rust/src/core/output_verification.rs
• rust/src/core/cache.rs

2) Orchestration (routing + budgets)

• Profile-driven pipelines (“Context as Code”): read modes, budgets, verification, autonomy.
• Intent/mode prediction and adaptive thresholds (bandits) to keep cost/quality stable.
• Client constraints compilation: the same policy must compile into client-safe instruction blocks.

Evidence:

• rust/src/core/profiles.rs
• rust/src/core/intent_engine.rs
• rust/src/core/mode_predictor.rs
• rust/src/core/adaptive_thresholds.rs
• rust/src/core/instruction_compiler.rs
• docs/integrations/client-constraints-matrix-v1.md

3) Memory (what persists)

• Session continuity (CCP), structured knowledge, contradictions/relations.
• Exportable handoffs and auditability across agents.

Evidence:

• rust/src/core/session.rs
• rust/src/core/knowledge.rs
• rust/src/core/gotcha_tracker/*
• rust/src/core/a2a/*

4) Verification (what must hold)

• Deterministic checks on compressed outputs (paths, identifiers, structure, line numbers).
• Proof artifacts and CI gates to prevent “it worked yesterday” drift.

Evidence:

• rust/src/core/output_verification.rs
• CONTRACTS.md
• rust/tests/*_up_to_date.rs

5) Delivery (everywhere)

• MCP + HTTP MCP + Team Server let the same primitives run locally, in CI, and enterprise setups.
• SDK + cookbook runs against a real server instance (no mock mode).

Evidence:

• rust/src/http_server/mod.rs
• rust/src/http_server/team.rs
• cookbook/sdk/src/client.e2e.test.ts

Contract: deterministic steering, not “prompt magic”

The Cognition Interface is only useful if it is:

• Deterministic: same inputs/policies → same compiled output.
• Bounded: caps enforced per client/model constraints.
• Auditable: evidence artifacts and CI gates catch drift.
• Local-first: no telemetry unless explicitly enabled.

Optional: Cognition Lab track

For open-weights experimentation (or internal models), the same interface becomes a research harness:

• learned attention/layout drivers
• calibration/evaluation suites
• ONNX models with versioning + rollout policies

See: docs/cognition-lab/plan-v1.md (tracked in GitLab #2344).