# 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/client_gen.md](../notes/client_gen.md) for the SDK generation details and [../notes/doc_gen.md](../notes/doc_gen.md) for the doc generation details.

## Installation

```bash
pip install goodmem
```

## Usage

### The programmatic way

```python
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 

```bash
# 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/v2/
├── python/              # Python SDK (this directory, published to PyPI as "goodmem")
├── _client_gen/         # Code generation (spec → SDK + MCP)
├── _doc_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 (client_gen.md, doc_gen.md)
├── client_gen.sh        # Full SDK generation pipeline
└── doc_gen.sh           # Full doc generation pipeline
```

## Development commands

```bash
# Generation (run from clients/v2/, not python/)
cd ..
./client_gen.sh                # compile server → IR → Python SDK → MCP → test
./client_gen.sh -y             # same, but skip server-reset confirmation (unattended/CI)
./doc_gen.sh                   # ref pages + skills + snippets
./doc_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 `client_gen.sh`, integration test is only activated when environment variables `GOODMEM_BASE_URL` and `GOODMEM_API_KEY` are set.

> **Warning:** Before the integration tests, `client_gen.sh` and CI all run `goodmem-reset.sh` to **delete ALL resources** on the target server. Never point `GOODMEM_BASE_URL` at a production server. We have a dedicated test server on Fly.io for this purpose. See [ci/README.md](../ci/README.md) for more details.

See [notes/client_gen.md](../notes/client_gen.md) for the full regeneration workflow and [notes/doc_gen.md](../notes/doc_gen.md) for the doc and auditing pipelines.



## Documentation

* [Code generation guide](../notes/client_gen.md) — architecture, regeneration, testing, tier details
* [Doc generation guide](../notes/doc_gen.md) — how ref docs are generated, docstring authoring
* [CI pipeline](../ci/README.md) — GitHub Actions workflow, secrets, Fly.io test server setup
* [API reference](https://docs.goodmem.ai/docs/reference/sdk/python) — 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. 
