luci-memory

Setup

Requires an MEMORIES_AI_KEY. On first use, if no key is found, the script will error and ask for one.

When the user provides their key, save it to {baseDir}/.env:

CODEBLOCK0

After that, everything just works — the key is loaded automatically from .env on every run.

Timezone

All timestamps in Luci-memory are stored and returned in UTC. Skill output labels them with " UTC" so this is unambiguous. The user's local timezone is in USER.md (e.g. Asia/Shanghai). You are responsible for converting in both directions:

1. 1. Reading results. When presenting captured_time to the user, convert from UTC to the user's local timezone. Never show raw UTC labels to the user.

1. 2. Writing filters. --after and --before are interpreted as UTC. If the user says relative dates like "yesterday" or "this morning", convert their local-time intent to a UTC range before passing the dates.

Example (user in Asia/Shanghai, UTC+8, asks "what did I do yesterday" on 2026-04-08):

• - Local intent: 2026-04-07 00:00 → 2026-04-08 00:00 (Asia/Shanghai)
• UTC range to pass: INLINECODE9

If USER.md has no timezone and the user uses relative dates, ask them first.

Unified search across personal media and portrait data from the Luci-memory API.

The user's videos go through two processing pipelines that produce different data:

• - Media content (personal): video summaries, audio transcripts, visual transcripts, keyframes, images
• People & knowledge (portrait): traits, events with participants, relationships, speeches attributed to speakers

When to use

• - User asks to find or search videos, images, or photos
• User asks what was said or shown in a video
• User asks to list recent videos or images
• User asks about media at a specific location or time
• User asks about traits, personality, hobbies, interests
• User asks what events happened, or events involving specific people
• User asks about relationships between people
• User asks about what someone said
• User mentions "luci memory" or wants to use their video memory

Choosing the right type

• - About content (what happened, what was said/shown, find media) → use media types (search_video, query_audio, etc.)
• About people (who, traits, relationships, named individuals) → use portrait types (traits, events, speeches, etc.)
• Ambiguous questions like "What happened with Alice last week?" → use both: portrait types to identify the person and events, media types to get detailed video content and transcripts.
• Person name fallback: Portrait data only exists for people who have appeared in at least 5 videos AND been named by the user in the app. If a portrait query by person name returns no results, fall back to media types — search video summaries, audio transcripts, or visual transcripts for mentions of that name instead.

Relevance guidelines

• - There is no rerank process — retrieved results may contain items irrelevant to the user's actual intent.
• Always verify relevance: after receiving results, check each item against the user's original query. Only present results that are relevant. Discard anything that doesn't match.
• Refine and retry: if results seem off or too broad, retry with a more specific query, narrower date range, or additional filters. Do not just dump low-quality results to the user.
• Ask the user: if the query is ambiguous or too vague to produce good results, ask the user for more specific conditions before searching. It is better to clarify than to return noise. Do this no more than 1 time.

No hallucination — ground every claim in retrieved data

• - Never fabricate what the user did, said, or experienced. Every detail in your answer must come from actual search results.
• Multi-step retrieval: for questions like "what did I do and say at XXX", do NOT answer from a single broad search. Follow this pattern:

• - Do not stuff keywords into search queries. Each semantic search query should be a short, coherent natural-language query, rather than stacking multiple possible words. You are encouraged to try different ones and query various times though.
• If data is missing, say so. Do not fill gaps with plausible-sounding guesses. "I couldn't find transcript data for that video" is always better than making something up.

How to invoke

Note: --after / --before are UTC. Convert from the user's local timezone first (see Timezone section above).

CODEBLOCK1

Parameters

Signed URLs

Image and keyframe results include a signed_url field — a temporary (1-hour) direct link to view/download from Google Cloud Storage. No authentication needed, but they expire after 1 hour.

Types reference

Media search types (require --query)

Type	What it searches	Supports
INLINECODE40	Video summaries by meaning	INLINECODE41, INLINECODE42
INLINECODE43

Image descriptions by meaning | --location, --after/before |

Media query types (list/filter)

Type	What it returns	Requires	Supports
INLINECODE55	Recent videos	—	INLINECODE56, INLINECODE57
INLINECODE58

Recent images | — | --location, --after/before |

Portrait query types (list/filter)

Type	What it returns	Supports
INLINECODE70	Personality traits, hobbies, interests	INLINECODE71
INLINECODE72

Events with participants | --person, --after/before, --event-ids |

Portrait search types (semantic, require --query)

Type	What it searches	Supports
INLINECODE82	Events by meaning	INLINECODE83, INLINECODE84
INLINECODE85

Traits by meaning | — |