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

import os
from claiv import ClaivClient
from openai import OpenAI

claiv  = ClaivClient(api_key=os.environ["CLAIV_API_KEY"])
openai = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

def chat(user_id: str, conversation_id: str, user_message: str) -> str:
    # 1. Recall — fetch everything Claiv knows about this user
    memory = claiv.recall({
        "user_id": user_id,
        "conversation_id": conversation_id,
        "query": user_message,
    })

    # 2. Call your LLM with memory injected
    response = 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 time
    claiv.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})

    return reply

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 immediately
result = 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 automatically
memory = claiv.recall({
    "user_id": "user-123",
    "conversation_id": "session-abc",
    "query": "How do I install the product?",
    "document_id": result["document_id"],
})

# Delete when done
claiv.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 it
claiv.add_document_to_collection(collection_id, {
    "user_id": "user-123",
    "document_id": "doc-abc",
})

# Recall across the whole collection
memory = claiv.recall({
    "user_id": "user-123",
    "conversation_id": "session-abc",
    "query": "What were our Q4 revenue figures?",
    "collection_id": collection_id,
})

---

Async client

from claiv import AsyncClaivClient
import asyncio

async def main():
    claiv = AsyncClaivClient(api_key=os.environ["CLAIV_API_KEY"])
    memory = await claiv.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

from claiv.errors import ClaivApiError, ClaivTimeoutError, ClaivNetworkError

try:
    claiv.ingest({...})
except ClaivApiError as e:
    print(e.status_code)  # HTTP status
    print(e.code)         # 'quota_exceeded' | 'invalid_request' | ...
    print(e.request_id)   # share with support
except ClaivTimeoutError:
    pass  # request timed out
except ClaivNetworkError:
    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