diff --git a/README.md b/README.md index 86978b0..c32a6d5 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ The host supplies the compiled state to the model so the constraint persists acr Prompt instructions are soft and easy to lose across long interactions. -The Context Compiler gives the host an **authoritative state snapshot** that is independent of transcript drift. +The Context Compiler gives the host an **authoritative state representation** that is independent of transcript drift. Only **explicit user directives** can modify state. @@ -126,7 +126,7 @@ Meaning: ## State Model -The compiler maintains an authoritative state snapshot: +The compiler maintains an authoritative state: ```json { @@ -140,11 +140,29 @@ The compiler maintains an authoritative state snapshot: } ``` +## State Export / Import + +The compiler exposes its authoritative state so host applications can +persist or restore it across sessions. + +Example lifecycle: + +```python +state = engine.export_state() +save_to_storage(state) + +restored = load_from_storage() +engine = create_engine(state=restored) +``` + +The compiler does not manage storage or snapshots. Persistence policies +belong to the host application. + **Note** -In M1, the fact schema contains a single exclusive slot: `facts["focus.primary"]`. +The fact schema currently contains a single exclusive slot: `facts["focus.primary"]`. This slot exists to demonstrate deterministic fact replacement and correction semantics. -Richer fact schemas may be introduced in future milestones. +Richer fact schemas may be introduced in future releases. ### State Properties @@ -311,39 +329,22 @@ The compiler enforces several invariants: --- -## Current Milestone - -The current implementation corresponds to: +## Implementation Status -### M1 — Deterministic State Engine - -Goal: - -Ensure explicit user corrections and constraints persist reliably within a single conversation. +The current implementation provides the deterministic directive compiler +defined in [this document](/docs/M1Design.md). --- -## Future Milestones - -Only **M1** is currently implemented. - -Possible future work: - -### M2 — Scope & Session Control (optional) - -Introduce isolation boundaries so state applies only within the intended conversational context. - -### M3 — Cross-Session Recall - -Allow explicit recall of prior authoritative state across sessions. - -### M4 — MCP Integration (optional) +## Future Work -Expose the state engine through a standardized context interface. +This project intentionally focuses on the deterministic directive compiler itself. -### M5 — Branch Awareness (optional / experimental) +Higher-level systems such as session scope management, memory layers, agent tooling, +or context routing belong in host applications or separate projects built on top of +the compiler. -Provide tools for managing multiple conversation branches during exploratory discussions. +One possible future extension is cross-session persistence using exported state. --- diff --git a/docs/DescriptionAndMilestones.md b/docs/DescriptionAndMilestones.md index 9fb47f3..701d2f1 100644 --- a/docs/DescriptionAndMilestones.md +++ b/docs/DescriptionAndMilestones.md @@ -1,6 +1,6 @@ # Context Compiler -Deterministic state management for LLM interactions\ +Deterministic state management for LLM interactions ## Project Purpose @@ -11,11 +11,10 @@ conversations, and long-term state accumulates contradictions rather than resolving them. This project introduces a deterministic state layer that governs authoritative state independently of the model. The model performs -interpretation and generation, while the state engine manages facts and -policy additions/removals, scope, and recall. By separating reasoning +interpretation and generation, while the state engine manages deterministic conversational state (facts and policies). By separating reasoning from state authority, the system improves reliability without requiring model retraining. The system never derives authoritative state from -model responses; only user directives modify state +model responses; only user directives modify state. The goal is not to make the model smarter, but to make interactions predictable: once a statement is corrected or scoped, future responses must respect that change. @@ -31,10 +30,9 @@ All state transitions originate from explicit user directives. ## Project Milestones -### M1 — Deterministic State Engine - -**Goal:** +### M1 — Deterministic State Engine (implemented) +**Goal** Explicit user commitments persist reliably within a conversation. A correction means replacing a previously set fact, not evaluating conversational accuracy. @@ -47,167 +45,40 @@ Richer fact schemas may be introduced in future milestones. **Core capability:** - Recognize high-confidence user directives (facts and policies) - - Apply corrections as deterministic replacements - - Block ambiguous updates until clarified - - Maintain an authoritative state independent of prior messages - - Provide structured state for host-provided model context **Deliverables:** - Directive grammar (conservative pattern set) - - State data model (facts + policies) - - Deterministic update rules (exclusive vs additive slots) - - Clarification mechanism for ambiguous mutations - - Context serialization interface (state → host application) - - Reference integration harness (example host) - - Tests: persistence and non-regression of corrections **User-visible outcome:** After correcting or constraining the assistant once, the behavior remains consistent for the rest of the conversation. -### M2 — Scope & Session Control (optional) - -**Goal:** - -Prevent topic leakage and cross-contamination between conversations. - -**Core capability:** - -- Session scopes - -- Explicit referent registration and binding - -- Controlled entity allow/block lists (“forget X”) - -- Clean-room context compilation - -- Separate profile preferences from session state - -**Deliverables:** - -- Scope lifecycle model - -- Deterministic reference binding and scoped state isolation - -- Scope reset logic - -- Context filtering layer - -- Tests: no topic bleed; preferences persist - -**User-visible outcome:** - -New topic feels clean; old projects do not resurface unintentionally. - -### M3 — Cross-Session Recall** +### M3 — Cross-Session Recall **Goal** -Recall past sessions safely and intentionally. +Allow host applications to restore previously exported state safely and intentionally. **Core capability:** -- Persist authoritative state when a session closes - -- Restore prior state into the active session only through an explicit - recall operation - -- Recalling a snapshot replaces the active state; subsequent user - directives may modify it - -- Allow selective forgetting and pinning of stored snapshots - -- Ensure recalled state behaves identically to live state +- Export the current authoritative state +- Initialize a new engine from previously exported state +- Ensure restored state behaves identically to live state **Deliverables:** -- Snapshot storage - -- Recall API - -- Forget/pin controls - -- Optional session summary generator - -- Tests: recall respects refutations and bans +- Import/Export API **User-visible outcome:** Assistant remembers decisions across sessions without resurrecting contradictions. - -### M4 — MCP Integration (optional) - -**Goal** -Expose the state engine via a standardized context interface. - -**Core capability:** - -- Read state (active facts, policies, constraints, scope) - -- Write events (correction, forget entity, close scope) - -- Interoperable with model ecosystems - -**Deliverables:** - -- MCP provider implementation - -- Read/write context endpoints - -- Documentation for integration - -**User-visible outcome:** - -System can plug into external agents and tools -without custom adapters. - -### M5 — Branch Awareness (Optional / Advanced) - -**Goal** -Make long exploratory conversations navigable. - -**Core capability:** - -- Detect multiple discussion threads - -- Branch registry - -- Conversation map - -- Anchor selection - -**Deliverables:** - -- Branch data model - -- Drift detection logic - -- Map generation - -- Tests: branch isolation and restoration - -**User-visible outcome:** - -Brainstorming stays structured and resumable. - -## Milestone Relationships - -M1 is the foundation. - -M3 builds directly on M1 and may be implemented without M2. - -M2 introduces optional scope and session isolation. - -M4 is an optional integration milestone. - -M5 is optional and independent of the other milestones. diff --git a/docs/M2M3Addendum.md b/docs/M2M3Addendum.md deleted file mode 100644 index 8e6f2e4..0000000 --- a/docs/M2M3Addendum.md +++ /dev/null @@ -1,105 +0,0 @@ -# Context Compiler — M2/M3 Constraint Addendum - -*(Non-normative behavior specification; normative invariants only)* -This document defines architectural guarantees for future milestones. -It prevents incompatible future implementations while preserving design -freedom. -M1 remains the only fully normative behavioral specification. - -## M2 — Scope & Session Control (Constraint Specification) - -### Purpose - -Introduce isolation boundaries so authoritative state applies only -within the intended conversational context. -M2 does **not** introduce inference, entity recognition correctness -guarantees, or semantic reasoning. - -### Required Invariants - -#### Scope Isolation - -State in one scope MUST NOT influence another scope unless explicitly transferred. -Equivalent inputs in separate scopes produce identical decisions independent of prior scopes. - -#### Clean Compilation - -Compiled context MUST derive only from authoritative state, never from transcript reconstruction. -No implementation may reconstruct facts by scanning previous messages. - -#### Explicit Reference Binding - -References to prior subjects must resolve only if explicitly registered in the active scope. -Unresolved references MUST NOT guess or infer prior meaning. - -#### Explicit Forgetfulness - -Removal of state requires an explicit directive.Ending a scope implicitly removes all non-persistent state. - -#### Preference Separation - -Persistent user preferences and session-specific facts MUST be stored independently and applied deterministically. -Session reset MUST NOT alter persistent preferences. - -#### Undefined Behavior (Deferred Decisions) - -The following are intentionally unspecified: - -- How scopes are detected or created -- Entity extraction algorithms -- UI/UX of topic switching -- Heuristics for implicit scope changes -- Naming or addressing of entities - -Implementations may vary provided invariants hold. - -## M3 — Cross-Session Recall (Constraint Specification) - -### Milestone Purpose - -Allow users to intentionally re-activate prior authoritative state without reintroducing contradictions or implicit history dependence. -M3 introduces persistence but does not introduce reasoning over history. - -### M3 Required Invariants - -#### Snapshot Authority - -A snapshot is a complete authoritative state representation.Recalled snapshots MUST behave identically to live state. - -#### Explicit Recall Only - -Prior state MUST NOT affect current state unless recall is explicitly requested. -Passive memory is forbidden. - -#### Replacement Semantics - -Recalling a snapshot replaces active state entirely.No automatic merge is permitted. -Subsequent directives follow M1 update rules. - -#### Temporal Safety - -A recalled snapshot must not resurrect state that the user has explicitly cleared after the snapshot unless the recall explicitly targets that snapshot. - -#### Selective Persistence - -Users must be able to explicitly remove or pin stored snapshots. -Deletion prevents future recall but does not alter already active state. - -#### M3 Undefined Behavior (Deferred Decisions) - -- Snapshot storage medium -- Retention policy defaults -- Snapshot naming conventions -- Automatic snapshot triggers -- Snapshot summarization format -- Multi-snapshot selection UX - -Implementations may vary provided invariants hold. - -## Architectural Guarantee - -Across all milestones: -Authoritative state is derived only from user directives and explicit recall operations. -The system must never infer, reconstruct, or learn state from model outputs or transcript history. - -This addendum preserves interoperability across independent implementations while allowing experimentation in future milestones.