memory_context.py 8.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185
  1. """Memory-context fencing: how recalled memory is wrapped for the model and kept out of output.
  2. ``build_memory_context_block`` fences prefetched recall for the prompt; ``sanitize_context`` and
  3. ``StreamingContextScrubber`` strip those fences (and anything a provider pre-wrapped) from text that
  4. leaves the agent. Pure text formatting: no provider calls, no profile state.
  5. """
  6. from __future__ import annotations
  7. import logging
  8. import re
  9. logger = logging.getLogger(__name__)
  10. _FENCE_TAG_RE = re.compile(r'</?\s*memory-context\s*>', re.IGNORECASE)
  11. _INTERNAL_CONTEXT_RE = re.compile(r'<\s*memory-context\s*>[\s\S]*?</\s*memory-context\s*>', re.IGNORECASE)
  12. _INTERNAL_NOTE_RE = re.compile(
  13. r'\[System note:\s*The following is recalled memory context,\s*NOT new user input\.\s*Treat as (?:informational background data|authoritative reference data[^\]]*)\.\]\s*',
  14. re.IGNORECASE,
  15. )
  16. def sanitize_context(text: str) -> str:
  17. """Strip fence tags, injected context blocks, and system notes from provider output."""
  18. for pattern in (_INTERNAL_CONTEXT_RE, _INTERNAL_NOTE_RE, _FENCE_TAG_RE):
  19. text = pattern.sub('', text)
  20. return text
  21. class StreamingContextScrubber:
  22. """Stateful scrubber for streaming text whose memory-context spans may straddle deltas.
  23. ``sanitize_context`` needs both tags in one string, so a split span would leak to the UI;
  24. this holds back partial-tag tails between ``feed()`` calls and drops span interiors.
  25. One scrubber (or ``reset()``) per top-level response; call ``flush()`` at end of stream.
  26. """
  27. _OPEN_TAG = "<memory-context>"
  28. _CLOSE_TAG = "</memory-context>"
  29. def __init__(self) -> None:
  30. self.reset()
  31. def reset(self) -> None:
  32. self._in_span: bool = False
  33. self._buf: str = ""
  34. self._at_block_boundary: bool = True
  35. def feed(self, text: str) -> str:
  36. """Return the visible portion of ``text``; a possible partial tag tail is held for the next call."""
  37. if not text:
  38. return ""
  39. buf = self._buf + text
  40. self._buf = ""
  41. out: list[str] = []
  42. while buf:
  43. if self._in_span:
  44. tag = self._CLOSE_TAG
  45. idx = buf.lower().find(tag)
  46. held = self._max_partial_suffix(buf, tag) # potential partial close tag
  47. else:
  48. tag = self._OPEN_TAG
  49. idx = self._find_boundary_open_tag(buf)
  50. # A complete boundary tag at the buffer end is held until the next char confirms it.
  51. n = len(tag)
  52. pending = n if buf.lower().endswith(tag) and self._ends_at_block_boundary(buf[:-n]) else 0
  53. held = pending or self._max_partial_suffix(buf, tag)
  54. if idx == -1:
  55. # Hold back the possible partial tag; inside a span the rest is dropped.
  56. if not self._in_span:
  57. self._append_visible(out, buf[:-held] if held else buf)
  58. self._buf = buf[-held:] if held else ""
  59. break
  60. if not self._in_span:
  61. self._append_visible(out, buf[:idx])
  62. buf = buf[idx + len(tag):]
  63. self._in_span = not self._in_span
  64. return "".join(out)
  65. def flush(self) -> str:
  66. """Emit the held-back tail at end-of-stream; inside an unterminated span it is discarded
  67. (leaking partial memory context is worse than a truncated answer)."""
  68. tail = "" if self._in_span else self._buf
  69. self._buf = ""
  70. self._in_span = False
  71. return tail
  72. @staticmethod
  73. def _max_partial_suffix(buf: str, tag: str) -> int:
  74. """Length of the longest buf-suffix that is a (case-insensitive) prefix of ``tag``, else 0."""
  75. tag_lower, buf_lower = tag.lower(), buf.lower()
  76. span = range(min(len(buf_lower), len(tag_lower) - 1), 0, -1)
  77. return next((i for i in span if tag_lower.startswith(buf_lower[-i:])), 0)
  78. def _find_boundary_open_tag(self, buf: str) -> int:
  79. """Find an opening fence only when it starts a block-like span (own line, newline after)."""
  80. buf_lower, tag_len = buf.lower(), len(self._OPEN_TAG)
  81. idx = buf_lower.find(self._OPEN_TAG)
  82. while idx != -1:
  83. after_idx = idx + tag_len
  84. if self._ends_at_block_boundary(buf[:idx]) and after_idx < len(buf) and buf[after_idx] in "\r\n":
  85. return idx
  86. idx = buf_lower.find(self._OPEN_TAG, idx + 1)
  87. return -1
  88. def _ends_at_block_boundary(self, text: str) -> bool:
  89. """Whether emitting ``text`` leaves the stream at a line start (blank tail after the last newline;
  90. no newline at all -> only whitespace and already at a boundary)."""
  91. _head, sep, tail = text.rpartition("\n")
  92. return tail.strip() == "" and (bool(sep) or self._at_block_boundary)
  93. def _append_visible(self, out: list[str], text: str) -> None:
  94. if text:
  95. out.append(text)
  96. self._at_block_boundary = self._ends_at_block_boundary(text)
  97. # A markdown bullet: a marker, whitespace, then content. The whitespace matters — it is what keeps
  98. # ``**Preferences**`` (a bold heading) and ``*emphasis*`` out of the rule.
  99. _RECALL_BULLET_RE = re.compile(r"[-*+]\s+\S")
  100. def _drop_repeated_recall_lines(text: str) -> str:
  101. """Drop a recalled bullet that an EARLIER line of this same block already states.
  102. Providers merge several stores (and this merges several providers), so one prefetch routinely
  103. surfaces the same fact two or three times. A byte-identical repeat inside one block tells the
  104. model nothing the block has not already said, and it is not free: the composed block is stamped
  105. into the user row's ``api_content`` sidecar and replayed verbatim on every later request for as
  106. long as that row is in context, so each duplicate is paid once per turn, forever.
  107. The ``seen`` set is scoped per section — every non-bullet line at column 0 (a heading of any
  108. style, a ``---`` rule, prose) starts a new one — so a repeat is only dropped when the SAME
  109. section already states it.
  110. Only a SELF-CONTAINED bullet is considered — a marker, whitespace, content, and no continuation
  111. line indented beneath it. A bullet that carries continuation lines is never dropped and never
  112. suppresses a later one, because two entries can share a headline and differ underneath it
  113. (``- prefers draft PRs`` / `` (logged 12 Jan, builtin)`` vs the same headline logged elsewhere):
  114. dropping one would re-parent its provenance under the other and invent a record neither provider
  115. reported. Headings — including ``**bold**`` ones — prose, blank lines, separators and numbered
  116. items are left exactly as written.
  117. """
  118. lines = text.split("\n")
  119. seen: set[str] = set()
  120. kept: list[str] = []
  121. for index, line in enumerate(lines):
  122. stripped = line.strip()
  123. # An indented line is a continuation of the bullet above it (nested child, provenance,
  124. # wrapped prose). It never participates in dedupe and is never dropped.
  125. if stripped and line[0].isspace():
  126. kept.append(line)
  127. continue
  128. is_bullet = bool(_RECALL_BULLET_RE.match(stripped))
  129. # Any column-0 non-bullet line (heading, rule, paragraph) opens a fresh dedupe scope.
  130. if stripped and not is_bullet:
  131. seen.clear()
  132. if is_bullet:
  133. following = lines[index + 1] if index + 1 < len(lines) else ""
  134. carries_continuation = bool(following.strip()) and following[0].isspace()
  135. if not carries_continuation:
  136. if stripped in seen:
  137. continue
  138. seen.add(stripped)
  139. kept.append(line)
  140. return "\n".join(kept)
  141. def build_memory_context_block(raw_context: str) -> str:
  142. """Wrap prefetched memory in a fenced block with system note."""
  143. if not raw_context or not raw_context.strip():
  144. return ""
  145. sanitized = sanitize_context(raw_context)
  146. if sanitized != raw_context:
  147. # Stays keyed on sanitization alone: a deduped bullet is routine, not a provider fault.
  148. logger.warning("memory provider returned pre-wrapped context; stripped")
  149. clean = _drop_repeated_recall_lines(sanitized)
  150. return (
  151. "<memory-context>\n"
  152. "[System note: The following is recalled memory context, "
  153. "NOT new user input. Treat as authoritative reference data — "
  154. "this is the agent's persistent memory and should inform all responses.]\n\n"
  155. f"{clean}\n"
  156. "</memory-context>"
  157. )