camel-goodmem

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.2.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 camel-goodmem

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

Use

from camel.agents import ChatAgent
from camel_goodmem 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, 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:

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": "...",
}

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 when reranker_id is set. If a threshold removes everything, the toolkit warns and names the range it actually saw rather than returning a silent empty list.

Metadata filters

Filters are expressions evaluated server-side, not SQL. Build them with the filters helper — 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:

from camel_goodmem import GoodMemToolkit, filters

toolkit = GoodMemToolkit(
    space_ids=["..."],
    metadata_filter={"tenant": "acme", "active": True},
)

expression = filters.all_of(
    filters.equals("tenant", "acme"),
    filters.compare("year", ">=", 2026),
    filters.one_of("kind", ["note", "doc"]),
)

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 filters never stringifies a bool.

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.

toolkit = GoodMemToolkit(space_ids=["..."], upload_dir="/srv/agent-uploads")

Retriever

from camel_goodmem import GoodMemRetriever, GoodMemToolkit

retriever = GoodMemRetriever(GoodMemToolkit(space_ids=["..."]))
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, and goodmem_statuses when degraded).

Bringing your own client

from goodmem import Goodmem
from camel_goodmem 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.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

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

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

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.