memory-gateway/docs/superpowers/plans/2026-06-15-memory-attachment-path-mapping.md

Memory Attachment Path Mapping Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Persist attachment-to-session mappings for resource and direct memory ingestion, then return filename-matched real URIs from memory search results.

Architecture: Add one SQLite attachment table and repository methods. Register resource files directly, materialize base64 memory attachments under Gateway storage, and enrich normalized search results by matching attachment names against recursive raw string values.

Tech Stack: Python 3.10+, FastAPI, SQLite, Pydantic, pytest, httpx.

---

Task 1: Attachment persistence

Files:

• Modify: core/db.py

• Modify: core/repository.py

• Modify: tests/test_gateway.py

• Write failing tests proving attachment records can be created, listed by user/session, deduplicated, and soft-deleted with resources.

• Run focused tests and verify failure because the table and methods do not exist.

• Add memory_attachments, indexes, resource backfill SQL, and focused repository methods.

• Run focused tests and verify they pass.

Task 2: Register attachments during ingestion

Files:

• Modify: core/api.py

• Modify: core/service.py

• Modify: tests/test_gateway.py

• Write failing tests for /resources, /memories/add URI items, and /memories/add base64 items.

• Run focused tests and verify missing mappings and files.

• Register resource mappings, pass authenticated user_id into add service, materialize base64 files, and persist successful add mappings.

• Run focused tests and verify they pass.

Task 3: Enrich search results

Files:

• Modify: core/service.py

• Modify: tests/test_gateway.py

• Write failing tests for filename match, no match, base64-key exclusion, and cross-user isolation.

• Run focused tests and verify attachments is absent.

• Recursively collect raw strings excluding base64 and return deduplicated matching attachments.

• Run focused tests and verify they pass.

Task 4: Documentation and regression

Files:

• Modify: README.md

• Modify: tests/test_command.md

• Document attachment persistence, historical backfill limits, matching behavior, and response shape.

• Update the search response example with attachments.

• Run git diff --check, compile checks, and the complete pytest suite.

• Review the final diff for user isolation and unintended URI exposure outside search.