Troubleshooting

When this repository misbehaves, the failures usually fall into one of a small number of buckets:

  • import or dependency problems goodmem is required for transport-backed workflows, and langchain-openai is required for GoodMemEmbeddings

  • missing environment variables public usage needs GOODMEM_API_KEY and GOODMEM_BASE_URL; live embeddings coverage and GoodMemEmbeddings.ensure_from_env(...) may also need GOODMEM_EMBEDDINGS_*, and GOODMEM_EMBEDDER_ID reuse still requires those bootstrap values to match the selected embedder

  • filter expression mistakes GoodMem filters are their own language and operate on memory-level metadata, not on chunk-level result objects

  • eventual consistency surprises a successful write does not guarantee that the memory is immediately searchable, because GoodMem still needs to process it into chunks

Good references while debugging:

  • the public embeddings and vectorstores module docstrings for user-facing setup and failure behavior

  • tests._integration_live_support for the exact live-test environment policy

  • the official GoodMem filter expressions reference when a filter is rejected by the backend

LangChain embeddings adapter for GoodMem-managed embedders.

GoodMemEmbeddings turns one existing GoodMem embedder resource into a LangChain Embeddings implementation, but only when that GoodMem embedder is compatible with an OPENAI-style upstream embeddings endpoint.

Use this adapter when you need local LangChain embedding calls such as embed_query(...) or embed_documents(...), or when you want GoodMemVectorStore.create(..., embedding=...) to both create a space and retain a LangChain Embeddings object on the returned store.

You do not need GoodMemEmbeddings just to search an existing GoodMem space. GoodMemVectorStore(space_id=..., ...) can retrieve directly from GoodMem without any local embeddings object.

Credential resolution order:

  1. readable inline API key stored on the GoodMem embedder

  2. GOODMEM_EMBEDDINGS_API_KEY

For clean-slate onboarding, GoodMemEmbeddings.ensure(...) and GoodMemEmbeddings.ensure_from_env(...) can find or create one compatible GoodMem embedder before returning a normal GoodMemEmbeddings instance. ensure_from_env(...) also supports GOODMEM_EMBEDDER_ID reuse, but when that path is used the bootstrap environment must still be present and must match the selected embedder so configuration drift stays explicit. For broader RAG-resource setup such as spaces, memories, and one-shot vector-store bootstrap, use GoodMemResources.

Additional environment support:

  • GOODMEM_EMBEDDINGS_DIMENSIONS remains optional, but when set it must match the dimensionality declared on the selected GoodMem embedder

  • GOODMEM_EMBEDDINGS_BASE_URL, GOODMEM_EMBEDDINGS_MODEL_IDENTIFIER, and GOODMEM_EMBEDDINGS_DIMENSIONS are required by GoodMemEmbeddings.ensure_from_env(...) even when that helper reuses an existing GOODMEM_EMBEDDER_ID

Common setup failures covered by this module include:

  • missing optional langchain-openai dependency

  • unsupported provider type or modality

  • upstream credential forwarding that GoodMem cannot perform directly

  • provider initialization or request failures, which normalize to GoodMemAPIError

LangChain vector-store integration backed by GoodMem semantic retrieval.

This module is the main public workflow surface for the repository.

Two primary usage modes are supported:

  • bind to an existing GoodMem space with GoodMemVectorStore(...)

  • create a new GoodMem space with GoodMemVectorStore.create(...)

GoodMem uses three related concepts that map differently to LangChain:

  • a space is the search scope

  • a memory is one stored item of source content plus metadata

  • a chunk is a searchable fragment produced by GoodMem from a memory

Write methods in this module create memories. Retrieval methods return chunks. One memory can therefore produce multiple search results over time.

Write behavior is intentionally explicit:

  • caller-provided IDs are treated as memory IDs with strict create-if-absent semantics

  • Document.id is used as a fallback memory ID source in add_documents(...)

  • duplicate IDs in a single call raise GoodMemDuplicateIDError before any backend call

Search behavior is chunk-level:

  • Document.id in search results is the GoodMem chunk_id

  • the parent memory ID is preserved in Document.metadata as _goodmem_memory_id

  • the originating space ID is preserved in Document.metadata as _goodmem_space_id

  • scored results also expose _goodmem_score in metadata

Metadata filters are passed through to GoodMem unchanged. They operate on the memory-level metadata JSON attached to each stored memory, not on LangChain Document.metadata after conversion and not on chunk text. The documented GoodMem filter language uses helpers such as val('$.field') and exists('$.array[*]'). A minimal equality example is val('$.lang') = 'en'.

GoodMem processes new memories asynchronously before they become searchable, so fresh writes may not appear in retrieval results immediately.

The create helper intentionally keeps a minimal LangChain-facing surface. If you need GoodMem resource helpers around the normal RAG/search path, use GoodMemResources. Broader platform administration remains outside this LangChain integration.

Live integration-test helpers and environment contract.

This module centralizes the resource lifecycle and environment policy for the repository’s live GoodMem tests.

Required base environment:

  • GOODMEM_API_KEY

  • GOODMEM_BASE_URL

Optional reuse controls:

  • GOODMEM_SPACE_ID to reuse an existing space for existing-space coverage

  • GOODMEM_EMBEDDER_ID to reuse an existing compatible embedder

Optional auto-provisioning inputs for embeddings coverage:

  • GOODMEM_EMBEDDINGS_API_KEY

  • GOODMEM_EMBEDDINGS_BASE_URL

  • GOODMEM_EMBEDDINGS_MODEL_IDENTIFIER

  • GOODMEM_EMBEDDINGS_DIMENSIONS

  • GOODMEM_EMBEDDINGS_PROVIDER_TYPE

Resource lifecycle:

  • existing resources referenced through environment variables are reused and not deleted

  • temporary spaces and embedders created by the tests are cleaned up at the end of the run

  • cleanup failures fail the test run so resource leaks stay visible

Additional behavior:

  • GOODMEM_VERIFY is parsed only here, not by GoodMemConnection.from_env

  • semantic retrieval is eventually consistent, so tests poll until the expected chunk becomes visible or the timeout is reached