mimir-agent 0.1.0__tar.gz

mimir_agent-0.1.0/.gitignore

@@ -0,0 +1,72 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Tools
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tool-versions
+
+# IDE
+.vscode/
+.idea/
+*.iml
+*.swp
+*.swo
+
+# Claude Code per-project settings (operator/host-specific permissions,
+# allowlists, and hooks — not part of the package contract).
+.claude/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Mimir runtime artifacts (only meaningful inside an agent home, never in the
+# package source — but the smoke-test harness occasionally drops them here).
+home/
+*.db
+*.db-shm
+*.db-wal
+*.tar.gz
+
+# v0.5 §3: saga's bench data + LongMemEval source are symlinks/dirs
+# pointing at large datasets that don't belong in git (msam2's .gitignore
+# had the same exclusions; preserved post-merge).
+/saga/data
+# saga/external is now vendored (the LongMemEval eval harness lives under
+# saga/external/longmemeval/ — see its PROVENANCE.md). Specific subdirs
+# that are too big or transient stay ignored.
+/saga/external/hindsight
+/saga/results
+# Integration bench output (per-run hypothesis JSONLs + scratch mimir homes).
+/results/
+/benchmarks/longmemeval_via_mimir/results/
+
+# Agent home dotenv (in case a smoke run spits one out at workspace root).
+.env
+
+# Local scratch / spike / backtest artifacts. Keep WIP scripts and
+# one-shot data dumps out of the repo (e.g. commitments-extraction
+# backtest results, throwaway profiling output).
+/scratch/
+
+# Runtime agent state. ``state/`` is per-deployment and accumulates
+# identity bindings, spec results, proposed-change drafts, wiki topics,
+# etc. — none of which belongs in source control. A fresh agent home
+# generates its own ``state/`` on first run.
+/state/

mimir_agent-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Jason Carreira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+----
+
+The saga/ subdirectory is independently MIT-licensed (combined copyright
+Jaden Schwab + Jason Carreira). See saga/LICENSE.

mimir_agent-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: mimir-agent
+Version: 0.1.0
+Summary: Memory-centric agent harness on deepagents / LangGraph
+Author: Jason Carreira
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.12
+Requires-Dist: apscheduler>=3.11
+Requires-Dist: deepagents>=0.6.1
+Requires-Dist: fastembed>=0.4
+Requires-Dist: langchain>=1.3
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.33.1
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic>=1.4; extra == 'anthropic'
+Provides-Extra: bench
+Requires-Dist: saga; extra == 'bench'
+Provides-Extra: codex-plus
+Requires-Dist: langchain-codex-plus<0.1,>=0.0.1; extra == 'codex-plus'
+Provides-Extra: dev
+Requires-Dist: discord-py>=2.6; extra == 'dev'
+Requires-Dist: faiss-cpu>=1.13; extra == 'dev'
+Requires-Dist: langchain-anthropic>=1.4; extra == 'dev'
+Requires-Dist: langchain-codex-plus<0.1,>=0.0.1; extra == 'dev'
+Requires-Dist: langchain-openai>=1.2.1; extra == 'dev'
+Requires-Dist: mcp>=1.27; extra == 'dev'
+Requires-Dist: pytest-aiohttp>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: slack-bolt>=1.18; extra == 'dev'
+Provides-Extra: discord
+Requires-Dist: discord-py>=2.6; extra == 'discord'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.27; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: langchain-openai>=1.2.1; extra == 'openai'
+Provides-Extra: slack
+Requires-Dist: slack-bolt>=1.18; extra == 'slack'

mimir_agent-0.1.0/mimir/__init__.py

@@ -0,0 +1,3 @@
+"""Mimir — memory-centric agent harness."""
+
+__version__ = "0.1.0"

mimir_agent-0.1.0/mimir/_context.py

@@ -0,0 +1,206 @@
+"""Per-turn ``TurnContext`` propagation via ``contextvars`` (SPEC §4.6, §9.3).
+
+The SAGA ``saga_query`` tool needs to auto-append returned ``atom_id``s to the
+parent's ``TurnContext.saga_atom_ids`` so the post-message hook can credit
+mid-turn retrievals without the agent having to remember (SPEC §9.3 "mid-turn
+``saga_query`` tracking"). Tools registered with the SDK are plain functions —
+they need a way to find the active turn.
+
+``contextvars`` are the right primitive for in-task lookups: each ``query()``
+call runs in its own asyncio task, and we set the ContextVar before invoking
+``query()``. Subagent calls run in distinct tasks with distinct contexts, so a
+subagent's ``saga_query`` does NOT mutate the parent's ``saga_atom_ids`` —
+matching SPEC §9.3 "Subagents do not inherit the parent's ``saga_atom_ids``".
+
+Hook callbacks (PreToolUse / PostToolUse) are dispatched on a different
+task — the SDK's control-protocol task, forked at first ``client.connect()``.
+That task captured the contextvar value at fork time (``None``) and never
+sees subsequent ``set()`` calls in ``run_turn``, so contextvar lookups from
+hooks return stale data. The ``_active_turns`` map fixes this: ``run_turn``
+registers the turn under its ``turn_id``, hooks pass their incoming
+``session_id`` (which is ``ctx.turn_id`` since stage 2 of the ClaudeSDKClient
+migration) to ``get_turn_by_session_id`` for a reliable lookup that doesn't
+depend on task-fork inheritance.
+
+**MCP tool dispatch hits the same pattern (chainlink #23).** Every MCP
+``tools/call`` control request lands in
+``Query._spawn_control_request_handler`` (SDK internals,
+``claude_agent_sdk/_internal/query.py:232``), which calls
+``spawn_detached`` to run the handler on a fresh asyncio task. That task
+captures contextvars from the SDK's read-loop task — forked at connect
+time, where ``_current_turn`` was ``None``. So the same staleness affects
+MCP-dispatched tools (``saga_query``, ``saga_store``, ``saga_feedback``,
+``saga_end_session``) as PreToolUse / PostToolUse hooks.
+
+The hook fix uses ``input_data["session_id"]`` which the SDK forwards on
+every hook callback. The MCP path is **asymmetric** — the SDK only
+forwards ``(server_name, mcp_message)`` to the MCP handler; per-call
+session_id is dropped at the boundary. So MCP tools can't use the same
+fix shape as hooks.
+
+The two helpers below cover the lookups available to MCP tool handlers:
+
+- ``get_turn_by_saga_session_id(saga_session_id)`` — for tools whose args
+  carry the saga_session_id (currently just ``saga_end_session``). Iterates
+  ``_active_turns`` matching ``ctx.saga_session_id``.
+- ``get_only_active_turn()`` — best-effort heuristic for tools whose args
+  don't carry any per-turn key. Returns the single active turn if exactly
+  one is registered, else ``None``. Works in single-channel deployments;
+  multi-active cases must be surfaced via observability events rather than
+  silently picking one.
+
+See ``state/spec/chainlink-23-saga-mcp-context-resolution.md`` for the
+full design and the per-tool migration sequence.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .models import TurnContext
+
+_current_turn: ContextVar["TurnContext | None"] = ContextVar(
+    "mimir_current_turn", default=None
+)
+
+# Registry of active turns keyed by turn_id. Populated by ``run_turn``,
+# read by hook callbacks that can't rely on contextvar inheritance.
+_active_turns: dict[str, "TurnContext"] = {}
+
+
+class _TurnCell:
+    """Per-client mutable holder for the currently-acquired turn id.
+
+    The SDK's hook control task is forked at first ``client.connect()``
+    and captures the surrounding ``ContextVar`` values at that instant.
+    A plain ``_current_turn`` value frozen at fork time is useless —
+    later turns can't update what the hook task sees.
+
+    A ``_TurnCell`` flips that property: the contextvar holds a *cell
+    reference*, which the hook task captures. The cell's ``turn_id``
+    attribute is mutable. Mimir stamps it on ``acquire`` and clears it
+    on ``release``; the hook reads ``cell.turn_id`` lazily and gets the
+    live value.
+
+    One cell per pooled client (created when the client is constructed),
+    so multi-channel concurrent turns each have their own cell — the
+    hook task on client A only sees writes from acquires of client A.
+    Cell reads/writes are bare attribute accesses (atomic under the GIL);
+    no lock needed because each cell has at most one acquire-stamping
+    task at a time (the pool serializes acquire of a given entry)."""
+
+    __slots__ = ("turn_id",)
+
+    def __init__(self) -> None:
+        self.turn_id: str | None = None
+
+
+# ContextVar set by the pool before each new client's ``connect()`` so
+# the SDK's forked hook task captures *this client's* cell. The cell
+# stays None outside of a per-client connect.
+_current_client_cell: ContextVar["_TurnCell | None"] = ContextVar(
+    "mimir_current_client_cell", default=None
+)
+
+
+def set_current_turn(ctx: "TurnContext") -> Token:
+    _active_turns[ctx.turn_id] = ctx
+    return _current_turn.set(ctx)
+
+
+def reset_current_turn(token: Token) -> None:
+    ctx = _current_turn.get()
+    if ctx is not None:
+        _active_turns.pop(ctx.turn_id, None)
+    _current_turn.reset(token)
+
+
+def get_current_turn() -> "TurnContext | None":
+    return _current_turn.get()
+
+
+def get_turn_by_session_id(session_id: str | None) -> "TurnContext | None":
+    """Look up an active turn by its ``turn_id``. Used by hook callbacks
+    where contextvar inheritance is unreliable (the hook task forked at
+    first connect, captured contextvar=None, and never sees later sets).
+    Returns ``None`` if the session is unknown — caller should treat
+    that as "no active turn" and skip per-turn enforcement."""
+    if not session_id:
+        return None
+    return _active_turns.get(session_id)
+
+
+def get_turn_by_saga_session_id(saga_session_id: str | None) -> "TurnContext | None":
+    """Look up an active turn by its ``saga_session_id``. Used by MCP
+    tool handlers whose args carry a ``saga_session_id`` (currently
+    ``saga_end_session``) where the SDK's task-fork dispatch breaks
+    contextvar inheritance (chainlink #23).
+
+    Iterates ``_active_turns.values()`` rather than maintaining a parallel
+    registry — active_turns is bounded by the dispatcher's per-channel
+    queue size (typically 1-3 in production), so the linear scan is cheap.
+
+    Returns ``None`` when ``saga_session_id`` is empty / None, or when no
+    active turn matches. Caller should fall back to ``get_current_turn``
+    (which works for direct-handler-call paths, e.g. unit tests) or
+    treat as "no active turn" and skip per-turn bookkeeping."""
+    if not saga_session_id:
+        return None
+    for ctx in _active_turns.values():
+        if ctx.saga_session_id == saga_session_id:
+            return ctx
+    return None
+
+
+def get_only_active_turn() -> "TurnContext | None":
+    """Return the unique active turn if exactly one is registered, else
+    ``None``. Best-effort heuristic for MCP tool handlers whose args
+    don't carry any per-turn lookup key (``saga_query``, ``saga_store``,
+    ``saga_feedback``) — works in single-channel deployments where
+    concurrent turns are serialized by the dispatcher.
+
+    Multi-active cases (multiple channels with concurrent in-flight
+    turns) return ``None`` rather than guessing — callers should emit a
+    ``resolution_path`` observability event so the rate at which the
+    heuristic punts is visible. See chainlink #23 design doc."""
+    if len(_active_turns) == 1:
+        return next(iter(_active_turns.values()))
+    return None
+
+
+def resolve_active_ctx(args: dict[str, Any]) -> tuple["TurnContext | None", str]:
+    """Standard three-level lookup chain for MCP tool handlers running
+    on a forked task that can't see ``_current_turn``.
+
+    Tries:
+
+    1. ``args["session_id"]`` (model-passed via Option P) → match against
+       ``ctx.saga_session_id`` in ``_active_turns``. Multi-channel safe.
+    2. ``get_only_active_turn()`` heuristic — the unique active turn if
+       exactly one is registered. Works in single-channel deployments;
+       returns None when 0 or >1 turns are active.
+    3. ``get_current_turn()`` contextvar — works for the direct-handler-
+       call test path. Won't fire under SDK dispatch.
+
+    Returns ``(ctx, resolution_path)`` where resolution_path is one of
+    ``"saga_session_id" | "single_active" | "contextvar" | "missing"``.
+    The path is logged via per-tool ``<tool>_ctx_resolution`` events so
+    the rate of each path is visible in events.jsonl.
+
+    Mirrors the chainlink #23 sagatools resolution chain; lifted here
+    so any new MCP-dispatched tool (currently the bash_async family)
+    can use the same shape without duplicating the logic.
+    """
+    sid = args.get("session_id") if args else None
+    ctx = get_turn_by_saga_session_id(sid) if sid else None
+    if ctx is not None:
+        return ctx, "saga_session_id"
+    ctx = get_only_active_turn()
+    if ctx is not None:
+        return ctx, "single_active"
+    ctx = get_current_turn()
+    if ctx is not None:
+        return ctx, "contextvar"
+    return None, "missing"

mimir_agent-0.1.0/mimir/_jsonl_tail.py

@@ -0,0 +1,134 @@
+"""Streaming tail-reader for JSONL files.
+
+Used by ``feedback.py`` (recent feedback signals from events.jsonl /
+turns.jsonl) and ``session_boundary_log.py`` (local mirror tail). Both
+read newest-first up to a small bound — typically ≤ 20 records — but
+the underlying file can grow unbounded (events.jsonl is the firehose).
+Loading the whole file into memory per turn is an O(file_size) memory
+spike on every prompt assembly; this module reads from the tail in
+chunks so memory use stays O(chunk_size) regardless of file length.
+
+Usage::
+
+    for rec in tail_jsonl_records(path):
+        if too_old(rec):
+            break
+        consume(rec)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Iterator
+
+log = logging.getLogger(__name__)
+
+# 8 KiB per chunk. Typical JSONL records are 100 B–4 KB, so each chunk
+# yields multiple records; a small bound (≤ ~20 records) almost always
+# resolves in one chunk read. Bigger chunks waste memory on small files;
+# smaller chunks waste seeks.
+_CHUNK_BYTES = 8192
+
+
+def tail_jsonl_records(path: Path) -> Iterator[dict]:
+    """Yield JSON-decoded records from ``path`` newest-first.
+
+    Streams chunks from the end of the file rather than reading the
+    whole file into memory. Skips lines that fail to JSON-decode (the
+    firehose may have torn lines from a crash). Yields nothing when the
+    file is missing or unreadable.
+    """
+    try:
+        for line in _tail_lines(path):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                yield json.loads(line)
+            except json.JSONDecodeError:
+                continue
+    except OSError:
+        return
+
+
+def count_lines_chunked(path: Path, *, chunk_bytes: int = 65536) -> int:
+    """Count newline-terminated lines in ``path`` without reading the
+    whole file into memory.
+
+    Streams the file in 64 KiB chunks and counts ``\\n`` bytes. Used
+    by ``EventLogger`` and ``TurnLogger`` at startup to learn how many
+    records the existing log holds (so the trim hysteresis knows when
+    to fire) without a multi-hundred-MB memory spike on a hot log.
+
+    A trailing line without a final newline is counted as one more
+    record — that's the shape of a torn write that left the file
+    without a final ``\\n``. ``wc -l`` would *miss* this one; we don't.
+
+    **Behavior note (vs. previous splitlines+strip implementation).**
+    The old code dropped blank lines (``if line.strip()``); this
+    counter does not — every ``\\n`` is one record. On a clean
+    firehose those produce identical counts, but a torn write that
+    leaves a bare ``\\n`` in the middle, or an external process
+    appending an empty line, will over-count by one here. The trim
+    hysteresis absorbs over-counts (a one-line drift just makes the
+    next trim fire a hair sooner — not load-bearing).
+
+    Returns 0 for missing or unreadable files.
+    """
+    try:
+        with path.open("rb") as f:
+            count = 0
+            had_data = False
+            last_byte: bytes = b""
+            while True:
+                chunk = f.read(chunk_bytes)
+                if not chunk:
+                    break
+                had_data = True
+                count += chunk.count(b"\n")
+                last_byte = chunk[-1:]
+            # File ended with content but no trailing newline → that's
+            # one more record (the pattern most JSONL appenders never
+            # produce, but a torn write can leave one behind).
+            if had_data and last_byte != b"\n":
+                count += 1
+            return count
+    except OSError:
+        return 0
+
+
+def _tail_lines(path: Path) -> Iterator[str]:
+    """Yield lines from ``path`` newest-first, reading in fixed-size
+    chunks from the end. Lines that span chunk boundaries are stitched
+    correctly via a leading-fragment buffer.
+
+    OSError is propagated to the caller (``tail_jsonl_records`` swallows
+    it); we don't paper over a deleted file mid-iteration here.
+    """
+    with path.open("rb") as f:
+        f.seek(0, 2)  # SEEK_END
+        pos = f.tell()
+        leading_fragment = b""
+        while pos > 0:
+            read_size = min(_CHUNK_BYTES, pos)
+            pos -= read_size
+            f.seek(pos)
+            chunk = f.read(read_size) + leading_fragment
+            lines = chunk.split(b"\n")
+            # If we haven't reached BOF, the first split is a partial
+            # line whose head lives in an earlier chunk — defer it.
+            if pos > 0:
+                leading_fragment = lines[0]
+                lines = lines[1:]
+            else:
+                leading_fragment = b""
+            # Yield in reverse so the caller sees newest-first.
+            for raw in reversed(lines):
+                if raw:
+                    yield raw.decode("utf-8", errors="replace")
+        # Once we've reached BOF, the leading fragment is the very first
+        # line of the file — yield it last (it's the oldest record).
+        if leading_fragment:
+            yield leading_fragment.decode("utf-8", errors="replace")