LlamaIndex

GoodMem handles document storage, chunking, embeddings and retrieval. The integration supplies a native LlamaIndex retriever, Document ingestion and optional administrative tools. Reranking runs on the GoodMem server and does not require an LLM.

Install and configure

pip install --upgrade 'llamaindex-goodmem>=0.2.0'
export GOODMEM_BASE_URL="http://localhost:8080"
export GOODMEM_API_KEY="your-api-key"
export GOODMEM_SPACE_ID="your-space-uuid"

Use a running GoodMem server and an existing space configured with an embedder. The examples read GOODMEM_SPACE_ID; the integration itself requires explicit space IDs.

Store and retrieve Documents

import os

from goodmem import Goodmem
from llama_index.core.schema import Document
from llama_index.tools.goodmem import (
    GoodMemDocumentIngestor,
    GoodMemRetriever,
    wait_for_memories,
)

with Goodmem(base_url=os.environ["GOODMEM_BASE_URL"],
             api_key=os.environ["GOODMEM_API_KEY"]) as client:
    space_id = os.environ["GOODMEM_SPACE_ID"]
    ids = GoodMemDocumentIngestor(client=client, space_id=space_id).add_documents([
        Document(
            text="The returns period is 30 days.",
            metadata={"source": "https://example.org/returns", "team": "support"},
        )
    ])
    wait_for_memories(client, ids, timeout=120)

    retriever = GoodMemRetriever(client=client, space_ids=[space_id])
    for result in retriever.retrieve("How long do I have to return an item?"):
        print(result.score, result.text, result.metadata.get("source"))

Ingestion sends whole Documents so GoodMem owns chunking and embeddings. It returns accepted IDs immediately; waiting is a separate operation on those IDs. An empty search returns immediately. Document UUIDs become memory IDs; other Document IDs map deterministically within the space. Duplicate IDs raise a conflict. Sources, custom metadata and LLM/embedding metadata exclusions survive storage.

Filter, rerank and connect an agent

Use LlamaIndex's standard filters and tool wrapper:

from llama_index.core.tools import RetrieverTool
from llama_index.core.vector_stores.types import MetadataFilter, MetadataFilters

search = RetrieverTool.from_defaults(
    GoodMemRetriever(
        space_ids=[os.environ["GOODMEM_SPACE_ID"]],
        filters=MetadataFilters(filters=[MetadataFilter(key="team", value="support")]),
        # reranker_id=os.environ["GOODMEM_RERANKER_ID"],
    ),
    name="returns_policy",
    description="Search the company's returns and refund policies.",
)
# Pass search to a llama_index.core.agent.workflow ReActAgent or FunctionAgent.

The model supplies the query; your application chooses the spaces, filters and reranker. Use top_k for the returned chunk count and fetch_k for candidates. Reranking defaults to four times top_k candidates. Supported filters include scalar comparisons, membership and nested AND/OR/single-child NOT. Missing and null fields follow LlamaIndex's matching semantics.

Results are GoodMemNodeWithScore objects, compatible with NodeWithScore, query engines, fusion and callbacks. Higher scores mean better matches. Original scores, score kind and status diagnostics are available as raw_score, score_kind and statuses on the result wrapper, outside node identity. Scores are not calibrated across models or normalized to 0–1.

Async and connections

aretrieve and aadd_documents use AsyncGoodmem natively:

from goodmem import AsyncGoodmem

async def search_async(query):
    async with AsyncGoodmem(base_url=os.environ["GOODMEM_BASE_URL"],
                            api_key=os.environ["GOODMEM_API_KEY"]) as client:
        return await GoodMemRetriever(
            async_client=client,
            space_ids=[os.environ["GOODMEM_SPACE_ID"]],
        ).aretrieve(query)

Without injected clients, components accept base_url, api_key, timeout and verify_ssl, or read the two connection environment variables. Inject client for sync calls and async_client for async calls. When either is injected, the other mode requires its own injected client; environment settings cannot silently select a different connection. Caller-owned clients remain open.

For local TLS, use a trusted CA bundle: verify_ssl="/path/to/local-ca.pem" on a component, or verify="/path/to/local-ca.pem" when constructing the SDK client. A local development server can use verify_ssl=False; deployed servers should verify TLS.

Administrative tools and recovery

GoodMemToolSpec provides space and memory management tools. Its retrieval result includes compact chunks, statuses, a partial flag and an optional abstract_reply. Known failures raise in the native retriever; unknown server status codes remain visible and do not abort it. File upload is opt-in and restricted to an application-configured directory.

The create-memory tool normally waits for its own memory. If indexing confirmation fails after creation, it returns the accepted ID and recovery guidance. Check that memory's status instead of uploading it again. Explicit wait helpers retain pending IDs on their exceptions.

Explore the four Agentic RAG notebooks or read the full usage guide.