@zerwiz/ymir 0.1.3 → 0.1.5

package/bin/host-sense.sh

@@ -0,0 +1,199 @@
+#!/usr/bin/env bash
+# host-sense.sh — learn THIS machine: distro, kernel, session, desktop, and what
+# the desktop can actually do.
+#
+# Ymir is **Omarchy-first**: the Omarchy layer is first-class (host sensing,
+# numbered-desktop placement, launcher entries, shell plugins, post-update hook),
+# and Rule 05 keeps the core portable so other hosts carry their own layer.
+# "First" is not "only": an operator may run Ubuntu, Fedora, Arch, Debian, on
+# Wayland or X11, under GNOME, KDE, Hyprland or Sway. A layer is gated on its
+# host and reports a clean skip elsewhere — never assumed, never faked.
+#
+# This is the one place that looks before anything acts.
+# It is a sensor: it observes and reports. It changes nothing.
+#
+# Usage:
+#   bin/host-sense.sh                     # the host, as TOON
+#   bin/host-sense.sh --json              # the same facts, machine-readable
+#   bin/host-sense.sh capability <name>   # yes|partial|no — for scripting
+#   bin/host-sense.sh --version
+#
+# Capabilities asked of a desktop:
+#   placement  can a window be pinned to its own numbered workspace from a script
+#   launcher   do .desktop entries land in a menu / taskbar / app grid
+#   tray       is there a native system-tray host (icons beside the clock)
+set -u
+
+VERSION="1.0.0"
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help) sed -n '2,26p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+
+MODE="toon"
+CAP=""
+case "${1-}" in
+  --json) MODE="json"; shift ;;
+  capability) CAP="${2:-}"; shift 2 2>/dev/null || true ;;
+  *) : ;;
+esac
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# ── os ───────────────────────────────────────────────────────────────────────
+OS_NAME="unknown"; OS_ID="unknown"; OS_LIKE=""; OS_VERSION=""
+if [ -r /etc/os-release ]; then
+  # shellcheck disable=SC1091
+  OS_NAME="$(. /etc/os-release 2>/dev/null; printf '%s' "${PRETTY_NAME:-${NAME:-unknown}}")"
+  OS_ID="$(. /etc/os-release 2>/dev/null; printf '%s' "${ID:-unknown}")"
+  OS_LIKE="$(. /etc/os-release 2>/dev/null; printf '%s' "${ID_LIKE:-}")"
+  OS_VERSION="$(. /etc/os-release 2>/dev/null; printf '%s' "${VERSION_ID:-}")"
+fi
+[ "$OS_ID" = "unknown" ] && [ -r /etc/lsb-release ] && { . /etc/lsb-release 2>/dev/null; OS_ID="${DISTRIB_ID:-unknown}"; OS_NAME="${DISTRIB_DESCRIPTION:-$OS_NAME}"; }
+
+# The family is what a package-manager choice actually keys on.
+FAMILY="other"
+case " $OS_ID ${OS_LIKE:-} " in
+  *" ubuntu "*|*" debian "*|*" linuxmint "*|*" pop "*) FAMILY="debian" ;;
+  *" fedora "*|*" rhel "*|*" centos "*|*" rocky "*|*" almalinux "*) FAMILY="rhel" ;;
+  *" arch "*|*" endeavouros "*|*" manjaro "*) FAMILY="arch" ;;
+  *" opensuse "*|*" sles "*) FAMILY="suse" ;;
+  *" alpine "*) FAMILY="alpine" ;;
+esac
+case "$OS_ID" in
+  ubuntu|debian|linuxmint|pop) FAMILY="debian" ;;
+  fedora|rhel|centos|rocky|almalinux) FAMILY="rhel" ;;
+  arch|endeavouros|manjaro|omarchy) FAMILY="arch" ;;
+  opensuse*|sles) FAMILY="suse" ;;
+  alpine) FAMILY="alpine" ;;
+esac
+
+PKG="none"
+for pm in apt dnf pacman zypper apk yum; do have "$pm" && { PKG="$pm"; break; }; done
+
+KERNEL="$(uname -sr 2>/dev/null || printf 'unknown')"
+ARCH="$(uname -m 2>/dev/null || printf 'unknown')"
+
+# ── platform ─────────────────────────────────────────────────────────────────
+# The core is portable; the host must be named before any layer can gate on it.
+# A Windows operator reaches Ymir through WSL, so WSL is its own platform, not
+# "linux with a strange kernel".
+PLATFORM="linux"; WSL="no"
+case "$(uname -s 2>/dev/null)" in
+  Darwin) PLATFORM="macos" ;;
+  MINGW*|MSYS*|CYGWIN*) PLATFORM="windows" ;;
+  Linux)
+    if grep -qiE 'microsoft|wsl' /proc/version 2>/dev/null; then PLATFORM="wsl"; WSL="yes"; fi ;;
+esac
+
+# ── session ──────────────────────────────────────────────────────────────────
+SESSION="none"
+if [ -n "${WAYLAND_DISPLAY:-}" ] || [ "${XDG_SESSION_TYPE:-}" = "wayland" ]; then
+  SESSION="wayland"
+elif [ -n "${DISPLAY:-}" ] || [ "${XDG_SESSION_TYPE:-}" = "x11" ]; then
+  SESSION="x11"
+fi
+
+# ── desktop ──────────────────────────────────────────────────────────────────
+# XDG_CURRENT_DESKTOP is a colon list ("ubuntu:GNOME"); DESKTOP_SESSION is a
+# fallback. Match the first token we recognise, and prefer a live compositor
+# binary over a stale environment variable.
+DESKTOP="unknown"
+for d in "${XDG_CURRENT_DESKTOP:-}" "${DESKTOP_SESSION:-}" "${XDG_SESSION_DESKTOP:-}"; do
+  [ -n "$d" ] || continue
+  for tok in $(printf '%s' "$d" | tr 'A-Z:' 'a-z '); do
+    case "$tok" in
+      hyprland) DESKTOP="hyprland" ;;
+      gnome|ubuntu) [ "$DESKTOP" = "unknown" ] && DESKTOP="gnome" ;;
+      kde|plasma) DESKTOP="kde" ;;
+      sway) DESKTOP="sway" ;;
+      niri) DESKTOP="niri" ;;
+      river) DESKTOP="river" ;;
+      xfce) DESKTOP="xfce" ;;
+      cinnamon) DESKTOP="cinnamon" ;;
+      mate) DESKTOP="mate" ;;
+      cosmic) DESKTOP="cosmic" ;;
+    esac
+  done
+  [ "$DESKTOP" != "unknown" ] && break
+done
+# A running compositor does not lie; an inherited variable can.
+have hyprctl && hyprctl version >/dev/null 2>&1 && DESKTOP="hyprland"
+have swaymsg && DESKTOP="sway"
+have gnome-shell && [ "${XDG_CURRENT_DESKTOP:-}" != "" ] && DESKTOP="gnome"
+have plasmashell && DESKTOP="kde"
+
+COMPOSITOR="none"
+have hyprctl && COMPOSITOR="hyprland"
+have swaymsg && COMPOSITOR="sway"
+have gnome-shell && COMPOSITOR="gnome-shell"
+have plasmashell && COMPOSITOR="plasmashell"
+have kwin_wayland && COMPOSITOR="kwin_wayland"
+
+# ── what the desktop can actually do ─────────────────────────────────────────
+# placement: a script can pin a window to its own numbered workspace.
+PLACEMENT="no"
+case "$COMPOSITOR" in
+  hyprland) have hyprctl && PLACEMENT="yes" ;;   # hyprctl keyword windowrule/dispatch
+  sway)     have swaymsg && PLACEMENT="yes" ;;   # swaymsg assign
+  *)        PLACEMENT="no" ;;                    # GNOME/KDE: dynamic workspaces, no rule
+esac
+
+# launcher: .desktop entries are a freedesktop standard, so this is the one
+# capability nearly every desktop has.
+DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
+APPS_DIR="$DATA_HOME/applications"
+LAUNCHER="no"
+[ -d "$APPS_DIR" ] && [ -w "$APPS_DIR" ] && LAUNCHER="yes"
+[ "$LAUNCHER" = "no" ] && [ -w "$DATA_HOME" ] && LAUNCHER="yes"   # can be created
+
+# tray: an icon beside the clock. GNOME needs an extension; KDE/Hyprland have
+# native hosts; the rest vary.
+TRAY="no"
+case "$DESKTOP" in
+  kde)      TRAY="yes" ;;
+  hyprland) TRAY="partial" ;;   # via a bar (waybar etc.), if one is running
+  gnome)    TRAY="partial" ;;   # only with an AppIndicator extension
+  *)        TRAY="no" ;;
+esac
+
+# A desktop that is managed by Ymir's own Omarchy layer, or merely compatible.
+OMARCHY="no"
+{ have omarchy || [ -d "$HOME/.local/share/omarchy" ]; } && OMARCHY="yes"
+
+if [ -n "$CAP" ]; then
+  case "$CAP" in
+    placement) printf '%s\n' "$PLACEMENT" ;;
+    launcher)  printf '%s\n' "$LAUNCHER" ;;
+    tray)      printf '%s\n' "$TRAY" ;;
+    *) printf 'error: unknown capability %s\nhelp: bin/host-sense.sh capability [placement|launcher|tray]\n' "$CAP" >&2; exit 2 ;;
+  esac
+  exit 0
+fi
+
+if [ "$MODE" = "json" ]; then
+  python3 - "$OS_NAME" "$OS_ID" "$FAMILY" "$OS_VERSION" "$KERNEL" "$ARCH" "$SESSION" "$DESKTOP" "$COMPOSITOR" "$PKG" "$PLACEMENT" "$LAUNCHER" "$TRAY" "$OMARCHY" "$PLATFORM" "$WSL" <<'PY'
+import json, sys
+keys = ["os","id","family","version","kernel","arch","session","desktop",
+        "compositor","package_manager","placement","launcher","tray","omarchy",
+        "platform","wsl"]
+print(json.dumps(dict(zip(keys, sys.argv[1:])), indent=2))
+PY
+  exit 0
+fi
+
+# human default: a small TOON block. Keys are plain; values quoted.
+printf 'host[1]{os,id,family,session,desktop}:\n'
+printf '  "%s","%s","%s","%s","%s"\n' "$OS_NAME" "$OS_ID" "$FAMILY" "$SESSION" "$DESKTOP"
+printf 'machine[5]{platform,wsl,kernel,arch,package_manager}:\n'
+printf '  "%s","%s","%s","%s","%s"\n' "$PLATFORM" "$WSL" "$KERNEL" "$ARCH" "$PKG"
+printf 'capabilities[3]{name,state,note}:\n'
+case "$PLACEMENT" in
+  yes) printf '  "placement","yes","%s can pin a window to its own workspace"\n' "$COMPOSITOR" ;;
+  *)   printf '  "placement","no","%s has no scriptable per-window workspace rule — placement is skipped, never faked"\n' "${DESKTOP:-desktop}" ;;
+esac
+printf '  "launcher","%s","%s"\n' "$LAUNCHER" "$APPS_DIR"
+printf '  "tray","%s","%s"\n' "$TRAY" "$([ "$TRAY" = yes ] && printf 'native tray host' || printf 'no native tray host — an icon needs an extension or a bar')"
+printf 'layer[1]{name,state}:\n'
+printf '  "omarchy","%s"\n' "$([ "$OMARCHY" = yes ] && printf 'FIRST-CLASS LAYER — Omarchy detected, the Omarchy layer applies here' || printf 'first-class layer, not on THIS host — Omarchy is absent, so its layer skips cleanly (Rule 05); the portable core runs, and this host gets its own layer')"

package/bin/huginn-research-worker.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# huginn-research-worker — Apodex-powered research worker (Eindri).
+# Takes a brief, recalls context from Mimirsbrunn, dispatches to the Apodex
+# endpoint, and writes a structured verdict. Runs anywhere: herdr pane
+# (preferred), Utgard sandbox, or host shell.
+#
+# Usage:
+#   huginn-research-worker --brief "<task>" --output-dir <path>
+#   huginn-research-worker --brief "<task>" --output-dir <path> [--model <model>]
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+BRIEF="" OUTDIR="" MODEL=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --brief)    BRIEF="${2:-}"; shift 2 ;;
+    --output-dir) OUTDIR="${2:-}"; shift 2 ;;
+    --model)    MODEL="${2:-}"; shift 2 ;;
+    --help|-h|"") sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *)          echo "error: unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ -n "$BRIEF" ]    || { echo "error: --brief required" >&2; exit 2; }
+[ -n "$OUTDIR" ]   || { echo "error: --output-dir required" >&2; exit 2; }
+mkdir -p "$OUTDIR"
+
+# Resolve env — source .env.local if present.
+for f in "$ROOT/.env.local" "${YMIR_HOARD:-$HOME/Documents/Ymir}/.env.local"; do
+  [ -f "$f" ] && . "$f" 2>/dev/null || true
+done
+
+BASE="${APODEX_BASE_URL:-http://localhost:1234/v1}"
+MODEL="${MODEL:-${APODEX_MODEL:-apodex-1.0-mini}}"
+KEY="${APODEX_API_KEY:-not-needed-for-local}"
+
+# 1. Recall context from Mimirsbrunn (boost, never blocker).
+RECALL=""
+if [ -x "$ROOT/bin/mimir.sh" ]; then
+  RECALL=$("$ROOT/bin/mimir.sh" recall "$BRIEF" --k 3 2>/dev/null | tail -20 || true)
+fi
+
+# 2. Build the request payload.
+PAYLOAD=$(python3 - "$BRIEF" "$RECALL" "$MODEL" <<'PY'
+import json, sys
+brief, recall, model = sys.argv[1], sys.argv[2], sys.argv[3]
+msgs = [{"role": "system", "content": "You are Huginn — a research worker. Analyse the task, recall any relevant context, and produce a structured verdict. Return your findings as a structured markdown report."}]
+content = f"Task: {brief}"
+if recall.strip():
+    content += f"\n\nRecalled context:\n{recall}"
+msgs.append({"role": "user", "content": content})
+print(json.dumps({"model": model, "messages": msgs, "temperature": 0.2}))
+PY
+)
+
+# 3. Dispatch to Apodex endpoint.
+RESP="$OUTDIR/response.json"
+HTTP_CODE=$(curl -sS -w '%{http_code}' --max-time 120 \
+  "$BASE/chat/completions" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $KEY" \
+  -d "$PAYLOAD" \
+  -o "$RESP" 2>/dev/null) || true
+
+# 4. Validate response.
+if ! python3 - "$RESP" <<'PY'
+import json, sys
+d = json.load(open(sys.argv[1]))
+assert "choices" in d and d["choices"], "no choices"
+msg = d["choices"][0].get("message", {})
+assert msg.get("content") or msg.get("tool_calls"), "no content/tool_calls"
+PY
+then
+  echo "failed: no valid response from $BASE" > "$OUTDIR/status"
+  echo "failed" >&2; exit 1
+fi
+
+# 5. Extract verdict into a clean summary.
+python3 - "$RESP" <<'PY'
+import json, sys
+d = json.load(open(sys.argv[1]))
+msg = d["choices"][0]["message"]
+verdict = msg.get("content", "")
+summary = {
+    "verdict": verdict,
+    "model": d.get("model", ""),
+    "tool_calls": bool(msg.get("tool_calls")),
+    "usage": d.get("usage", {}),
+}
+with open(sys.argv[1], "w") as f:
+    json.dump(summary, f, indent=2)
+PY
+
+# 6. Observe the verdict into Mimirsbrunn (never a blocker).
+if [ -x "$ROOT/bin/mimir.sh" ]; then
+  VERDICT=$(python3 -c "import json; print(json.load(open('$RESP')).get('verdict',''))" 2>/dev/null || true)
+  [ -n "$VERDICT" ] && \
+    "$ROOT/bin/mimir.sh" observe "$VERDICT" \
+      --tags "apodex,research,verdict" \
+      --source "huginn-research-worker" \
+      2>/dev/null || true
+fi
+
+echo "completed" > "$OUTDIR/status"
+echo "completed: verdict written to $OUTDIR/response.json" >&2
+exit 0

package/bin/local-model-lock.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# local-model-lock.sh — serialize LOCAL model inference on one machine.
+#
+# Most machines cannot run several local models at once. This runs a command
+# under an exclusive lock so only one local inference is active per host (a
+# second invocation waits). Different machines are independent; a big box may
+# allow more via `local_concurrency` in config/agents.yaml.
+#
+#   bin/local-model-lock.sh <command...>
+#   local_concurrency: 1        # in config/agents.yaml (default 1)
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CFG="${YMIR_AGENTS_YAML:-$ROOT/config/agents.yaml}"
+LOCK="$ROOT/state/local-model.lock"
+WAIT="${LOCAL_MODEL_WAIT:-1800}"
+
+[ $# -gt 0 ] || { printf 'error: usage: bin/local-model-lock.sh <command...>\n' >&2; exit 2; }
+
+# How many local models this host may run at once (default 1).
+N="$(python3 - "$CFG" <<'PY' 2>/dev/null || echo 1
+import sys, yaml
+try:
+    d = yaml.safe_load(open(sys.argv[1])) or {}
+    v = d.get("local_concurrency", 1)
+    print(int(v) if str(v).isdigit() else 1)
+except Exception:
+    print(1)
+PY
+)"
+[ -n "$N" ] || N=1
+
+mkdir -p "$ROOT/state"
+
+if [ "$N" -le 1 ]; then
+  # one at a time — exclusive lock, wait for the peer to finish
+  command -v flock >/dev/null 2>&1 || { printf 'local-model-lock: flock missing; running unlocked\n' >&2; exec "$@"; }
+  echo "local-model-lock: acquired (concurrency=1)" >&2
+  exec flock -w "$WAIT" "$LOCK" "$@"
+else
+  # a big host: N slots — take the first free lock in the pool
+  command -v flock >/dev/null 2>&1 || exec "$@"
+  for i in $(seq 1 "$N"); do
+    if flock -n "$LOCK.$i" -c "true" 2>/dev/null; then
+      exec flock -w "$WAIT" "$LOCK.$i" "$@"
+    fi
+  done
+  echo "local-model-lock: all $N slots busy; waiting on slot 1" >&2
+  exec flock -w "$WAIT" "$LOCK.1" "$@"
+fi

package/bin/mimir-bridge.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""mimir-bridge.py — the HTTP face of the well (Mimirsbrunn / engram, :4602).
+
+The upstream engram engine ships a CLI and an MCP (stdio) server, but the rest
+of Ymir — the gate API, `bin/mimir.sh`, `bin/mimir-ingest.sh`, the session
+start — speaks a small HTTP contract on 127.0.0.1:4602. This bridge is that
+face: a long-lived HTTP server wrapping the `engram` library over one
+`.engram` store.
+
+Endpoints:
+  GET  /health                 -> {status, store, episodes, agents}
+  GET  /recall?q&k&mode        -> {results:[{score, distance, episode}]}
+  POST /observe {content,...}  -> {id}
+  GET  /timeline?entity=       -> {facts:[...]}
+  GET  /inspect                -> {episodes, agents, store}
+
+No secrets here; the store is repo-local. Stdlib only.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import threading
+from datetime import datetime
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+
+ROOT = Path(__file__).resolve().parent.parent
+STORE = Path(os.environ.get("ENGRAM_DB", str(ROOT / ".agents/memory/kaia.engram")))
+HOST = os.environ.get("MIMIRSBRUNN_HOST", "127.0.0.1")
+PORT = int(os.environ.get("MIMIRSBRUNN_PORT", os.environ.get("ENGRAM_PORT", "4602")))
+DEFAULT_AGENT = os.environ.get("ENGRAM_AGENT_ID", "kaia")
+
+from engram import Engram  # noqa: E402  (after env is read)
+
+_pool: dict[str, Engram] = {}
+_lock = threading.Lock()
+
+
+def engine(agent: str | None) -> Engram:
+    """One Engram instance per agent scope (writes are scoped at construction)."""
+    key = agent or "__all__"
+    with _lock:
+        if key not in _pool:
+            _pool[key] = Engram(path=str(STORE), agent_id=agent)
+        return _pool[key]
+
+
+def count_episodes() -> int:
+    try:
+        con = sqlite3.connect(f"file:{STORE}?mode=ro", uri=True)
+        try:
+            return int(con.execute("select count(*) from episodes").fetchone()[0])
+        finally:
+            con.close()
+    except Exception:
+        return 0
+
+
+def ep_json(e) -> dict:
+    return {
+        "id": e.id,
+        "content": e.content,
+        "timestamp": e.timestamp.isoformat() if e.timestamp else None,
+        "actors": list(e.actors or []),
+        "agents": list(e.actors or []),
+        "tags": list(e.tags or []),
+        "salience": e.salience,
+        "importance": e.importance_score,
+        "agent_id": getattr(e, "agent_id", None),
+    }
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, *_args):  # keep the bridge quiet
+        pass
+
+    def _json(self, code: int, payload: dict) -> None:
+        body = json.dumps(payload).encode()
+        self.send_response(code)
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self) -> None:  # noqa: N802
+        u = urlparse(self.path)
+        q = parse_qs(u.query)
+        try:
+            if u.path == "/health":
+                return self._json(200, {
+                    "status": "up",
+                    "store": str(STORE),
+                    "episodes": count_episodes(),
+                    "agents": engine(None).list_agents(),
+                })
+            if u.path == "/inspect":
+                return self._json(200, {
+                    "store": str(STORE),
+                    "episodes": count_episodes(),
+                    "agents": engine(None).list_agents(),
+                })
+            if u.path == "/recent":
+                limit = int((q.get("limit") or ["60"])[0])
+                out = []
+                try:
+                    con = sqlite3.connect(f"file:{STORE}?mode=ro", uri=True)
+                    con.row_factory = sqlite3.Row
+                    try:
+                        for r in con.execute(
+                            "select id, content, timestamp, tags, actors, agent_id "
+                            "from episodes order by timestamp desc limit ?",
+                            (limit,),
+                        ):
+                            out.append({
+                                "id": r["id"],
+                                "content": r["content"],
+                                "timestamp": r["timestamp"],
+                                "tags": json.loads(r["tags"] or "[]"),
+                                "actors": json.loads(r["actors"] or "[]"),
+                                "agent_id": r["agent_id"],
+                            })
+                    finally:
+                        con.close()
+                except Exception:
+                    pass
+                return self._json(200, {"episodes": out})
+            if u.path == "/episode":
+                eid = (q.get("id") or [""])[0]
+                if not eid:
+                    return self._json(400, {"error": "episode needs id"})
+                rec = None
+                try:
+                    con = sqlite3.connect(f"file:{STORE}?mode=ro", uri=True)
+                    con.row_factory = sqlite3.Row
+                    try:
+                        rec = con.execute(
+                            "select id, content, timestamp, tags, actors, agent_id from episodes where id = ?",
+                            (eid,),
+                        ).fetchone()
+                    finally:
+                        con.close()
+                except Exception:
+                    rec = None
+                if not rec:
+                    return self._json(404, {"error": "no such episode"})
+                return self._json(200, {"episode": {
+                    "id": rec["id"], "content": rec["content"], "timestamp": rec["timestamp"],
+                    "tags": json.loads(rec["tags"] or "[]"),
+                    "actors": json.loads(rec["actors"] or "[]"),
+                    "agent_id": rec["agent_id"],
+                }})
+            if u.path == "/recall":
+                query = (q.get("q") or [""])[0]
+                k = int((q.get("k") or ["5"])[0])
+                mode = (q.get("mode") or ["hybrid"])[0]
+                agent = (q.get("agent_id") or [None])[0]
+                cross = (q.get("cross_agent") or ["1"])[0] not in ("0", "false", "")
+                eng = engine(agent)
+                hits = eng.recall(query, k=k, mode=mode, cross_agent=cross)
+                return self._json(200, {
+                    "results": [
+                        {"score": r.score, "distance": r.distance, "importance": r.importance, "episode": ep_json(r.episode)}
+                        for r in hits
+                    ]
+                })
+            if u.path == "/timeline":
+                entity = (q.get("entity") or [""])[0]
+                facts = engine(None).timeline(entity)
+                return self._json(200, {
+                    "facts": [
+                        {
+                            "id": f.id, "subject": f.subject, "predicate": f.predicate, "object": f.object,
+                            "valid_from": f.valid_from.isoformat() if f.valid_from else None,
+                            "valid_to": f.valid_to.isoformat() if f.valid_to else None,
+                            "confidence": f.confidence,
+                        }
+                        for f in facts
+                    ]
+                })
+            return self._json(404, {"error": f"no route {u.path}"})
+        except Exception as exc:  # noqa: BLE001
+            return self._json(500, {"error": str(exc)})
+
+    def do_POST(self) -> None:  # noqa: N802
+        u = urlparse(self.path)
+        length = int(self.headers.get("content-length") or 0)
+        try:
+            body = json.loads(self.rfile.read(length) or b"{}")
+        except Exception:
+            body = {}
+        try:
+            if u.path in ("/observe", "/remember"):
+                content = str(body.get("content") or "").strip()
+                if not content:
+                    return self._json(400, {"error": "observe needs content"})
+                agent = body.get("agent_id") or body.get("source") or DEFAULT_AGENT
+                ts = body.get("timestamp")
+                when = datetime.fromisoformat(ts) if ts else None
+                eid = engine(agent).observe(
+                    content,
+                    actors=body.get("actors") or None,
+                    tags=body.get("tags") or None,
+                    salience=float(body.get("salience", 0.5)),
+                    timestamp=when,
+                )
+                return self._json(200, {"id": eid, "agent_id": agent, "episodes": count_episodes()})
+            return self._json(404, {"error": f"no route {u.path}"})
+        except Exception as exc:  # noqa: BLE001
+            return self._json(500, {"error": str(exc)})
+
+
+def main() -> None:
+    STORE.parent.mkdir(parents=True, exist_ok=True)
+    # Touch the store so the schema exists before the first request.
+    engine(None)
+    server = ThreadingHTTPServer((HOST, PORT), Handler)
+    print(f"[mimir-bridge] Mimirsbrunn {HOST}:{PORT} · store {STORE}", flush=True)
+    server.serve_forever()
+
+
+if __name__ == "__main__":
+    main()

package/bin/mimir-bridge.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# mimir-bridge.sh — raise/lower the well bridge (Mimirsbrunn on :4602).
+# The engram engine speaks CLI + MCP; this keeps its HTTP face alive so the gate
+# API, `bin/mimir.sh`, and the session start can drink from the well.
+#
+# Usage: bin/mimir-bridge.sh [--start|--stop|--status] [--port N]
+#        bin/mimir-bridge.sh --version
+set -u
+
+# --- portability shim: bin/ymir-platform.sh --------------------------------
+if [ -z "${YMIR_PLATFORM_LOADED:-}" ]; then
+  for _ymir_c in "$(git rev-parse --show-toplevel 2>/dev/null)/bin/ymir-platform.sh"                  "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd)/bin/ymir-platform.sh"; do
+    [ -n "$_ymir_c" ] && [ -r "$_ymir_c" ] && { . "$_ymir_c"; YMIR_PLATFORM_LOADED=1; break; }
+  done
+  unset _ymir_c
+fi
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
+BRIDGE="$ROOT/bin/mimir-bridge.py"
+DB="${ENGRAM_DB:-$YMIR_HOME/memory/kaia.engram}"
+PORT="${MIMIRSBRUNN_PORT:-4602}"
+PID_FILE="${YMIR_STATE_DIR:-$YMIR_HOME/state}/mimir-bridge.pid"
+LOG_FILE="${YMIR_STATE_DIR:-$YMIR_HOME/state}/mimir-bridge.log"
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help) sed -n '2,9p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+ACTION="start"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --start|"") ACTION=start; shift ;;
+    --stop) ACTION=stop; shift ;;
+    --status) ACTION=status; shift ;;
+    --port) PORT=${2-}; shift 2 ;;
+    *) printf 'error: unknown flag %s\nhelp: bin/mimir-bridge.sh [--start|--stop|--status]\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+listening() { (exec 3<>"/dev/tcp/127.0.0.1/$PORT") 2>/dev/null && return 0 || return 1; }
+
+case "$ACTION" in
+  status)
+    if listening; then printf 'well[1]{port,status}:\n  %s,"up"\n' "$PORT"; else printf 'well[1]{port,status}:\n  %s,"down"\n' "$PORT"; fi
+    exit 0 ;;
+  stop)
+    stopped=0
+    if [ -r "$PID_FILE" ]; then pid=$(tr -d '[:space:]' <"$PID_FILE"); if kill "$pid" 2>/dev/null; then stopped=1; fi; rm -f "$PID_FILE"; fi
+    if listening; then ymir_kill_matching "bin/mimir-bridge.py" 2>/dev/null && stopped=1; fi
+    if [ "$stopped" = 1 ]; then printf 'well: stopped\n'; else printf 'well: already stopped\n'; fi
+    exit 0 ;;
+esac
+
+if listening; then
+  pgrep -f "bin/mimir-bridge.py" >"$PID_FILE" 2>/dev/null || true
+  printf 'well[1]{port,status}:\n  %s,"already up"\n' "$PORT"
+  exit 0
+fi
+[ -e "$BRIDGE" ] || { printf 'error: bridge not found: %s\nhelp: expected bin/mimir-bridge.py\n' "$BRIDGE" >&2; exit 1; }
+# engram needs Python >=3.12,<3.14, which the system python may not be. Prefer a
+# recorded interpreter, then a compatible one on PATH, and only then python3.
+PY="${YMIR_ENGRAM_PYTHON:-}"
+if [ -z "$PY" ] && [ -r "${YMIR_ENGRAM_PY:-$HOME/.config/ymir/engram-python}" ]; then
+  PY="$(cat "${YMIR_ENGRAM_PY:-$HOME/.config/ymir/engram-python}" 2>/dev/null)"
+fi
+if [ -z "$PY" ]; then
+  for c in python3.12 python3.13; do command -v "$c" >/dev/null 2>&1 && { PY="$c"; break; }; done
+fi
+[ -n "$PY" ] || PY=python3
+
+if ! "$PY" -c "import engram" 2>/dev/null; then
+  printf 'error: engram not installed for %s\nhelp: bin/prereq-ensure.sh engram   (installs it into a compatible Python)\n' "$PY" >&2; exit 1
+fi
+
+mkdir -p "$ROOT/state" "$(dirname "$DB")"
+ENGRAM_DB="$DB" MIMIRSBRUNN_PORT="$PORT" nohup "$PY" "$BRIDGE" >"$LOG_FILE" 2>&1 &
+echo $! >"$PID_FILE"
+sleep 3
+if listening; then
+  printf 'well[1]{port,store,status}:\n  %s,"%s","started"\n' "$PORT" "${DB#"$ROOT"/}"
+else
+  printf 'error: well failed to start; see %s\n' "${LOG_FILE#"$ROOT"/}" >&2
+  exit 1
+fi