claiv-memory (Python)

Give your AI a persistent memory.

Claiv Memory is a drop-in API that gives any LLM application persistent, cross-session memory and document RAG. Works with OpenAI, Claude, LangChain, or any framework — two calls to integrate, zero infrastructure to manage.

Get an API key → claiv.io

---

What it does

Without Claiv, every conversation starts from zero. With Claiv:

• Your AI remembers users across sessions — their preferences, history, context
• You can upload documents and your AI answers questions about them with full citation
• Everything is retrieved automatically and injected into your LLM prompt — no manual retrieval logic

---

Installation

pip install claiv-memory

---

Quickstart — 2 minutes

importosfromclaivimportClaivClientfromopenaiimportOpenAIclaiv=ClaivClient(api_key=os.environ["CLAIV_API_KEY"])
openai=OpenAI(api_key=os.environ["OPENAI_API_KEY"])
defchat(user_id: str, conversation_id: str, user_message: str) ->str:
# 1. Recall — fetch everything Claiv knows about this usermemory=claiv.recall({
"user_id": user_id,
"conversation_id": conversation_id,
"query": user_message,
})
# 2. Call your LLM with memory injectedresponse=openai.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": memory["llm_context"]["text"] or"You are a helpful assistant."},
{"role": "user", "content": user_message},
],
)
reply=response.choices[0].message.content# 3. Ingest — store this turn so it's remembered next timeclaiv.ingest({"user_id": user_id, "conversation_id": conversation_id,
"type": "message", "role": "user", "content": user_message})
claiv.ingest({"user_id": user_id, "conversation_id": conversation_id,
"type": "message", "role": "assistant", "content": reply})
returnreply

That's it. The AI now remembers this user across every future conversation.

---

Document RAG

Upload documents and your AI can answer questions about them — with persistent memory layered on top.

# Upload a document — parsed into sections and indexed immediatelyresult=claiv.upload_document({
"user_id": "user-123",
"project_id": "my-project",
"document_name": "Product Manual v2",
"content": open("manual.md").read(),
})
print(f"Indexed {result['spans_created']} spans across {len(result['sections'])} sections")
# Ask questions — Claiv routes to the right retrieval strategy automaticallymemory=claiv.recall({
"user_id": "user-123",
"conversation_id": "session-abc",
"query": "How do I install the product?",
"document_id": result["document_id"],
})
# Delete when doneclaiv.delete_document(result["document_id"])

Retrieval strategies (automatic)

Query type	Strategy	What happens
General question	LOCAL	Top spans by cosine similarity
"show me the installation section"	SECTION	Full section fetched in reading order
"summarise this document"	DOCUMENT	Full document context with distillations
collection_id provided	COLLECTION	Multi-document tiered context

---

Collections (folders)

Group documents for combined recall.

# Create a collection (acts as a folder)result=claiv.create_collection({
"user_id": "user-123",
"project_id": "my-project",
"name": "Q4 Reports",
})
collection_id=result["collection"]["collection_id"]
# Add documents to itclaiv.add_document_to_collection(collection_id, {
"user_id": "user-123",
"document_id": "doc-abc",
})
# Recall across the whole collectionmemory=claiv.recall({
"user_id": "user-123",
"conversation_id": "session-abc",
"query": "What were our Q4 revenue figures?",
"collection_id": collection_id,
})

---

Async client

fromclaivimportAsyncClaivClientimportasyncioasyncdefmain():
claiv=AsyncClaivClient(api_key=os.environ["CLAIV_API_KEY"])
memory=awaitclaiv.recall({
"user_id": "user-123",
"conversation_id": "session-abc",
"query": "What does this user prefer?",
})
print(memory["llm_context"]["text"])
asyncio.run(main())

---

API Reference

ClaivClient(api_key, base_url?, timeout?, max_retries?)

Param	Type	Default	Description
api_key	str	required	Your Claiv API key
base_url	str	https://api.claiv.io	API base URL
timeout	float	30.0	Request timeout (seconds)
max_retries	int	2	Retries on 429/5xx

Memory

Method	Description
client.ingest(request)	Store a memory event
client.recall(request)	Retrieve memory for a query
client.forget(request)	Delete memory by scope

Documents

Method	Description
client.upload_document(request)	Upload and index a document
client.list_documents(*, user_id, ...)	List documents for a user/project
client.delete_document(document_id)	Delete a document and all its data

Collections

Method	Description
client.create_collection(request)	Create a collection
client.list_collections(*, user_id, ...)	List collections
client.get_collection(id, *, user_id)	Get collection with document list
client.delete_collection(id, *, user_id)	Delete a collection
client.add_document_to_collection(id, request)	Add document to collection
client.remove_document_from_collection(col_id, doc_id)	Remove document

---

Error handling

fromclaiv.errorsimportClaivApiError, ClaivTimeoutError, ClaivNetworkErrortry:
claiv.ingest({...})
exceptClaivApiErrorase:
print(e.status_code) # HTTP statusprint(e.code) # 'quota_exceeded' | 'invalid_request' | ...print(e.request_id) # share with supportexceptClaivTimeoutError:
pass# request timed outexceptClaivNetworkError:
pass# network failure

The SDK automatically retries 429 and 5xx responses with exponential backoff.

---

Templates

Get up and running in under 5 minutes:

Template	Stack
template-openai-python	OpenAI + Python
template-openai-nodejs	OpenAI + Node.js
template-nextjs	Next.js + Vercel AI SDK
template-claude-python	Anthropic Claude + Python
template-langchain	LangChain agents
template-document-rag-python	Document RAG + Python
template-document-rag-nextjs	Document RAG + Next.js

---

Links

• claiv.io — sign up and get an API key
• JavaScript SDK
• Issues