feat(memory): add semantic lesson retraction workflow

Introduce  to selectively unlearn accepted semantic lessons with required rationale while preserving append-only audit history in . Update lesson rendering and recall loading to honor latest lesson state (including retracted entries), and add tests/docs covering retraction behavior end-to-end.

Author: utk7arsh

.agent/AGENTS.md

@@ -76,6 +76,8 @@ Daily driver, highest-leverage first:
   flywheel metrics. It does not train models or call APIs.
 - `list_candidates.py` / `graduate.py` / `reject.py` / `reopen.py` — review
   protocol for patterns the dream cycle has staged.
+- `retract_lesson.py <lesson_id> --rationale "..."` — stop an accepted lesson
+  from being injected into future recall/context while preserving audit history.
 - `memory_reflect.py <skill> <action> <outcome>` — log a significant event.
 
 ## Rules
@@ -85,7 +87,7 @@ Daily driver, highest-leverage first:
    via `.agent/tools/memory_reflect.py`.
 4. Update `memory/working/WORKSPACE.md` as you work; archive on completion.
 5. Never hand-edit `memory/semantic/LESSONS.md` — it's rendered from
-   `lessons.jsonl`. Use `graduate.py` / `reject.py` instead.
+   `lessons.jsonl`. Use `graduate.py` / `reject.py` / `retract_lesson.py`.
 6. Follow `protocols/permissions.md`. Blocked means blocked.
 7. When a self-rewrite hook fires, propose conservative edits only.
 8. The harness is dumb on purpose. Reasoning lives in skills + the host agent.

.agent/memory/render_lessons.py

@@ -103,14 +103,15 @@ def load_lessons(semantic_dir):
     if not os.path.exists(path):
         return []
     out = []
-    for line in open(path):
-        line = line.strip()
-        if not line:
-            continue
-        try:
-            out.append(json.loads(line))
-        except json.JSONDecodeError:
-            continue
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                out.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
     return out
 
 
@@ -124,6 +125,8 @@ def _bullet_for(lesson, superseded_by):
     sup_by = superseded_by.get(lid)
     if sup_by:
         return f"- ~~{claim}~~  <!-- {ann} superseded_by={sup_by} -->"
+    if status == "retracted":
+        return f"- ~~[RETRACTED] {claim}~~  <!-- {ann} -->"
     if status == "provisional":
         return f"- [PROVISIONAL] {claim}  <!-- {ann} -->"
     return f"- {claim}  <!-- {ann} -->"

.agent/tools/recall.py

@@ -42,19 +42,45 @@ def _load_structured():
     """
     if not os.path.exists(LESSONS_JSONL):
         return []
-    out = []
-    for line in open(LESSONS_JSONL):
-        line = line.strip()
-        if not line:
+    rows = []
+    with open(LESSONS_JSONL, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rows.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+
+    # lessons.jsonl is append-only, so only the latest row per lesson id is
+    # considered active. This keeps retracted/provisional transitions from
+    # leaking stale accepted rows into recall.
+    latest = {}
+    order = []
+    no_id_rows = []
+    for row in rows:
+        lid = row.get("id")
+        if not lid:
+            no_id_rows.append(row)
             continue
-        try:
-            l = json.loads(line)
-        except json.JSONDecodeError:
+        if lid not in latest:
+            order.append(lid)
+        latest[lid] = row
+
+    out = []
+    for lid in order:
+        lesson = latest[lid]
+        if lesson.get("status") != "accepted":
             continue
-        if l.get("status") != "accepted":
+        lesson.setdefault("_source", "lessons.jsonl")
+        out.append(lesson)
+
+    for lesson in no_id_rows:
+        if lesson.get("status") != "accepted":
             continue
-        l.setdefault("_source", "lessons.jsonl")
-        out.append(l)
+        lesson.setdefault("_source", "lessons.jsonl")
+        out.append(lesson)
     return out
 
 
@@ -68,7 +94,8 @@ def _load_markdown_fallback():
     """
     if not os.path.exists(LESSONS_MD):
         return []
-    text = open(LESSONS_MD).read()
+    with open(LESSONS_MD, encoding="utf-8") as f:
+        text = f.read()
     out = []
     for line in text.splitlines():
         s = line.strip()

.agent/tools/retract_lesson.py

@@ -0,0 +1,86 @@
+"""Retract an accepted lesson from semantic memory.
+
+This is an append-only transition: a new row with the same lesson id is
+written to lessons.jsonl with status='retracted'. LESSONS.md is then
+re-rendered from the structured source of truth.
+"""
+import argparse
+import datetime
+import os
+import sys
+
+BASE = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+sys.path.insert(0, os.path.join(BASE, "memory"))
+
+from render_lessons import append_lesson, load_lessons, render_lessons
+
+SEMANTIC = os.path.join(BASE, "memory/semantic")
+
+
+def _latest_by_id(lesson_id, lessons):
+    latest = None
+    for lesson in lessons:
+        if lesson.get("id") == lesson_id:
+            latest = lesson
+    return latest
+
+
+def retract_lesson(lesson_id, rationale, reviewer="host-agent", semantic_dir=SEMANTIC):
+    if not str(rationale or "").strip():
+        raise ValueError("retraction rationale is required")
+
+    lessons = load_lessons(semantic_dir)
+    latest = _latest_by_id(lesson_id, lessons)
+    if latest is None:
+        raise ValueError(f"lesson not found: {lesson_id}")
+
+    status = latest.get("status")
+    if status != "accepted":
+        raise ValueError(
+            f"lesson {lesson_id} is not retractable (current status: {status})"
+        )
+
+    now = datetime.datetime.now(datetime.timezone.utc).isoformat()
+    updated = {
+        **latest,
+        "status": "retracted",
+        "retracted_at": now,
+        "retracted_by": reviewer,
+        "retraction_rationale": rationale,
+    }
+
+    append_lesson(updated, semantic_dir)
+    md_path = render_lessons(semantic_dir)
+    return updated, md_path
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Retract an accepted lesson by lesson id."
+    )
+    parser.add_argument("lesson_id")
+    parser.add_argument(
+        "--rationale",
+        required=True,
+        help="Why this lesson should stop guiding future decisions.",
+    )
+    parser.add_argument("--reviewer", default="host-agent")
+    args = parser.parse_args()
+
+    try:
+        lesson, md_path = retract_lesson(
+            lesson_id=args.lesson_id,
+            rationale=args.rationale,
+            reviewer=args.reviewer,
+        )
+    except ValueError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"retracted {args.lesson_id}")
+    print(f"status: {lesson.get('status')}")
+    print(f"re-rendered: {md_path}")
+
+
+if __name__ == "__main__":
+    main()

README.md

@@ -287,11 +287,15 @@ python3 .agent/tools/reject.py <id> --reason "too specific to generalize"
 
 # requeue a previously-rejected candidate
 python3 .agent/tools/reopen.py <id>
+
+# retract an accepted lesson from future recall/context (append-only audit)
+python3 .agent/tools/retract_lesson.py <lesson_id> --rationale "obsolete after migration"
 ```
 
 Graduated lessons land in `semantic/lessons.jsonl` (source of truth) and
 are rendered to `semantic/LESSONS.md`. Rejected candidates retain full
-decision history so recurring churn is visible, not fresh.
+decision history so recurring churn is visible, not fresh. Retracted lessons
+stay in history with `status=retracted` but are excluded from proactive recall.
 
 See [`docs/architecture.md`](docs/architecture.md) for the full lifecycle.