honeyhive-goodmem

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.2.1. 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 honeyhive-goodmem

Use

from honeyhive import HoneyHiveTracer
from honeyhive_goodmem 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.

Metadata filters

Filters are expressions evaluated server-side, not SQL:

from honeyhive_goodmem 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) 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 is optional: leave it None for no reranker. An empty string is refused like any other non-UUID, so os.getenv("RERANKER_ID", "") needs or None.

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_honeyhive_goodmem.py

GOODMEM_API_KEY=... GOODMEM_BASE_URL=... \
  GOODMEM_TEST_EMBEDDER_ID=... \
  pytest tests/test_honeyhive_goodmem_live.py

ruff check honeyhive_goodmem tests && ruff format --check honeyhive_goodmem tests
mypy honeyhive_goodmem

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.