klaude-code 2.9.1__tar.gz → 2.10.0__tar.gz

{klaude_code-2.9.1 → klaude_code-2.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: klaude-code
-Version: 2.9.1
+Version: 2.10.0
 Summary: Minimal code agent CLI
 Requires-Dist: anthropic>=0.66.0
 Requires-Dist: chardet>=5.2.0

{klaude_code-2.9.1 → klaude_code-2.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "klaude-code"
-version = "2.9.1"
+version = "2.10.0"
 description = "Minimal code agent CLI"
 readme = "README.md"
 requires-python = ">=3.13"

{klaude_code-2.9.1 → klaude_code-2.10.0}/src/klaude_code/app/runtime.py

@@ -87,7 +87,7 @@ async def initialize_app_components(
     )
 
     if on_model_change is not None:
-        on_model_change(llm_clients.main.model_name)
+        on_model_change(llm_clients.main_model_alias)
 
     executor_task = asyncio.create_task(executor.start())
 

{klaude_code-2.9.1 → klaude_code-2.10.0}/src/klaude_code/cli/cost_cmd.py

@@ -343,7 +343,7 @@ def render_cost_table(daily_stats: dict[str, DailyStats]) -> Table:
                 sub_list = list(group.sub_providers.values())
                 for sub_idx, sub_group in enumerate(sub_list):
                     is_last_sub = sub_idx == len(sub_list) - 1
-                    sub_prefix = " └─ " if is_last_sub else " ├─ "
+                    sub_prefix = " ╰─ " if is_last_sub else " ├─ "
 
                     # Sub-provider row
                     add_stats_row(sub_group.total, prefix=sub_prefix, bold=True)
@@ -353,15 +353,15 @@ def render_cost_table(daily_stats: dict[str, DailyStats]) -> Table:
                         is_last_model = model_idx == len(sub_group.models) - 1
                         # Indent based on whether sub-provider is last
                         if is_last_sub:
-                            model_prefix = "     └─ " if is_last_model else "     ├─ "
+                            model_prefix = "     ╰─ " if is_last_model else "     ├─ "
                         else:
-                            model_prefix = " │   └─ " if is_last_model else " │   ├─ "
+                            model_prefix = " │   ╰─ " if is_last_model else " │   ├─ "
                         add_stats_row(stats, prefix=model_prefix)
             else:
                 # No sub-providers: render two-level tree (direct models)
                 for model_idx, stats in enumerate(group.models):
                     is_last_model = model_idx == len(group.models) - 1
-                    model_prefix = " └─ " if is_last_model else " ├─ "
+                    model_prefix = " ╰─ " if is_last_model else " ├─ "
                     add_stats_row(stats, prefix=model_prefix)
 
         if show_subtotal:

{klaude_code-2.9.1 → klaude_code-2.10.0}/src/klaude_code/cli/list_model.py

@@ -338,7 +338,7 @@ def _build_models_table(
     model_count = len(provider.model_list)
     for i, model in enumerate(provider.model_list):
         is_last = i == model_count - 1
-        prefix = " └─ " if is_last else " ├─ "
+        prefix = " ╰─ " if is_last else " ├─ "
 
         if provider_disabled:
             name = Text.assemble(
@@ -439,7 +439,6 @@ def display_models_and_providers(config: Config, *, show_all: bool = False):
         # Provider info panel
         provider_panel = _build_provider_info_panel(provider, provider_available, disabled=provider.disabled)
         console.print(provider_panel)
-        console.print()
 
         # Models table for this provider
         models_table = _build_models_table(provider, config)

{klaude_code-2.9.1 → klaude_code-2.10.0}/src/klaude_code/const.py

@@ -71,7 +71,6 @@ DEFAULT_ANTHROPIC_THINKING_BUDGET_TOKENS = 2048  # Default thinking budget token
 
 TODO_REMINDER_TOOL_CALL_THRESHOLD = 10  # Tool call count threshold for todo reminder
 REMINDER_COOLDOWN_TURNS = 3  # Cooldown turns between reminder triggers
-MEMORY_FILE_NAMES = ["CLAUDE.md", "AGENTS.md", "AGENT.md"]  # Memory file names to search for
 
 
 # =============================================================================
@@ -92,6 +91,7 @@ BINARY_CHECK_SIZE = 8192  # Bytes to check for binary file detection
 
 BASH_DEFAULT_TIMEOUT_MS = 120000  # Default timeout for bash commands (milliseconds)
 BASH_TERMINATE_TIMEOUT_SEC = 1.0  # Timeout before escalating to SIGKILL (seconds)
+BASH_MODE_SESSION_OUTPUT_MAX_BYTES = 200 * 1024 * 1024  # Max command output captured for session history
 
 
 # =============================================================================
@@ -156,8 +156,8 @@ CROP_ABOVE_LIVE_REFRESH_PER_SECOND = 4.0  # CropAboveLive default refresh rate
 MARKDOWN_STREAM_LIVE_REPAINT_ENABLED = True  # Enable live area for streaming markdown
 MARKDOWN_STREAM_SYNCHRONIZED_OUTPUT_ENABLED = True  # Use terminal "Synchronized Output" to reduce flicker
 STREAM_MAX_HEIGHT_SHRINK_RESET_LINES = 20  # Reset stream height ceiling after this shrinkage
-MARKDOWN_LEFT_MARGIN = 2  # Left margin (columns) for markdown rendering
-MARKDOWN_RIGHT_MARGIN = 2  # Right margin (columns) for markdown rendering
+MARKDOWN_LEFT_MARGIN = 0  # Left margin (columns) for markdown rendering
+MARKDOWN_RIGHT_MARGIN = 0  # Right margin (columns) for markdown rendering
 
 
 # =============================================================================
@@ -171,6 +171,7 @@ STATUS_WAITING_TEXT = "Loading …"
 STATUS_THINKING_TEXT = "Thinking …"
 STATUS_COMPOSING_TEXT = "Composing"
 STATUS_COMPACTING_TEXT = "Compacting"
+STATUS_RUNNING_TEXT = "Running …"
 
 # Backwards-compatible alias for the default spinner status text.
 STATUS_DEFAULT_TEXT = STATUS_WAITING_TEXT

klaude_code-2.10.0/src/klaude_code/core/bash_mode.py

@@ -0,0 +1,276 @@
+"""Bash-mode execution helpers.
+
+This module provides the implementation for running non-interactive shell commands
+with streaming output to the UI, plus session history recording.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import re
+import secrets
+import shutil
+import signal
+import subprocess
+import sys
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TextIO
+
+from klaude_code.const import BASH_MODE_SESSION_OUTPUT_MAX_BYTES, BASH_TERMINATE_TIMEOUT_SEC, TOOL_OUTPUT_TRUNCATION_DIR
+from klaude_code.core.tool.offload import offload_tool_output
+from klaude_code.protocol import events, message
+from klaude_code.session.session import Session
+
+
+@dataclass(frozen=True)
+class _BashModeToolCall:
+    tool_name: str = "Bash"
+
+
+_ANSI_ESCAPE_RE = re.compile(
+    r"""
+    \x1B
+    (?:
+        \[[0-?]*[ -/]*[@-~]         |  # CSI sequences
+        \][0-?]*.*?(?:\x07|\x1B\\) |  # OSC sequences
+        P.*?(?:\x07|\x1B\\)       |  # DCS sequences
+        _.*?(?:\x07|\x1B\\)       |  # APC sequences
+        \^.*?(?:\x07|\x1B\\)      |  # PM sequences
+        [@-Z\\-_]                      # 2-char sequences
+    )
+    """,
+    re.VERBOSE | re.DOTALL,
+)
+
+
+def _format_inline_code(text: str) -> str:
+    if not text:
+        return "``"
+    max_run = 0
+    run = 0
+    for ch in text:
+        if ch == "`":
+            run += 1
+            max_run = max(max_run, run)
+        else:
+            run = 0
+    fence = "`" * (max_run + 1)
+    return f"{fence}{text}{fence}"
+
+
+def _resolve_shell_command(command_text: str) -> list[str]:
+    # Use the user's default shell when possible.
+    # - macOS/Linux: $SHELL (supports bash/zsh/fish)
+    # - Windows: prefer pwsh/powershell
+    if sys.platform == "win32":  # pragma: no cover
+        exe = "pwsh" if shutil.which("pwsh") else "powershell"
+        return [exe, "-NoProfile", "-Command", command_text]
+
+    shell_path = os.environ.get("SHELL")
+    shell_name = Path(shell_path).name.lower() if shell_path else ""
+    if shell_path and shell_name in {"bash", "zsh", "fish"}:
+        # Use -lic to load both login profile and interactive config (e.g. aliases from .zshrc)
+        return [shell_path, "-lic", command_text]
+    return ["bash", "-lic", command_text]
+
+
+async def _terminate_process(proc: asyncio.subprocess.Process) -> None:
+    if proc.returncode is not None:
+        return
+
+    try:
+        if os.name == "posix":
+            os.killpg(proc.pid, signal.SIGTERM)
+        else:  # pragma: no cover
+            proc.terminate()
+    except ProcessLookupError:
+        return
+    except OSError:
+        pass
+
+    with contextlib.suppress(Exception):
+        await asyncio.wait_for(proc.wait(), timeout=BASH_TERMINATE_TIMEOUT_SEC)
+        return
+
+    with contextlib.suppress(Exception):
+        if os.name == "posix":
+            os.killpg(proc.pid, signal.SIGKILL)
+        else:  # pragma: no cover
+            proc.kill()
+    with contextlib.suppress(Exception):
+        await asyncio.wait_for(proc.wait(), timeout=BASH_TERMINATE_TIMEOUT_SEC)
+
+
+async def _emit_clean_chunk(
+    *,
+    emit_event: Callable[[events.Event], Awaitable[None]],
+    session_id: str,
+    chunk: str,
+    out_file: TextIO,
+) -> None:
+    if not chunk:
+        return
+
+    cleaned = _ANSI_ESCAPE_RE.sub("", chunk)
+    if cleaned:
+        await emit_event(events.BashCommandOutputDeltaEvent(session_id=session_id, content=cleaned))
+        with contextlib.suppress(Exception):
+            out_file.write(cleaned)
+
+
+async def run_bash_command(
+    *,
+    emit_event: Callable[[events.Event], Awaitable[None]],
+    session: Session,
+    session_id: str,
+    command: str,
+) -> None:
+    """Run a non-interactive bash command with streaming output to the UI.
+
+    The full (cleaned) output is appended to session history in a single UserMessage
+    as: `Ran <command>` plus truncated output via offload strategy.
+    """
+
+    await emit_event(events.BashCommandStartEvent(session_id=session_id, command=command))
+
+    # Create a log file to support large outputs without holding everything in memory.
+    # Use TOOL_OUTPUT_TRUNCATION_DIR (system temp) for consistency with offload.
+    tmp_root = Path(TOOL_OUTPUT_TRUNCATION_DIR)
+    tmp_root.mkdir(parents=True, exist_ok=True)
+    log_path = tmp_root / f"klaude-bash-mode-{secrets.token_hex(8)}.log"
+
+    env = os.environ.copy()
+    env.update(
+        {
+            "GIT_TERMINAL_PROMPT": "0",
+            "PAGER": "cat",
+            "GIT_PAGER": "cat",
+            "EDITOR": "true",
+            "VISUAL": "true",
+            "GIT_EDITOR": "true",
+            "JJ_EDITOR": "true",
+            "TERM": "dumb",
+        }
+    )
+
+    proc: asyncio.subprocess.Process | None = None
+    cancelled = False
+    exit_code: int | None = None
+
+    # Hold back any trailing ESC-started sequence to avoid leaking control codes
+    # when the subprocess output is chunked.
+    pending = ""
+
+    try:
+        kwargs: dict[str, object] = {
+            "stdin": asyncio.subprocess.DEVNULL,
+            "stdout": asyncio.subprocess.PIPE,
+            "stderr": asyncio.subprocess.STDOUT,
+            "env": env,
+        }
+        if os.name == "posix":
+            kwargs["start_new_session"] = True
+        elif os.name == "nt":  # pragma: no cover
+            kwargs["creationflags"] = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+
+        shell_argv = _resolve_shell_command(command)
+        proc = await asyncio.create_subprocess_exec(*shell_argv, **kwargs)  # type: ignore[arg-type]
+        assert proc.stdout is not None
+
+        with log_path.open("w", encoding="utf-8", errors="replace") as out_file:
+            while True:
+                data = await proc.stdout.read(4096)
+                if not data:
+                    break
+                piece = data.decode(errors="replace")
+                pending += piece
+
+                # Keep from the last ESC onwards to avoid emitting incomplete sequences.
+                last_esc = pending.rfind("\x1b")
+                if last_esc == -1:
+                    to_emit, pending = pending, ""
+                elif last_esc < len(pending) - 128:
+                    to_emit, pending = pending[:last_esc], pending[last_esc:]
+                else:
+                    # Wait for more bytes to complete the sequence.
+                    continue
+
+                await _emit_clean_chunk(
+                    emit_event=emit_event,
+                    session_id=session_id,
+                    chunk=to_emit,
+                    out_file=out_file,
+                )
+
+            if pending:
+                await _emit_clean_chunk(
+                    emit_event=emit_event,
+                    session_id=session_id,
+                    chunk=pending,
+                    out_file=out_file,
+                )
+                pending = ""
+
+        exit_code = await proc.wait()
+
+    except asyncio.CancelledError:
+        cancelled = True
+        if proc is not None:
+            with contextlib.suppress(Exception):
+                await asyncio.shield(_terminate_process(proc))
+    except Exception as exc:
+        # Surface errors to the UI as a final line.
+        msg = f"Execution error: {exc.__class__.__name__} {exc}"
+        await emit_event(events.BashCommandOutputDeltaEvent(session_id=session_id, content=msg))
+    finally:
+        header = f"Ran {_format_inline_code(command)}"
+
+        record_lines: list[str] = [header]
+        if cancelled:
+            record_lines.append("\n(command cancelled)")
+        elif isinstance(exit_code, int) and exit_code != 0:
+            record_lines.append(f"\nCommand exited with code {exit_code}")
+
+        output_text = ""
+        output_note_added = False
+        try:
+            if log_path.exists() and log_path.stat().st_size > BASH_MODE_SESSION_OUTPUT_MAX_BYTES:
+                record_lines.append(
+                    f"\n\n<system-reminder>Output truncated due to length. Full output saved to: {log_path} </system-reminder>"
+                )
+                output_note_added = True
+            else:
+                output_text = log_path.read_text("utf-8", errors="replace") if log_path.exists() else ""
+        except OSError:
+            output_text = ""
+
+        if output_text.strip() == "":
+            if not cancelled and not output_note_added:
+                record_lines.append("\n(no output)")
+                await emit_event(events.BashCommandOutputDeltaEvent(session_id=session_id, content="(no output)\n"))
+        else:
+            offloaded = offload_tool_output(output_text, _BashModeToolCall())
+            record_lines.append("\n\n" + offloaded.output)
+
+        # Always emit an end event so the renderer can finalize formatting.
+        await emit_event(
+            events.BashCommandEndEvent(
+                session_id=session_id,
+                exit_code=exit_code,
+                cancelled=cancelled,
+            )
+        )
+        session.append_history(
+            [
+                message.UserMessage(
+                    parts=message.parts_from_text_and_images(
+                        "".join(record_lines).rstrip(),
+                        None,
+                    )
+                )
+            ]
+        )

{klaude_code-2.9.1 → klaude_code-2.10.0}/src/klaude_code/core/executor.py

@@ -18,9 +18,11 @@ from klaude_code.config import load_config
 from klaude_code.config.sub_agent_model_helper import SubAgentModelHelper
 from klaude_code.core.agent import Agent
 from klaude_code.core.agent_profile import DefaultModelProfileProvider, ModelProfileProvider
+from klaude_code.core.bash_mode import run_bash_command
 from klaude_code.core.compaction import CompactionReason, run_compaction
 from klaude_code.core.loaded_skills import get_loaded_skill_names_by_location
 from klaude_code.core.manager import LLMClients, SubAgentManager
+from klaude_code.core.memory import get_existing_memory_paths_by_location
 from klaude_code.llm.registry import create_llm_client
 from klaude_code.log import DebugType, log_debug
 from klaude_code.protocol import commands, events, message, model, op
@@ -134,18 +136,19 @@ class AgentRuntime:
             compact_llm_client=self._llm_clients.compact,
         )
 
-        async for evt in agent.replay_history():
-            await self._emit_event(evt)
-
         await self._emit_event(
             events.WelcomeEvent(
                 session_id=session.id,
                 work_dir=str(session.work_dir),
                 llm_config=self._llm_clients.main.get_llm_config(),
                 loaded_skills=get_loaded_skill_names_by_location(),
+                loaded_memories=get_existing_memory_paths_by_location(work_dir=session.work_dir),
             )
         )
 
+        async for evt in agent.replay_history():
+            await self._emit_event(evt)
+
         self._agent = agent
         log_debug(
             f"Initialized agent for session: {session.id}",
@@ -179,6 +182,23 @@ class AgentRuntime:
         )
         self._task_manager.register(operation.id, task, operation.session_id)
 
+    async def run_bash(self, operation: op.RunBashOperation) -> None:
+        agent = await self.ensure_agent(operation.session_id)
+
+        existing_active = self._task_manager.get(operation.id)
+        if existing_active is not None and not existing_active.task.done():
+            raise RuntimeError(f"Active task already registered for operation {operation.id}")
+
+        task: asyncio.Task[None] = asyncio.create_task(
+            self._run_bash_task(
+                session=agent.session,
+                command=operation.command,
+                task_id=operation.id,
+                session_id=operation.session_id,
+            )
+        )
+        self._task_manager.register(operation.id, task, operation.session_id)
+
     async def continue_agent(self, operation: op.ContinueAgentOperation) -> None:
         """Continue agent execution without adding a new user message."""
         agent = await self.ensure_agent(operation.session_id)
@@ -230,6 +250,7 @@ class AgentRuntime:
                 work_dir=str(agent.session.work_dir),
                 llm_config=self._llm_clients.main.get_llm_config(),
                 loaded_skills=get_loaded_skill_names_by_location(),
+                loaded_memories=get_existing_memory_paths_by_location(work_dir=agent.session.work_dir),
             )
         )
 
@@ -249,18 +270,19 @@ class AgentRuntime:
             compact_llm_client=self._llm_clients.compact,
         )
 
-        async for evt in agent.replay_history():
-            await self._emit_event(evt)
-
         await self._emit_event(
             events.WelcomeEvent(
                 session_id=target_session.id,
                 work_dir=str(target_session.work_dir),
                 llm_config=self._llm_clients.main.get_llm_config(),
                 loaded_skills=get_loaded_skill_names_by_location(),
+                loaded_memories=get_existing_memory_paths_by_location(work_dir=target_session.work_dir),
             )
         )
 
+        async for evt in agent.replay_history():
+            await self._emit_event(evt)
+
         self._agent = agent
         log_debug(
             f"Resumed session: {target_session.id}",
@@ -359,6 +381,14 @@ class AgentRuntime:
                 debug_type=DebugType.EXECUTION,
             )
 
+    async def _run_bash_task(self, *, session: Session, command: str, task_id: str, session_id: str) -> None:
+        await run_bash_command(
+            emit_event=self._emit_event,
+            session=session,
+            session_id=session_id,
+            command=command,
+        )
+
     async def _run_compaction_task(
         self,
         agent: Agent,
@@ -467,7 +497,7 @@ class ModelSwitcher:
             config.main_model = model_name
             await config.save()
 
-        return llm_config, llm_client.model_name
+        return llm_config, model_name
 
     def change_thinking(self, agent: Agent, *, thinking: Thinking) -> Thinking | None:
         """Apply thinking configuration to the agent's active LLM config and persisted session."""
@@ -540,6 +570,9 @@ class ExecutorContext:
     async def handle_run_agent(self, operation: op.RunAgentOperation) -> None:
         await self._agent_runtime.run_agent(operation)
 
+    async def handle_run_bash(self, operation: op.RunBashOperation) -> None:
+        await self._agent_runtime.run_bash(operation)
+
     async def handle_continue_agent(self, operation: op.ContinueAgentOperation) -> None:
         await self._agent_runtime.continue_agent(operation)
 

{klaude_code-2.9.1 → klaude_code-2.10.0}/src/klaude_code/core/manager/llm_clients.py

@@ -19,6 +19,7 @@ class LLMClients:
     """Container for LLM clients used by main agent and sub-agents."""
 
     main: LLMClientABC
+    main_model_alias: str = ""
     sub_clients: dict[SubAgentType, LLMClientABC] = dataclass_field(default_factory=_default_sub_clients)
     compact: LLMClientABC | None = None
 

{klaude_code-2.9.1 → klaude_code-2.10.0}/src/klaude_code/core/manager/llm_clients_builder.py

@@ -53,7 +53,7 @@ def build_llm_clients(
         compact_client = create_llm_client(compact_llm_config)
 
     if skip_sub_agents:
-        return LLMClients(main=main_client, compact=compact_client)
+        return LLMClients(main=main_client, main_model_alias=model_name, compact=compact_client)
 
     helper = SubAgentModelHelper(config)
     sub_agent_configs = helper.build_sub_agent_client_configs()
@@ -63,4 +63,4 @@ def build_llm_clients(
         sub_llm_config = config.get_model_config(sub_model_name)
         sub_clients[sub_agent_type] = create_llm_client(sub_llm_config)
 
-    return LLMClients(main=main_client, sub_clients=sub_clients, compact=compact_client)
+    return LLMClients(main=main_client, main_model_alias=model_name, sub_clients=sub_clients, compact=compact_client)

klaude_code-2.10.0/src/klaude_code/core/memory.py

@@ -0,0 +1,140 @@
+"""Memory file loading and management.
+
+This module handles CLAUDE.md and AGENTS.md memory files - discovery, loading,
+and providing summaries for UI display.
+"""
+
+from collections.abc import Callable
+from pathlib import Path
+
+from pydantic import BaseModel
+
+MEMORY_FILE_NAMES = ["CLAUDE.md", "AGENTS.md", "AGENT.md"]
+
+
+class Memory(BaseModel):
+    """Represents a loaded memory file."""
+
+    path: str
+    instruction: str
+    content: str
+
+
+def get_memory_paths(*, work_dir: Path) -> list[tuple[Path, str]]:
+    """Return all possible memory file paths with their descriptions."""
+    user_dirs = [Path.home() / ".claude", Path.home() / ".codex"]
+    project_dirs = [work_dir, work_dir / ".claude"]
+
+    paths: list[tuple[Path, str]] = []
+    for d in user_dirs:
+        for fname in MEMORY_FILE_NAMES:
+            paths.append((d / fname, "user's private global instructions for all projects"))
+    for d in project_dirs:
+        for fname in MEMORY_FILE_NAMES:
+            paths.append((d / fname, "project instructions, checked into the codebase"))
+    return paths
+
+
+def get_existing_memory_files(*, work_dir: Path) -> dict[str, list[str]]:
+    """Return existing memory file paths grouped by location (user/project)."""
+    result: dict[str, list[str]] = {"user": [], "project": []}
+    work_dir = work_dir.resolve()
+
+    for memory_path, _instruction in get_memory_paths(work_dir=work_dir):
+        if memory_path.exists() and memory_path.is_file():
+            path_str = str(memory_path)
+            resolved = memory_path.resolve()
+            try:
+                resolved.relative_to(work_dir)
+                result["project"].append(path_str)
+            except ValueError:
+                result["user"].append(path_str)
+
+    return result
+
+
+def get_existing_memory_paths_by_location(*, work_dir: Path) -> dict[str, list[str]]:
+    """Return existing memory file paths grouped by location for WelcomeEvent."""
+    result = get_existing_memory_files(work_dir=work_dir)
+    if not result.get("user") and not result.get("project"):
+        return {}
+    return result
+
+
+def format_memory_content(memory: Memory) -> str:
+    """Format a single memory file content for display."""
+    return f"Contents of {memory.path} ({memory.instruction}):\n\n{memory.content}"
+
+
+def format_memories_reminder(memories: list[Memory], include_header: bool = True) -> str:
+    """Format memory files into a system reminder string."""
+    memories_str = "\n\n".join(format_memory_content(m) for m in memories)
+    if include_header:
+        return f"""<system-reminder>
+Loaded memory files. Follow these instructions. Do not mention them to the user unless explicitly asked.
+
+{memories_str}
+</system-reminder>"""
+    return f"<system-reminder>{memories_str}\n</system-reminder>"
+
+
+def discover_memory_files_near_paths(
+    paths: list[str],
+    *,
+    work_dir: Path,
+    is_memory_loaded: Callable[[str], bool],
+    mark_memory_loaded: Callable[[str], None],
+) -> list[Memory]:
+    """Discover and load CLAUDE.md/AGENTS.md from directories containing accessed files.
+
+    Args:
+        paths: List of file paths that have been accessed.
+        is_memory_loaded: Callback to check if a memory file is already loaded.
+        mark_memory_loaded: Callback to mark a memory file as loaded.
+
+    Returns:
+        List of newly discovered Memory objects.
+    """
+    memories: list[Memory] = []
+    work_dir = work_dir.resolve()
+    seen_memory_files: set[str] = set()
+
+    for p_str in paths:
+        p = Path(p_str)
+        full = (work_dir / p).resolve() if not p.is_absolute() else p.resolve()
+        try:
+            _ = full.relative_to(work_dir)
+        except ValueError:
+            continue
+
+        deepest_dir = full if full.is_dir() else full.parent
+
+        try:
+            rel_parts = deepest_dir.relative_to(work_dir).parts
+        except ValueError:
+            continue
+
+        current_dir = work_dir
+        for part in rel_parts:
+            current_dir = current_dir / part
+            for fname in MEMORY_FILE_NAMES:
+                mem_path = current_dir / fname
+                mem_path_str = str(mem_path)
+                if mem_path_str in seen_memory_files or is_memory_loaded(mem_path_str):
+                    continue
+                if mem_path.exists() and mem_path.is_file():
+                    try:
+                        text = mem_path.read_text(encoding="utf-8", errors="replace")
+                    except (PermissionError, UnicodeDecodeError, OSError):
+                        continue
+                    mark_memory_loaded(mem_path_str)
+                    seen_memory_files.add(mem_path_str)
+                    memories.append(
+                        Memory(
+                            path=mem_path_str,
+                            instruction="project instructions, discovered near last accessed path",
+                            content=text,
+                        )
+                    )
+
+    return memories