@zerwiz/ymir 0.1.4 → 0.1.7

package/bin/mimir-bridge.py

@@ -0,0 +1,259 @@
+#!/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 layers():
+    """What the well actually holds, layer by layer - the record a UI reads."""
+    out = {"facts": 0, "facts_active": 0, "facts_superseded": 0, "entities": 0,
+           "edges": 0, "reflections": 0, "last_reflection": None, "vec_index": 0}
+    try:
+        con = sqlite3.connect(f"file:{STORE}?mode=ro", uri=True)
+        for key, sql in (
+            ("facts", "select count(*) from facts"),
+            ("facts_active", "select count(*) from facts where superseded_at is null"),
+            ("facts_superseded", "select count(*) from facts where superseded_at is not null"),
+            ("entities", "select count(*) from entities"),
+            ("edges", "select count(*) from edges"),
+            ("reflections", "select count(*) from reflections"),
+            ("vec_index", "select count(*) from vec_episodes_rowids"),
+        ):
+            try:
+                out[key] = int(con.execute(sql).fetchone()[0])
+            except Exception:
+                pass
+        try:
+            out["last_reflection"] = con.execute(
+                "select max(finished_at) from reflections").fetchone()[0]
+        except Exception:
+            pass
+    except Exception as e:
+        out["error"] = str(e)
+    return out
+
+
+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":
+                # THE LAYERS, not just the count. The smithy shows what it is told,
+                # and it was told three fields while the well holds six: a panel that
+                # reads only episodes cannot show that facts and entities exist.
+                return self._json(200, {
+                    "store": str(STORE),
+                    "episodes": count_episodes(),
+                    "agents": engine(None).list_agents(),
+                    **layers(),
+                })
+            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,100 @@
+#!/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)"
+
+# The roots that live OUTSIDE the code tree: this machine's records and the
+# runtime state belong to the home the operator chose at installation, never in
+# the tree — a packaged install replaces its tree on upgrade (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_state_dir YMIR_STATE_DIR
+hoard_data_dir YMIR_DATA_DIR
+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 "$YMIR_STATE_DIR" "$(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

package/bin/mimir-ingest.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# mimir-ingest.sh — ingest the repo's data material into the well (Mimirsbrunn).
+#
+# Mímir drinks from the operator's business material — the hoard's
+# `docs/business/` (moved there from `assets/data/` by the hoard migration):
+# each Markdown section becomes an episode with
+# a content hash, tags, source, and timestamp. Episodes are appended to the local
+# well store (`.agents/memory/well/episodes.jsonl`) and POSTed to the engram
+# bridge (`MIMIRSBRUNN_URL`, default http://127.0.0.1:4602/observe) when it is
+# reachable. Idempotent by content hash. Galdr-style: TOON out, structured errors.
+#
+# Usage: bin/mimir-ingest.sh [--dry-run] [--path <file-or-dir>] [--quiet]
+#        bin/mimir-ingest.sh --version
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# shellcheck source=bin/hoard-lib.sh
+. "$SCRIPT_DIR/hoard-lib.sh"
+hoard_root HOARD
+# The business material lives in the hoard (private, untracked). Keep the old
+# location as a fallback so a pre-migration home still works.
+DATA="${BROKK_DATA_SOURCE:-$HOARD/docs/business}"
+[ -e "$DATA" ] || DATA="$ROOT/assets/data"
+STORE_DIR="$ROOT/.agents/memory/well"
+STORE="$STORE_DIR/episodes.jsonl"
+BRIDGE="${MIMIRSBRUNN_URL:-http://127.0.0.1:4602}"
+
+DRY=0; QUIET=0; SRC="$DATA"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+    -h|--help) sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    --dry-run) DRY=1; shift ;;
+    --quiet) QUIET=1; shift ;;
+    --path) SRC=${2-}; shift 2 ;;
+    *) printf 'error: unknown flag %s\nhelp: bin/mimir-ingest.sh [--dry-run|--path <p>|--quiet]\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+[ -e "$SRC" ] || { printf 'error: data path not found: %s\nhelp: pass --path, or put material in \$YMIR_HOARD/docs/business/\n' "$SRC"; exit 1; }
+
+mkdir -p "$STORE_DIR"
+[ -e "$STORE" ] || : >"$STORE"
+
+# Load every hash already in the store once, so dedupe is O(1) per section
+# instead of rescanning the whole store for each chunk (O(chunks x store)).
+declare -A SEEN_HASH
+while IFS= read -r _h; do [ -n "$_h" ] && SEEN_HASH["$_h"]=1; done < <(
+  grep -o '"hash":"[^"]*"' "$STORE" 2>/dev/null | cut -d'"' -f4
+)
+
+have_bridge=0
+if command -v curl >/dev/null 2>&1 && curl -fsS --max-time 2 "$BRIDGE/health" >/dev/null 2>&1; then
+  have_bridge=1
+fi
+
+declare -a FILE N ADD SKIP
+total_add=0; total_skip=0; files=0
+
+ingest_file() {
+  local file=$1 rel chunks=0 added=0 skipped=0 heading="" para="" line
+  rel="${file#"$ROOT"/}"
+  while IFS= read -r line; do
+    case "$line" in
+      \#*)
+        if [ -n "$heading" ] || [ -n "$para" ]; then
+          content=$(printf '%s\n\n%s' "$heading" "$para" | sed -e 's/[[:space:]]*$//')
+          if [ -n "$para" ]; then
+            hash=$(printf '%s' "$content" | sha256sum | cut -d' ' -f1)
+            if [ -n "${SEEN_HASH[$hash]:-}" ]; then
+              skipped=$((skipped + 1))
+            else
+              SEEN_HASH[$hash]=1
+              added=$((added + 1))
+              if [ "$DRY" = 0 ]; then
+                ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+                json=$(printf '{"timestamp":"%s","source":"%s","tags":["data"],"content":%s,"hash":"%s"}' \
+                  "$ts" "$rel" "$(printf '%s' "$content" | python3 -c 'import json,sys;print(json.dumps(sys.stdin.read()))')" "$hash")
+                printf '%s\n' "$json" >>"$STORE"
+                if [ "$have_bridge" = 1 ]; then
+                  curl -fsS --max-time 3 -X POST -H 'content-type: application/json' \
+                    -d "$json" "$BRIDGE/observe" >/dev/null 2>&1 || true
+                fi
+              fi
+            fi
+          fi
+          chunks=$((chunks + 1))
+        fi
+        heading="$line"
+        para=""
+        ;;
+      *) para="${para:+$para$'\n'}$line" ;;
+    esac
+  done <"$file"
+  # trailing section
+  if [ -n "$para" ]; then
+    content=$(printf '%s\n\n%s' "$heading" "$para" | sed -e 's/[[:space:]]*$//')
+    hash=$(printf '%s' "$content" | sha256sum | cut -d' ' -f1)
+    if [ -n "${SEEN_HASH[$hash]:-}" ]; then skipped=$((skipped + 1)); else
+      SEEN_HASH[$hash]=1
+      added=$((added + 1))
+      if [ "$DRY" = 0 ]; then
+        ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+        json=$(printf '{"timestamp":"%s","source":"%s","tags":["data"],"content":%s,"hash":"%s"}' \
+          "$ts" "$rel" "$(printf '%s' "$content" | python3 -c 'import json,sys;print(json.dumps(sys.stdin.read()))')" "$hash")
+        printf '%s\n' "$json" >>"$STORE"
+        [ "$have_bridge" = 1 ] && curl -fsS --max-time 3 -X POST -H 'content-type: application/json' -d "$json" "$BRIDGE/observe" >/dev/null 2>&1 || true
+      fi
+    fi
+    chunks=$((chunks + 1))
+  fi
+  FILE+=("$rel"); N+=("$chunks"); ADD+=("$added"); SKIP+=("$skipped")
+  total_add=$((total_add + added)); total_skip=$((total_skip + skipped)); files=$((files + 1))
+}
+
+if [ -d "$SRC" ]; then
+  while IFS= read -r f; do ingest_file "$f"; done < <(find "$SRC" -name '*.md' | sort)
+else
+  ingest_file "$SRC"
+fi
+
+if [ "$QUIET" = 0 ]; then
+  printf 'mimir_ingest[%s]{source,sections,added,skipped}:\n' "${#FILE[@]}"
+  for i in "${!FILE[@]}"; do
+    printf '  "%s",%s,%s,%s\n' "${FILE[$i]}" "${N[$i]}" "${ADD[$i]}" "${SKIP[$i]}"
+  done
+fi
+printf 'well: store=%s entries=%s bridge=%s\n' "${STORE#"$ROOT"/}" "$(wc -l <"$STORE" | tr -d ' ')" "$([ "$have_bridge" = 1 ] && echo online || echo offline)"
+printf 'help[1]: query the well with `bin/rodd-operational-input.sh` kinds / the Mimirsbrunn bridge\n'

package/bin/mimir-reflect.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# mimir-reflect — smelt the well's episodes into facts, through the LLAMA-ROUTER.
+#
+# The router is Ymir's one door to local models: its seats are llama.cpp on :8080
+# (coding) and Apodex on :1234 (research/planning). NEVER point this at Ollama —
+# ollama is the machine's own server, not a Ymir provider, and one local model
+# rides the router at a time. Swap seats by re-pointing the router, not by
+# reaching past it.
+#
+#   bin/mimir-reflect.sh              # the well, with the default seat
+#   YMIR_ROUTER_URL=http://127.0.0.1:8080/v1 YMIR_REFLECT_MODEL=qwen3.6-35b-a3b bin/mimir-reflect.sh
+set -euo pipefail
+
+WELL="${YMIR_WELL:-${YMIR_HOME:-$HOME/Documents/Ymir}/memory/kaia.engram}"
+BASE="${YMIR_ROUTER_URL:-http://127.0.0.1:1234/v1}"
+MODEL="${YMIR_REFLECT_MODEL:-apodex-1.0-mini}"
+
+[ -f "$WELL" ] || { echo "error: no well at $WELL" >&2; echo "help: set YMIR_WELL or run bin/mimir-bridge.py first" >&2; exit 1; }
+
+echo "mimir-reflect[well,seat]:"
+echo "  \"$WELL\""
+echo "  \"$BASE\"  model \"$MODEL\""
+echo
+
+# A local seat needs no key; an empty one keeps the OpenAI client quiet.
+OPENAI_API_KEY="${OPENAI_API_KEY:-local}" \
+  exec engram reflect "$WELL" --llm openai --model "$MODEL" --base-url "$BASE"

package/bin/mimir.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# mimir.sh — the well (Mimirsbrunn). Drink before you act, water it after.
+#
+# Talks to Kaia's engram bridge (:4602) when it is up; otherwise operates the
+# local well store (`.agents/memory/well/episodes.jsonl`). Galdr-style TOON.
+#
+# Usage:
+#   mimir.sh health
+#   mimir.sh recall <query> [--k N] [--mode hybrid|cosine|spreading]
+#   mimir.sh observe <text> [--tags a,b] [--source S]
+#   mimir.sh timeline [--entity X]
+#   mimir.sh --version
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
+WELL="${YMIR_MEMORY_DIR:-$YMIR_HOME/memory/well}/episodes.jsonl"
+BRIDGE="${MIMIRSBRUNN_URL:-http://127.0.0.1:4602}"
+
+usage() { sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; }
+
+CMD="${1-}"; shift || true
+case "$CMD" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") usage; exit 0 ;;
+esac
+[ -e "$WELL" ] || : >"$WELL"
+
+bridge_up() { command -v curl >/dev/null 2>&1 && curl -fsS --max-time 2 "$BRIDGE/health" >/dev/null 2>&1; }
+well_count() { wc -l <"$WELL" | tr -d ' '; }
+
+case "$CMD" in
+  health)
+    if bridge_up; then
+      printf 'well[1]{state,entries,bridge}:\n  "WARM",%s,"online"\n' "$(well_count)"
+    else
+      printf 'well[1]{state,entries,bridge}:\n  "COLD",%s,"offline"\n' "$(well_count)"
+    fi
+    ;;
+
+  recall)
+    Q="${1-}"; shift || true
+    K=5; MODE=hybrid
+    while [ $# -gt 0 ]; do case "$1" in --k) K=${2-5}; shift 2 ;; --mode) MODE=${2-hybrid}; shift 2 ;; *) shift ;; esac; done
+    [ -n "$Q" ] || { printf 'error: recall needs a query\nhelp: bin/mimir.sh recall "<query>"\n' >&2; exit 2; }
+    if bridge_up; then
+      out=$(curl -fsS --max-time 5 "$BRIDGE/recall?q=$(printf '%s' "$Q" | python3 -c 'import sys,urllib.parse;print(urllib.parse.quote(sys.stdin.read()))')&k=$K&mode=$MODE" 2>/dev/null)
+      [ -n "$out" ] && { printf '%s\n' "$out" | python3 -c 'import json,sys
+d=json.load(sys.stdin)
+rs=d.get("results",d if isinstance(d,list) else [])
+print(f"recall[{len(rs)}]{{score,source,title}}:")
+for r in rs[:20]:
+    e=r.get("episode",r); sc=r.get("score",0)
+    t=(e.get("content","").split("\n")[0] or "")[:90]
+    print(f"  {sc},{(e.get(\"agents\") or [\"well\"])[0]},{t}")' 2>/dev/null && exit 0; }
+    fi
+    # local fallback: substring search over the well
+    python3 - "$WELL" "$Q" "$K" <<'PY'
+import json,sys
+well,q,k=sys.argv[1],sys.argv[2].lower(),int(sys.argv[3])
+rows=[]
+for line in open(well, encoding='utf-8', errors='ignore'):
+    if not line.strip().startswith('{'): continue
+    try: e=json.loads(line)
+    except: continue
+    c=e.get('content','')
+    if q in c.lower(): rows.append((e,c))
+print(f"recall[{min(len(rows),k)}]{{score,source,title}}:")
+for e,c in rows[-k:][::-1]:
+    t=(c.split('\n')[0] or '').replace('#','').strip()[:90]
+    print(f"  0.5,\"{e.get('source','well')}\",\"{t}\"")
+PY
+    ;;
+
+  observe)
+    TEXT="${1-}"; shift || true
+    TAGS="runtime"; SRC="brokk"
+    while [ $# -gt 0 ]; do case "$1" in --tags) TAGS=${2-}; shift 2 ;; --source) SRC=${2-}; shift 2 ;; *) shift ;; esac; done
+    [ -n "$TEXT" ] || { printf 'error: observe needs text\nhelp: bin/mimir.sh observe "<text>"\n' >&2; exit 2; }
+    json=$(printf '%s' "$TEXT" | python3 -c 'import json,sys,hashlib,datetime
+t=sys.stdin.read()
+print(json.dumps({"timestamp":datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),"source":"'"$SRC"'","tags":"'"$TAGS"'".split(","),"content":t,"hash":hashlib.sha256(t.encode()).hexdigest()}))')
+    printf '%s\n' "$json" >>"$WELL"
+    if bridge_up; then curl -fsS --max-time 3 -X POST -H 'content-type: application/json' -d "$json" "$BRIDGE/observe" >/dev/null 2>&1 || true; fi
+    printf 'observed[1]{source,tags,bridge}:\n  "%s","%s","%s"\n' "$SRC" "$TAGS" "$(bridge_up && echo online || echo local)"
+    ;;
+
+  timeline)
+    ENTITY=""; while [ $# -gt 0 ]; do case "$1" in --entity) ENTITY=${2-}; shift 2 ;; *) shift ;; esac; done
+    if bridge_up && [ -n "$ENTITY" ]; then
+      curl -fsS --max-time 5 "$BRIDGE/timeline?entity=$(printf '%s' "$ENTITY" | python3 -c 'import sys,urllib.parse;print(urllib.parse.quote(sys.stdin.read()))')" 2>/dev/null && exit 0
+    fi
+    python3 - "$WELL" <<'PY'
+import json,sys
+rows=[]
+for line in open(sys.argv[1], encoding='utf-8', errors='ignore'):
+    if not line.strip().startswith('{'): continue
+    try: e=json.loads(line)
+    except: continue
+    rows.append(e)
+print(f"timeline[{min(len(rows),20)}]{{ts,source,title}}:")
+for e in rows[-20:][::-1]:
+    t=(e.get('content','').split('\n')[0] or '').replace('#','').strip()[:80]
+    print(f"  \"{e.get('timestamp','')}\",\"{e.get('source','well')}\",\"{t}\"")
+PY
+    ;;
+
+  *)
+    printf 'error: unknown command %s\nhelp: bin/mimir.sh [health|recall|observe|timeline|--version]\n' "$CMD" >&2
+    exit 2 ;;
+esac