@claiv/memory

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, Vercel AI SDK, 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

npm install @claiv/memory

---

Quickstart — 2 minutes

import{ClaivClient}from'@claiv/memory';importOpenAIfrom'openai';constclaiv=newClaivClient({apiKey: process.env.CLAIV_API_KEY});constopenai=newOpenAI({apiKey: process.env.OPENAI_API_KEY});asyncfunctionchat(userId: string,conversationId: string,userMessage: string){// 1. Recall — fetch everything Claiv knows about this userconstmemory=awaitclaiv.recall({user_id: userId,conversation_id: conversationId,query: userMessage,});// 2. Call your LLM with memory injectedconstresponse=awaitopenai.chat.completions.create({model: 'gpt-4o',messages: [{role: 'system',content: memory.llm_context.text||'You are a helpful assistant.'},{role: 'user',content: userMessage},],});constreply=response.choices[0].message.content!;// 3. Ingest — store this turn so it's remembered next timeawaitclaiv.ingest({user_id: userId,conversation_id: conversationId,type: 'message',role: 'user',content: userMessage,});awaitclaiv.ingest({user_id: userId,conversation_id: conversationId,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.

import{readFileSync}from'fs';// Upload a document — parsed into sections and indexed immediatelyconst{ document_id, spans_created, sections }=awaitclaiv.uploadDocument({user_id: 'user-123',project_id: 'my-project',document_name: 'Product Manual v2',content: readFileSync('manual.md','utf8'),});console.log(`Indexed ${spans_created} spans across ${sections.length} sections`);// Now ask questions — Claiv routes to the right retrieval strategy automaticallyconstmemory=awaitclaiv.recall({user_id: 'user-123',conversation_id: 'session-abc',query: 'How do I install the product?',
document_id,// restrict recall to this document});// Delete when doneawaitclaiv.deleteDocument(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)const{ collection }=awaitclaiv.createCollection({user_id: 'user-123',project_id: 'my-project',name: 'Q4 Reports',});// Add documents to itawaitclaiv.addDocumentToCollection(collection.collection_id,{user_id: 'user-123',document_id: 'doc-abc',});// Recall across the whole collectionconstmemory=awaitclaiv.recall({user_id: 'user-123',conversation_id: 'session-abc',query: 'What were our Q4 revenue figures?',collection_id: collection.collection_id,});

---

API Reference

new ClaivClient(options)

Option	Type	Default	Description
apiKey	string	required	Your Claiv API key
baseUrl	string	https://api.claiv.io	API base URL
timeout	number	30000	Request timeout (ms)
maxRetries	number	2	Retries on 429/5xx
fetch	function	globalThis.fetch	Custom fetch

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.uploadDocument(request)	Upload and index a document
client.listDocuments(options)	List documents for a user/project
client.deleteDocument(documentId)	Delete a document and all its data

Collections

Method	Description
client.createCollection(request)	Create a collection
client.listCollections(options)	List collections
client.getCollection(id, userId)	Get collection with document list
client.deleteCollection(id, userId)	Delete a collection
client.addDocumentToCollection(id, request)	Add document to collection
client.removeDocumentFromCollection(collectionId, documentId)	Remove document from collection

Usage

Method	Description
client.getUsageSummary(range?)	Aggregated usage with daily breakdown
client.getUsageBreakdown(range?)	Usage by endpoint
client.getUsageLimits()	Current plan limits and quota

---

Error handling

import{ClaivApiError,ClaivTimeoutError,ClaivNetworkError}from'@claiv/memory';try{awaitclaiv.ingest({ ... });}catch(err){if(errinstanceofClaivApiError){console.log(err.status);// HTTP status codeconsole.log(err.code);// 'quota_exceeded' | 'invalid_request' | ...console.log(err.requestId);// share with support}elseif(errinstanceofClaivTimeoutError){// request timed out}elseif(errinstanceofClaivNetworkError){// network failure}}

The SDK automatically retries 429 and 5xx responses with exponential backoff. Client errors (4xx) are never retried.

---

TypeScript

Fully typed — all request and response shapes are exported.

importtype{IngestRequest,RecallRequest,RecallResponse,RecallFact,DocumentUploadRequest,DocumentUploadResponse,CollectionCreateRequest,CollectionRow,}from'@claiv/memory';

---

Templates

Get up and running in under 5 minutes with a working starter:

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
• Python SDK
• Issues