# GoldHold Python SDK

**Your AI agent forgets everything when the session ends. GoldHold fixes that.**

Persistent memory that survives session boundaries, compaction, and crashes. 14 memory types, 4 storage classes, semantic search, cross-agent messaging -- all through a simple Python client.

```
pip install goldhold
```

### Why GoldHold?

- **Survives death** -- agent context is preserved across sessions, restarts, and compaction events
- **Semantic search** -- find relevant memories by meaning, not keywords
- **Cross-agent messaging** -- agents on the same account can communicate via GUMP protocol
- **Zero LLM overhead** -- retrieval uses 9-factor scoring (temporal decay, evidence, associations), no extra model calls
- **Compound operations** -- search + store + send in a single API call (saves tokens and latency)
- **Works with any framework** -- OpenClaw, LangChain, CrewAI, AutoGen, raw Python scripts

## Quickstart

```python
from goldhold import GoldHold

gh = GoldHold(api_key="your-key")

# Store a memory
gh.store("User prefers dark mode", "Stated explicitly on March 9", type="FACT")

# Search memories
results = gh.search("user preferences")

# Compound turn -- search + store in one call
resp = gh.turn(
    search={"query": "project status"},
    store={"subject": "Deploy complete", "body": "v2 shipped", "type": "DECISION"},
)

# Session resume
auto = gh.auto(context_budget=2000)

# Check status
status = gh.status()
print(f"{status.namespace}: {status.total_vectors} vectors")
```

## Setup

```python
GoldHold.setup()  # interactive -- prints signup URL, saves key to ~/.goldhold/config.json
```

Or set `GOLDHOLD_API_KEY` in your environment.

## API

| Method | What it does |
|--------|-------------|
| `store(subject, body, type, confidence)` | Store a memory packet |
| `search(query, limit, filters)` | Semantic search |
| `turn(search, store, send, compact)` | Compound: search + store + send in one call |
| `auto(context_budget)` | Session resume with capability card |
| `batch(operations)` | Multiple operations in one request |
| `close(session_summary)` | Graceful session close |
| `status()` | Namespace info, vector count, agent trust |
| `setup()` | Interactive CLI setup |

## Tiers

| | Lite (free) | Vault Pro ($9/mo) |
|---|---|---|
| Vectors | 1,000 | Unlimited |
| Agents | 1 | Unlimited |
| Namespaces | 1 | Unlimited |
| Tasks | 10 | Unlimited |
| Messages | 50/month | Unlimited |

Sign up at [goldhold.ai/account](https://goldhold.ai/account).

## Error Handling

```python
from goldhold.exceptions import AuthError, RateLimitError, VectorLimitError

try:
    gh.store("test", "test")
except VectorLimitError:
    print("Upgrade to Vault Pro for unlimited vectors")
except AuthError:
    print("Bad API key")
except RateLimitError:
    print("Slow down")
```

---

Patent Pending. All Auto Tunes LLC. U.S. Patent Application #63/988,484.
