agentram-sdk 0.1.0

Persistent memory for AI agents in two API calls. The official Python SDK for AgentRAM.

AgentRAM Python SDK

Persistent memory for AI agents, in two API calls. This is the official Python client for AgentRAM - 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

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 for an API key. New accounts start with 1,000 free credits, no card required.

Quickstart

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

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

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.
• TTL: pass ttl_days to expire a memory automatically.

License

MIT