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

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

Development Status
- 4 - Beta
Intended Audience
- Developers
Programming Language
Typing
- Typed

Metadata

Development Status
- 4 - Beta
Intended Audience
- Developers
Programming Language
Typing
- Typed

Release files for goodmem 0.1.37

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for goodmem 0.1.37
File	Size	Uploaded
goodmem-0.1.37.tar.gz	272.3 kB	Sep 30, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for goodmem 0.1.37
File	Interpreter	ABI	Platform	Reset
goodmem-0.1.37-py3-none-any.whl 273.7 kB Sep 30, 2026	Python 3	none	any	Details

Total release size: 546.0 kB

Release files / goodmem-0.1.37.tar.gz

Download URL	goodmem-0.1.37.tar.gz
Size	272.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`a84745941746b220b2aed11489d5b16d3e7681f6d15872a5ab351705074cca58`
BLAKE2b-256 checksum How to use checksums	`a5381416ba99e61c12d3d580e4aa25c3c94519c3dd27112e11432c8500aae911`
Upload date	Sep 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`

Release files / goodmem-0.1.37-py3-none-any.whl

Download URL	goodmem-0.1.37-py3-none-any.whl
Size	273.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`9ddc55f1c44b4a48b5c55014d7aa15613e3be53f50d0db123af7c952076b24a9`
BLAKE2b-256 checksum How to use checksums	`f631a64727633d17f90659d01c6ec6748b21cb84c298f5cb87f298ff585575ca`
Upload date	Sep 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`