Gemdex

Permanently delete a stored memory by id (and its attachments/blobs). 🎯 **When to use**: when a memory is obsolete, wrong beyond repair, duplicated after consolidation, or the user explicitly asks to forget something. Prefer `update_memory` when the facts can be corrected in place. Get the id from a prior save_memory, recall, or get_memory result. Behavior: removes the memory from the backend (local LanceDB or remote BYOI `DELETE /v1/memories/:id`). Also clears this client's per-memory outcome stats for that id. Irreversible via MCP — confirm with the user when unsure.

Load the full content of one stored memory by id. 🎯 **When to use**: after `recall` returns a title that looks clearly relevant to the current task — or when you already have an exact id from `save_memory`. This is the only MCP path that returns the full parent body. Most recalls need no follow-up; only open memories you actually intend to use. Behavior: returns title, id, relative age, optional track-record and attachment metadata, and the full content. Use `read_attachment` afterward if you need attachment/transcript bytes. Opening a memory counts as a recall for the per-client outcome ledger (feeds track-record / optional trust ranking).

Read the bytes of an attachment on a stored memory as text (UTF-8) or base64. 🎯 **When to use**: after `get_memory` shows a memory with attachments — especially chat digests that include a `file` attachment captioned "Full transcript (source file)". Prefer this over opening a local path when running in remote mode (BYOI): the bytes live in the server blob store and are fetched over HTTP. No GEMINI_API_KEY required. Args: `memory_id` (required), optional `attachment_id` (omit when there is exactly one attachment, or a single transcript/`file` attachment), optional `max_chars` (default ~1.5M; truncates with a clear overflow note).

Search the user's global memory layer by natural-language query and return a cheap ranked title index (never full bodies). 🎯 **When to use**: proactively and by default — make checking memory a reflex, not something you wait to be told to do. Recall at the start of a task, before solving a problem, before setting up a tool or environment, before making a design/convention decision, and before asking the user for information they may have already given you. A title-index recall is cheap; prefer checking first over assuming nothing is stored. Behavior: hybrid semantic + BM25 search, fused by relevance. Always returns up to 10 hits as title + id only (plus a track-record line when outcome stats exist). Most tasks end here with nothing useful — that is expected. When a title looks clearly task-relevant, open THAT memory with `get_memory({ id })`. Do not expect bodies from this tool. Setting `GEMDEX_TRUST_RANKING=true` re-ranks the title index by track record (off by default; ranking stays pure relevance until you opt in).

Report how acting on a recalled memory went, so the memory layer learns which memories are trustworthy. 🎯 **When to use**: right after you used a recalled memory and the outcome is clear — `worked` (followed it and it was correct), `failed` (its information was wrong or broken), `stale` (clearly outdated, e.g. rotated credentials or moved paths). One call per memory actually used; do not report memories you merely saw in results. This is meta-feedback on the memory layer itself and is the one gemdex tool you should call without being asked, whenever a clear outcome exists. Recorded locally in a per-client ledger keyed by memory id (not written back into the memory itself). With `GEMDEX_TRUST_RANKING=true` it also adjusts future `recall` ranking — proven memories rank higher, memories that have burned the agent rank lower.

Persist a new memory to the user's global, durable memory layer. 🎯 **When to use**: proactively, as you work — you do NOT need the user to ask. Save durable, reusable knowledge the moment you learn it: hard-won fixes and root causes, project conventions and architecture decisions, setup/build/deploy steps, credentials and paths the user shares, gotchas, and the rationale behind choices. If it's likely to matter in a future session or repo, store it now without waiting for permission. Explicit user requests ("remember that…", "save this") are just one trigger among many. Keep memories to durable, reusable facts — skip one-off trivia and anything easily re-derived from the current context. Behavior: the content is chunked, embedded via the selected text provider (Gemini or local MLX), and stored globally (searchable from every repo and session). Returns the new memory id. Multimodal: optionally pass `attachments` (image/audio/video/PDF) to embed media alongside the text. Each attachment is either a local file `path` (preferred — the server reads + encodes the bytes, so you don't emit base64) or inline base64 `data`. Requires the gemini-embedding-2 model. Either `content` or at least one attachment is required. If the response includes a "⚠ similar existing memories already stored" block, the store found near-duplicate/conflicting memories already there — read it and consolidate with `update_memory` (or confirm with the user which should win) rather than leaving both.

Revise an existing memory in place, identified by its id. 🎯 **When to use**: proactively whenever you discover a stored memory is outdated, wrong, or duplicated — not only when the user asks ("the notarization step changed — update that memory"). If you learn a better fact, or a `save_memory` response flags "⚠ similar existing memories already stored", prefer correcting/consolidating the existing memory in place over leaving stale or conflicting copies. Get the id from a prior save_memory, recall, or get_memory result. Two ways to change the text: - `edits`: targeted find-and-replace — preferred for large memories. Pass an array of `{ oldText, newText, replaceAll? }`; you emit only the changed snippets instead of resending the whole note. Each `oldText` must match exactly and be unique (set `replaceAll: true` to change every occurrence). - `content`: full replacement of the text. Use for small memories or rewrites. `content` and `edits` are mutually exclusive. Behavior: re-chunks and re-embeds the resulting content under the same id. Omitted fields are preserved — leave out `content`/`edits` to keep the prior text, leave out `attachments` to keep the prior media (pass `attachments: []` to clear it). Each attachment is either a local file `path` (preferred) or inline base64 `data`. To remove a memory entirely, use `delete_memory`.