GoodMem Python SDK

An OpenAI-style API for Goodmem with auto-inference of model parameters, streaming retrieval, async support, and auto-pagination. The SDK stays in sync with the server's OpenAPI spec — except for hand-written convenience methods (model registry auto-inference, flat post-processor kwargs, etc.) that wrap the generated layer. Please see ../notes/clients_gen.md for the SDK generation details and ../notes/docs_gen.md for the doc generation details.

Installation

pip install goodmem

Usage

The programmatic way

from goodmem import Goodmem

client = Goodmem(
    base_url="http://localhost:8080",
    api_key="gm_..."
)

embedder = client.embedders.create(
    display_name="OpenAI Embedder",
    model_identifier="text-embedding-3-large",
    api_key="sk-your-openai-key",
)

print(f"Created: {embedder.embedder_id}")

The Skill way

# One-time setup — copy the skill into your Claude Code skills directory
cp -r $(python -c "import goodmem; print(goodmem.__path__[0])")/skills ~/.claude/skills/goodmem

Once installed, Claude Code automatically loads the GoodMem SDK reference when you ask it to create embedders, store memories, run retrieval, etc.

Project structure

clients/
├── python/              # Python SDK (this directory, published to PyPI as "goodmem")
├── _clients_gen/         # Code generation (spec → SDK + MCP)
├── _docs_gen/            # Doc generation (ref pages, skills, sdk2rest)
├── mcp/                 # MCP server (published to npm as @pairsystems/goodmem-mcp)
├── claude/              # Claude Code plugin (git subtree → public repo)
├── vibe/                # Cross-SDK vibe auditing (audit_docs.sh, audit_ref_doc.sh, ...)
├── registries/          # Shared model registries (copied into each SDK)
├── ci/                  # CI infrastructure
├── notes/               # Internal dev notes (clients_gen.md, docs_gen.md)
├── clients_gen.sh        # Full SDK generation pipeline
└── docs_gen.sh           # Full doc generation pipeline

Development commands

# Generation (run from clients/, not python/)
cd ..
./clients_gen.sh                # compile server → IR → Python SDK → MCP → test
./clients_gen.sh -y             # same, but skip server-reset confirmation (unattended/CI)
./docs_gen.sh                   # ref pages + skills + snippets
./docs_gen.sh --sdk2rest        # translate SDK test snippets → REST equivalents

# Publishing (run from python/)
cd python
./publish.sh                   # Publish to PyPI
./publish.sh --test            # Publish to TestPyPI

# Vibe auditing (Claude Code non-interactive)
../vibe/audit_docs.sh          # run all doc audits (ref docs + skill docs)
../vibe/audit_ref_doc.sh       # audit generated MDX ref docs against SDK source
../vibe/audit_skill_doc.sh     # audit generated skill reference (SDK, REST, patterns)

In clients_gen.sh, integration test is only activated when environment variables GOODMEM_BASE_URL and GOODMEM_API_KEY are set.

Warning: Before the integration tests, clients_gen.sh runs goodmem-reset.sh to delete ALL resources on the target server. Never point GOODMEM_BASE_URL at a production server — use a throwaway local instance. (CI no longer resets anything: it composes a fresh server per suite and tears it down. See ci/README.md.)

See notes/clients_gen.md for the full regeneration workflow and notes/docs_gen.md for the doc and auditing pipelines.

Documentation

• Code generation guide — architecture, regeneration, testing, tier details
• Doc generation guide — how ref docs are generated, docstring authoring
• CI pipeline — GitHub Actions workflow, secrets, Fly.io test server setup
• API reference — published SDK docs

TODO

1. Add gemini-embedding-001 to embedder registry once backend adds OPENAI_COMPATIBLE to ProviderType.
2. Add Anthropic, Google, Cohere, and Mistral LLMs to registry once backend adds matching LLMProviderType values.
3. Automate model registry updates to add new models as they are released.
4. Generate SDK to an intermediate representation, then map that to cURL, HTTPie, HTTPX, Go, JavaScript, etc.