goodmem-honeyhive

GoodMem memory as HoneyHive-traced operations. Every call appears as a span alongside the rest of your agent's work, so memory reads and writes are visible in the same trace as the model calls they feed.

Version 0.4.0. Verified against GoodMem server v1.0.320.

Upgrading from 0.1.0. This is an observability package, which makes 0.1.0's worst defect specific to it: retrieval statuses were dropped, so a retrieval that failed was recorded as a successful span. A space whose embedder was unavailable produced success: true, totalResults: 0 — in HoneyHive that reads as "the index is empty", not "the search broke". See Changes in 0.2.0.

Security. 0.1.0's test file carried a live GoodMem API key as a default value, on the public default branch and in the v0.1.0 tag. It is removed here and the environment variable is now required with no fallback — but removing it from the tree does not un-leak it. That key needs rotating.

Security (0.2.1). Every id argument must now be a UUID. In 0.2.0 the GoodMem SDK put ids into URL paths raw, so delete_memory("../spaces/<id>") sent DELETE /v1/spaces/<id>, deleted a whole space and returned success: True. And GoodMemConfig printed its API key: HoneyHive's @trace records a traced function's arguments with str(), so a function that took the config exported the key to HoneyHive. It is now masked everywhere. See Changes in 0.2.1.

Install

pip install goodmem-honeyhive

Use

from honeyhive import HoneyHiveTracer
from goodmem_honeyhive import GoodMemClient, GoodMemConfig

HoneyHiveTracer.init(api_key="<your-honeyhive-key>", project="my-project")

client = GoodMemClient(
    GoodMemConfig(base_url="https://your-goodmem-server", api_key="<your-goodmem-key>")
)

Both GoodMem settings fall back to GOODMEM_BASE_URL and GOODMEM_API_KEY.

GoodMemConfig stores the key as a SecretStr (a str or a pydantic.SecretStr is accepted too). repr(), str(), f-strings, logging, dataclasses.asdict() and json.dumps(..., default=str) all show **********, and so does the span of a @trace-decorated function of yours that takes the config as an argument. GoodMemClient does not keep the key itself; it goes straight to the SDK, which sends it as X-API-Key. When you need the raw value, ask for it:

config = GoodMemConfig(base_url="https://your-goodmem-server", api_key="<your-goodmem-key>")
print(config)                  # GoodMemConfig(..., api_key=SecretStr('**********'), ...)
raw = config.get_api_key()     # or config.api_key.get_secret_value()

config.api_key is no longer a str, so passing it straight to an HTTP library raises TypeError rather than sending the mask; use get_api_key(). For the same reason config.api_key == "<your-goodmem-key>" is always False; compare config.get_api_key() instead.

Without a tracer the methods still run; HoneyHive logs that no tracer is active and no span is emitted. With a tracer, a call that raises GoodMemError — a refused id included — is an error span carrying the exception.

What a retrieval span records

client.retrieve_memories("what did I store?", space_ids=["<space-uuid>"], max_results=5)

{
  "success": True,
  "query": "...",
  "results": [
    {
      "chunk_id": "...", "chunk_text": "...", "memory_id": "...", "space_id": "...",
      "score": 0.64,          # higher is better
      "raw_score": -0.64,     # exactly what the server sent
      "score_kind": "vector", # or "reranker" -- not the same scale
      "content_type": "text/plain",
      "metadata": {...},      # the memory's metadata, joined by UUID
    }
  ],
  "total_results": 1,
  "partial": False,           # True when the server reported a problem
  "statuses": [],             # what it reported
  "result_set_id": "...",
}

partial means exactly one thing: the server reported a real problem during this retrieval. It is independent of whether hits came back. A degraded search still returns whatever arrived, with partial set and a warning key; when nothing usable arrives the result is empty and still flagged. The span therefore shows a failed retrieval as failed.

For structured use, client.retrieve(...) returns the same data as a RetrievalOutcome object instead of a traced dictionary.

Scores

GoodMem produces two kinds of score and they are not comparable. Vector scores are negative distances, so score is the flipped value with raw_score kept beside it. Reranker scores are already higher-is-better, on a provider-dependent scale — measured live on the same five documents, Voyage rerank-2.5 returned 0.27..0.93 and Jina jina-reranker-v3 returned -0.14..0.43. There is therefore no default threshold anywhere in this package.

score_kind records what the server did, not what was asked for. When a requested reranker fails, the server reports RERANKING_FAILED (and NOT_FOUND for a reranker id it cannot find) and still returns the vector-stage hits. Those hits are labelled "vector" and flipped like any other vector score, and the retrieval is partial with both statuses.

LLM answers (opt-in)

GoodMem can run one of its configured LLMs over the chunks a retrieval found and send back a grounded answer. Ask for it by passing the LLM's id, the same way you pass reranker_id:

out = client.retrieve_memories(
    "What is HoneyHive?", ["<space-uuid>"], llm_id="<llm-uuid>"
)
out["abstract_reply"]   # "HoneyHive is an LLM observability platform built on ..."
out["results"]          # the chunks the answer was drawn from, as always

outcome = client.retrieve("What is HoneyHive?", ["<space-uuid>"], llm_id="<llm-uuid>")
outcome.abstract_reply  # the same text on the RetrievalOutcome

• Opt-in and set by you. llm_id defaults to None, and then the request is exactly what it was before: no post-processor, no LLM call. It is an argument of your own code's call, not something a model chooses.
• Checked like every other id. It must be a UUID; anything else, including "", raises GoodMemError and nothing is sent. It travels in the retrieval's post-processor config beside reranker_id, and both can be set.
• Where the answer appears. abstract_reply in the traced payload, so the HoneyHive retrieval span records it as honeyhive_outputs.result.abstract_reply, and RetrievalOutcome.abstract_reply from retrieve(...). The key is absent when no LLM was asked for or none answered.
• When the LLM fails, the retrieval still succeeds, flagged. The server reports SUMMARIZATION_FAILED (with NOT_FOUND first for an LLM id it does not know). Nothing is raised: the hits are kept, partial is True, both statuses are in statuses and warning, there is no abstract_reply, and the span records exactly that. Measured live: an unknown id gave partial: True, [NOT_FOUND, SUMMARIZATION_FAILED], 1 hit; an LLM whose provider answered 429 gave [SUMMARIZATION_FAILED], 1 hit.
• Scores are untouched. An LLM does not rerank: hits keep the score_kind of the stage that scored them, and a failed LLM never changes a reranker's scores into vector ones or back.

Metadata filters

Filters are expressions evaluated server-side, not SQL:

from goodmem_honeyhive import filters

client.retrieve_memories("q", ["<space-uuid>"], metadata_filter={"tenant": "acme"})

expression = filters.all_of(
    filters.equals("tenant", "acme"),
    filters.compare("year", ">=", 2026),
)

The helper applies the escaping the server accepts (' → \', \ → \\; SQL-style '' doubling is rejected with HTTP 400), refuses control characters, restricts field names, and casts each value to the type GoodMem stored — a boolean compared as TEXT is accepted with HTTP 200 and matches nothing.

Operations

update_space takes name and labels. It no longer offers public_read: the server removed that field and answers 400 Unrecognized field "publicRead".

Every id argument (space_id, memory_id, embedder_id, space_ids, reranker_id, llm_id) must be a UUID, because the SDK places ids into URL paths unescaped and a value such as ../spaces/<id> would otherwise address a different resource. Anything else raises GoodMemError before a request is made; upper-case UUIDs and uuid.UUID objects are accepted and sent in lower case. What is sent is a new plain string built from the id's own characters (or a uuid.UUID's stored value), never the object passed in, so a str or uuid.UUID subclass cannot change it through lower() or __str__. reranker_id and llm_id are optional: leave them None for no reranker and no LLM. An empty string is refused like any other non-UUID, so os.getenv("RERANKER_ID", "") needs or None.

Changes in 0.4.0

No other changes. Span names (goodmem.create_space, goodmem.retrieve_memories, ...) never contained the module name and are unchanged.

Changes in 0.3.0

Changes in 0.2.1

Measured against a local server that records every request, driving the real SDK and httpx:

Changes in 0.2.0

Reproduced against the published 0.1.0 wheel, live against GoodMem v1.0.320.

Already correct in 0.1.0 and unchanged: request timeouts (30 s by default), and the error path — the server's own message reaches the caller.

Tests

pip install -e . pytest httpx "ruff==0.7.4" mypy

pytest tests/test_goodmem_honeyhive.py

GOODMEM_API_KEY=... GOODMEM_BASE_URL=... \
  GOODMEM_TEST_EMBEDDER_ID=... GOODMEM_TEST_LLM_ID=... \
  pytest tests/test_goodmem_honeyhive_live.py

ruff check goodmem_honeyhive tests && ruff format --check goodmem_honeyhive tests
mypy goodmem_honeyhive

One offline test scans the tree for a credential-shaped string, so the defect that shipped in 0.1.0 cannot come back unnoticed. The live suite creates one space per run and asserts, against a fresh listing, that it is gone.

License

MIT — see LICENSE.