Feat/memory maintenance

[GilesStrong]

Adds a memory-maintenance system to regularly scan the current set of saved memories and compact as needed.
Also, adds a search budget to the daily deck-theme agent
Also updates docs to account for memory system

[Copilot]

Pull request overview

Adds an AI memory maintenance pipeline to periodically cluster and compact saved memories, introduces a per-run search budget for the daily deck-theme agent, and updates docs/agent instrumentation to reflect the memory system.

Changes:

• Adds memory maintenance graph + agent, a scheduled Celery task, and a MemoryMaintenanceReport model/migration.
• Adds a per-run theme search budget (ThemeDeps) and enforces it in find_similar_themes.
• Expands prefetching of printings for card/deck endpoints and adds/updates tests and docs.

Reviewed changes

Copilot reviewed 33 out of 36 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
uv.lock	Adds clustering/typing dependencies (UMAP/HDBSCAN/jaxtyping + transitive deps).
requirements.txt	Pins new clustering dependencies and transitive requirements.
README.md	Adds memory ops docs/commands and links to memory system doc.
pyproject.toml	Declares new dependencies + mypy ignore entries.
docs/developer-architecture-guide.md	Documents memory system + maintenance runtime notes.
docs/deck-building.md	Documents memory tool touchpoints and constraints in deck building.
app/appcards/serializers/card.py	Prefetches printings when resolving a card by ID.
app/appcards/routes/deck.py	Prefetches printings for deck card retrieval to reduce N+1 queries.
app/appcards/modules/summarise_card.py	Names/configures the card summary agent.
app/appcards/modules/card_validation.py	Adds shared validation helper for related card UUIDs.
app/appcards/constants/cards.py	Adds a new Standard set code.
app/appai/tests/test_task_memory_maintenance.py	Adds tests for the memory maintenance Celery task gating/behavior.
app/appai/tests/test_query_tools_theme_search.py	Updates tests for theme search tool budget and context usage.
app/appai/tests/test_memory_maintenance_graph.py	Adds unit tests for the memory maintenance graph nodes.
app/appai/tests/test_memory_maintenance_agent.py	Adds tests for maintenance agent output validation + persistence behavior.
app/appai/tests/test_deck_theme_agent.py	Updates daily theme agent tests for deps + retry settings.
app/appai/tasks/memory_maintenance.py	New Celery task to run maintenance once/day with threshold gating.
app/appai/tasks/init.py	Exposes the new memory maintenance task module.
app/appai/services/graphs/memory_maintenance.py	Implements the maintenance graph: retrieve → embed → UMAP → HDBSCAN → maintain → report.
app/appai/services/agents/tools/query_tools.py	Enforces theme-search budget and adjusts exception handling.
app/appai/services/agents/tools/memory_tools.py	Refactors card UUID validation + uses shared Memory dataclass and names agents.
app/appai/services/agents/tools/card_tools.py	Prefetches printings for card inspection.
app/appai/services/agents/memory_maintenance.py	New agent to rewrite clustered memories + update Postgres/Qdrant.
app/appai/services/agents/guardrails.py	Names/instruments the guardrail agent.
app/appai/services/agents/filter_constructor.py	Names the filter construction agent.
app/appai/services/agents/deps.py	Introduces ThemeDeps and MAX_THEME_SEARCHES.
app/appai/services/agents/deck_theme.py	Adds theme length constants, tool budget guidance, deps wiring, and agent settings.
app/appai/services/agents/deck_constructor.py	Names several deck-related agents.
app/appai/models/memory.py	Adds MemoryMaintenanceReport model.
app/appai/models/init.py	Exports MemoryMaintenanceReport.
app/appai/migrations/0008_memorymaintenancereport.py	Migration for the new maintenance report table.
app/appai/management/commands/run_memory_maintenance.py	Adds a management command to run maintenance.
app/appai/management/commands/no_prod_test_memory_maintenance.py	Adds a (dangerous) test command that seeds memories then runs maintenance.
app/appai/dataclasses/memory.py	Introduces Pydantic Memory / ExistingMemory dataclasses.
app/appai/dataclasses/init.py	Package marker for dataclasses.
app/app/settings.py	Schedules the new maintenance task via Celery beat.

Comments suppressed due to low confidence (1)

app/appcards/routes/deck.py:204

• get_deck now prefetches card__printings, but it still builds possible_replacements via card_to_info(replacement_card), which calls replacement_card.printings.all() and will trigger N+1 queries unless replacement_cards__printings is also prefetched (as already done in update_deck). Consider adding replacement_cards__printings to this queryset’s prefetch_related.

    deck_cards = list(
        DeckCard.objects.filter(deck_id=deck.id)
        .select_related('card')
        .prefetch_related('replacement_cards', 'card__printings')
    )
    card_infos = [
        DeckCardInfo(
            quantity=deck_card.quantity,
            card_info=card_to_info(deck_card.card),
            role=deck_card.role,
            importance=deck_card.importance,
            possible_replacements=[
                card_to_info(replacement_card) for replacement_card in deck_card.replacement_cards.all()
            ],
        )

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f0e09bef1e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".