Skip to content

docs: surface soft-delete and demote patterns via update_episode#22

Merged
mikejgray merged 1 commit intoOscillateLabsLLC:mainfrom
jjrawlins:docs/cleanup-patterns
Apr 13, 2026
Merged

docs: surface soft-delete and demote patterns via update_episode#22
mikejgray merged 1 commit intoOscillateLabsLLC:mainfrom
jjrawlins:docs/cleanup-patterns

Conversation

@jjrawlins
Copy link
Copy Markdown
Contributor

Summary

Agents can already expire episodes via update_episode but the current description — "Update metadata, tags, or expiration of an episode" — doesn't hint at the cleanup use case. This documents the two agent-safe patterns:

  • Soft-delete via expired_at past timestamp (reversible — clear expired_at to restore)
  • Demote via a deprecated tag (visible but filterable at query time)

Follows the "no delete_episode MCP tool" design from #16/#18 — permanent deletion remains a deliberate human action outside the agent's toolkit.

Changes (docs only, no behavior changes)

  • internal/mcp/server.go: update_episode tool description and its tags / expired_at property descriptions now mention soft-delete and demote use cases
  • internal/api/openapi.go: PUT /api/v1/memory/episodes/{id} description matches
  • README.md: new "Cleanup Patterns" section with MCP examples for soft-delete, demote, and scheduled expiration

Test plan

  • go build ./... — compiles
  • just test — all existing tests pass (no test changes needed, docs-only)
  • Live test: served /openapi.json reflects the new description
  • Live test: update_episode with past expired_at hides the episode from default search and listing (both REST and MCP)
  • Live test: soft-deleted episodes remain in the store (episode count unchanged, recoverable)

Agents can already expire episodes via update_episode but the current description doesn't mention this cleanup use case. Documents the two agent-safe patterns: soft-delete via expired_at (reversible) and demote via deprecated tag (visible but filterable). No behavior changes, only description text.
@mikejgray mikejgray merged commit 7188140 into OscillateLabsLLC:main Apr 13, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants