# 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`

- [x] Write failing tests proving attachment records can be created, listed by user/session, deduplicated, and soft-deleted with resources.
- [x] Run focused tests and verify failure because the table and methods do not exist.
- [x] Add `memory_attachments`, indexes, resource backfill SQL, and focused repository methods.
- [x] 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`

- [x] Write failing tests for `/resources`, `/memories/add` URI items, and `/memories/add` base64 items.
- [x] Run focused tests and verify missing mappings and files.
- [x] Register resource mappings, pass authenticated `user_id` into add service, materialize base64 files, and persist successful add mappings.
- [x] Run focused tests and verify they pass.

### Task 3: Enrich search results

**Files:**
- Modify: `core/service.py`
- Modify: `tests/test_gateway.py`

- [x] Write failing tests for filename match, no match, base64-key exclusion, and cross-user isolation.
- [x] Run focused tests and verify `attachments` is absent.
- [x] Recursively collect raw strings excluding base64 and return deduplicated matching attachments.
- [x] Run focused tests and verify they pass.

### Task 4: Documentation and regression

**Files:**
- Modify: `README.md`
- Modify: `tests/test_command.md`

- [x] Document attachment persistence, historical backfill limits, matching behavior, and response shape.
- [x] Update the search response example with `attachments`.
- [x] Run `git diff --check`, compile checks, and the complete pytest suite.
- [x] Review the final diff for user isolation and unintended URI exposure outside search.