contextos-memory-runtime 1.0.0rc2__py3-none-any.whl

contextos/cli/dashboard.py

@@ -0,0 +1,174 @@
+"""Terminal dashboard rendering with no untrusted terminal control sequences."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from rich.console import Group, RenderableType
+from rich.table import Table
+from rich.text import Text
+
+_escape = re.compile(r"\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x1b\x07]*(?:\x07|\x1b\\)|.)")
+
+
+def safe(value: object, limit: int = 160, allow_newlines: bool = False) -> str:
+    if value is None:
+        return ""
+    text = _escape.sub("", str(value))
+    if allow_newlines:
+        return "".join(ch for ch in text if ch.isprintable() or ch in ("\n", "\t"))[:limit]
+    return "".join(ch for ch in text if ch.isprintable())[:limit]
+
+
+def _model_kind(model: dict[str, Any]) -> str:
+    if not model["enabled"]:
+        return "unavailable"
+    if model["simulated"]:
+        return "simulation"
+    return "local" if model["local"] else "remote"
+
+
+def render_dashboard(
+    data: dict[str, Any], model: str | None = None, compare: bool = False
+) -> Group:
+    counts = data["memories"]
+    summary = data["summary"]
+    models = summary.get("by_model", {})
+    bases = data.get("context_measurement_bases", [])
+    table = Table(title="ContextOS - Live activity", show_header=False)
+    table.add_column("Metric", style="cyan", overflow="crop")
+    table.add_column("Value", overflow="crop")
+    table.add_row(
+        "Memories",
+        f"{counts['active']} active | {counts['historical']} historical | "
+        f"{counts['expired']} expired",
+    )
+    temporal = data.get("temporal")
+    if temporal:
+        table.add_row(
+            "Temporal",
+            f"{temporal['superseded']} superseded | {temporal['contradicted']} contradicted",
+        )
+    table.add_row(
+        "Connectors",
+        ", ".join(
+            f"{safe(c['id'])}: {safe(c['status'])} ({c.get('tracked_items', 0)} tracked)"
+            for c in data["connectors"]
+        ) or "none registered",
+    )
+    mcp = data.get("mcp")
+    if mcp:
+        table.add_row(
+            "MCP config", "disabled" if not mcp["enabled"] else
+            f"configured {safe(mcp['transport'])} | read={mcp['read']} | write={mcp['write']}"
+        )
+    table.add_row(
+        "Models",
+        ", ".join(
+            f"{safe(item['model'], 32)} ({_model_kind(item)})"
+            for item in data.get("models", [])
+        ) or "none discoverable",
+    )
+    table.add_row("Successful invocations", str(summary["total_invocations"]))
+    error_count = sum(row.get("errors", 0) for row in data.get("provider_models", []))
+    table.add_row("Recorded errors", str(error_count))
+    if (model or len(models) == 1) and len(bases) == 1 and bases[0]["source"] != "unknown":
+        table.add_row(
+            "Context basis",
+            f"{safe(bases[0]['source'])} | {safe(bases[0]['tokenizer'])}",
+        )
+        table.add_row("Context avoided", f"{summary['total_tokens_avoided']:,} context tokens")
+        table.add_row("Average reduction", f"{summary['average_reduction_ratio']:.1%} (arithmetic)")
+        table.add_row(
+            "Weighted reduction",
+            f"{summary['weighted_reduction_ratio']:.1%} (candidate-token weighted)",
+        )
+    elif models:
+        table.add_row("Reduction", "Select --model; a single known context-token basis is required")
+    else:
+        table.add_row("Reduction", "No measured invocations")
+    activity = Table(title="Recent invocations - metadata only")
+    for name in (
+        "Time", "Model", "Status", "Preflight", "Provider input", "Candidate -> compiled",
+        "Lex/Dense/Selected", "Context source", "Avoided", "Graph", "Retrieve", "Compile",
+        "Provider",
+    ):
+        activity.add_column(name, overflow="crop")
+    for row in data["recent"]:
+        activity.add_row(
+            safe(row["timestamp"], 19), safe(row["model"], 32), safe(row["status"], 20),
+            str(row["preflight_input_tokens"]),
+            f"{row['provider_input_tokens']} ["
+            f"{safe(row.get('provider_measurement_label', 'UNKNOWN'), 20)}]",
+            f"{row['candidate_context_tokens']} -> {row['compiled_context_tokens']}",
+            f"{row.get('lexical_candidate_count', 0)}/"
+            f"{row.get('dense_candidate_count', 0)}/{row.get('selected_memory_count', 0)}",
+            safe(row.get("context_measurement_label", "UNKNOWN"), 20),
+            str(row["context_tokens_avoided"]), str(row["graph_expanded_count"]),
+            f"{row['retrieval_ms']:.1f} ms", f"{row['compilation_ms']:.1f} ms",
+            f"{row.get('provider_ms', 0):.1f} ms",
+        )
+    if not data["recent"]:
+        activity.add_row("No activity", *([""] * 12))
+    sections: list[RenderableType] = [table, activity]
+    graph = data.get("graph")
+    if graph:
+        graph_table = Table(title="Graph projection [MEASURED]")
+        graph_table.add_column("Nodes")
+        graph_table.add_column("Edges")
+        graph_table.add_column("Supports")
+        graph_table.add_column("State")
+        graph_table.add_row(str(graph["nodes"]), str(graph["edges"]), str(graph["supports"]),
+                            "dirty" if graph["dirty"] else "clean")
+        sections.append(graph_table)
+    breakdown = data.get("provider_models", [])
+    if compare and breakdown:
+        models_table = Table(title="Provider + model (successful invocations by context basis)")
+        for name in (
+            "Provider", "Model", "Runs", "Errors", "Candidate", "Compiled", "Avoided",
+            "Reduction", "Basis",
+        ):
+            models_table.add_column(name, overflow="crop")
+        for row in breakdown[:50]:
+            ratio = row["weighted_reduction_ratio"]
+            models_table.add_row(
+                Text(safe(row["provider"])), Text(safe(row["model"])),
+                str(row["invocations"]), str(row["errors"]),
+                str(row["candidate_context_tokens"]), str(row["compiled_context_tokens"]),
+                str(row["context_tokens_avoided"]),
+                f"{ratio:.1%}" if ratio is not None else "UNKNOWN",
+                Text(
+                    safe(row["context_measurement_source"])
+                    + " / "
+                    + safe(row["context_tokenizer"])
+                ),
+            )
+        sections.append(models_table)
+    if (
+        len(breakdown) == 1
+        and breakdown[0]["invocations"] > 0
+        and breakdown[0]["context_measurement_source"] != "unknown"
+    ):
+        row = breakdown[0]
+        candidate = row["candidate_context_tokens"]
+        compiled = row["compiled_context_tokens"]
+        avoided = row["context_tokens_avoided"]
+        maximum = max(candidate, compiled, avoided, 1)
+        bars = Table(title="[MEASURED] Context tokens, one tokenizer basis")
+        bars.add_column("Stage")
+        bars.add_column("Scale")
+        bars.add_column("Tokens", justify="right")
+        for label, value in (
+            ("Candidate", candidate), ("Compiled", compiled), ("Avoided", avoided)
+        ):
+            bars.add_row(label, "#" * round(24 * value / maximum), f"{value:,}")
+        sections.append(bars)
+    sections.append(
+        Text(
+            "Context and preflight counts use the recorded target tokenizer or approximation. "
+            "Provider usage is separate; no cross-tokenizer totals are shown.",
+            style="dim",
+        )
+    )
+    return Group(*sections)

contextos/cli/formatters.py

@@ -0,0 +1,299 @@
+"""Rich output formatters for the ContextOS CLI.
+
+Centralizes all terminal formatting so CLI commands stay clean.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from contextos.cli.dashboard import safe
+
+from contextos.core.enums import MemoryStatus, PrivacyLevel
+from contextos.core.models import (
+    CompiledContext,
+    IngestResult,
+    Memory,
+    RetrievalResult,
+    ScoredMemory,
+    SystemStatus,
+    TokenStats,
+)
+
+console = Console()
+error_console = Console(stderr=True)
+
+
+# --- Status Colors ---
+
+STATUS_COLORS: dict[MemoryStatus, str] = {
+    MemoryStatus.ACTIVE: "green",
+    MemoryStatus.CANDIDATE: "yellow",
+    MemoryStatus.SUPERSEDED: "dim",
+    MemoryStatus.CONTRADICTED: "red",
+    MemoryStatus.EXPIRED: "dim yellow",
+    MemoryStatus.HISTORICAL: "dim",
+    MemoryStatus.DELETED: "dim red",
+    MemoryStatus.PURGED: "dim red",
+    MemoryStatus.MERGED: "dim cyan",
+}
+
+PRIVACY_COLORS: dict[PrivacyLevel, str] = {
+    PrivacyLevel.PUBLIC: "green",
+    PrivacyLevel.PERSONAL: "blue",
+    PrivacyLevel.SENSITIVE: "yellow",
+    PrivacyLevel.RESTRICTED: "red",
+}
+
+
+def format_status(status: SystemStatus) -> None:
+    """Print system status."""
+    table = Table(title="ContextOS Status", show_header=False, box=None, padding=(0, 2))
+    table.add_column("Key", style="bold cyan")
+    table.add_column("Value")
+
+    running_text = Text("[OK] Running", style="bold green") if status.daemon_running else Text("[X] Stopped", style="bold red")
+    table.add_row("Status", running_text)
+    table.add_row("PID", str(status.pid or "-"))
+    table.add_row("Uptime", _format_duration(status.uptime_seconds))
+    table.add_row("", "")
+    table.add_row("Memories", f"{status.active_memories} active / {status.total_memories} total")
+    table.add_row("Events", str(status.total_events))
+    table.add_row("", "")
+    table.add_row("Embedding Model", status.embedding_model or "-")
+    table.add_row("Vector Index", f"{status.vector_index_size} vectors")
+    table.add_row("BM25 Index", f"{status.bm25_index_size} documents")
+    table.add_row("Database Size", _format_bytes(status.database_size_bytes))
+    table.add_row("Data Directory", status.data_directory)
+
+    console.print(table)
+
+
+def format_stats(stats: TokenStats) -> None:
+    """Print token statistics."""
+    table = Table(title="Token Statistics", show_header=False, box=None, padding=(0, 2))
+    table.add_column("Metric", style="bold cyan")
+    table.add_column("Value", justify="right")
+
+    table.add_row("Total Tokens Stored", f"{stats.total_tokens_stored:,}")
+    table.add_row("Tokens Per Memory", f"{stats.tokens_per_memory:.1f}")
+    table.add_row("", "")
+    table.add_row("Total Compilations", f"{stats.total_compilations:,}")
+    table.add_row("Total Tokens Compiled", f"{stats.total_tokens_compiled:,}")
+    table.add_row("Total Tokens Saved", f"{stats.total_tokens_saved:,}")
+    table.add_row("Avg Compression Ratio", f"{stats.average_compression_ratio:.1%}")
+
+    console.print(table)
+
+
+def format_memory(memory: Memory, detailed: bool = False) -> None:
+    """Print a single memory."""
+    status_color = STATUS_COLORS.get(memory.status, "white")
+
+    header = f"[bold]{memory.type.value.upper()}[/bold] | "
+    header += f"[{status_color}]{memory.status.value}[/{status_color}]"
+    header += f" | confidence: {memory.confidence:.0%}"
+    header += f" | importance: {memory.importance:.0%}"
+
+    panel = Panel(
+        Text(safe(memory.content, 10_000)),
+        title=header,
+        subtitle=f"ID: {str(memory.id)[:8]}... | {memory.token_count} tokens | {memory.created_at.strftime('%Y-%m-%d %H:%M')}",
+        border_style=status_color,
+        padding=(0, 1),
+    )
+    console.print(panel)
+
+    if detailed:
+        detail_table = Table(show_header=False, box=None, padding=(0, 2))
+        detail_table.add_column("Key", style="dim")
+        detail_table.add_column("Value")
+
+        detail_table.add_row("Full ID", str(memory.id))
+        detail_table.add_row("Source", Text(safe(f"{memory.source_type} ({memory.source_uri or ''})")))
+        detail_table.add_row("Privacy", Text(memory.privacy_level.value, style=PRIVACY_COLORS.get(memory.privacy_level, "white")))
+        detail_table.add_row("Tags", Text(safe(", ".join(memory.tags) if memory.tags else "-")))
+        detail_table.add_row("Access Count", str(memory.access_count))
+        detail_table.add_row("Last Accessed", memory.last_accessed_at.strftime('%Y-%m-%d %H:%M') if memory.last_accessed_at else "-")
+        detail_table.add_row("Version", str(memory.version))
+        if memory.expires_at:
+            detail_table.add_row("Expires", memory.expires_at.strftime('%Y-%m-%d %H:%M'))
+        if memory.superseded_by:
+            detail_table.add_row("Superseded By", str(memory.superseded_by)[:8] + "...")
+        if memory.supersedes:
+            detail_table.add_row("Supersedes", str(memory.supersedes)[:8] + "...")
+
+        console.print(detail_table)
+
+
+def format_memory_list(memories: list[Memory]) -> None:
+    """Print a list of memories as a table."""
+    if not memories:
+        console.print("[dim]No memories found.[/dim]")
+        return
+
+    table = Table(title=f"{len(memories)} Memories")
+    table.add_column("ID", style="dim", width=10)
+    table.add_column("Content", max_width=60)
+    table.add_column("Type", width=12)
+    table.add_column("Status", width=12)
+    table.add_column("Conf.", width=6, justify="right")
+    table.add_column("Tokens", width=7, justify="right")
+    table.add_column("Created", width=12)
+
+    for mem in memories:
+        status_color = STATUS_COLORS.get(mem.status, "white")
+        content_preview = safe(mem.content, 57)
+
+        table.add_row(
+            str(mem.id)[:8] + "...",
+            Text(content_preview),
+            mem.type.value,
+            Text(mem.status.value, style=status_color),
+            f"{mem.confidence:.0%}",
+            str(mem.token_count),
+            mem.created_at.strftime("%Y-%m-%d"),
+        )
+
+    console.print(table)
+
+
+def format_ingest_result(result: IngestResult) -> None:
+    """Print ingestion result."""
+    if result.memories_created:
+        console.print(f"[green][OK][/green] Created {len(result.memories_created)} memor{'y' if len(result.memories_created) == 1 else 'ies'}")
+        for mid in result.memories_created:
+            console.print(f"  [dim]{str(mid)[:8]}...[/dim]")
+
+    if result.memories_merged:
+        console.print(f"[cyan][MERGED][/cyan] Merged into {len(result.memories_merged)} existing memor{'y' if len(result.memories_merged) == 1 else 'ies'}")
+
+    if result.secrets_detected:
+        if result.secrets_redacted:
+            console.print("[yellow][!] Secrets detected and redacted[/yellow]")
+        else:
+            console.print("[yellow][!] Secrets detected[/yellow]")
+
+    for warning in result.warnings:
+            console.print(f"[yellow][!] {warning}[/yellow]")
+
+
+def format_retrieval_result(result: RetrievalResult, show_trace: bool = False) -> None:
+    """Print retrieval results."""
+    if not result.memories:
+        console.print("[dim]No memories found.[/dim]")
+        return
+
+    console.print(f"\nRetrieved {len(result.memories)} memories for:", Text(safe(result.query)))
+
+    for i, sm in enumerate(result.memories, 1):
+        score_text = f"score: {sm.final_score:.4f}"
+        if sm.vector_score is not None:
+            score_text += f" (vec: {sm.vector_score:.3f}"
+        if sm.bm25_score is not None:
+            score_text += f", bm25: {sm.bm25_score:.3f}"
+        if sm.vector_score is not None or sm.bm25_score is not None:
+            score_text += ")"
+
+        status_color = STATUS_COLORS.get(sm.memory.status, "white")
+        console.print(
+            Text(f"  {i}. {safe(sm.memory.content, 10_000)}")
+        )
+        console.print(f"     [dim]{score_text} | {sm.memory.type.value} | {sm.memory.token_count} tokens[/dim]")
+
+    if show_trace:
+        console.print("\n[bold]Pipeline Trace[/bold]")
+        trace_table = Table(box=None, padding=(0, 1))
+        trace_table.add_column("Stage", style="cyan")
+        trace_table.add_column("In", justify="right")
+        trace_table.add_column("Out", justify="right")
+        trace_table.add_column("Latency", justify="right")
+
+        for stage in result.trace.stages:
+            trace_table.add_row(
+                stage.stage_name,
+                str(stage.input_count),
+                str(stage.output_count),
+                f"{stage.latency_ms:.1f}ms",
+            )
+
+        trace_table.add_row(
+            "[bold]Total[/bold]", "", str(result.trace.total_results),
+            f"[bold]{result.trace.total_latency_ms:.1f}ms[/bold]",
+        )
+        console.print(trace_table)
+
+
+def format_compiled_context(compiled: CompiledContext, show_context: bool = False) -> None:
+    """Print compilation result."""
+    console.print("\nContext Compilation for:", Text(safe(compiled.query)))
+
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column("Metric", style="cyan")
+    table.add_column("Value", justify="right")
+
+    table.add_row("Budget", f"{compiled.budget:,} tokens")
+    table.add_row("Compiled", f"{compiled.total_tokens:,} tokens")
+    table.add_row("Compression", f"{compiled.compression_ratio:.1%}")
+    table.add_row("Memories Included", f"{compiled.memories_included} / {compiled.memories_considered}")
+
+    console.print(table)
+
+    if show_context:
+        console.print("\n[bold]Compiled Context:[/bold]")
+        console.print(Panel(Text(safe(compiled.context_text, 50_000)), border_style="green"))
+
+
+def format_doctor_results(results: dict) -> None:
+    """Print doctor diagnostic results."""
+    console.print(f"\n[bold]ContextOS Doctor[/bold] (v{results.get('version', '?')})\n")
+
+    for check_name, check_result in results.get("checks", {}).items():
+        ok = check_result.get("ok", False)
+        icon = "[green][OK][/green]" if ok else "[red][X][/red]"
+        console.print(f"  {icon} {check_name}")
+
+        for key, value in check_result.items():
+            if key == "ok":
+                continue
+            if key == "warnings" and value:
+                for w in value:
+                    console.print(f"      [yellow][!] {w}[/yellow]")
+            elif key != "warnings":
+                console.print(f"      [dim]{key}: {value}[/dim]")
+
+    overall = results.get("overall", False)
+    console.print()
+    if overall:
+        console.print("[bold green]All checks passed.[/bold green]")
+    else:
+        console.print("[bold red]Some checks failed.[/bold red]")
+
+
+# --- Utilities ---
+
+
+def _format_duration(seconds: float) -> str:
+    """Format seconds into human-readable duration."""
+    if seconds < 60:
+        return f"{seconds:.0f}s"
+    minutes = int(seconds // 60)
+    secs = int(seconds % 60)
+    if minutes < 60:
+        return f"{minutes}m {secs}s"
+    hours = minutes // 60
+    mins = minutes % 60
+    return f"{hours}h {mins}m"
+
+
+def _format_bytes(bytes_val: int) -> str:
+    """Format bytes into human-readable size."""
+    for unit in ("B", "KB", "MB", "GB"):
+        if bytes_val < 1024:
+            return f"{bytes_val:.1f} {unit}"
+        bytes_val /= 1024  # type: ignore
+    return f"{bytes_val:.1f} TB"

contextos/config/__init__.py

@@ -0,0 +1 @@
+"""Config package for ContextOS."""

contextos/config/settings.py

@@ -0,0 +1,160 @@
+"""Configuration management for ContextOS.
+
+Uses Pydantic Settings for config validation with TOML file support.
+Config is loaded from ~/.config/contextos/config.toml (XDG-compliant).
+"""
+
+from __future__ import annotations
+
+import platform
+import re
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field, field_validator, model_validator
+from pydantic_settings import BaseSettings
+
+
+def _default_data_dir() -> Path:
+    """Platform-appropriate default data directory."""
+    system = platform.system()
+    if system == "Windows":
+        base = Path.home() / "AppData" / "Local" / "contextos"
+    elif system == "Darwin":
+        base = Path.home() / "Library" / "Application Support" / "contextos"
+    else:
+        # Linux / other Unix — XDG
+        xdg_data = Path.home() / ".local" / "share"
+        base = xdg_data / "contextos"
+    return base
+
+
+def _default_config_dir() -> Path:
+    """Platform-appropriate default config directory."""
+    system = platform.system()
+    if system == "Windows":
+        return Path.home() / "AppData" / "Local" / "contextos"
+    elif system == "Darwin":
+        return Path.home() / "Library" / "Application Support" / "contextos"
+    else:
+        xdg_config = Path.home() / ".config"
+        return xdg_config / "contextos"
+
+
+class DaemonConfig(BaseSettings):
+    """Daemon process configuration."""
+    host: str = "127.0.0.1"
+    port: int = 52411
+    log_level: str = "info"
+    data_dir: Path = Field(default_factory=_default_data_dir)
+    config_dir: Path = Field(default_factory=_default_config_dir)
+    readiness_timeout: float = Field(default=30.0, ge=1, le=300, allow_inf_nan=False)
+    lock_timeout: float = Field(default=45.0, ge=1, le=600, allow_inf_nan=False)
+
+    @model_validator(mode="after")
+    def bounded_startup(self):
+        if self.lock_timeout <= self.readiness_timeout + 5:
+            raise ValueError("lock_timeout must exceed readiness_timeout by more than 5 seconds")
+        return self
+
+    @field_validator("host")
+    @classmethod
+    def loopback_only(cls, value: str) -> str:
+        if value not in {"127.0.0.1", "::1", "localhost"}:
+            raise ValueError("ContextOS daemon must bind to loopback")
+        return value
+
+
+class EmbeddingConfig(BaseSettings):
+    """Embedding model configuration."""
+    model: str = "deterministic"
+    device: str = "cpu"
+    batch_size: int = 32
+
+
+class TokenCounterConfig(BaseSettings):
+    """Offline approximation by default; exact tokenizers require explicit setup."""
+
+    encoding: Literal["deterministic", "cl100k_base", "o200k_base"] = "deterministic"
+
+
+class RetrievalConfig(BaseSettings):
+    """Default retrieval parameters."""
+    vector_top_k: int = 20
+    bm25_top_k: int = 20
+    rrf_k: int = 60
+    default_budget: int = 4000
+
+
+class PrivacyConfig(BaseSettings):
+    """Privacy and security configuration."""
+    secret_detection: str = "strict"  # "strict", "redact", "warn"
+    default_privacy_level: str = "personal"
+    entropy_threshold: float = 4.5
+
+
+class LLMConfig(BaseSettings):
+    """LLM provider configuration."""
+    provider: str = "none"
+    model: str = ""
+    api_key_env: str = ""
+
+
+class MCPConfig(BaseSettings):
+    """Local MCP exposure; writes and destructive operations fail closed."""
+
+    enabled: bool = False
+    transport: str = "stdio"
+    allow_read: bool = True
+    allow_write: bool = False
+    allow_delete: bool = False
+    allow_telemetry: bool = True
+    max_input_chars: int = Field(default=10_000, ge=1, le=100_000)
+    max_search_results: int = Field(default=25, ge=1, le=200)
+    max_history_entries: int = Field(default=50, ge=1, le=200)
+    max_graph_nodes: int = Field(default=100, ge=1, le=1_000)
+    max_graph_edges: int = Field(default=250, ge=1, le=2_500)
+    max_compilation_tokens: int = Field(default=8_000, ge=1, le=32_000)
+
+
+class ConnectorConfig(BaseSettings):
+    """Explicit local sources only; no discovered paths or credentials."""
+
+    local_files: dict[str, list[Path]] = Field(default_factory=dict)
+    json_imports: dict[str, Path] = Field(default_factory=dict)
+
+    @field_validator("local_files", "json_imports")
+    @classmethod
+    def valid_ids(cls, value):
+        if len(value) > 20 or any(not re.fullmatch(r"[A-Za-z0-9_-]{1,64}", key) for key in value):
+            raise ValueError("Connector IDs must be short alphanumeric identifiers")
+        return value
+
+
+class Settings(BaseSettings):
+    """Root settings for ContextOS."""
+    daemon: DaemonConfig = Field(default_factory=DaemonConfig)
+    embedding: EmbeddingConfig = Field(default_factory=EmbeddingConfig)
+    token_counter: TokenCounterConfig = Field(default_factory=TokenCounterConfig)
+    retrieval: RetrievalConfig = Field(default_factory=RetrievalConfig)
+    privacy: PrivacyConfig = Field(default_factory=PrivacyConfig)
+    llm: LLMConfig = Field(default_factory=LLMConfig)
+    mcp: MCPConfig = Field(default_factory=MCPConfig)
+    connectors: ConnectorConfig = Field(default_factory=ConnectorConfig)
+
+
+def load_settings() -> Settings:
+    """Load settings from config file, falling back to defaults."""
+    config_dir = _default_config_dir()
+    config_file = config_dir / "config.toml"
+
+    if config_file.exists():
+        try:
+            import tomllib
+            with open(config_file, "rb") as f:
+                data = tomllib.load(f)
+            return Settings(**data)
+        except Exception as exc:
+            raise ValueError(f"Invalid ContextOS configuration: {config_file}") from exc
+
+    return Settings()

contextos/connectors/__init__.py

@@ -0,0 +1,6 @@
+"""Credential-free local activity connectors for ContextOS Phase 11."""
+
+from contextos.connectors.manager import ConnectorManager
+from contextos.connectors.models import ConnectorItem, ConnectorSyncResult, RetentionPolicy
+
+__all__ = ["ConnectorItem", "ConnectorManager", "ConnectorSyncResult", "RetentionPolicy"]

contextos/connectors/fake.py

@@ -0,0 +1,11 @@
+"""Deterministic offline connector used by tests and benchmarks."""
+from __future__ import annotations
+from contextos.connectors.models import ConnectorItem
+class FakeConnector:
+    source_type="fake"
+    def __init__(self,connector_id:str,items:list[ConnectorItem])->None:self.connector_id,self.items=connector_id,items;self.failure:Exception|None=None
+    async def health(self)->bool:return self.failure is None
+    async def close(self)->None:pass
+    async def scan(self,cursor:str|None)->tuple[list[ConnectorItem],str|None]:
+        if self.failure: raise self.failure
+        return list(self.items),str(len(self.items))