Getting Started

Use this page to build the right mental model before you look at the individual APIs.

The most important thing to understand is that this package is a focused LangChain wrapper around a subset of GoodMem:

  • it writes memories into a GoodMem space

  • it retrieves chunk-level semantic matches from that space

  • it optionally exposes a GoodMem-managed embedder as a LangChain Embeddings object

  • it exposes GoodMemResources for the embedders, spaces, and memories needed by normal LangChain RAG/search workflows

Core Capabilities

  • GoodMemVectorStore binds to an existing GoodMem space or creates a new one

  • GoodMemResources manages the embedders, spaces, and memories needed for normal LangChain RAG/search workflows without exposing the full GoodMem SDK

  • GoodMemEmbeddings exposes a GoodMem-managed OPENAI-compatible embedder as a LangChain Embeddings implementation

  • the integration keeps create, write, search, filter, and error semantics explicit for LangChain callers

What GoodMem Means Here

GoodMem has a few core concepts that matter when you use this package:

  • a space is the container you write into and search within

  • a memory is one stored source item plus metadata

  • GoodMem processes a memory asynchronously and may split it into one or more searchable chunk values

That means write and search APIs return different identifiers:

  • write calls return memory IDs

  • search calls return chunk-level Document values

  • Document.id in search results is the matching chunk ID

  • the parent memory ID and space ID stay available in Document.metadata under _goodmem_memory_id and _goodmem_space_id

Quick Start

If your GoodMem instance is already initialized, reachable, and you have a valid API key, the shortest clean-slate path looks like this:

from langchain_core.documents import Document

from langchain_goodmem import GoodMemResources

resources = GoodMemResources.from_env()
store = resources.bootstrap_vector_store(
    space_name="langchain-demo",
    endpoint_url="https://embeddings.example/v1",
    model_identifier="text-embedding-3-small",
    dimensionality=1536,
)
store.add_documents([Document(page_content="GoodMem works with LangChain.")])
results = store.similarity_search("How does GoodMem work with LangChain?", k=1)

For a complete runnable version, see examples/goodmem_embeddings_bootstrap_workflow.py in the repository.

Which Entry Point Should I Use?

  • Use GoodMemVectorStore(space_id=..., connection=...) when you already have a GoodMem space ID.

  • Use GoodMemVectorStore.create(...) when you want this package to create a new space for you.

  • Use GoodMemResources(...) when you need to create/list/get/delete the embedders, spaces, or memories used by the normal LangChain workflow.

  • Use GoodMemResources.bootstrap_vector_store(...) when you want the package to create or reuse the server-side GoodMem embedder, create a space, and return a store for add_documents(...) and similarity_search(...).

  • Use GoodMemEmbeddings(...) only when you need local LangChain embedding calls or when GoodMemVectorStore.create(..., embedding=...) should retain a LangChain Embeddings object on the returned store.

  • Use GoodMemEmbeddings.ensure(...) or GoodMemEmbeddings.ensure_from_env(...) when you want the package to bridge the clean-slate setup gap by finding or creating one compatible OPENAI-style GoodMem embedder before returning a normal GoodMemEmbeddings instance. ensure_from_env(...) also supports GOODMEM_EMBEDDER_ID reuse when the bootstrap environment is present and explicitly matches that embedder.

Two Startup Paths

For embeddings workflows, there are two intentionally different ways to begin:

  • Existing-resource path: if you already have a compatible GoodMem embedder, construct GoodMemEmbeddings(embedder_id=..., connection=...) directly.

  • Clean-slate bootstrap path: if you do not yet have a compatible embedder, use GoodMemEmbeddings.ensure(...) or GoodMemEmbeddings.ensure_from_env(...). If you set GOODMEM_EMBEDDER_ID for ensure_from_env(...), still provide the bootstrap environment and keep it aligned with that embedder so config drift is caught early.

GoodMemResources.bootstrap_vector_store(...) is the one-shot clean-slate path: it can resolve a compatible embedder, create a space, and return a ready-to-use GoodMemVectorStore for add/search workflows. It does not initialize or retain a local LangChain Embeddings object; use GoodMemEmbeddings.ensure(...) explicitly when your application needs local embedding calls. Broader platform administration such as API keys, server init, migrations, system operations, and LLM/reranker/OCR/extension management stays in GoodMem’s SDK, CLI, and UI.

Before You Start

  • You need a running GoodMem server or deployment.

  • You need GOODMEM_API_KEY and GOODMEM_BASE_URL, or you can pass those values directly into GoodMemConnection(...).

  • If you plan to use local GoodMemEmbeddings, install the optional extra with pip install -e '.[openai]'.

  • If you plan to use GoodMemResources.bootstrap_vector_store(...), provide GOODMEM_EMBEDDINGS_BASE_URL, GOODMEM_EMBEDDINGS_MODEL_IDENTIFIER, and GOODMEM_EMBEDDINGS_DIMENSIONS. Set GOODMEM_EMBEDDINGS_API_KEY when the upstream provider key must be stored on a newly created embedder. The GOODMEM_EMBEDDER_ID environment variable is used only by GoodMemEmbeddings.ensure_from_env(...).

If you are new to GoodMem itself, the official product documentation is the best place to learn the platform concepts and server setup:

The package module docstring below is the canonical quick-start narrative for the public surface.

langchain-goodmem package entry point and quick-start guide.

This package exposes a small, explicit LangChain-facing surface for GoodMem:

  • GoodMemConnection for shared API/TLS configuration

  • GoodMemResources for GoodMem resources needed by normal RAG workflows

  • GoodMemVectorStore for writing memories and retrieving semantic matches

  • GoodMemEmbeddings for GoodMem-managed OPENAI-compatible embedders

  • GoodMemSpaceEmbedder for create-time space/embedder declarations

GoodMem concepts used throughout this package:

  • a space is the top-level container you write into and search within

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

  • GoodMem processes each memory asynchronously and may split it into one or more retrievable chunk values

That distinction matters when you read search results:

  • write methods such as add_documents(...) and add_texts(...) return memory IDs

  • search methods return LangChain Document values whose Document.id is the GoodMem chunk ID for the matching chunk

  • the parent memory ID and originating space ID remain available in Document.metadata under _goodmem_memory_id and _goodmem_space_id

Python 3.10 or newer is required.

Install the core package:

pip install -e .

Install optional extras only when needed:

  • pip install -e '.[openai]' for GoodMemEmbeddings

  • pip install -e '.[test]' for the unit and live test suites

  • pip install -e '.[docs]' for the Sphinx documentation build

Provide GoodMem credentials either directly in code or through environment variables consumed by GoodMemConnection.from_env():

  • GOODMEM_API_KEY

  • GOODMEM_BASE_URL

Choose a store-binding flow:

  • if you already have a GoodMem space ID, bind directly with GoodMemVectorStore(space_id=..., ...)

  • if you need the package to create a new space for you, use GoodMemVectorStore.create(...)

  • if you need to manage the GoodMem resources around the LangChain workflow, use GoodMemResources

  • if you are starting from a clean GoodMem instance and want a ready-to-use add/search store, use GoodMemResources.bootstrap_vector_store(...)

Choose an embeddings flow:

  • if you already have one compatible GoodMem embedder ID, construct GoodMemEmbeddings(embedder_id=..., ...) directly

  • if you are starting from a clean slate and need the package to find or create one compatible OPENAI-style embedder first, use GoodMemEmbeddings.ensure(...) or GoodMemEmbeddings.ensure_from_env() and, when reusing GOODMEM_EMBEDDER_ID through the environment helper, keep the bootstrap environment present and aligned with that embedder

GoodMemResources covers the GoodMem resources needed for normal LangChain RAG/search workflows: embedders, spaces, memories, and server-side search bootstrap. bootstrap_vector_store(...) does not initialize or retain a local LangChain Embeddings object. It intentionally leaves broader platform administration to GoodMem’s SDK, CLI, and UI.

Minimal existing-space add-and-search flow:

from langchain_core.documents import Document
from langchain_goodmem import GoodMemConnection, GoodMemVectorStore

connection = GoodMemConnection.from_env()
store = GoodMemVectorStore(
    space_id="your-existing-space-id",
    connection=connection,
)
memory_ids = store.add_documents(
    [Document(page_content="GoodMem stores semantically searchable memories.")],
    ids=["memory-1"],
)
results = store.similarity_search(
    "How does GoodMem work with LangChain?",
    k=1,
)
print("created memory:", memory_ids[0])
print("matching chunk:", results[0].id)
print("parent memory:", results[0].metadata["_goodmem_memory_id"])

Search visibility is eventually consistent because GoodMem processes written memories before they become searchable.

For fuller workflows:

  • see examples/basic_semantic_search.py for existing-space usage

  • see examples/goodmem_embeddings_bootstrap_workflow.py for clean-slate RAG/search bootstrap usage

  • see GoodMemVectorStore.create for create-helper usage

  • see examples/goodmem_embeddings_workflow.py for embeddings-driven usage