/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