langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/memory/memdir/loader.py

@@ -0,0 +1,187 @@
+"""
+memory/memdir/loader.py — Layer 2 prompt 加载编排。
+
+职责：
+    负责 MEMORY.md 入口读取、截断保护与 auto_memory section 文本组装。
+
+链路位置：
+    Loop 启动时通过 section("auto_memory") 调用 load_memory_prompt() 注入 system prompt。
+
+当前裁剪范围：
+    Phase 2 仅实现全量注入（行为说明 + MEMORY.md 正文），不含相关性召回。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from langchain_agentx.workspace import AgentWorkspaceConfig
+
+from .paths import is_memory_enabled
+from .types import (
+    DIR_EXISTS_GUIDANCE,
+    HOW_TO_SAVE_SECTION,
+    MEMORY_AND_PERSISTENCE_SECTION,
+    TRUSTING_RECALL_SECTION,
+    TYPES_SECTION_INDIVIDUAL,
+    WHAT_NOT_TO_SAVE_SECTION,
+    WHEN_TO_ACCESS_SECTION,
+)
+
+MAX_ENTRYPOINT_LINES = 200
+MAX_ENTRYPOINT_BYTES = 25_000
+
+
+@dataclass(frozen=True)
+class EntrypointTruncation:
+    content: str
+    was_line_truncated: bool
+    was_byte_truncated: bool
+    warning: str | None
+
+
+class MemoryPromptLoader:
+    def __init__(self, workspace_cfg: AgentWorkspaceConfig) -> None:
+        self._cfg = workspace_cfg
+
+    def _ensure_memory_dir(self) -> None:
+        self._cfg.memory_dir.mkdir(parents=True, exist_ok=True)
+
+    def truncate_entrypoint_content(self, raw: str) -> EntrypointTruncation:
+        return _truncate_entrypoint_content(raw)
+
+    def build_memory_lines(self, entrypoint_text: str) -> list[str]:
+        return _build_memory_lines(memory_dir=self._cfg.memory_dir, entrypoint_text=entrypoint_text)
+
+    def load_memory_prompt(self) -> str | None:
+        self._ensure_memory_dir()
+        if not is_memory_enabled(self._cfg):
+            return None
+
+        entrypoint = self._cfg.memory_entrypoint
+        if entrypoint.exists():
+            raw = entrypoint.read_text(encoding="utf-8")
+        else:
+            raw = ""
+        truncated = self.truncate_entrypoint_content(raw)
+        lines = self.build_memory_lines(truncated.content)
+        if truncated.warning:
+            lines.extend(["", truncated.warning])
+        return "\n".join(lines)
+
+
+def _build_warning(
+    *,
+    line_count: int,
+    original_bytes_len: int,
+    line_truncated: bool,
+    byte_truncated: bool,
+) -> str | None:
+    if not line_truncated and not byte_truncated:
+        return None
+    bytes_text = f"{round(original_bytes_len / 1000)} KB"
+    if line_truncated and byte_truncated:
+        reason = f"{line_count} lines and {bytes_text}"
+    elif line_truncated:
+        reason = f"{line_count} lines (limit: {MAX_ENTRYPOINT_LINES})"
+    else:
+        reason = (
+            f"{bytes_text} (limit: {MAX_ENTRYPOINT_BYTES // 1000} KB) "
+            "— index entries are too long"
+        )
+    return (
+        f"> WARNING: MEMORY.md is {reason}. Only part of it was loaded.\n"
+        "> Keep index entries to one line under ~200 chars; move detail into topic files."
+    )
+
+
+def _truncate_entrypoint_content(raw: str) -> EntrypointTruncation:
+    lines = raw.splitlines()
+    line_truncated = len(lines) > MAX_ENTRYPOINT_LINES
+    if line_truncated:
+        truncated_lines = lines[:MAX_ENTRYPOINT_LINES]
+        working = "\n".join(truncated_lines)
+    else:
+        working = raw
+
+    original_bytes_len = len(raw.encode("utf-8"))
+    working_bytes = working.encode("utf-8")
+    byte_truncated = original_bytes_len > MAX_ENTRYPOINT_BYTES
+    if byte_truncated:
+        working = working_bytes[:MAX_ENTRYPOINT_BYTES].decode("utf-8", errors="ignore")
+
+    warning = _build_warning(
+        line_count=len(lines),
+        original_bytes_len=original_bytes_len,
+        line_truncated=line_truncated,
+        byte_truncated=byte_truncated,
+    )
+    return EntrypointTruncation(
+        content=working.strip(),
+        was_line_truncated=line_truncated,
+        was_byte_truncated=byte_truncated,
+        warning=warning,
+    )
+
+
+def _build_memory_lines(*, memory_dir: Path, entrypoint_text: str) -> list[str]:
+    header = [
+        "# auto memory",
+        "",
+        f"You have a persistent, file-based memory system at `{memory_dir}`.",
+        DIR_EXISTS_GUIDANCE,
+        "",
+        "You should build up this memory system over time so that future conversations",
+        "can have a complete picture of who the user is, how they'd like to collaborate",
+        "with you, what behaviors to avoid or repeat, and the context behind the work",
+        "the user gives you.",
+        "",
+        "If the user explicitly asks you to remember something, save it immediately as",
+        "whichever type fits best. If they ask you to forget something, find and remove",
+        "the relevant entry.",
+        "",
+        TYPES_SECTION_INDIVIDUAL,
+        "",
+        WHAT_NOT_TO_SAVE_SECTION,
+        "",
+        HOW_TO_SAVE_SECTION,
+        "",
+        WHEN_TO_ACCESS_SECTION,
+        "",
+        TRUSTING_RECALL_SECTION,
+        "",
+        MEMORY_AND_PERSISTENCE_SECTION,
+        "",
+        "## MEMORY.md",
+        "",
+    ]
+    body = (
+        entrypoint_text.strip()
+        if entrypoint_text.strip()
+        else "Your MEMORY.md is currently empty. When you save new memories, they will appear here."
+    )
+    return [*header, body]
+
+
+def truncate_entrypoint_content(raw: str) -> EntrypointTruncation:
+    return _truncate_entrypoint_content(raw)
+
+
+def build_memory_lines(*, entrypoint_text: str, workspace_cfg: AgentWorkspaceConfig) -> list[str]:
+    return MemoryPromptLoader(workspace_cfg).build_memory_lines(entrypoint_text)
+
+
+def load_memory_prompt(workspace_cfg: AgentWorkspaceConfig) -> str | None:
+    return MemoryPromptLoader(workspace_cfg).load_memory_prompt()
+
+
+__all__ = [
+    "EntrypointTruncation",
+    "MAX_ENTRYPOINT_BYTES",
+    "MAX_ENTRYPOINT_LINES",
+    "MemoryPromptLoader",
+    "build_memory_lines",
+    "load_memory_prompt",
+    "truncate_entrypoint_content",
+]

langchain_agentx/memory/memdir/paths.py

@@ -0,0 +1,63 @@
+"""
+memory/memdir/paths.py — Layer 2 路径与启用门禁。
+
+职责：
+    提供 memdir 启用判断与路径安全校验，作为 Layer 2 的统一入口。
+
+链路位置：
+    loader/extractor 调用本模块判断是否启用与路径是否在 memory_dir 内。
+
+当前裁剪范围：
+    仅覆盖本地路径语义与环境变量门禁，不包含远端 feature flag。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from langchain_agentx.workspace import AgentWorkspaceConfig
+
+
+class MemoryPathResolver:
+    """Layer 2 路径解析与安全校验协作者。"""
+
+    def __init__(self, workspace_cfg: AgentWorkspaceConfig) -> None:
+        self._cfg = workspace_cfg
+        self._memory_dir = self._cfg.memory_dir.resolve()
+
+    def get_memory_dir(self) -> Path:
+        return self._memory_dir
+
+    def is_memory_path(self, candidate: str | Path) -> bool:
+        try:
+            resolved = Path(candidate).resolve()
+        except (TypeError, OSError, RuntimeError):
+            return False
+        try:
+            resolved.relative_to(self._memory_dir)
+            return True
+        except ValueError:
+            return False
+
+
+def is_memory_enabled(workspace_cfg: AgentWorkspaceConfig) -> bool:
+    """Layer 2 是否启用：环境变量优先，默认启用。"""
+    del workspace_cfg
+    return os.environ.get("LANGCHAIN_AGENTX_DISABLE_MEMORY") != "1"
+
+
+def get_memory_dir(workspace_cfg: AgentWorkspaceConfig) -> Path:
+    return MemoryPathResolver(workspace_cfg).get_memory_dir()
+
+
+def is_memory_path(candidate: str | Path, workspace_cfg: AgentWorkspaceConfig) -> bool:
+    return MemoryPathResolver(workspace_cfg).is_memory_path(candidate)
+
+
+__all__ = [
+    "MemoryPathResolver",
+    "get_memory_dir",
+    "is_memory_enabled",
+    "is_memory_path",
+]

langchain_agentx/memory/memdir/recall.py

@@ -0,0 +1,45 @@
+"""
+memory/memdir/recall.py — Layer 2 相关性召回接口空桩。
+
+职责：
+    提供 Phase 5 的稳定异步接口签名，供后续 side-query 召回实现复用。
+
+链路位置：
+    query 前召回路径将调用本模块（Phase 5 先空桩，不接入主链）。
+
+当前裁剪范围：
+    仅返回空结果，确保默认配置下行为不变。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+async def find_relevant_memories(
+    *,
+    query: str,
+    memory_dir: Path,
+    limit: int = 5,
+    max_scan: int = 200,
+    recent_tools: list[str] | None = None,
+) -> list[dict[str, Any]]:
+    del query, memory_dir, limit, max_scan, recent_tools
+    return []
+
+
+async def select_relevant_memories(
+    *,
+    query: str,
+    manifest_text: str,
+    limit: int = 5,
+) -> list[str]:
+    del query, manifest_text, limit
+    return []
+
+
+__all__ = [
+    "find_relevant_memories",
+    "select_relevant_memories",
+]

langchain_agentx/memory/memdir/runtime.py

@@ -0,0 +1,43 @@
+"""
+memory/memdir/runtime.py — Layer 2 在 loop 侧的注入协作者。
+
+职责：
+    将 MemoryPromptLoader 适配为 `section("auto_memory")`，统一供 loop 工厂接线。
+
+链路位置：
+    LoopGraphBuilder._prepare_compile_context() -> MemoryPromptBootstrap.build_sections()。
+
+当前裁剪范围：
+    仅提供 Phase 2 的 prompt 注入，不包含 extractor/recall 链路。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from langchain_agentx.workspace import resolve_agent_workspace_config
+
+from .loader import MemoryPromptLoader
+
+if TYPE_CHECKING:
+    from langchain_agentx.loop.prompt.sections import SystemPromptSection
+
+
+class MemoryPromptBootstrap:
+    def __init__(self, *, workspace_root: str | Path, agent_home: str) -> None:
+        self._workspace_root = workspace_root
+        self._agent_home = agent_home
+
+    def build_sections(self) -> list["SystemPromptSection"]:
+        from langchain_agentx.loop.prompt.sections import section
+
+        workspace_cfg = resolve_agent_workspace_config(
+            workspace_root=self._workspace_root,
+            agent_home=self._agent_home,
+        )
+        loader = MemoryPromptLoader(workspace_cfg)
+        return [section("auto_memory", loader.load_memory_prompt)]
+
+
+__all__ = ["MemoryPromptBootstrap"]

langchain_agentx/memory/memdir/scan.py

@@ -0,0 +1,135 @@
+"""
+memory/memdir/scan.py — Layer 2 memory 文件扫描器。
+
+职责：
+    扫描 memory 目录下的 markdown 文件，解析 frontmatter 的 type 字段，输出可组装清单。
+
+链路位置：
+    memdir runtime 读取 MEMORY.md 或 fallback 扫描时使用。
+
+当前裁剪范围：
+    Phase 1 仅实现基础扫描与轻量 frontmatter 解析，不做异步缓存。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import logging
+from pathlib import Path
+
+from .age import memory_freshness_text
+from .types import parse_memory_type
+
+logger = logging.getLogger(__name__)
+
+MAX_SCAN_FILES = 200
+
+
+@dataclass(frozen=True)
+class MemoryFileHeader:
+    path: Path
+    rel_path: str
+    title: str
+    memory_type: str | None
+    freshness: str
+
+
+class FrontmatterParseError(ValueError):
+    """frontmatter 结构损坏。"""
+
+
+class MemoryScanner:
+    def __init__(self, *, memory_dir: Path, max_scan: int = MAX_SCAN_FILES) -> None:
+        self._memory_dir = memory_dir
+        self._max_scan = max_scan
+
+    def scan_memory_files(self) -> list[MemoryFileHeader]:
+        if not self._memory_dir.exists() or not self._memory_dir.is_dir():
+            return []
+
+        candidates = self._iter_candidates()
+        headers: list[MemoryFileHeader] = []
+        for path in candidates:
+            try:
+                content = path.read_text(encoding="utf-8")
+            except OSError:
+                continue
+            try:
+                memory_type = self._parse_frontmatter_type(content)
+            except FrontmatterParseError as exc:
+                logger.warning("skip memory file with malformed frontmatter: %s (%s)", path, exc)
+                continue
+            headers.append(
+                MemoryFileHeader(
+                    path=path,
+                    rel_path=path.relative_to(self._memory_dir).as_posix(),
+                    title=self._first_heading(content, fallback=path.stem),
+                    memory_type=memory_type,
+                    freshness=memory_freshness_text(path),
+                )
+            )
+        return headers
+
+    def _iter_candidates(self) -> list[Path]:
+        all_md = [path for path in self._memory_dir.rglob("*.md") if path.name != "MEMORY.md"]
+        all_md.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+        return all_md[: self._max_scan]
+
+    def _parse_frontmatter_type(self, content: str) -> str | None:
+        lines = content.splitlines()
+        if not lines:
+            return None
+        if lines[0].strip() != "---":
+            return None
+        end_index: int | None = None
+        for idx in range(1, len(lines)):
+            if lines[idx].strip() == "---":
+                end_index = idx
+                break
+        if end_index is None:
+            raise FrontmatterParseError("missing closing ---")
+        for raw in lines[1:end_index]:
+            line = raw.strip()
+            if not line:
+                continue
+            if ":" not in line:
+                raise FrontmatterParseError(f"invalid frontmatter line: {line}")
+            key, value = line.split(":", 1)
+            if key.strip() != "type":
+                continue
+            normalized = value.strip().strip('"').strip("'")
+            parsed = parse_memory_type(normalized)
+            return parsed.value if parsed else None
+        return None
+
+    @staticmethod
+    def _first_heading(content: str, fallback: str) -> str:
+        for line in content.splitlines():
+            if line.startswith("# "):
+                title = line[2:].strip()
+                if title:
+                    return title
+        return fallback
+
+
+def scan_memory_files(memory_dir: Path) -> list[MemoryFileHeader]:
+    return MemoryScanner(memory_dir=memory_dir).scan_memory_files()
+
+
+def format_memory_manifest(headers: list[MemoryFileHeader]) -> str:
+    if not headers:
+        return ""
+    lines = [
+        f"- [{h.rel_path}] type={h.memory_type or 'unknown'} ({h.freshness})"
+        for h in headers
+    ]
+    return "\n".join(lines)
+
+
+__all__ = [
+    "MAX_SCAN_FILES",
+    "MemoryScanner",
+    "MemoryFileHeader",
+    "format_memory_manifest",
+    "scan_memory_files",
+]

langchain_agentx/memory/memdir/types.py

@@ -0,0 +1,104 @@
+"""
+memory/memdir/types.py — Layer 2 类型与提示词常量。
+
+职责：
+    定义记忆类型闭集与通用提示词片段，供 loader/extractor 复用。
+
+链路位置：
+    build_memory_lines() 与 build_extract_prompt() 从本模块读取同源常量。
+
+当前裁剪范围：
+    仅定义静态契约，不包含 IO 或业务编排逻辑。
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class MemoryType(str, Enum):
+    USER = "user"
+    FEEDBACK = "feedback"
+    PROJECT = "project"
+    REFERENCE = "reference"
+
+
+MEMORY_TYPES: tuple[str, ...] = (
+    MemoryType.USER.value,
+    MemoryType.FEEDBACK.value,
+    MemoryType.PROJECT.value,
+    MemoryType.REFERENCE.value,
+)
+
+TYPES_SECTION_INDIVIDUAL = """
+## Memory types
+
+- user: User profile, preferences, and collaboration style.
+- feedback: Corrections and explicit preferences from the user.
+- project: Non-code project context and constraints.
+- reference: Pointers to external systems and resources.
+""".strip()
+
+WHAT_NOT_TO_SAVE_SECTION = """
+## What not to save
+
+- Anything that can be derived from code or git history.
+- Task-local TODOs that belong to the current run only.
+- Anything already documented in instruction files (e.g. CLAUDE.md / AGENT.md / .cursorrules).
+""".strip()
+
+HOW_TO_SAVE_SECTION = """
+## How to save
+
+1. Create or update a topic file under memory/.
+2. Keep MEMORY.md as an index line list pointing to topic files.
+""".strip()
+
+WHEN_TO_ACCESS_SECTION = """
+## When to access memory
+
+- At session start to recover long-term context.
+- Before making personalized recommendations.
+- If the user asks to ignore memory, proceed as if MEMORY.md were empty.
+""".strip()
+
+TRUSTING_RECALL_SECTION = """
+## Before recommending from memory
+
+A memory is a historical claim, not a guarantee of current truth.
+Verify code/file/function claims against the current workspace before recommending actions.
+""".strip()
+
+DIR_EXISTS_GUIDANCE = """
+This directory already exists — write to it directly with the Write tool
+(do not run mkdir or check for its existence).
+""".strip()
+
+MEMORY_AND_PERSISTENCE_SECTION = """
+## Memory vs task state
+
+Use memory for durable facts that should survive across sessions.
+Use task/session state for temporary execution details.
+""".strip()
+
+
+def parse_memory_type(raw: str) -> MemoryType | None:
+    normalized = str(raw or "").strip().lower()
+    for item in MemoryType:
+        if item.value == normalized:
+            return item
+    return None
+
+
+__all__ = [
+    "DIR_EXISTS_GUIDANCE",
+    "HOW_TO_SAVE_SECTION",
+    "MEMORY_TYPES",
+    "MEMORY_AND_PERSISTENCE_SECTION",
+    "MemoryType",
+    "TRUSTING_RECALL_SECTION",
+    "TYPES_SECTION_INDIVIDUAL",
+    "WHAT_NOT_TO_SAVE_SECTION",
+    "WHEN_TO_ACCESS_SECTION",
+    "parse_memory_type",
+]

langchain_agentx/memory/session/__init__.py

@@ -0,0 +1,76 @@
+"""
+memory/session/__init__.py — Session Memory 包入口
+
+职责：
+    暴露 Layer 3 Session Memory 的 prompt 构建能力。
+
+链路位置：
+    被 loop/session memory 实现层导入，用于生成提取提示词与模板内容。
+
+当前裁剪范围：
+    本阶段仅实现 Phase 1（prompts），不包含提取调度与 compact bridge。
+"""
+
+from .prompts import (
+    DEFAULT_SESSION_MEMORY_TEMPLATE,
+    EXTRACT_SESSION_MEMORY_PROMPT,
+    MAX_SECTION_LENGTH,
+    analyze_section_sizes,
+    build_session_memory_update_prompt,
+    generate_section_reminders,
+    load_session_memory_prompt,
+    load_session_memory_template,
+    substitute_variables,
+)
+from .session_memory import (
+    SESSION_MEMORY_INIT_TOKEN_THRESHOLD,
+    SESSION_MEMORY_TOOL_CALL_THRESHOLD,
+    SESSION_MEMORY_UPDATE_TOKEN_THRESHOLD,
+    SessionMemoryExtractionState,
+    SessionMemoryManager,
+    create_memory_file_can_use_tool,
+    make_session_memory_section,
+    should_extract_session_memory,
+)
+from .compact_bridge import (
+    EXTRACTION_STALE_THRESHOLD_SECONDS,
+    EXTRACTION_WAIT_TIMEOUT_SECONDS,
+    MAX_SECTION_CHARS,
+    TRUNCATION_MARKER,
+    SessionMemoryCompactBridge,
+    adjust_index_to_preserve_api_invariants,
+    is_session_memory_empty,
+    truncate_session_memory_for_compact,
+    try_session_memory_compaction,
+    wait_for_session_memory_extraction,
+)
+
+__all__ = [
+    "MAX_SECTION_LENGTH",
+    "DEFAULT_SESSION_MEMORY_TEMPLATE",
+    "EXTRACT_SESSION_MEMORY_PROMPT",
+    "substitute_variables",
+    "analyze_section_sizes",
+    "generate_section_reminders",
+    "build_session_memory_update_prompt",
+    "load_session_memory_template",
+    "load_session_memory_prompt",
+    "SESSION_MEMORY_INIT_TOKEN_THRESHOLD",
+    "SESSION_MEMORY_UPDATE_TOKEN_THRESHOLD",
+    "SESSION_MEMORY_TOOL_CALL_THRESHOLD",
+    "SessionMemoryExtractionState",
+    "SessionMemoryManager",
+    "should_extract_session_memory",
+    "create_memory_file_can_use_tool",
+    "make_session_memory_section",
+    "EXTRACTION_WAIT_TIMEOUT_SECONDS",
+    "EXTRACTION_STALE_THRESHOLD_SECONDS",
+    "MAX_SECTION_CHARS",
+    "TRUNCATION_MARKER",
+    "wait_for_session_memory_extraction",
+    "is_session_memory_empty",
+    "truncate_session_memory_for_compact",
+    "adjust_index_to_preserve_api_invariants",
+    "try_session_memory_compaction",
+    "SessionMemoryCompactBridge",
+]