GoodMem

View saved version →

---
name: goodmem-sdk
description: Versioned SDK references for building GoodMem into applications, in Python (goodmem), TypeScript (@pairsystems/goodmem), Java (ai.pairsys:goodmem-java), or .NET (PairSystems.Goodmem.Client). Use only when the user explicitly asks to write code that integrates GoodMem — spaces, ingestion, semantic retrieval, RAG pipelines. Default to Python unless they choose another language. Not for adding an embedder, reranker, or LLM to the user's own GoodMem instance — that is a one-time console link; follow using-goodmem-memory.
---

# GoodMem SDK

Use this skill for explicitly requested application code, scripts, or integrations.
Use Python unless the user chooses another language. Setting up a model in the
user's own instance is a console task: follow `using-goodmem-memory` and
`goodmem_console_setup`.

GoodMem stores memories inside spaces and chunks/embeds content for semantic
retrieval, with optional reranking or LLM answers. SDKs wrap `{base_url}/v1`,
using an `x-api-key` header with a `gm_…` key. Registering a known model through
the SDK's convenience API auto-fills provider, endpoint, and dimensionality.
Use space keys (`space_keys` in Python) for per-space filters and embedder weights;
Python's `stream=False` collects retrieval events instead of streaming them.

## Read only the relevant reference

1. Open the chosen language overview below. Use its tested example for a common
   workflow, or choose a namespace and operation from the linked indexes.
2. Read the operation page for exact signatures, behavior, and overload notes.
3. Open request-model pages for the arguments being constructed. Follow nested
   type links only for fields being used; optional fields do not require reading
   their entire model graph.

When search is available, search for the exact method or type name within the
chosen language directory. Do not concatenate reference directories or load
other languages. Small linked indexes provide the same navigation without shell
access.

- [Python](references/python.md)
- [TypeScript](references/typescript.md)
- [Java](references/java.md)
- [.NET](references/dotnet.md)

Each overview identifies the supported published SDK version. Server guidance
assumes GoodMem **1.0.320 or later**; older servers may lack APIs. Inspect an
existing application's installed version before reusing signatures, and do not
silently upgrade it. Read credentials from environment/configuration.

## Shared behavior

- **Spaces need an embedder.** Reuse or register one before creating a space.
  Current APIs use access policies; space creation has no public-read flag.
- **Ingestion is asynchronous.** After creation, poll until `COMPLETED`, stop on
  `FAILED`, and enforce a deadline before retrieval. Unindexed memories are
  invisible to search.
- **Retrieval is scoped and streamed.** Select the intended spaces and filters.
  Optional rerankers reorder passages; an LLM can generate an answer. Preserve
  usable passages when synthesis fails and report warnings or partial coverage.
- **Revocation is permanent.** API-key `status=INACTIVE` and DELETE perform the
  same revocation. Issue a replacement key; revoked keys cannot become ACTIVE.
  Revocation requires `DELETE_API_KEY`; label edits require `UPDATE_API_KEY`.
- **Protect credentials.** Provider error bodies can include secrets; do not
  log them or expose them in user-facing responses.
- **OCR requires Enterprise.** On other instances, ingest document text/PDF
  memories instead of calling the OCR namespace.

Referenced files: 864

View saved version →

---
name: goodmem-troubleshooting
description: Verify and troubleshoot the hosted GoodMem Cloud connection, authorization, model setup, processing failures, and retrieval problems. Use when GoodMem is unavailable or the user asks how to connect or repair it.
---

# Troubleshoot GoodMem Cloud

GoodMem connects only through its hosted OAuth gateway to the user's selected
GoodMem Cloud instance. Never request an API key, instance URL, or local server
configuration for this plugin.

## Verify the connection

Call `goodmem_users_me` first. Success confirms the selected account and instance;
report the connected identity and continue with the original task.

## Diagnose failures

| Symptom | Likely cause | Action |
|---|---|---|
| Connection is unauthorized after previously working | The instance key or grant changed | Reconnect GoodMem through the current host |
| Sign-in rejects the account | Organization access is not enabled | Ask the GoodMem administrator |
| Instance is absent from the picker | Wrong team, provisioning, or paused instance | Select the correct team and check the GoodMem Cloud console |
| Space creation returns a setup link | No embedder is configured | Relay the Quick Start link exactly; afterward list spaces and reuse the first space before attempting another create |
| Memory status is `FAILED` | Embedding pipeline or provider configuration failed | Read `processing_error` and direct the user to repair it in the cloud console |
| Agent transcribes a PDF into separate text memories | Outdated instructions or an unavailable upload tool | Check that `goodmem_memories_upload` is available and refresh the plugin instructions and tool list; do not repeat the text saves |
| Upload tool or native file object is unavailable | Outdated tool discovery or the host did not provide a usable attachment | Refresh available tools or request a fresh attachment; explain the limitation without silently transcribing |
| Retrieval with synthesis times out | Large search or answer-generation workload | Reduce the result scope or retrieve without synthesis |

Do not retry authorization failures blindly.

## Reconnect through the current host

Disconnect and reconnect the GoodMem app through the current host's connection
settings. This restarts OAuth against the same hosted gateway and cloud instance.

When the user asks to create or add an embedder, reranker, or LLM, follow the
model-setup steps in `using-goodmem-memory`: call `goodmem_console_setup` with
the matching `kind` and relay the one-time console link verbatim — never write
code or collect provider keys in chat for this.

View saved version →

---
name: save-conversation
description: Save a useful conversation to GoodMem as self-contained question-and-answer pairs, including documents shared in the conversation. Use only when the user asks to save, remember, or keep the discussion.
---

# Save a conversation

Save only when the user asks. Capture durable decisions, facts, and conclusions;
omit greetings, clarifying one-liners, and tool-call chatter.

## Choose the space

Call `goodmem_spaces_list` first. Reuse an obviously matching space or create one
named for the topic, not the date. If the user supplies a name, use it exactly.
Tell the user which space you chose. Keep using that space if they save more of
the same session later.

If no embedder is configured, follow the Quick Start steps in
`using-goodmem-memory`. After setup, list spaces again and reuse a suitable space
before creating another.

## Save self-contained exchanges

Create one memory per useful exchange with both sides present:

```text
Q: What did we decide about the vendor contract?
A: We chose Cooperativa San Rafael at 6.80 USD/kg, quarterly shipments,
   pending legal review of the termination clause.
```

Call `goodmem_memories_create` once per pair with metadata such as
`{"type":"qa_pair","topic":"vendor contract"}`. Never save a bare answer that
will lose its meaning outside the current chat.

## Include shared documents

A document discussed in the saved conversation is part of what the user asked to
keep. Follow `work-with-documents` to upload each original attachment as one
memory with `goodmem_memories_upload`; do not transcribe it into per-page text
memories. Use metadata connecting it to the conversation, and name the document
in the related Q&A answer so later retrieval connects them. Use text creates for
pasted text or explicitly requested excerpts.

If a file cannot be uploaded or GoodMem reports a processing failure, explain
the problem while preserving the useful discussion. Do not silently replace the
original with a transcription or claim that an unsaved file was retained.

## Confirm the result

Report the space name, number of Q&A pairs, and documents saved. If processing is
still underway, distinguish "saved" from "searchable" and follow the processing
rules in `using-goodmem-memory`.

Confirm the specific memory before deletion. Never bulk-delete unless the user
explicitly covers the whole set.

View saved version →

---
name: using-goodmem-memory
description: Recall, store, and manage knowledge in the user's GoodMem Cloud instance, and add or configure its models. Use when stored project or team knowledge may answer a question, when the user asks to save or organize knowledge, or when they ask to create, add, or set up an embedder, embedding model, reranker, or LLM on GoodMem — model setup is a one-time console link, never code. Use the SDK skill only when the user explicitly asks to write code.
---

# Using GoodMem memory

Treat GoodMem as the user's persistent project or team memory. The connection is
always through GoodMem's hosted gateway to the GoodMem Cloud instance selected
during sign-in. Never ask for an instance URL, API key, or local GoodMem server.

## Recall relevant knowledge

When stored decisions, notes, documents, project context, or earlier conversations
could plausibly answer the user's question, call `goodmem_memories_retrieve`
without asking permission first. Skip retrieval for general knowledge, arithmetic,
or questions fully answered by the current conversation.

- Scope to `space_ids` when the relevant space is clear. Otherwise search all
  spaces; use `goodmem_spaces_list` when seeing their names would help.
- Use `metadata_filter` for constraints represented by metadata, such as filename,
  type, topic, or year.
- Use `answer: true` when synthesis across many memories would materially help.
  Otherwise retrieve passages and answer from them directly.
- Report `warnings` and `skipped_spaces` when retrieval is partial. If
  `synthesis_error` is present, answer from the usable passages and explain the
  limitation. Per-space fallback interleaves local rankings; do not interpret
  its scores as one global relevance order.
- Name the source memory, document, or space. Prefer the user's retrieved record
  over general assumptions and call out conflicts.
- If nothing relevant is returned, say so plainly. Never invent a memory or imply
  that an unindexed memory appeared in search.

Use `goodmem_memories_content` for stored text, following `next_offset` while
`truncated` is true, and
`goodmem_memories_pages` to navigate page-oriented documents.

## Create and organize knowledge

Write only when the user asks to save, remember, ingest, or organize something.

1. Call `goodmem_spaces_list` and reuse an obviously matching space.
2. Otherwise call `goodmem_spaces_create` with a clear topic or project name and
   tell the user which space was chosen. The instance's embedder is selected
   automatically; if several exist, use an `embedder_name` offered by the tool.
3. For text, create one coherent memory per fact, passage, or natural section
   with useful typed metadata such as topic, source, filename, page, or date.
   For an uploaded file, use `goodmem_memories_upload` to save the original as
   one memory; do not extract and save each page yourself.

For conversations, follow the `save-conversation` skill. For files, follow the
`work-with-documents` skill.

If space creation reports that no embedder exists, relay its one-time Quick Start
link exactly. Quick Start sets up an embedding model, any chat model or reranker
supported by the provider, and an optional first space from a provider key entered
on the console page. For an explicit initial-setup request, call
`goodmem_console_setup` with `kind: "quick_start"`.

When the user finishes Quick Start, call `goodmem_spaces_list` again. Reuse the
space it created if suitable for the user's task; do not blindly retry the failed
space creation and create a duplicate. If the user skipped creating a space, or
needs a separate one, create it using the now-configured embedder and continue
the original save. If setup was incomplete, explain what is still needed.

## Add or change models — embedder, reranker, LLM

On GoodMem, "create an LLM", "add an embedder", or "set up a reranker" means
registering a model configuration on the user's GoodMem Cloud instance. It is a
console action, identical on every surface:

1. Call `goodmem_console_setup` with `kind` set to `embedder`, `reranker`, or
   `llm`. An `embedder` request automatically opens Quick Start when the instance
   has no embedders; check the returned `kind`.
2. Relay the returned link verbatim, noting it works once, expires in about
   30 minutes, and asks for the user's own model provider API key on the page.
3. When the user says they are done, follow the space-discovery steps above if
   the returned `kind` was `quick_start`; otherwise retry whatever needed the model.

Never write code, scaffold a project, or touch provider credentials for this —
the API key belongs on the console page, not in the chat. An embedder makes
memories searchable, a reranker sharpens retrieval order, and an LLM enables
synthesized answers. Write integration code only when the user explicitly asks
for code; then follow the `goodmem-sdk` skill.

## Processing and failures

Ingestion is asynchronous. Keep saving instead of polling after every memory.
A memory is searchable only at `COMPLETED`; do not describe `PENDING` or
`PROCESSING` content as searchable.

When a response reports `failed_count`, state how many memories failed. Use
`goodmem_memories_list` to inspect statuses and `goodmem_memories_get` when the
processing error is needed. Explain that model and provider-key repairs happen in
the GoodMem Cloud console. A `not_indexed` result means the content exists but is
not available to semantic search.

## Changes and deletion

Creating, updating, and deleting require user intent. Confirm the specific target
before `goodmem_memories_delete`; never loop over a whole space on a vague deletion
request. Keep raw tool output out of the response unless the user asks for it.

View saved version →

---
name: work-with-documents
description: Save original file attachments in GoodMem and later search, quote, compare, or navigate their contents. Use when the user asks to remember a shared file or work with a document already stored in GoodMem.
---

# Work with documents in GoodMem

When the user asks to save a PDF or another uploaded file, send the original file
to GoodMem. GoodMem preserves its bytes and handles extraction and chunking.
Create one memory per original file, not one memory per page. Reading or
transcribing the attachment first is unnecessary and loses its original structure.

## Ingest a shared document

1. Call `goodmem_spaces_list`; reuse the matching space or create a topic-based
   one. If setup is needed, follow Quick Start in `using-goodmem-memory` and list
   spaces again afterward so its first space can be reused. Tell the user which
   space you used.
2. Call `goodmem_memories_upload` with the selected `space_id`, a unique
   `operation_id`, and the attachment's native `file` object: `download_url` and
   `file_id`, plus `file_name` and `mime_type` when available. Do not pass base64,
   a local path, or extracted page text to the text-create tool.
3. Include metadata such as `{"type":"document","filename":"<original name>"}`
   and the context it was shared for. Set `extract_page_images=true` when PDF
   page images should also be retained; separate per-page uploads are unnecessary.
4. After an interrupted response, retry with the same operation ID, file ID,
   and other arguments. Refresh only an expired download URL. The gateway can
   recover an accepted file without uploading it again.
5. Keep ingesting without polling every file. Check the space in bulk with
   `goodmem_memories_list`, then apply the processing and failure rules from
   `using-goodmem-memory`.

Follow the file-size limit advertised by the upload tool. If a known size exceeds
it, ask for a smaller file or a split original document. If size is unknown, try
the upload and explain any size-limit rejection without retrying the unchanged file.

If `goodmem_memories_upload` or a usable native file object is unavailable, explain
that original-file upload is unavailable on this connection. Check for updated
tools or request a fresh attachment; do not invent a download URL or silently
switch to transcription. Use `goodmem_memories_create` for pasted text, notes, or
excerpts only when the user asks to save that text. Split those text saves at
natural boundaries when useful, preserving source and page metadata.

An upload by itself is not permission to retain the file indefinitely. Save it to
GoodMem when the user asks to remember, add, store, or ingest it; otherwise work
with the upload only for the current request.

## Work with stored documents

- Retrieve passages with `goodmem_memories_retrieve`; use `metadata_filter` when
  the user identifies a filename, type, or other stored attribute.
- Read stored text with `goodmem_memories_content`. When `truncated` is true,
  continue with the returned `next_offset` until the needed text is read.
  Offsets count UTF-8 bytes; use the returned value rather than a character
  count. The native `fetch` tool returns the first page; when `truncated` is true,
  continue with `goodmem_memories_content`, setting `memory_id` to the returned
  `id` and `offset` to `next_offset`. `fetch` itself does not accept an offset.
  For binary originals such as PDFs, use retrieved text passages and page
  metadata; do not present the original binary bytes as extracted text.
- Use `goodmem_memories_pages` to list retained page images. It does not upload
  pages or replace the original-file upload.
- Use `goodmem_memories_list` to see what a space contains.

Quote or paraphrase the relied-on passage and name its filename. When comparing
documents, attribute each claim and describe disagreements explicitly.

An original-file upload has one memory ID; older text ingestions may have several
parts. Confirm the document and scope before calling `goodmem_memories_delete`
on the relevant memory IDs.