goodmem-camel

GoodMem memory for CAMEL agents. Documents are chunked, embedded and searched server-side; this package wraps the official goodmem Python SDK and exposes it to CAMEL both as a toolkit and as a BaseRetriever.

Version 0.4.0. Verified against GoodMem server v1.0.320.

Upgrading from 0.1.0. 0.1.0 talked to GoodMem over hand-written HTTP and had defects that were invisible from its return values — a failed search reported success: true with no indication anything had gone wrong, and publicRead was sent on space updates although the server had removed the field and answers 400. See Changes in 0.2.0.

Install

pip install goodmem-camel

Requires Python 3.10+, camel-ai>=0.2.79, goodmem>=0.1.35, pydantic>=2.11 and mcp<2. CI installs exactly those floors and runs the offline suite against them.

export GOODMEM_API_KEY="gm_your_key_here"
export GOODMEM_BASE_URL="https://your-goodmem-server"

Use

from camel.agents import ChatAgent
from goodmem_camel import GoodMemToolkit

toolkit = GoodMemToolkit(space_ids=["<space-uuid>"])
agent = ChatAgent("You remember things.", tools=toolkit.get_tools())

By default the model sees exactly two tools:

Every operational setting — which spaces are readable, which reranker, which LLM answers from the results, whether a threshold applies, whether files can be uploaded — is fixed by you at construction time. The model cannot widen its own access, pick another space, or turn on indexing waits.

Opt in to more:

Ids must be UUIDs

Every GoodMem id this package handles — the space_ids, reranker_id and llm_id you configure, and the memory_id, space_id and embedder_id a tool or method takes — must be a UUID. Anything else raises GoodMemIdError, naming the argument, before any request is made, because the GoodMem SDK puts ids into request paths unescaped: delete_memory("../spaces/<id>") would otherwise send DELETE /v1/spaces/<id> and delete a whole space. Upper-case UUIDs are accepted and sent lower-case. The tool schemas declare these arguments with the same UUID pattern, so the model is told up front.

An empty string is not a UUID either: for no reranker, pass reranker_id=None or leave it out. reranker_id="" meant "no reranker" in 0.2.0 and is now refused at construction, so reranker_id=os.getenv("GOODMEM_RERANKER_ID", "") fails at startup — write os.getenv("GOODMEM_RERANKER_ID") or None. llm_id="" is refused the same way; for no LLM, pass llm_id=None or leave it out.

Retrieval results

{
  "success": True,
  "query": "...",
  "results": [
    {
      "chunkId": "...", "text": "...", "memoryId": "...", "spaceId": "...",
      "score": 0.64,          # higher is better
      "rawScore": -0.64,      # exactly what the server sent
      "scoreKind": "vector",  # or "reranker" -- not the same scale
      "contentType": "text/plain",
      "metadata": {...},      # the memory's metadata, joined by UUID
    }
  ],
  "totalResults": 1,
  "partial": False,           # True when the server reported a problem
  "statuses": [],             # what it reported
  "resultSetId": "...",
  "abstractReply": "...",     # only with llm_id -- see "LLM answers"
}

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 hits arrived, with partial set; when nothing usable arrives the result is empty, partial is set, and a warning key plus a WARNING log line carry the server's own reason. A failed search is never presented as an empty one.

Scores

GoodMem produces two kinds of score, and they are not comparable:

• vector scores are negative distances. score is the flipped value so higher is better, with rawScore 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, Jina jina-reranker-v3 returned -0.14..0.43.

So there is no default threshold, and min_score applies only to reranker scores. If a threshold removes everything, the toolkit warns and names the range it actually saw rather than returning a silent empty list.

scoreKind says what the server actually did, not what was configured. When a reranker is set but fails, the server reports RERANKING_FAILED (and NOT_FOUND for a missing reranker) and still returns the vector-stage hits. Those hits are scoreKind: "vector", flipped like any vector score, and min_score is not applied to them, so a reranker threshold cannot discard them; partial is set and statuses carries both codes.

LLM answers

GoodMem can run one of its configured LLMs over the chunks a search retrieved and return a grounded answer beside them. This is off by default and set by you, like reranker_id: pass the UUID of a GoodMem LLM as llm_id when you construct the toolkit. The model never sees or chooses it — goodmem_search still takes only query and top_k.

from goodmem_camel import GoodMemRetriever, GoodMemToolkit

toolkit = GoodMemToolkit(space_ids=["<space-uuid>"], llm_id="<llm-uuid>")

result = toolkit.goodmem_search("What is the canary?")
result["abstractReply"]   # "The canary is **ORYX-2290** ..."
result["results"]         # the hits, exactly as without an LLM

rows = GoodMemRetriever(toolkit).query("What is the canary?")
rows[0]["extra_info"]["goodmem_abstract_reply"]   # the same answer

Where the answer appears:

• goodmem_search (and so the tool result the model reads): the abstractReply key, a string.
• GoodMemRetriever.query(): goodmem_abstract_reply in every row's extra_info, since CAMEL's retriever returns a plain list of rows. It is one answer for the whole retrieval, repeated on each row so it survives a caller keeping only some of them.
• The key is present whenever llm_id is set, and absent otherwise.

The id is sent as llm_id in the retrieval's post-processor config, beside reranker_id when both are set. It is a UUID like every other id: anything else raises GoodMemIdError before a request is made.

An LLM does not rerank. Hits keep their scores, scoreKind and order exactly as without it; combine it with reranker_id if you want reranking as well.

When the LLM fails, the search does not. The server reports SUMMARIZATION_FAILED — plus NOT_FOUND when no LLM has that id — and still returns the hits. You get the hits, partial: True, both statuses in statuses, a warning, and abstractReply: None (in the retriever, goodmem_partial: True, goodmem_statuses and goodmem_abstract_reply: None). Nothing is raised and no hit is dropped. Measured live: an LLM id that does not exist gave [NOT_FOUND, SUMMARIZATION_FAILED] with the hit kept; a provider out of credits gave SUMMARIZATION_FAILED carrying the provider's 429. A reranker configured beside a failing LLM keeps its reranker scores.

Metadata filters

Filters are expressions evaluated server-side, not SQL. You set them when you construct the toolkit or the retriever; the model never supplies one — in 0.1.0 the filter was a raw string the model supplied, which let it widen its own scope and broke on any value containing an apostrophe.

metadata_filter takes either form:

• a dict — every pair must match (an AND of equalities);
• a string built with the filters helper — equals, not_equals, compare, one_of, combined with all_of / any_of — sent verbatim.

from goodmem_camel import GoodMemRetriever, GoodMemToolkit, filters

# dict: tenant == "acme" AND active == true
toolkit = GoodMemToolkit(
    space_ids=["<space-uuid>"],
    metadata_filter={"tenant": "acme", "active": True},
)

# expression: anything the dict form cannot say
expression = filters.all_of(
    filters.equals("tenant", "acme"),
    filters.compare("year", ">=", 2026),
    filters.one_of("kind", ["note", "doc"]),
)
toolkit = GoodMemToolkit(space_ids=["<space-uuid>"], metadata_filter=expression)
result = toolkit.goodmem_search("quarterly plan")

# the retriever takes the same argument; it is ANDed with the toolkit's
# filter, so a retriever can narrow the toolkit's scope but never widen it
retriever = GoodMemRetriever(
    toolkit,
    metadata_filter=filters.not_equals("status", "archived"),
)
rows = retriever.query("quarterly plan", top_k=5)

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, so neither filters nor the dict form ever stringifies a bool; a None, list or dict value is refused with GoodMemFilterError when the toolkit is constructed. A string is sent as written, so build it with filters rather than by hand.

Uploads

Uploads are off unless you set upload_dir. When set, every path is resolved — symlinks included — and refused if it lands outside that directory, so a model-supplied path cannot read arbitrary files from the host.

from goodmem_camel import GoodMemToolkit

toolkit = GoodMemToolkit(
    space_ids=["<space-uuid>"], upload_dir="/srv/agent-uploads"
)

Retriever

from goodmem_camel import GoodMemRetriever, GoodMemToolkit

retriever = GoodMemRetriever(GoodMemToolkit(space_ids=["<space-uuid>"]))
retriever.process("Text to remember.")
rows = retriever.query("what did I store?", top_k=5)

query() returns CAMEL's retriever shape — similarity score, content path, metadata, extra_info, text — with GoodMem specifics under extra_info (goodmem_chunk_id, goodmem_memory_id, goodmem_space_id, goodmem_score_kind, goodmem_raw_score, goodmem_partial, goodmem_statuses when degraded, and goodmem_abstract_reply when the toolkit has an llm_id).

Bringing your own client

from goodmem import Goodmem
from goodmem_camel import GoodMemToolkit

toolkit = GoodMemToolkit(client=Goodmem(base_url=..., api_key=...))

An injected client keeps its own server, credentials and TLS settings, and is never closed by the toolkit.

Changes in 0.4.0

Renamed to goodmem-camel (import goodmem_camel), the goodmem-<framework> naming used by goodmem-adk and goodmem-semantic-kernel. Breaking: update imports from camel_goodmem to goodmem_camel. No other code changes.

Changes in 0.3.0

New, opt-in: an LLM answer from the retrieved chunks. See LLM answers.

Changes in 0.2.1

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

Changes in 0.2.0

Every item below was reproduced against the published 0.1.0 wheel, live against GoodMem v1.0.320.

Tests

pip install -e ".[dev]"

# offline
pytest tests/test_goodmem_toolkit.py tests/test_goodmem_ids.py

# live (pin the embedder if the server's first one is unhealthy)
GOODMEM_API_KEY=... GOODMEM_BASE_URL=... \
  GOODMEM_TEST_EMBEDDER_ID=... GOODMEM_TEST_LLM_ID=... \
  pytest tests/test_goodmem_live.py

# what CI runs
ruff check goodmem_camel tests
ruff format --check goodmem_camel tests
mypy goodmem_camel

# ...and the declared floors, on Python 3.10
uv venv --python 3.10 floor
uv pip install --python floor/bin/python --resolution lowest-direct -e .
uv pip install --python floor/bin/python pytest pytest-timeout
floor/bin/python -m pytest tests/test_goodmem_toolkit.py tests/test_goodmem_ids.py

The live suite creates one space per run and asserts, against a fresh server inventory, that it is gone afterwards.

Deliberately not done

• No AgentMemory implementation. CAMEL's AgentMemory is chat history with a context-window policy; GoodMem is a document store with server-side embedding. Implementing it would fake one side of the contract.
• Turning off TLS verification is possible via verify_ssl for self-signed development servers. It defaults to on, no example here turns it off, and CI fails if shipped Python does.

License

Apache-2.0.