Developer Getting Started

This page is the recommended first stop for contributors who are new to the repository.

What This Package Is

langchain-goodmem is a focused LangChain wrapper around a subset of GoodMem. It is not a full GoodMem SDK replacement.

The package is intentionally narrow:

  • it exposes GoodMem spaces as LangChain-facing vector-store workflows

  • it exposes one compatible class of GoodMem-managed embedders as LangChain Embeddings

  • it includes GoodMemResources for embedders, spaces, memories, and clean-slate server-side vector-store bootstrap needed by normal RAG/search workflows

  • it keeps validation, transport mapping, and error normalization inside package-owned layers so behavior stays explicit and testable

If you need the full GoodMem platform surface such as API keys, server init, migrations, system operations, or LLM/reranker/OCR/extension administration, contributors should expect to use the official GoodMem SDK, CLI, or UI rather than growing langchain-goodmem into a full mirror of the platform.

GoodMem Concepts That Matter To Contributors

These concepts appear throughout both the user-facing API and the internal layers:

  • 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 a memory asynchronously and may split it into one or more searchable chunk values

  • an embedder is a GoodMem-managed embedding configuration that can be attached to a space and, in some cases, exposed locally as LangChain Embeddings

  • GoodMemResources covers the GoodMem resources needed by the normal LangChain RAG/search path without becoming a full platform admin client

  • metadata filters apply to memory-level JSON metadata through the GoodMem filter language, not to chunk-level LangChain result objects

  • search is eventually consistent because writes need to be processed into retrievable chunks before they appear in semantic search

The most important identifier distinction in this repository is:

  • write APIs return memory IDs

  • search APIs return LangChain Document values whose Document.id is the matching chunk ID

Layer Map

Read and reason about the repository in this order:

  1. public entry points src/langchain_goodmem/connection.py, src/langchain_goodmem/vectorstores.py, src/langchain_goodmem/embeddings.py, src/langchain_goodmem/space_embedders.py, src/langchain_goodmem/errors.py

  2. validators src/langchain_goodmem/_internal/validators.py

  3. behavior layer src/langchain_goodmem/_internal/memory_ops.py

  4. transport layer src/langchain_goodmem/_internal/transport.py

  5. internal normalized types src/langchain_goodmem/_internal/types.py

  6. tests tests/ plus the live helper module in tests/_integration_live_support.py

The intent behind this split is simple:

  • public modules define the supported behavior

  • validators reject malformed caller input before the SDK is touched

  • behavior helpers turn raw GoodMem responses into stable package semantics

  • the transport layer is the only place that talks directly to the official GoodMem SDK

  • internal types let upper layers depend on package-owned contracts instead of raw SDK models

For more detail after this overview, continue to Internal Architecture and Internal Types.

Where To Read First

Start from the entrypoint that matches the change you want to make:

  • public behavior Read src/langchain_goodmem/vectorstores.py and src/langchain_goodmem/embeddings.py, then confirm expected behavior in the public docs under API Reference.

  • transport boundary Read src/langchain_goodmem/_internal/transport.py and tests/test_transport_unit.py.

  • internal normalized types Read src/langchain_goodmem/_internal/types.py and then the companion Internal Types page.

  • unit tests Start with Testing, then narrow to tests/test_connection_unit.py, tests/test_embeddings_unit.py, tests/test_resources_unit.py, tests/test_transport_unit.py, or tests/test_vectorstore_unit.py.

  • live integration helpers Read tests/_integration_live_support.py and the Test Helpers page before changing live coverage.

Local Setup And Verification

Use the minimum setup needed to read, test, and rebuild docs locally:

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[test]'
pip install -e '.[docs]'

Run the static quality checks:

./.venv/bin/ruff check src tests
./.venv/bin/ruff format --check src tests

Rebuild docs:

./.venv/bin/sphinx-build -W -E -b text docs/source docs/build/text
./.venv/bin/sphinx-build -W -E -b html docs/source docs/build/html

Run the unit suite:

./.venv/bin/python -m pytest \
  tests/test_connection_unit.py \
  tests/test_embeddings_unit.py \
  tests/test_resources_unit.py \
  tests/test_transport_unit.py \
  tests/test_vectorstore_unit.py

Run the live integration suite:

./.venv/bin/python -m pytest \
  tests/test_integration_existing_space_live.py \
  tests/test_integration_create_live.py \
  tests/test_integration_embeddings_live.py \
  -m integration

How To Choose The Right Test Surface

Use unit tests when:

  • you are changing validation logic

  • you are changing vector-store behavior or result mapping

  • you are changing embeddings setup or provider compatibility rules

  • you are changing transport normalization and want fast feedback without a live GoodMem deployment

Use live integration tests when:

  • you are changing behavior that depends on the real GoodMem SDK or server

  • you need to confirm eventual-consistency handling

  • you need confidence that create, write, retrieval, and embedder wiring still works end to end

If a change touches both public behavior and the SDK boundary, start with unit tests to pin down semantics, then run the live suite for end-to-end confidence.

Common First Tasks

If you are changing vector-store behavior:

  • start with src/langchain_goodmem/vectorstores.py

  • then review src/langchain_goodmem/_internal/memory_ops.py

  • verify with tests/test_vectorstore_unit.py

If you are changing embeddings behavior:

  • start with src/langchain_goodmem/embeddings.py

  • then review src/langchain_goodmem/_internal/providers.py

  • then review src/langchain_goodmem/_internal/types.py and src/langchain_goodmem/_internal/transport.py if the change touches bootstrap matching, creation, or SDK mapping

  • verify with tests/test_embeddings_unit.py

If you are changing transport mapping or SDK exception handling:

  • start with src/langchain_goodmem/_internal/transport.py

  • verify with tests/test_transport_unit.py

If you are changing docs only:

  • start with the relevant page under docs/source/

  • rebuild both text and HTML docs

  • confirm that any referenced public semantics still match the module docstrings

Boundaries And Non-Goals

Everything under src/langchain_goodmem/_internal is implementation-facing. It exists to keep the public package surface small and explicit, not to serve as its own stable API.

The public contract lives in the pages generated from:

  • src/langchain_goodmem/connection.py

  • src/langchain_goodmem/vectorstores.py

  • src/langchain_goodmem/embeddings.py

  • src/langchain_goodmem/space_embedders.py

  • src/langchain_goodmem/errors.py

Contributors should treat the reference docs as the source of truth for externally visible behavior and treat the internal developer pages as guidance for how the implementation is organized today.