Metadata-Version: 2.4
Name: goldhold
Version: 0.2.0
Summary: Persistent memory for AI agents -- search, store, and recall across sessions.
Home-page: https://goldhold.ai
Author: All Auto Tunes LLC
License: Proprietary
Project-URL: Homepage, https://goldhold.ai
Project-URL: Documentation, https://goldhold.ai/docs
Project-URL: Dashboard, https://goldhold.ai/account
Keywords: ai,agent,memory,persistent,llm,semantic-search,langchain,crewai,openclaw
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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.
