Stanford DSPy

Wrap GoodMem's RAG pipeline as a DSPy retriever and expose memory-lifecycle tools to dspy.ReAct agents.

Stable· Python (3.10+)

Overview

GoodMem is a self-hosted RAG system that handles the full retrieval pipeline — ingestion, chunking, embedding, storage, hybrid search, reranking, and summarization — server-side. This integration wraps it for DSPy: plug GoodMemRM into any pipeline through the standard dspy.Retrieve interface, or hand GoodMem's memory lifecycle to a dspy.ReAct agent as callable tools built with make_goodmem_tools — search and store by default, with opt-in administrative, delete, and upload tools. GoodMemClient is also exposed directly when you want raw control over memory and space operations.

Installation

pip install goodmem-dspy

The pip package is goodmem-dspy; the import name is goodmem_dspy. A running GoodMem server is required. Install the optional goodmem-dspy[examples] extra to load a .env file via python-dotenv when running the example scripts.

Configuration

Variable	Description
`GOODMEM_BASE_URL`	Base URL of your GoodMem server (no `/v1` suffix), e.g. `https://your-goodmem-server.example.com`.
`GOODMEM_API_KEY`	API key used to authenticate requests.

The OPENAI_API_KEY environment variable is also needed when configuring an OpenAI model as the DSPy LM. GoodMemRM and GoodMemClient accept api_key, base_url, and verify_ssl arguments directly in code.

Quick start

import dspy
from goodmem_dspy import GoodMemRM

dspy.configure(lm=dspy.LM("openai/gpt-5-mini"))

rm = GoodMemRM(
    space_ids=["<your-space-uuid>"],
    api_key="gm_...",
    base_url="https://your-goodmem-server.example.com",
    k=3,
)

class RAG(dspy.Module):
    def __init__(self, retriever):
        super().__init__()
        self.retriever = retriever
        self.respond = dspy.ChainOfThought("context, question -> response")

    def forward(self, question):
        passages = self.retriever(question)
        context = "\n\n".join(p["long_text"] for p in passages)
        return self.respond(context=context, question=question)

rag = RAG(retriever=rm)
print(rag(question="Summarize what's in the knowledge base.").response)

Each passage is a dict-like object carrying long_text alongside chunk_id, memory_id, space_id, metadata, score, raw_score, and score_kind ("vector" or "reranker" — the two are not on a common scale). Scores are oriented so higher is better. When the server reports a problem, the passages it returned still come back flagged goodmem_partial; a degraded retrieval with no passages returns an empty result with a warning rather than looking like a clean miss.

Local development. The example above uses a TLS-verified production URL. If you are running GoodMem locally with a self-signed certificate, use https://localhost:8080 and disable TLS verification with the client's verify-SSL option (see the Configuration table above). Keep TLS verification enabled for any deployed server.

Retrieval post-processing

This integration exposes these optional retrieval parameters:

Parameter	Where	Description
`k`	`GoodMemRM` (default 3)	How many passages to return; override per call with `rm(query, k=...)`.
`max_results`	`GoodMemClient.retrieve` (default 5)	How many chunks to ask the server for.
`reranker_id`	both	UUID of a server-side reranker that reorders matched chunks by relevance; needs no LLM. If the server reports that reranking failed, the vector-stage hits are returned instead.
`metadata_filter`	both	Metadata every retrieved memory must match, applied server-side and escaped by `goodmem_dspy.filters`.
`min_score`	`GoodMemRM` only	Drop passages scoring below this value. Applies only to reranker scores, whose scales are provider-dependent and not 0–1; ignored without a reranker or when reranking failed. Off by default.

Learn more

The full README, examples, and API reference are available on the PyPI package page.