Metadata-Version: 2.4
Name: agentram-sdk
Version: 0.1.0
Summary: Persistent memory for AI agents in two API calls. The official Python SDK for AgentRAM.
Project-URL: Homepage, https://agentram.dev
Project-URL: Documentation, https://agentram.dev/docs.html
Project-URL: Source, https://github.com/seanmarkwei/agentram-python
Author-email: Sean Markwei <hello@agentram.dev>
License: MIT
License-File: LICENSE
Keywords: agentram,agents,ai,llm,memory,persistent-memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# AgentRAM Python SDK

Persistent memory for AI agents, in two API calls. This is the official Python
client for [AgentRAM](https://agentram.dev) - a simple, credit-based HTTP API
that gives your agents long-term memory. No vector database, no embeddings, no
infrastructure to run.

Zero third-party dependencies (standard library only).

## Install

```bash
pip install agentram-sdk
```

> Installs as **`agentram-sdk`** on PyPI, but you import it as **`agentram`** in code (the install name and import name differ, which is common for Python packages).

## Get a key

Sign up at [agentram.dev](https://agentram.dev) for an API key. New accounts
start with **1,000 free credits**, no card required.

## Quickstart

```python
from agentram import AgentRAM

ram = AgentRAM(api_key="agentram_...", agent_id="agent-01")

# Store something (1 credit)
ram.store("user_language", "French")

# Read it back later, even in a brand-new session (1 credit)
lang = ram.recall("user_language")   # -> "French"  (or None if missing/expired)
```

That's the whole idea: one call to remember, one to recall.

## Everything you can do

```python
# Personal memory (scoped to an agent_id)
ram.store("tone", "formal", ttl_days=30)   # auto-expire after 30 days
ram.recall("tone")                          # -> "formal" | None
ram.delete("tone")                          # -> True | False
ram.list(limit=50)                          # -> [{"key","value","created_at","expires_at"}, ...]
ram.search("lang")                          # -> matching records (text search, no embeddings)

# Shared memory (several agents reading/writing one pool)
ns = ram.create_namespace("team-alpha")     # -> {"namespace_key": "ns_...", "label": "team-alpha"}
ram.store_shared(ns["namespace_key"], "goal", "ship v1")
ram.recall_shared(ns["namespace_key"], "goal")   # -> "ship v1" | None
ram.list_shared(ns["namespace_key"])

# Account
ram.credits()               # -> current balance (free)
ram.credits_remaining       # last known balance, updated after every call (no extra request)
```

You can override the agent per call: `ram.store("k", "v", agent_id="agent-02")`.

## Errors

Everything inherits from `AgentRAMError`, so one `except` catches all of it:

```python
from agentram import AgentRAM, InsufficientCreditsError, RateLimitError, AgentRAMError

try:
    ram.store("k", "v")
except InsufficientCreditsError:
    ...  # balance hit zero - top up at agentram.dev/#pricing
except RateLimitError:
    ...  # 60 requests/minute per key - back off and retry
except AgentRAMError as e:
    print(e.status_code, e.message)
```

`recall()` and `recall_shared()` return `None` for a missing or expired memory
rather than raising, and `delete()` returns `False` - so the common "not there"
case stays out of your `try/except`.

## Notes

- **Rate limit:** 60 requests/minute per API key. The client automatically
  retries `429` and `5xx` responses a couple of times with backoff.
- **Credits:** writes and reads cost 1 credit; `create_namespace()` and
  `credits()` are free. Full pricing at [agentram.dev](https://agentram.dev/#pricing).
- **TTL:** pass `ttl_days` to expire a memory automatically.

## License

MIT
