Add TUI CLI Bridge Utility

.gitignore

@@ -14,3 +14,9 @@ venv/
 server.log
 tests/phase5_ordeal/mock_db.json
 tests/phase5_ordeal_v2/
+
+# Memory Thread Enterprise Data
+.mt/
+vault.json
+audit_ledger.jsonl
+authority_grants.jsonl

docs/COGNITIVE_GALAXY.md

@@ -0,0 +1,95 @@
+# Cognitive Galaxy Schema: OLAP for Cognition
+
+> "Memory Thread normalizes truth the way data warehouses normalize facts."
+
+## The Core Insight
+
+Most AI memory systems follow a flat pattern: **Flatten → Embed → Forget Source**.
+Memory Thread (MT) follows a structural pattern: **Normalize → Relate → Reason**.
+
+This structure maps directly to **Data Warehouse Galaxy Schemas**, but applied to *cognition* instead of *analytics*.
+
+## The Schema Mapping
+
+| Data Warehouse Concept | Memory Thread Implementation | Description |
+|------------------------|------------------------------|-------------|
+| **Fact Table** | **Immutable Events** | The raw, undisputed reality. Code files, logs, sensor dumps. Append-only, versioned, no opinion. |
+| **Dimension Table** | **Derived Beliefs** | Interpretations, summaries, and meanings derived from facts. Subject to decay, perspective, and contradiction. |
+| **Surrogate Key** | **Entity ID** | The stable identifier linking diverse observations to a single conceptual entity. |
+| **Slowly Changing Dimension (SCD)** | **Memory Decay / Freshness** | How beliefs evolve over time (Type 2 SCD). |
+| **Lineage** | **Provenance Envelope** | The `derived_from` metadata tracking exactly which Fact generated which Belief. |
+| **Rollback** | **Event Replay** | Deterministic reconstruction of state at any point in time. |
+
+## Structural Visualization
+
+```mermaid
+erDiagram
+    FACT_SOURCE ||--o{ EVENT_LOG : generates
+    EVENT_LOG ||--|{ COGNITIVE_JOIN : feeds
+    AGENT_DIMENSION ||--|{ COGNITIVE_JOIN : interprets
+
+    FACT_SOURCE {
+        string uri "file://auth_service.py"
+        string version "v1.2"
+        blob content "Raw Code/Text"
+    }
+
+    EVENT_LOG {
+        uuid event_id
+        timestamp t
+        string payload "The objective reality"
+    }
+
+    AGENT_DIMENSION {
+        string role "Security Auditor"
+        float authority_score "0.95"
+        string context "Security Review 2024"
+    }
+
+    COGNITIVE_JOIN {
+        uuid entity_id
+        string belief "Critical Security Boundary"
+        float confidence
+        string provenance "Derived from Event X by Agent Y"
+    }
+```
+
+## The "Galaxy" Concept
+
+In a Galaxy Schema, multiple Fact Tables share Dimensions. In MT, **Multiple Belief Systems (Dimensions)** coexist over the same **Facts**.
+
+### Example: The "Auth Service" Fact
+
+**FACT:** `src/auth_service.py` (Content hash: `abc1234`)
+
+1.  **Dimension A (Coder Agent):**
+    *   *Belief:* "Handles JWT token parsing."
+    *   *Confidence:* 0.9
+    *   *Action:* Refactor for performance.
+
+2.  **Dimension B (Security Agent):**
+    *   *Belief:* "Legacy OAuth implementation; potential vulnerability."
+    *   *Confidence:* 0.7
+    *   *Action:* Flag for audit.
+
+3.  **Dimension C (Architect Agent):**
+    *   *Belief:* "Core infrastructure component."
+    *   *Authority:* High
+    *   *Action:* Protect from deletion.
+
+**Result:** No conflict. Just different "Cognitive Joins" on the same truth.
+
+## OLAP Operations for Cognition
+
+Because we have this structure, we can perform OLAP-style operations on memory:
+
+*   **SLICE (by Source):** "Show me all beliefs derived from `auth_service.py`."
+*   **DICE (by Authority):** "Show me beliefs about `auth_service.py` held by agents with `Authority > 0.8`."
+*   **DRILL DOWN:** "Show me the raw event log that led to this belief."
+*   **ROLL UP:** "Summarize the system architecture based on all high-confidence beliefs."
+
+## Terminology
+
+*   **Cognitive Galaxy Schema:** The overarching architectural pattern.
+*   **Truth-Normalized Memory:** The data storage strategy (store facts once, reference many).
+*   **Epistemic Star:** A specific cluster of beliefs surrounding a single entity.

docs/PRIME_RULE.md

@@ -0,0 +1,54 @@
+# The Prime Rule: Cognitive Governance
+
+> "MT only persists what can be replayed, audited, and justified without an LLM."
+
+## 1. The Prime Rule (Non-Negotiable)
+
+If something cannot survive deterministic replay, it does not belong in MT core storage.
+Everything else is derived.
+
+## 2. Two Ingestion Classes
+
+MT enforces a strict separation between **Ontology (What Is)** and **Epistemology (What We Know)**.
+
+### Class A: Canonical Truth (Facts)
+
+These are external reality snapshots.
+
+*   **Examples:** Source code, specs, logs, sensor dumps, user messages.
+*   **Properties:** Immutable, Versioned, Content-Addressed, No "Cleaning".
+*   **Constraint:** Must be ingestible without an LLM.
+
+### Class B: Epistemic Artifacts (Beliefs)
+
+These are interpretations, summaries, and conclusions derived from facts.
+
+*   **Examples:** Code summaries, classifications, confidence scores, hypotheses.
+*   **Properties:** Mutable, Decaying, Subjective, Contradictory.
+*   **Constraint:** Must have explicit **Provenance**.
+
+## 3. Forbidden Patterns (Poison Control)
+
+The following must **NEVER** be persisted as Truth (Class A):
+
+1.  **Embeddings as Truth:** Vectors are derived artifacts, not facts.
+2.  **Chain-of-Thought:** Internal reasoning traces are transient runtime noise.
+3.  **Unattributed Beliefs:** "The system thinks X" without an Agent ID and Source ID.
+4.  **Confidence without Source:** A number without a derivation path is meaningless noise.
+
+## 4. Enforcement Policy
+
+The `SecureMemoryClient` enforces these rules at runtime:
+
+| Violation | Action |
+|-----------|--------|
+| Belief stored as Fact | ❌ **Hard Error** |
+| Missing `derived_from` on Belief | ❌ **Hard Error** |
+| Fact with Confidence/Authority | ❌ **Hard Error** |
+| Deprecated `remember()` usage | ⚠️ **Warning + Audit** |
+
+## 5. Self-Observation
+
+MT can ingest its own logs (e.g., `audit_ledger.jsonl`) as **Facts**.
+MT must **never** treat its own previous outputs as canonical truth by default.
+**Self-Observation ≠ Self-Belief.**

docs/enterprise_rbac_design.md

@@ -0,0 +1,86 @@
+# RBAC & Authority Design for Memory Thread Enterprise
+
+## 1. Role Hierarchy & Permissions
+
+We will implement a Role-Based Access Control (RBAC) system defined in a configuration structure (simulating a policy file).
+
+### Roles
+
+| Role | Clearance Level | Description |
+| :--- | :--- | :--- |
+| **GUEST** | 0 | Public access only. Can read `public` namespace. |
+| **EMPLOYEE** | 1 | Standard internal access. Can read/write `team_*` namespaces. |
+| **DEVELOPER** | 2 | Technical access. Can read/write `tech_*`, read `product`. |
+| **RESEARCHER** | 3 | Cross-domain access. Read ALL. Write `research`. |
+| **EXECUTIVE** | 4 | Strategic access. Full Read/Write/Override power. |
+
+### Domains (Namespaces)
+
+*   `public`: Accessible by everyone.
+*   `team_general`: Accessible by Employees+.
+*   `tech_core`: Accessible by Developers, Researchers, Execs.
+*   `finance_secret`: Accessible by Executives only.
+*   `research_lab`: Accessible by Researchers, Execs.
+
+---
+
+## 2. The "Firewall" Logic (Read Access)
+
+When a `recall()` or `chat()` happens, the Firewall checks:
+
+1.  **Direct Namespace Access:** Does user have `READ` permission on the memory's namespace?
+2.  **Clearance Level:** Is the memory tagged with a clearance level higher than the user?
+    *   *Note: In the Core SDK, we store `clearance` in the memory's metadata/payload.*
+
+**Rule:** `IF (User.Roles allows Namespace) AND (User.Clearance >= Memory.Clearance) THEN Access Granted.`
+
+---
+
+## 3. The "Truth Authority" Logic (Write Access)
+
+When a `remember()` happens, we calculate the `authority` (0.0 - 1.0) passed to the Core SDK based on the User's Role and the Domain they are writing to.
+
+**Matrix:**
+
+| User Role | Target Domain | Authority Score | Logic |
+| :--- | :--- | :--- | :--- |
+| **EXECUTIVE** | Any | **0.95** | Strategic override. |
+| **RESEARCHER**| `research_lab` | **0.90** | Expert domain. |
+| **RESEARCHER**| `tech_core` | **0.50** | Observer. |
+| **DEVELOPER** | `tech_core` | **0.90** | Expert domain. |
+| **DEVELOPER** | `finance_secret`| **0.00** | (Write Denied) |
+| **EMPLOYEE** | `team_general` | **0.60** | Standard input. |
+| **GUEST** | `public` | **0.10** | Low trust. |
+
+*   **Conflict Resolution:** If an *Employee* says "Sky is Green" (Auth 0.6) and an *Executive* says "Sky is Blue" (Auth 0.95), the Core SDK's math naturally resolves "Blue" as the truth.
+*   **Decay:** Higher authority memories decay slower (managed by core, but we can influence initial freshness).
+
+---
+
+## 4. Implementation Strategy (No Core Changes)
+
+1.  **`AccessControlService` (New Class):**
+    *   Holds the hardcoded Policy (the matrix above).
+    *   `calculate_write_authority(user, namespace) -> float`
+    *   `can_read(user, memory_namespace, memory_metadata) -> bool`
+
+2.  **`SecureMemoryClient` (Wrapper Class):**
+    *   Wraps `MemoryClient`.
+    *   **Input:** `user_id`, `role`.
+    *   **On `remember(content, namespace)`:**
+        *   Call `AccessControlService` to get authority.
+        *   Inject `clearance_level` into the `metadata` of the memory (Core SDK stores payload/metadata).
+        *   Call `CoreSDK.remember(content, authority=calculated_auth)`.
+    *   **On `recall(query)`:**
+        *   Call `CoreSDK.recall(query)`.
+        *   Iterate results.
+        *   Filter out any memory where `AccessControlService.can_read(...)` is False.
+        *   Return filtered list (or "[REDACTED]" placeholders).
+
+## 5. TUI Integration
+
+*   **New Command:** `/login <role>` (Simulates switching user token).
+*   **Visuals:**
+    *   Display current "Security Clearance" in the footer.
+    *   Show `[REDACTED]` for memories the current user shouldn't see.
+    *   Show "Authority: High/Med/Low" indicators on messages.

memory_thread/models/provenance.py

@@ -0,0 +1,64 @@
+from dataclasses import dataclass, field
+from typing import Optional, Dict
+from datetime import datetime
+import uuid
+
+@dataclass
+class Actor:
+    user_id: str
+    role: str
+    agent_id: Optional[str] = None
+
+    def to_dict(self) -> Dict:
+        return {
+            "user_id": self.user_id,
+            "role": self.role,
+            "agent_id": self.agent_id
+        }
+
+@dataclass
+class Origin:
+    client_id: str
+    session_id: Optional[str] = None
+    machine_id: Optional[str] = None
+
+    def to_dict(self) -> Dict:
+        return {
+            "client_id": self.client_id,
+            "session_id": self.session_id,
+            "machine_id": self.machine_id
+        }
+
+@dataclass
+class Scope:
+    namespace: str
+    domain: Optional[str] = None
+    project_id: Optional[str] = None
+
+    def to_dict(self) -> Dict:
+        return {
+            "namespace": self.namespace,
+            "domain": self.domain,
+            "project_id": self.project_id
+        }
+
+@dataclass
+class ProvenanceEnvelope:
+    """
+    The immutable Identity & Namespace Envelope.
+    Must be embedded in every memory event payload.
+    """
+    event_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: str = field(default_factory=lambda: datetime.utcnow().isoformat())
+    actor: Actor = None
+    origin: Origin = None
+    scope: Scope = None
+
+    def to_dict(self) -> Dict:
+        return {
+            "event_id": self.event_id,
+            "timestamp": self.timestamp,
+            "actor": self.actor.to_dict() if self.actor else None,
+            "origin": self.origin.to_dict() if self.origin else None,
+            "scope": self.scope.to_dict() if self.scope else None
+        }