Repository navigation
Adr 0001 Agent Memory Deletion
- Status: Accepted
- Date: 2026-09-25
- Blocks: AG7 implementation, AG6 preference inspection/delete (hard gate)
-
Related: #110,
docs/wiki/delivery-roadmap.mdPhase 4
AG7’s plan required two things that could not both hold without a mechanism:
- After clearing Agent Memory, Context / Tutor must not be able to query it.
- Clearing must not delete learning facts (courses, events, checkpoints).
“Still there but the agent cannot see it” is a wish until the kind of deletion, the derived views, the audit trail, and cache invalidation are written down. This ADR freezes those four answers before AG7 code.
| Class | What it is today | Decision | Why not the alternative |
|---|---|---|---|
| Working | Tutor transcript (in-process, keyed by session) |
Physical delete (forget(sessionId)) |
Nothing else reads it; a tombstone would keep learner text in memory for no reader. |
| Episodic (agent-scoped session history) |
learning_events, checkpoints, interventions, outcomes, resume_cards, agent_proposals rows for one session |
Physical delete of those rows for the cleared session | Soft delete keeps content on disk that a “clear” promised to remove; access tombstones require every future reader to remember the denylist (easy to miss in a new query). Physical delete is the only kind a DELETE then query test can prove. |
| Preference (AG6/AG7, not yet implemented) | N/A | Physical delete of preference rows when built | Same reason as episodic: inspection UI must show the row gone, not deleted_at. |
Session catalog rows (learning_sessions, course structure, material documents) are not memory in this ADR’s sense: they are the learner’s own course state (which course, which tasks completed). Clearing agent/session memory does not remove the course or the session row.
They may not use cleared episodic data. After clearAgentMemory(sessionId):
-
learning_events/checkpoints/interventions/outcomes/resume_cards/agent_proposalsfor that session are gone → dashboard aggregates and insights that fold those tables drop to zero contribution for that session. - If a view still showed the cleared numbers, the data was not cleared and the product wording would be a lie — so we do not keep a parallel “display copy”.
Session-level fields that live on the session row itself (e.g. completedTaskIds on engine_state) remain: they are catalog/progress facts about which tasks were done, not the episodic event stream. Dashboard task counts therefore may still include completed tasks from a cleared session; interruptions, event timeline, resume outcomes, intervention outcomes must not.
Wording rule: the UI says “Clear session memory” (清除会话记忆), not “Delete my learning history”, unless a separate destructive catalog wipe is ever designed.
| Kept | Not kept |
|---|---|
session_id (opaque id already known to the local DB) |
Event payloads, checkpoint text, intervention reasons, resume timings |
cleared_at timestamp |
Tutor question/answer strings (never persisted anyway) |
actor (user | system) |
Material excerpts, learner prose |
A dedicated agent_memory_clears table records only those three columns. An audit that retained content would defeat the deletion; an opaque id + timestamp is enough to answer “was this session cleared, and when?”.
Retention of the audit row: same lifetime as the local database (no auto-purge). It contains no learner content.
There is no long-lived cache of agent context or tutor prompts: buildAgentContext and buildTutorPrompt run per request from the store. Checkpoints are rows, not a cache.
Invalidation is therefore “delete the rows / maps the readers use”:
| Reader | After clear |
|---|---|
| Tutor transcript |
forget(sessionId) — next ask has an empty turn list |
| Pending proposals |
agent_proposals rows deleted, so a confirm after the clear finds no row and is refused instead of applying a write computed against deleted context |
getAgentContext |
Rebuilt per request from the store, so it sees an empty event window and no checkpoint once they are deleted. There is no "session cleared" flag: deletion is the mechanism, not a denylist |
| Dashboard / insights | Query empty tables for that session |
Proof: a regression test per class does write → clear → query, asserting empty on the direct path and on derived paths (dashboard aggregate, context builder, tutor transcript). A test that only checked the direct listEvents would pass while a stale checkpoint still fed the dashboard.
- AG7 implements inspection UI on top of this ADR; preference delete follows the same physical-delete rule when AG6 lands.
- AG6’s hard gate (preference inspection/delete) can proceed once AG7 ships that path — semantics are frozen here.
- Learner-facing copy must not promise “events vanish from disk” for working memory only — transcript was never on disk.
-
Soft delete (
deleted_aton every episodic row) — keeps forensic copy; every query must filter; dashboard “cleared” views still find rows unless filtered twice. Rejected: easier to ship a leak. - Access tombstone (denylist table) — preserves rows forever; any new reader that forgets the denylist re-exposes data. Rejected: the failure mode is exactly “cleared but still queried”.
- Dashboard keeps using cleared events (with copy change only) — honest only if we never said “cleared”. Rejected: AG7’s acceptance criteria require derived paths to go empty.