loki-mode 6.82.0 → 6.83.0

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Multi-agent autonomous startup system. Triggers on "Loki Mode". Takes PRD to deployed product with minimal human intervention. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v6.82.0
+# Loki Mode v6.83.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -269,4 +269,4 @@ The following features are documented in skill modules but not yet fully automat
 | Quality gates 3-reviewer system | Implemented (v5.35.0) | 5 specialist reviewers in `skills/quality-gates.md`; execution in run.sh |
 | Benchmarks (HumanEval, SWE-bench) | Infrastructure only | Runner scripts and datasets exist in `benchmarks/`; no published results |
 
-**v6.82.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v6.83.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-6.82.0
+6.83.0

package/autonomy/completion-council.sh

@@ -72,6 +72,38 @@ COUNCIL_DONE_SIGNALS=0
 COUNCIL_TOTAL_DONE_SIGNALS=0
 COUNCIL_LAST_DIFF_HASH=""
 
+#===============================================================================
+# v6.83.0 Phase 1: Managed Agents memory augmentation (opt-in).
+#
+# When LOKI_MANAGED_AGENTS=true AND LOKI_MANAGED_MEMORY=true, this function
+# pulls up to 3 related prior verdicts from the Claude Managed Agents store
+# and writes them to a file the council prompt-assembly step appends as
+# "RELATED PRIOR VERDICTS". 5s hard timeout so a slow/unreachable API can
+# never block the council. Silent no-op when the flags are off.
+#===============================================================================
+council_augment_from_managed_memory() {
+    if [ "${LOKI_MANAGED_AGENTS:-false}" != "true" ] || \
+       [ "${LOKI_MANAGED_MEMORY:-false}" != "true" ]; then
+        return 0
+    fi
+    local target_dir="${TARGET_DIR:-.}"
+    local project_dir="${PROJECT_DIR:-$(pwd)}"
+    local out_file="$target_dir/.loki/managed/council-augment.txt"
+    mkdir -p "$target_dir/.loki/managed" 2>/dev/null || true
+    (
+        cd "$project_dir" 2>/dev/null && \
+        LOKI_TARGET_DIR="$target_dir" \
+        timeout 5 python3 -m memory.managed_memory.retrieve \
+            --query "completion-council verdict context" --top-k 3 \
+            > "$out_file" 2>/dev/null || true
+    ) || true
+    if [ -s "$out_file" ]; then
+        echo "RELATED PRIOR VERDICTS:"
+        cat "$out_file"
+    fi
+    return 0
+}
+
 #===============================================================================
 # Initialization
 #===============================================================================
@@ -1366,6 +1398,11 @@ council_should_stop() {
         return 1
     fi
 
+    # v6.83.0 Phase 1: silent no-op unless both managed flags are on.
+    # Writes related prior verdicts into $TARGET_DIR/.loki/managed/council-augment.txt
+    # which the council prompt assembly step can read and append to its prompt.
+    council_augment_from_managed_memory >/dev/null 2>&1 || true
+
     # Check circuit breaker first (stagnation detection)
     local circuit_triggered=false
     if council_circuit_breaker_triggered; then
@@ -1396,6 +1433,27 @@ council_should_stop() {
         # Store final council report
         council_write_report
 
+        # v6.83.0 Phase 1: shadow-write the final council verdict to the
+        # managed memory store. Backgrounded + silent; flags gate the work
+        # inside the Python module so no-op when off.
+        if [ "${LOKI_MANAGED_AGENTS:-false}" = "true" ] && \
+           [ "${LOKI_MANAGED_MEMORY:-false}" = "true" ]; then
+            local _verdict_file="$loki_dir/council/verdicts/iteration-$ITERATION_COUNT.json"
+            if [ ! -f "$_verdict_file" ]; then
+                # Fall back to the round vote file as the verdict payload.
+                _verdict_file="$COUNCIL_STATE_DIR/votes/round-${ITERATION_COUNT}.json"
+            fi
+            if [ -f "$_verdict_file" ]; then
+                (
+                    cd "${PROJECT_DIR:-$(pwd)}" 2>/dev/null && \
+                    LOKI_TARGET_DIR="$loki_dir/.." \
+                    timeout 15 python3 -m memory.managed_memory.shadow_write \
+                        --verdict "$_verdict_file" >/dev/null 2>&1 || true
+                ) &
+                disown 2>/dev/null || true
+            fi
+        fi
+
         return 0  # STOP
     fi
 

package/autonomy/run.sh

@@ -644,6 +644,19 @@ LOKI_SESSION_MODEL="${LOKI_SESSION_MODEL:-sonnet}"
 LOKI_LEGACY_TIER_SWITCHING="${LOKI_LEGACY_TIER_SWITCHING:-false}"
 export LOKI_SESSION_MODEL LOKI_LEGACY_TIER_SWITCHING
 
+# Managed Agents (v6.83.0 Phase 1): opt-in integration with Claude Managed Agents
+# Memory store backend. Parent flag gates everything; child flags gate features.
+# Both off (default) => zero behavior change from v6.82.0.
+LOKI_MANAGED_AGENTS="${LOKI_MANAGED_AGENTS:-false}"
+LOKI_MANAGED_MEMORY="${LOKI_MANAGED_MEMORY:-false}"
+export LOKI_MANAGED_AGENTS LOKI_MANAGED_MEMORY
+
+# Fail-fast: child on with parent off is a misconfiguration.
+if [ "$LOKI_MANAGED_MEMORY" = "true" ] && [ "$LOKI_MANAGED_AGENTS" != "true" ]; then
+    echo "ERROR: LOKI_MANAGED_MEMORY=true requires LOKI_MANAGED_AGENTS=true" >&2
+    exit 2
+fi
+
 # Parallel Workflows (Git Worktrees)
 PARALLEL_MODE=${LOKI_PARALLEL_MODE:-false}
 MAX_WORKTREES=${LOKI_MAX_WORKTREES:-5}
@@ -7977,6 +7990,32 @@ try:
 except Exception as e:
     pass  # Silently fail if memory not available
 PYEOF
+
+    # v6.83.0 Phase 1: RARV-C REASON augment. When both managed flags are on,
+    # pull related prior verdicts from the Claude Managed Agents store and
+    # append them AFTER local results. 5s hard timeout so a slow remote never
+    # blocks the loop. On timeout or error, emit a fallback event and continue.
+    if [ "$LOKI_MANAGED_AGENTS" = "true" ] && [ "$LOKI_MANAGED_MEMORY" = "true" ]; then
+        local managed_start_ms
+        managed_start_ms=$(python3 -c "import time; print(int(time.time()*1000))" 2>/dev/null || echo "0")
+        local managed_out
+        managed_out=$(
+            cd "$PROJECT_DIR" 2>/dev/null && \
+            LOKI_TARGET_DIR="$target_dir" \
+            timeout 5 python3 -m memory.managed_memory.retrieve \
+                --query "$goal" --top-k 3 2>/dev/null || true
+        )
+        if [ -n "$managed_out" ]; then
+            echo ""
+            echo "RELATED PRIOR LEARNINGS (managed store):"
+            echo "$managed_out"
+        else
+            # No output could mean: flags off (unreachable here), timeout, or
+            # zero hits. Emit a fallback event only if a timeout likely occurred.
+            LOKI_TARGET_DIR="$target_dir" \
+            python3 -c "from memory.managed_memory.events import emit_managed_event; emit_managed_event('managed_memory_retrieve_empty', {'phase': '$phase'})" 2>/dev/null || true
+        fi
+    fi
 }
 
 # Store episode trace after task completion
@@ -8080,14 +8119,21 @@ auto_capture_episode() {
     fi
 
     # Pass all context via environment variables (prevents injection)
+    # v6.83.0: also stash the resolved episode path so the bash caller can
+    # optionally shadow-write it to the managed store if importance >= 0.6.
+    local episode_path_file="/tmp/loki-episode-path-$$"
+    : > "$episode_path_file"
     _LOKI_PROJECT_DIR="$PROJECT_DIR" _LOKI_TARGET_DIR="$target_dir" \
     _LOKI_ITERATION="$iteration" _LOKI_EXIT_CODE="$exit_code" \
     _LOKI_RARV_PHASE="$rarv_phase" _LOKI_GOAL="$goal" \
     _LOKI_DURATION="$duration" _LOKI_OUTCOME="$outcome" \
     _LOKI_FILES_MODIFIED="$files_modified" _LOKI_GIT_COMMIT="$git_commit" \
+    _LOKI_EPISODE_PATH_FILE="$episode_path_file" \
     python3 << 'PYEOF' 2>/dev/null || true
 import sys
 import os
+import json
+from pathlib import Path
 
 project_dir = os.environ.get('_LOKI_PROJECT_DIR', '')
 target_dir = os.environ.get('_LOKI_TARGET_DIR', '.')
@@ -8098,6 +8144,7 @@ duration = os.environ.get('_LOKI_DURATION', '0')
 outcome = os.environ.get('_LOKI_OUTCOME', 'success')
 files_modified = os.environ.get('_LOKI_FILES_MODIFIED', '')
 git_commit = os.environ.get('_LOKI_GIT_COMMIT', '')
+path_out_file = os.environ.get('_LOKI_EPISODE_PATH_FILE', '')
 
 sys.path.insert(0, project_dir)
 try:
@@ -8120,9 +8167,47 @@ try:
     trace.files_modified = [f for f in files_modified.split('|') if f] if files_modified else []
 
     engine.store_episode(trace)
+
+    # v6.83.0: surface the on-disk episode path + importance so bash can
+    # decide whether to shadow-write. Writing to a known file (not stdout)
+    # keeps the existing stdout contract intact.
+    try:
+        importance = float(getattr(trace, 'importance', 0.0) or 0.0)
+    except (TypeError, ValueError):
+        importance = 0.0
+    episode_file = Path(f'{target_dir}/.loki/memory/episodic') / f'{trace.id}.json'
+    if path_out_file:
+        try:
+            with open(path_out_file, 'w', encoding='utf-8') as f:
+                json.dump({'path': str(episode_file), 'importance': importance}, f)
+        except OSError:
+            pass
 except Exception:
     pass  # Silently fail -- memory capture must never break the loop
 PYEOF
+
+    # v6.83.0 Phase 1: RARV-C REFLECT/VERIFY shadow-write. Only when both
+    # managed flags are on AND the episode meets the consolidation importance
+    # threshold (>= 0.6). Fully non-blocking (backgrounded subprocess).
+    if [ "$LOKI_MANAGED_AGENTS" = "true" ] && [ "$LOKI_MANAGED_MEMORY" = "true" ] \
+        && [ -s "$episode_path_file" ]; then
+        local _ep_path _ep_imp
+        _ep_path=$(python3 -c "import json,sys; d=json.load(open(sys.argv[1])); print(d.get('path',''))" "$episode_path_file" 2>/dev/null || echo "")
+        _ep_imp=$(python3 -c "import json,sys; d=json.load(open(sys.argv[1])); print(d.get('importance',0.0))" "$episode_path_file" 2>/dev/null || echo "0")
+        if [ -n "$_ep_path" ] && [ -f "$_ep_path" ]; then
+            local _above_threshold
+            _above_threshold=$(python3 -c "print('yes' if float('$_ep_imp') >= 0.6 else 'no')" 2>/dev/null || echo "no")
+            if [ "$_above_threshold" = "yes" ]; then
+                (
+                    cd "$PROJECT_DIR" 2>/dev/null && \
+                    LOKI_TARGET_DIR="$target_dir" \
+                    timeout 15 python3 -m memory.managed_memory.shadow_write --path "$_ep_path" >/dev/null 2>&1 || true
+                ) &
+                disown 2>/dev/null || true
+            fi
+        fi
+    fi
+    rm -f "$episode_path_file" 2>/dev/null || true
 }
 
 # Run memory consolidation pipeline

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "6.82.0"
+__version__ = "6.83.0"
 
 # Expose the control app for easy import
 try:

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Complete installation instructions for all platforms and use cases.
 
-**Version:** v6.82.0
+**Version:** v6.83.0
 
 ---
 

package/mcp/__init__.py

@@ -57,4 +57,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '6.82.0'
+__version__ = '6.83.0'

package/mcp/requirements.txt

@@ -1,2 +1,3 @@
 mcp>=1.0.0
 chromadb>=1.0.0
+anthropic>=0.40

package/memory/managed_memory/__init__.py

@@ -0,0 +1,113 @@
+"""
+Loki Managed Agents Memory package (v6.83.0 Phase 1).
+
+Opt-in integration with Claude Managed Agents memory stores. All behavior in
+this package is gated on the two environment variables:
+
+    LOKI_MANAGED_AGENTS   parent switch (default: false)
+    LOKI_MANAGED_MEMORY   child switch  (default: false)
+
+Both must be "true" for any API call to be issued. If the child is "true" while
+the parent is "false", the loki runner fails fast at startup (see
+autonomy/run.sh). If the flags are off, every exported function is a cheap
+no-op -- importing this package will NOT trigger any network or SDK import
+side-effects.
+
+This package is intentionally the ONLY place in the codebase that imports the
+`anthropic` SDK. A CI test (tests/managed_memory/test_sdk_isolation.sh)
+enforces that invariant.
+
+Exports:
+    is_enabled()                - bool, True iff both flags are on
+    ManagedDisabled             - raised when callers try to force an op while off
+    shadow_write_verdict(path)  - shadow-write a council verdict JSON to the store
+    shadow_write_pattern(obj)   - shadow-write a semantic pattern dict
+    retrieve_related_verdicts(q, top_k=3, store_id=None)
+                                - return list of related prior verdicts
+    hydrate_patterns(mtime_floor)
+                                - pull recent patterns and merge locally
+    probe_beta_header()         - return the active beta header string
+    emit_managed_event(type, payload)
+                                - low-level event writer
+
+None of these functions raise on SDK or network errors. They return empty /
+None and log one WARN line. Real SDK errors surface through
+`.loki/managed/events.ndjson`.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from ._beta import BETA_HEADER
+from .events import emit_managed_event
+
+
+class ManagedDisabled(Exception):
+    """Raised when a managed-memory operation is attempted while flags are off."""
+
+
+def is_enabled() -> bool:
+    """True iff LOKI_MANAGED_AGENTS=true AND LOKI_MANAGED_MEMORY=true."""
+    parent = os.environ.get("LOKI_MANAGED_AGENTS", "").strip().lower() == "true"
+    child = os.environ.get("LOKI_MANAGED_MEMORY", "").strip().lower() == "true"
+    return parent and child
+
+
+def probe_beta_header() -> str:
+    """Return the pinned managed-agents beta header."""
+    return BETA_HEADER
+
+
+# Lazy re-exports. Importing the top-level package MUST NOT import the
+# anthropic SDK, so we defer the real imports until the functions are called.
+
+
+def shadow_write_verdict(verdict_json_path: str) -> None:
+    """Shadow-write a council verdict file to the managed store (opt-in)."""
+    if not is_enabled():
+        return None
+    from . import shadow_write as _sw  # local import: gated on flags
+    return _sw.shadow_write_verdict(verdict_json_path)
+
+
+def shadow_write_pattern(pattern: dict) -> None:
+    """Shadow-write a semantic pattern dict to the managed store (opt-in)."""
+    if not is_enabled():
+        return None
+    from . import shadow_write as _sw
+    return _sw.shadow_write_pattern(pattern)
+
+
+def retrieve_related_verdicts(
+    query: str,
+    top_k: int = 3,
+    store_id: Optional[str] = None,
+):
+    """Return related verdicts from the managed store; [] when disabled or on error."""
+    if not is_enabled():
+        return []
+    from . import retrieve as _r
+    return _r.retrieve_related_verdicts(query, top_k=top_k, store_id=store_id)
+
+
+def hydrate_patterns(local_mtime_floor: float):
+    """Pull semantic patterns updated after floor; no-op when disabled."""
+    if not is_enabled():
+        return None
+    from . import retrieve as _r
+    return _r.hydrate_patterns(local_mtime_floor)
+
+
+__all__ = [
+    "BETA_HEADER",
+    "ManagedDisabled",
+    "emit_managed_event",
+    "hydrate_patterns",
+    "is_enabled",
+    "probe_beta_header",
+    "retrieve_related_verdicts",
+    "shadow_write_pattern",
+    "shadow_write_verdict",
+]

package/memory/managed_memory/_beta.py

@@ -0,0 +1,11 @@
+"""
+Loki Managed Agents Memory - Beta Header (v6.83.0 Phase 1).
+
+Single source of truth for the anthropic-beta header required by Claude
+Managed Agents. All callers in memory/managed_memory/ import BETA_HEADER
+from here. Update this constant to roll to a new beta.
+"""
+
+# Pin to the public Managed Agents beta channel current as of v6.83.0.
+# This value is sent as the `anthropic-beta` HTTP header on every request.
+BETA_HEADER = "managed-agents-2026-04-01"

package/memory/managed_memory/client.py

@@ -0,0 +1,210 @@
+"""
+Loki Managed Agents Memory - Client wrapper (v6.83.0 Phase 1).
+
+Thin wrapper around the `anthropic` SDK. This is the ONLY file in the codebase
+that imports `anthropic`. A CI invariant test enforces that.
+
+The wrapper:
+    - Sets anthropic-beta: managed-agents-2026-04-01 on every request.
+    - Reads ANTHROPIC_API_KEY from env. Absence raises ManagedDisabled.
+    - Wraps every SDK call in a 10s hard timeout. Timeouts are treated as
+      recoverable: the caller decides whether to fall back.
+    - Never retries inside the client (no retry-storm). Callers implement
+      bounded retry (e.g. 409 precondition merge-and-retry-once).
+
+NOTE on API surface: the exact Managed Agents memory endpoints are under a
+beta channel. This wrapper implements a minimal, forward-compatible subset --
+stores_list, stores_get_or_create, memory_create, memory_read, memories_list.
+If the SDK version installed does not expose `beta.memory`, calls raise an
+AttributeError which the callers translate into a ManagedDisabled/fallback.
+
+Not tested end-to-end against a live ANTHROPIC_API_KEY in CI. Automated tests
+use memory/managed_memory/fakes.py.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import threading
+from typing import Any, Dict, List, Optional
+
+from . import ManagedDisabled
+from ._beta import BETA_HEADER
+
+_DEFAULT_TIMEOUT = 10.0  # seconds
+
+
+def _check_flags_or_raise() -> None:
+    parent = os.environ.get("LOKI_MANAGED_AGENTS", "").strip().lower() == "true"
+    child = os.environ.get("LOKI_MANAGED_MEMORY", "").strip().lower() == "true"
+    if not (parent and child):
+        raise ManagedDisabled(
+            "managed memory flags are off "
+            "(LOKI_MANAGED_AGENTS and LOKI_MANAGED_MEMORY must both be 'true')"
+        )
+
+
+def _require_api_key() -> str:
+    key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+    if not key:
+        raise ManagedDisabled("ANTHROPIC_API_KEY is not set")
+    return key
+
+
+def compute_sha256(content: str) -> str:
+    """Stable content hash used as an optimistic precondition on writes."""
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+class ManagedClient:
+    """
+    Thin SDK wrapper. Instantiating this class imports anthropic and validates
+    credentials; callers should construct it lazily inside flag-gated paths.
+    """
+
+    def __init__(self, timeout: float = _DEFAULT_TIMEOUT) -> None:
+        _check_flags_or_raise()
+        api_key = _require_api_key()
+        # Import lazily so the top-level package stays SDK-free.
+        try:
+            import anthropic  # noqa: F401  (imported for side-effects + symbol)
+        except ImportError as e:  # pragma: no cover - import surface
+            raise ManagedDisabled(f"anthropic SDK not installed: {e}")
+
+        self._anthropic = anthropic
+        self._client = anthropic.Anthropic(
+            api_key=api_key,
+            timeout=timeout,
+            default_headers={"anthropic-beta": BETA_HEADER},
+        )
+        self._timeout = timeout
+
+    # ---------- helpers -------------------------------------------------
+
+    def _beta(self):
+        """Return the beta namespace, if the SDK exposes it.
+
+        Newer SDK versions expose `client.beta.memory.*`. If the attribute
+        path is missing we raise ManagedDisabled so callers can fall back.
+        """
+        beta = getattr(self._client, "beta", None)
+        if beta is None:
+            raise ManagedDisabled("anthropic SDK missing `beta` namespace")
+        return beta
+
+    # ---------- stores --------------------------------------------------
+
+    def stores_list(self) -> List[Dict[str, Any]]:
+        """List managed memory stores on this account (may be empty)."""
+        beta = self._beta()
+        stores = getattr(beta, "memory_stores", None) or getattr(beta, "stores", None)
+        if stores is None or not hasattr(stores, "list"):
+            raise ManagedDisabled("memory_stores API not available in SDK")
+        result = stores.list()
+        # SDK returns a pydantic model; normalize to list of dicts.
+        data = getattr(result, "data", result)
+        return [self._to_dict(x) for x in (data or [])]
+
+    def stores_get_or_create(
+        self, name: str, description: str = "", scope: str = "project"
+    ) -> Dict[str, Any]:
+        """Return existing store with `name` or create it."""
+        existing = [s for s in self.stores_list() if s.get("name") == name]
+        if existing:
+            return existing[0]
+        beta = self._beta()
+        stores = getattr(beta, "memory_stores", None) or getattr(beta, "stores", None)
+        if stores is None or not hasattr(stores, "create"):
+            raise ManagedDisabled("memory_stores.create not available in SDK")
+        created = stores.create(name=name, description=description, scope=scope)
+        return self._to_dict(created)
+
+    # ---------- memories ------------------------------------------------
+
+    def memory_create(
+        self,
+        store_id: str,
+        path: str,
+        content: str,
+        sha256_precondition: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Create a memory entry at `path` in `store_id`.
+
+        When sha256_precondition is supplied, this is an optimistic
+        concurrency hint: if the store already holds a different hash the
+        SDK is expected to surface a 409-shaped error. Callers handle the
+        409 by re-reading, merging, and retrying once.
+        """
+        beta = self._beta()
+        memories = getattr(beta, "memories", None)
+        if memories is None or not hasattr(memories, "create"):
+            raise ManagedDisabled("memories.create not available in SDK")
+        kwargs: Dict[str, Any] = {
+            "store_id": store_id,
+            "path": path,
+            "content": content,
+        }
+        if sha256_precondition:
+            kwargs["if_match_sha256"] = sha256_precondition
+        created = memories.create(**kwargs)
+        return self._to_dict(created)
+
+    def memory_read(self, store_id: str, memory_id: str) -> Dict[str, Any]:
+        beta = self._beta()
+        memories = getattr(beta, "memories", None)
+        if memories is None or not hasattr(memories, "retrieve"):
+            raise ManagedDisabled("memories.retrieve not available in SDK")
+        got = memories.retrieve(store_id=store_id, memory_id=memory_id)
+        return self._to_dict(got)
+
+    def memories_list(
+        self, store_id: str, path_prefix: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        beta = self._beta()
+        memories = getattr(beta, "memories", None)
+        if memories is None or not hasattr(memories, "list"):
+            raise ManagedDisabled("memories.list not available in SDK")
+        kwargs: Dict[str, Any] = {"store_id": store_id}
+        if path_prefix:
+            kwargs["path_prefix"] = path_prefix
+        result = memories.list(**kwargs)
+        data = getattr(result, "data", result)
+        return [self._to_dict(x) for x in (data or [])]
+
+    # ---------- internal ------------------------------------------------
+
+    @staticmethod
+    def _to_dict(obj: Any) -> Dict[str, Any]:
+        """Best-effort pydantic-or-dict to dict conversion."""
+        if isinstance(obj, dict):
+            return obj
+        to_dict = getattr(obj, "model_dump", None) or getattr(obj, "dict", None)
+        if callable(to_dict):
+            try:
+                return to_dict()
+            except TypeError:
+                return to_dict()
+        return {"raw": str(obj)}
+
+
+# Optional helper for callers that want a thread-safe singleton.
+_singleton: Optional[ManagedClient] = None
+_singleton_lock = threading.Lock()
+
+
+def get_client() -> ManagedClient:
+    """Return a lazily-constructed singleton. Raises ManagedDisabled if off."""
+    global _singleton
+    with _singleton_lock:
+        if _singleton is None:
+            _singleton = ManagedClient()
+        return _singleton
+
+
+def reset_client() -> None:
+    """Test hook: drop the cached singleton so tests can swap implementations."""
+    global _singleton
+    with _singleton_lock:
+        _singleton = None

package/memory/managed_memory/events.py

@@ -0,0 +1,79 @@
+"""
+Loki Managed Agents Memory - Event emission (v6.83.0 Phase 1).
+
+Appends structured JSONL events to .loki/managed/events.ndjson. Single-writer
+convention: only code in memory/managed_memory/ writes to this file. Rotates
+when the file exceeds 10MB.
+
+Events are used to record fallbacks, shadow-write successes/failures, and
+retrieve hits. The file is safe to tail for observability during development.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+# 10 MB rotation threshold. Keeping rotation simple: rename to .<YYYYMMDD>.
+_ROTATE_BYTES = 10 * 1024 * 1024
+
+
+def _events_dir(target_dir: Optional[str] = None) -> Path:
+    base = target_dir or os.environ.get("LOKI_TARGET_DIR") or os.getcwd()
+    return Path(base) / ".loki" / "managed"
+
+
+def _maybe_rotate(path: Path) -> None:
+    """Rotate the events file if it has exceeded the size threshold."""
+    try:
+        if path.exists() and path.stat().st_size >= _ROTATE_BYTES:
+            stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+            rotated = path.with_suffix(path.suffix + f".{stamp}")
+            # Best-effort rename; if another writer got there first, move on.
+            try:
+                path.rename(rotated)
+            except OSError:
+                pass
+    except OSError:
+        # If stat fails, skip rotation; next write will retry.
+        pass
+
+
+def emit_managed_event(
+    event_type: str,
+    payload: Dict[str, Any],
+    target_dir: Optional[str] = None,
+) -> None:
+    """
+    Append a managed-memory event to .loki/managed/events.ndjson.
+
+    Never raises: on any I/O error the function silently returns. Callers
+    rely on this to keep the main RARV-C loop unblocked.
+
+    Args:
+        event_type: short tag, e.g. "managed_agents_fallback",
+            "managed_memory_retrieve", "managed_memory_shadow_write".
+        payload: JSON-serializable context for the event.
+        target_dir: optional project root override. Defaults to
+            LOKI_TARGET_DIR env or cwd.
+    """
+    try:
+        dir_path = _events_dir(target_dir)
+        dir_path.mkdir(parents=True, exist_ok=True)
+        path = dir_path / "events.ndjson"
+        _maybe_rotate(path)
+
+        record = {
+            "ts": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+            "type": event_type,
+            "payload": payload,
+        }
+        # Line-buffered append; JSONL.
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record, default=str) + "\n")
+    except Exception:
+        # Never raise from the event emitter.
+        return