The Python SDK. Typed, async-first.

Install

pip install octamem

Requires Python 3.9 or newer. Type hints are included via Pydantic models, and there are no native dependencies. The package is published on PyPI as pypi.org/project/octamem.

Construct a client

import os
from octamem import OctaMem

client = OctaMem(api_key=os.environ["OCTAMEM_API_KEY"])

# Async client, same surface, every call awaitable.
from octamem import AsyncOctaMem
async_client = AsyncOctaMem(api_key=os.environ["OCTAMEM_API_KEY"])

Use OctaMem for synchronous code and AsyncOctaMem inside an async runtime such as FastAPI. Both retry automatically on connection, timeout, rate-limit, and 5xx errors.

details()

Validate the API key and read current plan, memory usage, storage, and wallet balance. Call it before get() or add() to confirm the key is live and the wallet can cover the request.

info = client.details()

print(info.valid)           # key is live
print(info.memory)          # memory used
print(info.plan)            # current plan
print(info.wallet_balance)  # remaining balance

get()

Query memory in natural language. Consumes tokens and returns the retrieval result.

results = client.get(
    query="What did we decide about the launch date?",
    previous_context="Q1 product planning meeting",
)

print(results)

Arguments

• query: required. The natural-language question.
• previous_context: optional. Prior context that scopes the search.

add()

Store content as memory. Consumes tokens and counts against your storage allowance.

client.add(
    content="Launch date set for April 15. Beta opens March 20.",
    previous_context="Q1 product planning meeting",
)

Arguments

• content: required. The content to remember.
• previous_context: optional. Context the content belongs to.

Framework integrations

The package ships optional extras for LangChain, LlamaIndex, and CrewAI. See the CrewAI tutorial and the LangGraph tutorial.

Async usage

AsyncOctaMem mirrors the sync surface; every method is await-able.

import asyncio
from octamem import AsyncOctaMem


async def main():
    client = AsyncOctaMem(api_key="oct_live_...")
    results = await client.get(query="launch date")
    print(results)


asyncio.run(main())

Errors

The SDK raises typed exceptions that map onto the HTTP status codes returned by the REST API: authentication (401), insufficient balance (402), storage full (400), and rate limit (429).