/media-memory

name: media-memory
description: "Use when the user sends or generates an image, screenshot, video, audio or file and wants it saved, or asks to find past media (that diagram, the mockup from last week). Ingests and searches with local ChromaDB embeddings."
domain: engineering

/media-memory — Multimodal Memory System

You have access to a persistent multimodal memory system at `~/.claude/media-memory/`. It stores every piece of media (images, video, audio, files) with rich metadata and local ChromaDB embeddings.

**Prerequisites:** if `~/.claude/media-memory/scripts/ingest.py` is missing, the system is not installed. Say so and stop instead of running the commands below.

Directory Layout

~/.claude/media-memory/
  assets/          # stored media files
  chroma/          # ChromaDB vector store
  metadata.db      # SQLite structured metadata
  scripts/
    ingest.py      # ingestion + embedding
    search.py      # search with filters
    schema.py      # metadata models

Commands

All commands run from `~/.claude/media-memory/` using `uv run`.

Ingest (store + embed)

cd ~/.claude/media-memory && uv run scripts/ingest.py "<file_path>" \
  --source "user|generated|url|ingested" \
  --description "Natural language description of the media" \
  --tags "tag1,tag2,tag3" \
  --type "image|video|audio|document|file" \
  --text "Extracted text or transcript content"

Search (hybrid: semantic + metadata)

cd ~/.claude/media-memory && uv run scripts/search.py "search query" \
  --type image \
  --source user \
  --tags "architecture,diagram" \
  --from "2026-03-01" \
  --to "2026-03-28" \
  --limit 10 \
  --mode hybrid|semantic|metadata \
  --json

Recent items

cd ~/.claude/media-memory && uv run scripts/search.py --recent --limit 10

Stats

cd ~/.claude/media-memory && uv run scripts/search.py --stats

Behavior Rules

On Ingest (when user sends or generates media)

1. Copy the file to `assets/` via `ingest.py` 2. ALWAYS provide `--description` with a rich natural language description of the content 3. ALWAYS provide relevant `--tags` for semantic categorization 4. Set `--source` accurately: `user` (user sent it), `generated` (Claude/AI created it), `url` (downloaded), `ingested` (bulk import) 5. For screenshots: describe what's visible (UI elements, text, code, diagrams) 6. For documents: extract key text into `--text` 7. Report the result to the user: "Saved to media memory: {description}"

On Search (when user asks about past media)

1. Use `--mode hybrid` by default (combines semantic + metadata) 2. Add `--type` filter when user specifies media kind 3. Add `--tags` filter when user mentions categories 4. Add date filters when user references timeframes ("last week", "this month") 5. Show results with descriptions and asset paths 6. Offer to open/display the asset if it's an image

Proactive Recall

When a conversation topic overlaps with stored media: 1. Run a quick semantic search with the current topic 2. If relevant results found (similarity > 0.7), mention: "I found a related {type} in media memory: {description}" 3. Don't be noisy — only surface genuinely relevant assets

Environment

• **No API key needed** — uses ChromaDB's built-in local embeddings (all-MiniLM-L6-v2 via onnxruntime)
• Everything runs locally, zero external calls
• ChromaDB: local persistent storage, cosine similarity
• Model cached at `~/.cache/chroma/onnx_models/` (downloaded once on first use)

Metadata Schema

| Field | Type | Description | |-------|------|-------------| | id | string | Auto-generated: `{type}_{hash}_{stem}` | | filename | string | Original filename | | type | string | image, video, audio, document, file | | timestamp | ISO 8601 | When ingested | | source | string | user, generated, url, ingested | | description | string | Natural language description | | extracted_text | string | OCR / transcript / content | | tags | JSON array | Semantic tags | | original_path | string | Where it came from | | asset_path | string | Path in assets/ | | embedded | boolean | Whether vector is in ChromaDB |