Doc updates

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.
 
 ---
 

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.