Merge pull request #170 from PlateerLab/feat/task-memory

feat(memory): TASK 기억, 여러 단계·여러 턴 일을 하나의 기억 단위로 (4.98.0)

Author: CocoRoF

CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to `xgen-agent-runtime` are recorded here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [4.98.0] - 2026-10-23
+
+### Added: TASK 기억, 여러 단계·여러 턴 일을 하나의 기억 단위로 (`memory.tasks`)
+
+사실은 사용자가 누구인지, 원문은 무슨 말이 오갔는지를 담는다. 지금 무슨 일을 하던 중인지는 어디에도 없었다. 여러 턴짜리
+요청은 원문에만 있었고, 창이 그 턴을 지나거나 압축이 요약으로 접으면 목표·계획·결정·파일이 함께 사라졌다. "계속" 은 이어 갈
+것이 없었다.
+
+- **기억 층**: `Task`(제목, 목표, 완료 조건, 상태, 계획, 결정, 파일, 다음 할 일, 프로젝트)와 `TaskEvent`(열기·바꾸기·턴·
+  계획·체크포인트·메모·닫기). 저장 계약 `TaskStore`(호스트 구현, 사람 단위 범위), 참조 구현 `InMemoryTaskStore`.
+  provider 의 선택 층 `tasks()`(`provider_tasks()` 로 읽는다). 대화를 넘어 이어진다.
+- **판단(모델 선언 + 호스트 보완)**: 새 도구 `Task(action=open|update|switch|close|list)`. 호스트는 턴이 끝나면 LLM 없이
+  기록한다. 현재 TASK 에 그 턴(요청·답·도구 수·파일·결과)을 덧붙이고, TodoWrite 목록을 계획으로 옮기며, 압축 요약을
+  체크포인트로 남긴다. 모델이 열지 않았어도 여러 단계 일이 분명하면 요청으로 TASK 를 연다(호스트가 열었다고 적는다).
+  기준은 끝나지 않은 계획 2단계 이상, 또는 도구를 쓰다 끝나지 못한 턴이다. 도구도 Task 도 쓰지 않은 짧은 질문은 현재
+  TASK 의 기록에 넣지 않는다.
+- **회상**: 매 턴 TASK 판(`TaskBoardBlock`, volatile)이 실린다. 이 대화의 현재 TASK 는 전부, 다른 열린 TASK 는 한 줄씩이다.
+  검색을 거치지 않으므로 "계속" 에도 일의 상태가 온다. 판의 몫은 창의 5%(최소 3,000자)이고, 넘치면 오래된 항목부터 빼고
+  뺀 수와 `TaskRecall` 을 적는다. 기억 검색 질의에 현재 TASK 의 제목·목표를 더한다. 새 도구
+  `TaskRecall(view=card|history|turn)` 는 TASK 의 전체 기록을 읽는다. 그 턴의 원문도 읽는데, 이 대화는 ConversationHistory,
+  다른 대화는 provider 의 `session_stm(session_id)` 로 읽는다. TASK 마다 `tasks/task-<id>.md` 노트를 만들어 기억 검색에도 오른다.
+- TASK 노트는 기록에서 다시 쓰는 화면용이라고 첫 줄에 적는다(노트를 고쳐도 TASK 는 바뀌지 않는다). 이 대화의 현재 TASK
+  노트는 판이 이미 실으므로 기억 검색에서 뺀다.
+- 판의 사용 안내(Task 를 부르라는 말)는 그 호출에 Task 도구가 있을 때만 붙는다. 메모리 도구가 없는 백엔드에는 "호스트가
+  기록한다" 만 적는다. Stage 3 은 블록을 그리기 전에 이번 호출에 나가는 도구 이름을 알린다(`_offered_tools`).
+- TASK 는 사람의 것이다. 노트가 에이전트 공용인 provider 는 `task_notes = False` 로 TASK 노트를 받지 않는다(다른 사람이
+  기억 검색으로 남의 TASK 를 보지 않게). 그런 provider 에서는 판과 `Task(action="list", query=...)`(열린·닫힌 TASK 를 낱말로
+  찾는다)로 찾는다.
+- 실행 기록(Executions)과 잇는다: 실행 카드에 그 턴이 기록된 TASK(`> **Task:** [id] 제목`, frontmatter `task_id`)를,
+  날짜 일지 줄에 `task <id>` 를 적는다.
+- 이벤트 `context.task_board`(카탈로그 v19).
+
 ## [4.97.0] - 2026-10-23
 
 ### Fixed: 모델과 사용자가 받는 것이 실제와 같다 (정직성 감사)

docs/events.md

@@ -4,7 +4,7 @@
 <!-- Regenerate: python scripts/gen_event_docs.py -->
 
 > Generated from `xgen_agent_runtime.events.catalog` on 2026-10-23.
-> Catalogue version: **18** · events: **145**
+> Catalogue version: **19** · events: **146**
 
 Every event name the engine emits, value == wire string. The enum
 is a *names registry*, not a rename — consumers matching raw strings
@@ -445,6 +445,15 @@ Enum member: `EventTypes.CONTEXT_SHORT_TERM_WINDOW`
 | `chars` | int — 창의 직렬화 길이 |
 | `degraded` | list[str] — 예산 강등 단계 |
 
+### `context.task_board`
+
+Enum member: `EventTypes.CONTEXT_TASK_BOARD`
+
+| Field | Description |
+|---|---|
+| `current` | str — 이 대화의 현재 TASK id (없으면 빈 문자열) |
+| `chars` | int — 판의 길이 |
+
 ## Stage 18 — Memory (+ Stage 2 compaction)
 
 ### `memory.compaction.summarized`

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "xgen-agent-runtime"
-version = "4.97.0"
+version = "4.98.0"
 description = "Harness-engineered agent pipeline library with 21-stage dual-abstraction architecture, built on the Anthropic API"
 readme = "README.md"
 license = "Apache-2.0"

src/xgen_agent_runtime/core/compaction.py

@@ -315,6 +315,44 @@ def _summary_text(state: PipelineState) -> str:
     return ""
 
 
+async def _keep_checkpoint_on_task(
+    state: Any, provider: Any, *, trigger: str, replaced: int
+) -> None:
+    """A compaction's summary goes onto this conversation's current task (memory.tasks).
+
+    The checkpoint's sections (requests, work done, decisions, problems, open items, current state)
+    are the task's own state. Kept on the task, a compaction tidies the task's record instead of
+    being the moment the work's details were lost. Best-effort: the checkpoint itself is in context.
+    """
+    try:
+        from xgen_agent_runtime.memory.tasks import CURRENT_KEY, TaskEvent, provider_tasks
+
+        store = provider_tasks(provider)
+        if store is None:
+            return
+        session_id = str(getattr(state, "session_id", "") or "")
+        task = await store.current(session_id)
+        if task is None:
+            task_id = str((getattr(state, "shared", None) or {}).get(CURRENT_KEY) or "")
+            task = await store.get(task_id) if task_id else None
+        if task is None:
+            return
+        summary = _summary_text(state)
+        if not summary.strip():
+            return
+        await store.append_event(
+            TaskEvent(
+                task_id=task.id,
+                kind="checkpoint",
+                session_id=session_id,
+                summary=f"context compacted ({trigger}, {replaced} messages summarized)",
+                data={"summary": summary},
+            )
+        )
+    except Exception:  # noqa: BLE001
+        logger.debug("could not keep the checkpoint on the task", exc_info=True)
+
+
 def _prune(state: PipelineState, *, aggressive: bool, trigger: str) -> Dict[str, int]:
     """Deterministic pre-pass. In-place, count/order-preserving, pair-safe.
 
@@ -625,6 +663,9 @@ async def run_compaction(
             )
             logger.debug("record_compaction failed: %s", exc)
 
+    if replaced > 0 and provider is not None:
+        await _keep_checkpoint_on_task(state, provider, trigger=trigger, replaced=replaced)
+
     return {
         "ok": True,
         "before_messages": before_msgs,

src/xgen_agent_runtime/events/catalog.py

@@ -67,7 +67,8 @@
 #: v17: ``tool.call_start`` / ``tool.call_complete`` gain ``capabilities`` / ``origin``.
 #: v18: + ``loop.review_start`` / ``loop.review_end`` (4.95.0 the completion review's span, so a host can
 #: say "checking the files in the answer" while it reads them).
-EVENT_CATALOG_VERSION = 18
+#: v19: + ``context.task_board`` (4.98.0 TASK memory: the board loaded at the start of each turn).
+EVENT_CATALOG_VERSION = 19
 
 
 class EventTypes(str, Enum):
@@ -142,6 +143,8 @@ class EventTypes(str, Enum):
     #: 단기 기억 창(4.36.0) — 호스트가 이력을 preload 하지 않은 턴에서 STM 의 최근 논리 턴을
     #: messages 앞에 되살렸다(가까운 턴은 도구까지, 먼 턴은 대화만).
     CONTEXT_SHORT_TERM_WINDOW = "context.short_term_window"
+    #: TASK 판(4.98.0) — 이 대화의 현재 TASK 와 열린 TASK 를 이번 턴 프롬프트에 실었다.
+    CONTEXT_TASK_BOARD = "context.task_board"
     MEMORY_COMPACTION_SUMMARIZED = "memory.compaction.summarized"
     MEMORY_COMPACTION_LLM_FAILED = "memory.compaction.llm_failed"
 
@@ -464,6 +467,10 @@ class EventTypes(str, Enum):
         "chars": "int — 창의 직렬화 길이",
         "degraded": "list[str] — 예산 강등 단계",
     },
+    EventTypes.CONTEXT_TASK_BOARD: {
+        "current": "str — 이 대화의 현재 TASK id (없으면 빈 문자열)",
+        "chars": "int — 판의 길이",
+    },
     EventTypes.CONTEXT_COMPACTED: {
         "strategy": "str — compactor name/class, or 'prune' when the deterministic pass alone met the target",
         "trigger": "str? — proactive | requested | manual | guard | overflow | internal_loop | background",

src/xgen_agent_runtime/host/execution_record.py

@@ -112,6 +112,8 @@ def _build_card_body(
     tool_calls: int = 0,
     tool_failures: int = 0,
     blocked: int = 0,
+    task_id: str = "",
+    task_title: str = "",
 ) -> str:
     """Geny ``_build_execution_entry`` 형식 미러 (구조 동일, 필드 간소)."""
     outcome = outcome or classify_outcome(
@@ -124,6 +126,9 @@ def _build_card_body(
         f"> **Task:** {_clip(input_text, _TASK_CLIP)}",
         f"> **Duration:** {secs:.1f}s · **Session:** {session_id or '-'}",
     ]
+    if task_id:
+        # 이 턴이 기록된 TASK(memory.tasks) — 실행 기록과 일을 잇는다.
+        lines.append(f"> **Task:** [{task_id}] {_clip(task_title, 80)}")
     if tool_calls:
         tools_line = f"> **Tools:** {int(tool_calls)} calls · {int(tool_failures)} failed"
         if blocked:
@@ -166,6 +171,8 @@ async def record_turn_execution(
     tool_calls: int = 0,
     tool_failures: int = 0,
     blocked: int = 0,
+    task_id: str = "",
+    task_title: str = "",
 ) -> None:
     """실행 1회를 daily 카드 + executions 저널에 기록 (best-effort).
 
@@ -219,6 +226,8 @@ async def record_turn_execution(
         tool_calls=tool_calls,
         tool_failures=tool_failures,
         blocked=blocked,
+        task_id=task_id,
+        task_title=task_title,
     )
     try:
         await notes.write(
@@ -237,6 +246,7 @@ async def record_turn_execution(
                     "tool_calls": int(tool_calls),
                     "tool_failures": int(tool_failures),
                     "duration_ms": int(duration_ms),
+                    "task_id": task_id or None,
                 },
             )
         )
@@ -249,6 +259,7 @@ async def record_turn_execution(
     line = (
         f"- {now.strftime('%H:%M')} {mark} #{number} "
         f"{_clip(input_text, 60)} ({duration_ms / 1000.0:.1f}s)"
+        + (f" · task {task_id}" if task_id else "")
     )
     try:
         existing = await notes.read(journal_filename)

src/xgen_agent_runtime/host/memory_tools.py

@@ -429,6 +429,10 @@ def _schema(props: Dict[str, Any], required: Optional[List[str]] = None) -> Dict
             capabilities=read_caps,
         ),
     ]
+    # TASK 층(memory.tasks)이 있는 provider 면 Task·TaskRecall 도 준다.
+    from xgen_agent_runtime.host.task_tools import build_task_tools
+
+    tools.extend(build_task_tools(provider))
     # 종류 표지 — 호스트의 결과 필터가 이름이 아니라 종류로 판정한다(tools.base.tool_origin).
     return [with_origin(t, "memory") for t in tools]
 

src/xgen_agent_runtime/host/runner.py

@@ -778,6 +778,7 @@ def build_pipeline(
                 DateTimeBlock,
                 PinnedFactsBlock,
                 RetrievedMemoryBlock,
+                TaskBoardBlock,
                 TurnNotesBlock,
             )
 
@@ -807,6 +808,7 @@ def build_pipeline(
                         PinnedFactsBlock(),
                         DateTimeBlock(),
                         RetrievedMemoryBlock(),
+                        TaskBoardBlock(),
                         TurnNotesBlock(),
                     ]
                 ),
@@ -1277,6 +1279,19 @@ def _record_execution(
         return
     spec = getattr(pipeline, "_memory_distill_spec", None)
     calls, failures, blocked = _tool_stats_from_events(state)
+    # TASK 먼저: 실행 카드가 이 턴이 기록된 TASK 를 적는다(Executions ↔ TASK 연결).
+    task = _record_task_turn(
+        provider,
+        loop,
+        state=state,
+        input_text=input_text,
+        output_text=output_text,
+        success=success,
+        cancelled=cancelled,
+        calls=calls,
+        failures=failures,
+        blocked=blocked,
+    )
     try:
         from xgen_agent_runtime.host.execution_record import record_turn_execution
 
@@ -1297,6 +1312,8 @@ def _record_execution(
                     tool_calls=calls,
                     tool_failures=failures,
                     blocked=blocked,
+                    task_id=getattr(task, "id", "") or "",
+                    task_title=getattr(task, "title", "") or "",
                 ),
                 timeout=10.0,
             )
@@ -1305,6 +1322,84 @@ def _record_execution(
         logger.debug("geny_bridge: execution record failed (turn unaffected)", exc_info=True)
 
 
+def _record_task_turn(
+    provider: Any,
+    loop: asyncio.AbstractEventLoop,
+    *,
+    state: PipelineState,
+    input_text: Any,
+    output_text: str,
+    success: bool,
+    cancelled: bool,
+    calls: int,
+    failures: int,
+    blocked: int,
+) -> Any:
+    """이 턴이 한 일을 이 대화의 현재 TASK 에 남긴다(memory.tasks, LLM 없음). 기록한 TASK 를 돌려준다.
+
+    모델이 TASK 를 열지 않았어도 여러 단계 일이 분명하면(끝나지 않은 계획 2단계 이상, 도구를 쓰다
+    끝나지 못한 턴) 요청으로 TASK 를 연다(호스트가 열었다고 적는다). 실패는 로그만.
+    """
+    from xgen_agent_runtime.memory.tasks import (
+        CURRENT_KEY,
+        provider_tasks,
+        record_turn,
+        tool_calls_in,
+        turn_messages,
+    )
+
+    store = provider_tasks(provider)
+    if store is None:
+        return None
+    try:
+        from xgen_agent_runtime.host.execution_record import _as_text, classify_outcome
+        from xgen_agent_runtime.host.task_tools import sync_task_note
+        from xgen_agent_runtime.stages.s16_loop.completion_review import written_paths
+
+        msgs = turn_messages(list(state.messages or []))
+        n_calls = max(int(calls or 0), tool_calls_in(msgs))
+        outcome = classify_outcome(
+            success,
+            tool_calls=n_calls,
+            tool_failures=failures,
+            blocked=blocked,
+            cancelled=cancelled,
+        )
+        # TodoWrite 를 이번 턴에 썼을 때만 그 목록이 이 TASK 의 계획이다(지난 턴의 목록을 다른 TASK 에
+        # 덮어쓰지 않는다).
+        used = {
+            str(b.get("name") or "")
+            for m in msgs
+            if isinstance(m, dict) and isinstance(m.get("content"), list)
+            for b in m["content"]
+            if isinstance(b, dict) and b.get("type") == "tool_use"
+        }
+        wrote_todos = "TodoWrite" in used
+
+        async def _go() -> Any:
+            task = await record_turn(
+                store,
+                session_id=str(getattr(state, "session_id", "") or ""),
+                request=_as_text(input_text),
+                answer=str(output_text or ""),
+                outcome=outcome,
+                tool_calls=n_calls,
+                tool_failures=int(failures or 0),
+                files=written_paths(msgs),
+                todos=state.shared.get("executor.todos") if wrote_todos else None,
+                current_id=str(state.shared.get(CURRENT_KEY) or ""),
+                task_tool_used="Task" in used,
+            )
+            if task is not None:
+                await sync_task_note(provider, store, task)
+            return task
+
+        return loop.run_until_complete(asyncio.wait_for(_go(), timeout=10.0))
+    except Exception:  # noqa: BLE001 — 기록은 best-effort
+        logger.debug("geny_bridge: task record failed (turn unaffected)", exc_info=True)
+        return None
+
+
 #: 끝나지 못한 턴을 기억에 남길 때 그 턴 끝에 붙이는 표식 — 다음 턴의 단기 기억 창이 이 턴을 "끝나지
 #: 않은 턴" 으로 읽는다. 위의 도구 호출·결과는 그때까지 실제로 한 일이다.
 UNFINISHED_TURN_NOTES = {