arkaos 2.28.0 → 2.31.0

package/VERSION

@@ -1 +1 @@
-2.28.0
+2.31.0

package/arka/skills/dreams/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: arka-dreams
+description: >
+  Surface for Dreaming v2 — the nightly cognitive consolidation engine
+  shipped in PR8 v2.30.0. Lists insights ArkaOS surfaced from the user's
+  recent vault activity and session digests, optionally promotes one
+  into a tracked task via /pm. The cognitive layer's user-facing surface.
+allowed-tools: [Read, Bash, Agent]
+---
+
+# /arka dreams — what ArkaOS noticed last night
+
+> The motor without an ignition is a research demo. This skill is the
+> ignition: it reads what Dreaming v2 wrote to the vault and surfaces
+> it so the user can act.
+
+## Subcommands
+
+| Command | What it does |
+| --- | --- |
+| `/arka dreams` | List insights surfaced today (UTC-day, generous tolerance). |
+| `/arka dreams --since 7` | Last N days of insights, newest first. |
+| `/arka dreams --all` | Every insight ever surfaced (since the vault was indexed). |
+| `/arka dreams promote <id>` | Convert an insight into a sprint backlog item. Delegates to `/pm` (Carolina). |
+| `/arka dreams trigger` | Manually run a Dreaming pass *right now* instead of waiting for 02:00. Useful for end-to-end smoke tests after an install or a model swap. |
+
+## How it works
+
+```
+1. Read insight files from ${VAULT_PATH}/Projects/ArkaOS/Dreams/*.md
+2. Parse plugin-compat frontmatter (type: arkaos-insight)
+3. Filter by --since window (default: today)
+4. Render compact list:
+       [date] [confidence] [title]
+                sources: [[file1]], [[file2]]
+                body: <first 200 chars>
+5. Wait for follow-up: promote / discard / open
+```
+
+Insights are produced by `core/cognition/dreaming.py` running locally
+on a schedule defined in `~/.arkaos/schedules.yaml` (default 02:00 user
+time). The engine is backend-agnostic per the 2026-05-13 Conclave
+Phase 4 correction — uses Claude Code by default, Ollama if the user
+opts in via `cognitiveBackend: ollama` in `profile.json`.
+
+## Cost & budget
+
+Dreaming runs **once per night**, costs depend on the configured
+backend:
+
+- **Claude Code backend (default):** consumes the user's existing
+  Claude session tokens (~3-10k tokens / night per 20 clusters).
+- **Ollama backend (opt-in):** zero token cost, ~15-30 min compute
+  on the user's machine.
+- **Anthropic API backend:** per-call billing per the user's API key.
+
+`/arka costs` surfaces the spend if Dreaming used a metered backend.
+Variable Reward driver is the surprise of *what* ArkaOS surfaces, not
+the cost of *running* the engine.
+
+## Boundaries
+
+- **Read-only over the vault.** This skill never writes to or deletes
+  vault notes. Dreaming v2 writes, this skill only reads.
+- **Promote handoff stays explicit.** `/arka dreams promote <id>`
+  spawns a /pm backlog item — it does not act on the insight itself.
+  The user is always the decision-maker.
+- **No auto-dismiss.** Even insights the user ignores stay in the
+  vault for future retrieval. Build the data moat.
+
+## Cross-references
+
+- Engine: `core/cognition/dreaming.py` (PR8 v2.30.0)
+- Backend abstraction: `core/runtime/llm_provider.py`
+- Strategy: [[2026-05-13-arkaos-local-personal-agi]]
+- Memory: [[project_arkaos_local_personal_agi]]
+- Companion skill: `/arka research` (one-off research) — different
+  primitive, similar fan-out pattern

package/config/cognition/schedules.yaml

@@ -6,6 +6,12 @@
 schedules:
   dreaming:
     command: dreaming
+    # PR9 v2.31.0: Dreaming v2 is a Python engine (see core.cognition.dreaming).
+    # The legacy prompt_file path is kept as fallback for installs that
+    # still ship the older Claude-CLI-prompt dreaming task. python_module
+    # wins when both are present.
+    python_module: "core.cognition.dreaming"
+    module_args: ["run"]
     prompt_file: "~/.arkaos/cognition/prompts/dreaming.md"
     time: "02:00"
     timezone: auto

package/core/cognition/dreaming.py

@@ -0,0 +1,368 @@
+"""Dreaming v2 — nightly cognitive consolidation that surfaces insights.
+
+Runs (manually or on a schedule) over the user's recent vault notes and
+session digests, groups related content into clusters, asks the
+configured LLM (Claude Code by default, Ollama / Anthropic / OpenAI on
+opt-in) for one observation per cluster, and applies a second LLM pass
+that filters noise. Accepted insights are written to the Obsidian vault
+in a plugin-compat shape that a future mobile reader can consume.
+
+Backend-agnostic by design — completion goes through
+``core.runtime.llm_provider.get_llm_provider()``. The same engine works
+with any registered provider; the user picks in ``profile.json``.
+
+See PR8 v2.30.0 and the 2026-05-13 Conclave Phase 4 correction (multi-
+backend, not Ollama-only) for the architectural rationale.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+from core.runtime.llm_provider import LLMResponse, LLMUnavailable, get_llm_provider
+from core.runtime.path_resolver import ProfileMissingError, load_profile
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_VAULT_LOOKBACK_DAYS = 7
+_DEFAULT_MIN_CLUSTER_SIZE = 3
+_DEFAULT_MAX_CLUSTERS = 12
+_DEFAULT_MAX_INSIGHTS = 5
+_MIN_CHUNK_CHARS = 80
+_MAX_CHUNK_CHARS = 1200
+_CRITIC_PASS_TOKEN = "VALUABLE"
+
+
+@dataclass
+class Insight:
+    """One accepted insight ready for vault write."""
+
+    title: str
+    body: str
+    confidence: str  # "high" | "medium" | "low"
+    sources: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+
+    def to_frontmatter(self, date_str: str) -> dict:
+        return {
+            "type": "arkaos-insight",
+            "date": date_str,
+            "status": "surfaced",
+            "confidence": self.confidence,
+            "sources": [f"[[{s}]]" for s in self.sources],
+            "tags": ["arkaos-dream", *self.tags],
+            "plugin_compat_version": "1.0",
+        }
+
+
+@dataclass
+class Chunk:
+    """A piece of source text fed into clustering."""
+
+    source_path: str
+    text: str
+    kind: str  # "vault" | "session-digest" | "capture"
+
+
+@dataclass
+class Cluster:
+    """A group of related chunks."""
+
+    topic: str
+    chunks: list[Chunk] = field(default_factory=list)
+
+
+class Dreaming:
+    """Engine that produces nightly insights from recent activity."""
+
+    def __init__(
+        self,
+        vault_path: Path,
+        output_dir: Path,
+        digest_dir: Path | None = None,
+        lookback_days: int = _DEFAULT_VAULT_LOOKBACK_DAYS,
+        max_insights: int = _DEFAULT_MAX_INSIGHTS,
+        provider=None,
+    ) -> None:
+        self._vault = Path(vault_path)
+        self._output_dir = Path(output_dir)
+        self._digest_dir = Path(digest_dir) if digest_dir else None
+        self._lookback_days = lookback_days
+        self._max_insights = max_insights
+        self._provider = provider or get_llm_provider()
+
+    @classmethod
+    def from_profile(cls, output_subpath: str = "Projects/ArkaOS/Dreams") -> "Dreaming":
+        """Construct a Dreaming engine from the user's profile.json."""
+        profile = load_profile()
+        vault = Path(profile.vault_path)
+        output = vault / output_subpath
+        digests = Path.home() / ".arkaos" / "session-digests"
+        return cls(vault_path=vault, output_dir=output, digest_dir=digests)
+
+    def run(self, dry_run: bool = False) -> list[Insight]:
+        """Execute one dreaming pass. Returns accepted insights."""
+        chunks = self._collect_chunks()
+        if not chunks:
+            logger.info("Dreaming: no chunks to process — quiet night")
+            return []
+
+        clusters = self._cluster(chunks)
+        if not clusters:
+            logger.info("Dreaming: no clusters formed — quiet night")
+            return []
+
+        accepted: list[Insight] = []
+        for cluster in clusters[: _DEFAULT_MAX_CLUSTERS]:
+            insight = self._draft_insight(cluster)
+            if insight is None:
+                continue
+            if not self._critic_accepts(insight):
+                continue
+            accepted.append(insight)
+            if len(accepted) >= self._max_insights:
+                break
+
+        if not dry_run:
+            for insight in accepted:
+                self._write_insight(insight)
+        return accepted
+
+    def _collect_chunks(self) -> list[Chunk]:
+        chunks: list[Chunk] = []
+        chunks.extend(self._collect_vault_chunks())
+        chunks.extend(self._collect_digest_chunks())
+        return chunks
+
+    def _collect_vault_chunks(self) -> list[Chunk]:
+        if not self._vault.is_dir():
+            return []
+        cutoff = datetime.now(timezone.utc).timestamp() - self._lookback_days * 86400
+        out: list[Chunk] = []
+        for md in self._vault.rglob("*.md"):
+            try:
+                if md.stat().st_mtime < cutoff:
+                    continue
+                text = md.read_text(encoding="utf-8", errors="ignore")
+            except OSError:
+                continue
+            relative = str(md.relative_to(self._vault))
+            for piece in _split_for_clustering(text):
+                out.append(Chunk(source_path=relative, text=piece, kind="vault"))
+        return out
+
+    def _collect_digest_chunks(self) -> list[Chunk]:
+        if not self._digest_dir or not self._digest_dir.is_dir():
+            return []
+        cutoff = datetime.now(timezone.utc).timestamp() - self._lookback_days * 86400
+        out: list[Chunk] = []
+        for f in self._digest_dir.glob("*.md"):
+            try:
+                if f.stat().st_mtime < cutoff:
+                    continue
+                text = f.read_text(encoding="utf-8", errors="ignore")
+            except OSError:
+                continue
+            for piece in _split_for_clustering(text):
+                out.append(Chunk(source_path=f.name, text=piece, kind="session-digest"))
+        return out
+
+    def _cluster(self, chunks: list[Chunk]) -> list[Cluster]:
+        """Lightweight clustering by shared CamelCase / path tokens.
+
+        Embedding-based clustering is the obvious upgrade but requires
+        fastembed to be installed and warmed. The token-overlap baseline
+        ships value today and the embedding path is a follow-up.
+        """
+        buckets: dict[str, list[Chunk]] = {}
+        for chunk in chunks:
+            for token in _extract_topic_tokens(chunk.text):
+                buckets.setdefault(token, []).append(chunk)
+        clusters: list[Cluster] = []
+        seen_keys: set[str] = set()
+        for topic, items in sorted(buckets.items(), key=lambda kv: -len(kv[1])):
+            if len(items) < _DEFAULT_MIN_CLUSTER_SIZE:
+                continue
+            key = "|".join(sorted({c.source_path for c in items}))
+            if key in seen_keys:
+                continue
+            seen_keys.add(key)
+            clusters.append(Cluster(topic=topic, chunks=items))
+        return clusters
+
+    def _draft_insight(self, cluster: Cluster) -> Insight | None:
+        prompt = _build_insight_prompt(cluster)
+        try:
+            response = self._provider.complete(prompt, max_tokens=400)
+        except LLMUnavailable as exc:
+            logger.warning("Dreaming: provider unavailable, skipping cluster (%s)", exc)
+            return None
+        return _parse_insight(response, cluster)
+
+    def _critic_accepts(self, insight: Insight) -> bool:
+        prompt = _build_critic_prompt(insight)
+        try:
+            response = self._provider.complete(prompt, max_tokens=20)
+        except LLMUnavailable:
+            return False  # safer to reject than to publish unchecked
+        return _CRITIC_PASS_TOKEN in response.text.upper()
+
+    def _write_insight(self, insight: Insight) -> Path:
+        self._output_dir.mkdir(parents=True, exist_ok=True)
+        date_str = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+        slug = _slugify(insight.title) or "insight"
+        path = self._output_dir / f"{date_str}-{slug}.md"
+        frontmatter = insight.to_frontmatter(date_str)
+        path.write_text(_render_markdown(frontmatter, insight), encoding="utf-8")
+        return path
+
+
+def _split_for_clustering(text: str) -> list[str]:
+    pieces = re.split(r"\n\s*\n", text)
+    out: list[str] = []
+    for p in pieces:
+        p = p.strip()
+        if len(p) < _MIN_CHUNK_CHARS:
+            continue
+        out.append(p[:_MAX_CHUNK_CHARS])
+    return out
+
+
+def _extract_topic_tokens(text: str) -> list[str]:
+    tokens = re.findall(r"\b([A-Z][a-zA-Z0-9_-]{3,})\b", text)
+    return list({t for t in tokens if t not in _STOP_TOPIC_TOKENS})[:8]
+
+
+_STOP_TOPIC_TOKENS = frozenset({
+    "The", "This", "That", "When", "Where", "Then", "Note", "TODO", "FIXME",
+    "README", "ArkaOS", "Claude", "Read", "Write", "Edit", "Run",
+})
+
+
+def _build_insight_prompt(cluster: Cluster) -> str:
+    excerpts = []
+    sources = []
+    for c in cluster.chunks[:6]:
+        sources.append(c.source_path)
+        excerpts.append(f"[{c.source_path}]\n{c.text[:400]}\n")
+    src_lines = "\n".join(f"- {s}" for s in sorted(set(sources)))
+    return (
+        "You are reviewing the user's recent work. Several notes share a topic.\n\n"
+        f"Topic anchor: {cluster.topic}\n\n"
+        f"Sources:\n{src_lines}\n\n"
+        f"Excerpts:\n{''.join(excerpts)}\n"
+        "Return ONE concrete observation, pattern, or action the user might "
+        "want to consider. Two sentences maximum. If nothing is genuinely "
+        "surprising or actionable, return literally: PASS\n\n"
+        "Format your reply as:\n"
+        "TITLE: <very short title>\n"
+        "BODY: <two sentences>\n"
+        "CONFIDENCE: high | medium | low\n"
+    )
+
+
+def _build_critic_prompt(insight: Insight) -> str:
+    return (
+        "Judge this insight as if it were going to land on the user's desk "
+        "tomorrow morning. Is it specific, actionable, and non-generic? "
+        "Or is it noise that would erode trust over time?\n\n"
+        f"Title: {insight.title}\n"
+        f"Body: {insight.body}\n\n"
+        "Reply with exactly one word: VALUABLE or NOISE."
+    )
+
+
+def _parse_insight(response: LLMResponse, cluster: Cluster) -> Insight | None:
+    text = response.text.strip()
+    if not text or text.upper().startswith("PASS"):
+        return None
+    title = _extract_field(text, "TITLE") or _first_line(text)
+    body = _extract_field(text, "BODY") or text
+    confidence = _extract_field(text, "CONFIDENCE") or "medium"
+    confidence = confidence.lower()
+    if confidence not in {"high", "medium", "low"}:
+        confidence = "medium"
+    sources = sorted({c.source_path for c in cluster.chunks})[:6]
+    tags = [cluster.topic.lower()] if cluster.topic else []
+    return Insight(title=title.strip(), body=body.strip(), confidence=confidence,
+                   sources=sources, tags=tags)
+
+
+def _extract_field(text: str, field_name: str) -> str | None:
+    pattern = re.compile(
+        rf"^{re.escape(field_name)}\s*:\s*(.+?)$", re.IGNORECASE | re.MULTILINE
+    )
+    match = pattern.search(text)
+    if match:
+        return match.group(1).strip()
+    return None
+
+
+def _first_line(text: str) -> str:
+    for line in text.splitlines():
+        line = line.strip()
+        if line:
+            return line[:80]
+    return "Insight"
+
+
+def _slugify(title: str) -> str:
+    slug = re.sub(r"[^a-zA-Z0-9-]+", "-", title.lower()).strip("-")
+    return slug[:60]
+
+
+def _render_markdown(frontmatter: dict, insight: Insight) -> str:
+    lines = ["---"]
+    for key, value in frontmatter.items():
+        if isinstance(value, list):
+            lines.append(f"{key}:")
+            for v in value:
+                lines.append(f"  - {v}")
+        else:
+            lines.append(f"{key}: {value}")
+    lines.append("---")
+    lines.append("")
+    lines.append(f"# {insight.title}")
+    lines.append("")
+    lines.append("## What I noticed")
+    lines.append(insight.body)
+    if insight.sources:
+        lines.append("")
+        lines.append("## Sources")
+        for s in insight.sources:
+            lines.append(f"- [[{s}]]")
+    return "\n".join(lines) + "\n"
+
+
+# ─── CLI ──────────────────────────────────────────────────────────────
+
+
+def main(argv: list[str]) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("command", choices=["run"], help="action to perform")
+    parser.add_argument("--dry-run", action="store_true", help="cluster + draft without writing")
+    args = parser.parse_args(argv)
+
+    try:
+        engine = Dreaming.from_profile()
+    except ProfileMissingError as exc:
+        print(f"Cannot start Dreaming: {exc}")
+        return 2
+
+    insights = engine.run(dry_run=args.dry_run)
+    print(f"Dreaming produced {len(insights)} insight(s).")
+    for i, insight in enumerate(insights, start=1):
+        print(f"{i}. ({insight.confidence}) {insight.title}")
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main(sys.argv[1:]))

package/core/cognition/dreams_reader.py

@@ -0,0 +1,141 @@
+"""Read Dreaming v2 insights from the Obsidian vault.
+
+Surface used by the ``/arka dreams`` skill. Parses the plugin-compat
+frontmatter shape written by ``core.cognition.dreaming`` and groups
+results by date so the CLI can show today, since-N-days, or all.
+
+Read-only; never modifies vault content.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+
+@dataclass
+class StoredInsight:
+    """An insight surfaced by Dreaming v2 and parsed back from disk."""
+
+    path: Path
+    date: str  # YYYY-MM-DD
+    title: str
+    confidence: str
+    sources: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+    body: str = ""
+
+
+_FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n(.*)", re.DOTALL)
+
+
+def list_insights(dreams_dir: Path, since_days: int = 1) -> list[StoredInsight]:
+    """List insights from *dreams_dir* whose date is within *since_days*.
+
+    ``since_days=1`` is "today only" (UTC-day boundary, generous tolerance
+    of one calendar day so a late-night dream surfaced after midnight
+    still counts). ``since_days=7`` returns last week, etc.
+    """
+    dreams_dir = Path(dreams_dir)
+    if not dreams_dir.is_dir():
+        return []
+    cutoff = datetime.now(timezone.utc).date() - timedelta(days=max(since_days - 1, 0))
+    out: list[StoredInsight] = []
+    for md in sorted(dreams_dir.glob("*.md"), reverse=True):
+        try:
+            text = md.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        insight = parse_insight(md, text)
+        if insight is None:
+            continue
+        try:
+            insight_date = datetime.strptime(insight.date, "%Y-%m-%d").date()
+        except ValueError:
+            continue
+        if insight_date >= cutoff:
+            out.append(insight)
+    return out
+
+
+def parse_insight(path: Path, text: str) -> StoredInsight | None:
+    """Parse one Dreaming v2 markdown file into a StoredInsight."""
+    match = _FRONTMATTER_RE.match(text)
+    if not match:
+        return None
+    fm_block, body = match.group(1), match.group(2)
+    fm = _parse_frontmatter(fm_block)
+    if fm.get("type") != "arkaos-insight":
+        return None
+    title = _extract_h1(body) or path.stem
+    return StoredInsight(
+        path=path,
+        date=str(fm.get("date", "")),
+        title=title,
+        confidence=str(fm.get("confidence", "medium")),
+        sources=_parse_list(fm.get("sources")),
+        tags=_parse_list(fm.get("tags")),
+        body=_extract_body(body),
+    )
+
+
+def _parse_frontmatter(block: str) -> dict:
+    """Tiny YAML-ish parser. Frontmatter shape is constrained by Dreaming v2
+    output (`core/cognition/dreaming.py:_render_markdown`) so a full YAML
+    dependency is not warranted here.
+    """
+    out: dict[str, object] = {}
+    current_key: str | None = None
+    current_list: list[str] = []
+    for raw_line in block.splitlines():
+        if not raw_line.strip():
+            continue
+        if raw_line.startswith("  - "):
+            current_list.append(raw_line[4:].strip())
+            continue
+        if current_key is not None and current_list:
+            out[current_key] = list(current_list)
+            current_list = []
+        current_key = None
+        if ":" not in raw_line:
+            continue
+        key, _, value = raw_line.partition(":")
+        key = key.strip()
+        value = value.strip()
+        if value == "":
+            current_key = key
+            continue
+        out[key] = value
+    if current_key is not None and current_list:
+        out[current_key] = list(current_list)
+    return out
+
+
+def _parse_list(value: object) -> list[str]:
+    if isinstance(value, list):
+        return [str(v) for v in value]
+    if isinstance(value, str) and value:
+        return [value]
+    return []
+
+
+def _extract_h1(body: str) -> str | None:
+    for line in body.splitlines():
+        if line.startswith("# "):
+            return line[2:].strip()
+    return None
+
+
+def _extract_body(body: str) -> str:
+    """Return the prose under '## What I noticed' if present, else the body."""
+    marker = "## What I noticed"
+    idx = body.find(marker)
+    if idx < 0:
+        return body.strip()
+    after = body[idx + len(marker):]
+    next_section = after.find("\n## ")
+    if next_section < 0:
+        return after.strip()
+    return after[:next_section].strip()

package/core/cognition/scheduler/daemon.py

@@ -18,7 +18,16 @@ import yaml
 
 @dataclass
 class ScheduleConfig:
-    """Configuration for a single scheduled cognitive task."""
+    """Configuration for a single scheduled cognitive task.
+
+    Two execution modes (mutually exclusive):
+      - prompt_file (default): shell out to the active Claude CLI with the
+        rendered prompt as the user input. Backward-compat for legacy
+        dreaming.md / research.md schedules.
+      - python_module: invoke ``python -m <module> [args...]`` directly.
+        Used by Dreaming v2 (PR8) which is a Python engine, not a
+        prompt-only task.
+    """
 
     command: str
     prompt_file: str
@@ -27,6 +36,8 @@ class ScheduleConfig:
     retry_on_fail: bool = True
     max_retries: int = 2
     timeout_minutes: int = 60
+    python_module: str | None = None
+    module_args: list[str] = field(default_factory=list)
 
     @classmethod
     def load(cls, config_path: str) -> "list[ScheduleConfig]":
@@ -43,12 +54,14 @@ class ScheduleConfig:
             schedules.append(
                 cls(
                     command=cfg["command"],
-                    prompt_file=cfg["prompt_file"],
+                    prompt_file=cfg.get("prompt_file", ""),
                     run_time=time(hour, minute),
                     enabled=cfg.get("enabled", True),
                     retry_on_fail=cfg.get("retry_on_fail", True),
                     max_retries=cfg.get("max_retries", 2),
                     timeout_minutes=cfg.get("timeout_minutes", 60),
+                    python_module=cfg.get("python_module"),
+                    module_args=list(cfg.get("module_args") or []),
                 )
             )
         return schedules
@@ -140,7 +153,14 @@ class ArkaScheduler:
         )
 
     def _build_command(self, schedule: ScheduleConfig) -> list[str]:
-        """Build the Claude CLI invocation for a schedule."""
+        """Build the subprocess invocation for a schedule.
+
+        Dispatches on python_module first (PR8 Dreaming v2 path), falls
+        back to the legacy Claude-CLI-with-prompt path for unchanged
+        schedules.
+        """
+        if schedule.python_module:
+            return [sys.executable, "-m", schedule.python_module, *schedule.module_args]
         claude_bin = self._resolve_claude_binary()
         prompt_path = os.path.expanduser(schedule.prompt_file)
         prompt_content = Path(prompt_path).read_text(encoding="utf-8")

package/core/runtime/llm_provider.py

@@ -31,7 +31,7 @@ from core.runtime.pricing import estimate_cost_usd
 
 
 _DEFAULT_CONFIG_PATH = Path.home() / ".arkaos" / "config.json"
-_FALLBACK_ORDER: tuple[str, ...] = ("subagent", "anthropic-direct", "stub")
+_FALLBACK_ORDER: tuple[str, ...] = ("subagent", "ollama", "anthropic-direct", "stub")
 
 
 # ─── Public dataclass ─────────────────────────────────────────────────
@@ -305,8 +305,15 @@ class StubProvider:
 # ─── Factory + fallback chain ─────────────────────────────────────────
 
 
+def _import_ollama_provider() -> type:
+    """Lazy import to keep the Ollama provider optional at runtime."""
+    from core.runtime.ollama_provider import OllamaProvider
+    return OllamaProvider
+
+
 _PROVIDERS: dict[str, type] = {
     "subagent": SubagentProvider,
+    "ollama": _import_ollama_provider(),
     "anthropic-direct": AnthropicDirectProvider,
     "stub": StubProvider,
 }

package/core/runtime/ollama_provider.py

@@ -0,0 +1,144 @@
+"""Ollama provider — local LLM inference via the localhost API.
+
+One of several backends behind the `LLMProvider` Protocol in
+``core/runtime/llm_provider.py``. The cognitive layer never imports
+this class directly; it goes through ``get_llm_provider()`` which
+selects from a configurable chain (subagent → ollama → anthropic-direct
+→ stub by default; user-configurable in ``~/.arkaos/config.json``).
+
+Communicates with the local Ollama service at the standard
+``http://localhost:11434`` endpoint via stdlib ``urllib`` — no extra
+dependencies. Model picked from ``OLLAMA_MODEL`` env var, then
+``profile.json:cognitiveModel``, then a sensible default. Whichever
+the user has chosen sticks to a single chat completion call per
+``complete()`` invocation.
+
+See ``docs/adr/2026-05-13-cognitive-layer-pivot-to-hooks.md`` and the
+PR8 v2.30.0 commit for the architectural rationale.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from core.runtime.llm_provider import LLMResponse, LLMUnavailable
+
+
+_OLLAMA_HOST = "http://localhost:11434"
+_DEFAULT_MODEL = "gemma3:27b"  # fallback only — most users override via env / profile
+_GENERATE_TIMEOUT_S = 120  # nightly Dreaming run — large prompts allowed
+
+
+class OllamaProvider:
+    """Provider that hits the local Ollama daemon for chat completion."""
+
+    ENV_HOST = "OLLAMA_HOST"
+    ENV_MODEL = "OLLAMA_MODEL"
+
+    def __init__(self, model: str | None = None, host: str | None = None) -> None:
+        self._model_override = model
+        self._host = host or os.environ.get(self.ENV_HOST, _OLLAMA_HOST)
+
+    def name(self) -> str:
+        return "ollama"
+
+    def is_available(self) -> bool:
+        """Cheap reachability check against ``/api/tags``."""
+        url = f"{self._host.rstrip('/')}/api/tags"
+        try:
+            with urllib.request.urlopen(url, timeout=1.5) as response:
+                return response.status == 200
+        except (urllib.error.URLError, TimeoutError, OSError):
+            return False
+
+    def complete(
+        self,
+        prompt: str,
+        *,
+        max_tokens: int = 2000,
+        system: str = "",
+    ) -> LLMResponse:
+        model = self._resolve_model()
+        if not model:
+            raise LLMUnavailable("Ollama model not configured (set OLLAMA_MODEL or profile.cognitiveModel)")
+
+        payload = self._build_payload(model, prompt, system, max_tokens)
+        data = self._post_generate(payload)
+        return self._to_response(data, model)
+
+    def _resolve_model(self) -> str | None:
+        if self._model_override:
+            return self._model_override
+        env_value = os.environ.get(self.ENV_MODEL, "").strip()
+        if env_value:
+            return env_value
+        profile_model = _read_profile_model()
+        if profile_model:
+            return profile_model
+        return _DEFAULT_MODEL
+
+    def _build_payload(self, model: str, prompt: str, system: str, max_tokens: int) -> dict:
+        """Build /api/chat payload.
+
+        Using the chat endpoint (not /api/generate) means Ollama applies
+        the model's official chat template, which is critical for
+        instruction-tuned models like Qwen, Gemma, Mistral — without the
+        template most models burn through their token budget before
+        emitting visible content. Smoke-tested 2026-05-13 against
+        qwen3-coder:30b which returned the expected "hi" in 2 tokens.
+        """
+        messages: list[dict] = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        return {
+            "model": model,
+            "messages": messages,
+            "stream": False,
+            "options": {"num_predict": max_tokens},
+        }
+
+    def _post_generate(self, payload: dict) -> dict:
+        url = f"{self._host.rstrip('/')}/api/chat"
+        body = json.dumps(payload).encode("utf-8")
+        request = urllib.request.Request(
+            url, data=body, headers={"Content-Type": "application/json"}
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=_GENERATE_TIMEOUT_S) as response:
+                raw = response.read().decode("utf-8")
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            raise LLMUnavailable(f"Ollama request failed: {exc}") from exc
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise LLMUnavailable(f"Ollama returned invalid JSON: {exc}") from exc
+
+    def _to_response(self, data: dict, model: str) -> LLMResponse:
+        message = data.get("message", {}) or {}
+        text = (message.get("content") or data.get("response") or "").strip()
+        tokens_in = int(data.get("prompt_eval_count", 0) or 0)
+        tokens_out = int(data.get("eval_count", 0) or 0)
+        return LLMResponse(
+            text=text,
+            tokens_in=tokens_in,
+            tokens_out=tokens_out,
+            cached_tokens=0,  # Ollama does not surface a cache signal
+            model=model,
+        )
+
+
+def _read_profile_model() -> str | None:
+    path = Path.home() / ".arkaos" / "profile.json"
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    value = data.get("cognitiveModel")
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None

package/installer/cli.js

@@ -20,6 +20,7 @@ const { values, positionals } = parseArgs({
     path: { type: "string", short: "p" },
     force: { type: "boolean", short: "f" },
     "no-system": { type: "boolean" },
+    "with-ollama": { type: "boolean" },
   },
   allowPositionals: true,
   strict: false,
@@ -75,7 +76,13 @@ async function main() {
   switch (command) {
     case "install":
       const runtime = values.runtime || await detectRuntime();
-      await install({ runtime, path: values.path, force: values.force, skipSystem: values["no-system"] });
+      await install({
+        runtime,
+        path: values.path,
+        force: values.force,
+        skipSystem: values["no-system"],
+        withOllama: values["with-ollama"],
+      });
       break;
 
     case "init": {

package/installer/doctor.js

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import { execSync } from "node:child_process";
 import { getArkaosPython, getVenvPython, canImportCore, getRepoRoot } from "./python-resolver.js";
 import { IS_WINDOWS, HOOK_EXT, CMD_FINDER } from "./platform.js";
-import { checkNode, checkObsidian } from "./system-tools.js";
+import { checkNode, checkObsidian, checkOllama } from "./system-tools.js";
 
 const INSTALL_DIR = join(homedir(), ".arkaos");
 
@@ -147,6 +147,18 @@ const checks = [
       return `Install Node.js 20+ from ${s.fallbackUrl || "https://nodejs.org/en/download"}`;
     },
   },
+  {
+    name: "ollama",
+    description: "Ollama present (optional — cognitive layer LLM runtime)",
+    severity: "warn",
+    check: () => checkOllama().installed,
+    fix: () => {
+      const s = checkOllama();
+      if (s.needsAction === "start") return `Run: ${s.suggestedCommand}`;
+      if (s.suggestedCommand) return `Run: ${s.suggestedCommand}`;
+      return `Install Ollama from ${s.fallbackUrl || "https://ollama.com/download"}`;
+    },
+  },
   {
     name: "claude-code-version",
     description: "Claude Code 2.1.122+ (ToolSearch late-binding + hooks isolation)",

package/installer/index.js

@@ -12,7 +12,7 @@ const __dirname = dirname(__filename);
 const ARKAOS_ROOT = resolve(__dirname, "..");
 const VERSION = JSON.parse(readFileSync(join(ARKAOS_ROOT, "package.json"), "utf-8")).version;
 
-export async function install({ runtime, path, force, skipSystem }) {
+export async function install({ runtime, path, force, skipSystem, withOllama }) {
   const startTime = Date.now();
   const config = getRuntimeConfig(runtime);
   const isUpgrade = existsSync(join(path || join(homedir(), ".arkaos"), "install-manifest.json"));
@@ -80,16 +80,19 @@ export async function install({ runtime, path, force, skipSystem }) {
     try {
       const { ensureSystemTools } = await import("./system-tools.js");
       const { formatSudoInstructions } = await import("./package-manager.js");
-      const sys = ensureSystemTools({ skipSystem: false });
+      const sys = ensureSystemTools({ skipSystem: false, withOllama });
       if (sys.sudoCommands && sys.sudoCommands.length > 0) {
         console.log(formatSudoInstructions(sys.sudoCommands));
       }
-      for (const tool of [sys.obsidian, sys.node]) {
+      for (const tool of [sys.obsidian, sys.node, sys.ollama]) {
         if (!tool) continue;
         if (tool.justInstalled) ok(`${tool.name} installed`);
         else if (tool.needsAction === "none") ok(`${tool.name} ready`);
         else warn(`${tool.name} ${tool.needsAction} — see commands above`);
       }
+      if (withOllama && sys.ollama?.needsAction === "none") {
+        ok("Ollama backend ready — cognitive layer can use local LLM inference");
+      }
     } catch (err) {
       warn(`System tool check failed: ${err.message}. Continuing without it.`);
     }

package/installer/system-tools.js

@@ -41,13 +41,27 @@ const NODE_PACKAGE = {
   choco: "nodejs",
 };
 
+const OLLAMA_PACKAGE = {
+  brew: "ollama",
+  winget: "Ollama.Ollama",
+  choco: "ollama",
+};
+
 const OBSIDIAN_FALLBACK_URL = "https://obsidian.md/download";
 const NODE_FALLBACK_URL = "https://nodejs.org/en/download";
 const PYTHON_FALLBACK_URL = "https://www.python.org/downloads/";
+const OLLAMA_FALLBACK_URL = "https://ollama.com/download";
 
 /**
  * Validate every required tool, install what can be installed without
  * sudo, and collect copy-paste commands for the ones that can't.
+ *
+ * When ``options.withOllama`` is set, Ollama is included in the check
+ * + install set as one possible **backend** for the cognitive layer.
+ * Opt-in: most users keep the Claude Code backend (default) and never
+ * need a local LLM runtime. Multi-backend selection lives in
+ * ``profile.json:cognitiveBackend``; this flag only governs the
+ * Ollama prerequisite at install time.
  */
 export function ensureSystemTools(options = {}) {
   if (options.skipSystem) {
@@ -56,6 +70,7 @@ export function ensureSystemTools(options = {}) {
       obsidian: null,
       node: null,
       python: null,
+      ollama: null,
       sudoCommands: [],
     };
   }
@@ -64,7 +79,13 @@ export function ensureSystemTools(options = {}) {
   const node = ensureTool("node", checkNode, NODE_PACKAGE, NODE_FALLBACK_URL, options);
   const python = checkPython();  // never auto-install Python — leave to OS
 
-  const sudoCommands = [obsidian, node]
+  let ollama = null;
+  if (options.withOllama) {
+    ollama = ensureTool("ollama", checkOllama, OLLAMA_PACKAGE, OLLAMA_FALLBACK_URL, options);
+  }
+
+  const tools = [obsidian, node, ollama].filter(Boolean);
+  const sudoCommands = tools
     .filter((t) => t?.needsSudo && t.suggestedCommand)
     .map((t) => t.suggestedCommand);
 
@@ -72,7 +93,7 @@ export function ensureSystemTools(options = {}) {
     sudoCommands.push(python.suggestedCommand);
   }
 
-  return { skipped: false, obsidian, node, python, sudoCommands };
+  return { skipped: false, obsidian, node, python, ollama, sudoCommands };
 }
 
 /**
@@ -131,6 +152,40 @@ export function checkNode() {
   };
 }
 
+/**
+ * Detect Ollama presence + whether the local service responds.
+ *
+ * Ollama is the cognitive-layer LLM runtime. Linux install uses an
+ * official script (``curl https://ollama.com/install.sh | sh``) that
+ * requires sudo — we never run it; we surface the command.
+ */
+export function checkOllama() {
+  const location = findBinary("ollama");
+  if (!location) {
+    const suggested = buildOllamaSuggestion();
+    return {
+      name: "ollama",
+      installed: false,
+      needsAction: "install",
+      suggestedCommand: suggested.command,
+      needsSudo: suggested.needsSudo,
+      fallbackUrl: OLLAMA_FALLBACK_URL,
+    };
+  }
+  const reachable = isOllamaReachable();
+  const version = readVersion("ollama --version");
+  return {
+    name: "ollama",
+    installed: true,
+    location,
+    version,
+    needsAction: reachable ? "none" : "start",
+    suggestedCommand: reachable ? undefined : "ollama serve   # or run the Ollama app",
+    needsSudo: false,
+  };
+}
+
+
 export function checkPython() {
   const candidates = IS_WINDOWS ? ["python", "py"] : ["python3", "python3.12", "python3.13"];
   for (const cmd of candidates) {
@@ -195,6 +250,28 @@ function buildSuggestedInstall(packageMap, fallbackUrl) {
   return { command: `Download from ${fallbackUrl}`, needsSudo: false, fallbackUrl };
 }
 
+function buildOllamaSuggestion() {
+  const os = platform();
+  if (os === "darwin") return { command: "brew install ollama", needsSudo: false };
+  if (IS_WINDOWS) return { command: "winget install --id Ollama.Ollama --silent --accept-source-agreements --accept-package-agreements", needsSudo: false };
+  if (os === "linux") return { command: "curl -fsSL https://ollama.com/install.sh | sh", needsSudo: true };
+  return { command: `Download from ${OLLAMA_FALLBACK_URL}`, needsSudo: false };
+}
+
+
+function isOllamaReachable() {
+  try {
+    execSync("ollama list", {
+      stdio: ["ignore", "ignore", "ignore"],
+      timeout: 1500,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+
 function findBinary(name) {
   try {
     const out = execSync(`${CMD_FINDER} ${name}`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "2.28.0",
+  "version": "2.31.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "2.28.0"
+version = "2.31.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}