Back to docs

Walkthrough

Complete setup guide for running CLAIV Memory locally and integrating with your application.

This walkthrough assumes you're running the claiv-memory infrastructure locally. For cloud-hosted CLAIV, skip to step 4.

1Install Prerequisites

Make sure you have the following installed:

  • Node.js 18+ (LTS recommended)
  • pnpm or npm
  • Docker Desktop (for local infrastructure)
  • PostgreSQL client (optional, for debugging)
Verify installations
node --version  # Should be 18+
pnpm --version  # Or npm --version
docker --version

2Start Infrastructure

Clone the claiv-memory repository and start the infrastructure using Docker Compose:

Terminal
git clone https://github.com/claiv/claiv-memory.git
cd claiv-memory
docker compose up -d

This starts PostgreSQL, the vector store, and background workers.

3Run Migrations

Apply database migrations to create the required tables:

Terminal
pnpm install
pnpm migrate

4Create an API Key

Sign in to the CLAIV Console and create a project:

  1. Register at claiv.io for beta access and create an account once invited
  2. Create a new project from the dashboard
  3. Navigate to the API Keys page
  4. Click "Create API Key" and save it securely

Your API key is only shown once. Copy it immediately and store it in a secure location.

5Test Ingest

Ingest your first event using curl:

Terminal
curl -X POST http://localhost:3000/v1/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test-user-001",
    "type": "message",
    "content": "User prefers concise, technical explanations"
  }'

Expected response:

{
  "event_id": "evt_abc123",
  "deduped": false
}

Note: After ingest, a background worker enriches the event asynchronously (1–5 seconds). Recall may return empty until enrichment completes.

6Test Recall

Retrieve context using the task field for relevance ranking. CLAIV returns context; your LLM generates the reply.

Terminal
curl -X POST http://localhost:3000/v1/recall \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test-user-001",
    "task": "How should I explain things to this user?",
    "token_budget": 2000
  }'

Expected response:

{
  "system_context": "User prefers concise, technical explanations.",
  "memory_blocks": [
    {
      "type": "fact",
      "content": "Prefers concise, technical explanations",
      "relevance": 0.92
    }
  ],
  "citations": ["evt_abc123"],
  "token_estimate": 38
}

token_budget: Controls the maximum tokens returned (range: 200–8000). CLAIV packs the most relevant context within this budget. Inject system_context into your LLM's system prompt.

7Test Forget

Delete derived data and receive a compliance receipt:

Terminal
curl -X POST http://localhost:3000/v1/forget \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test-user-001"
  }'

Expected response with deletion receipt:

{
  "receipt_id": "rcpt_xyz789",
  "deleted_counts": {
    "facts": 1,
    "episodes": 0,
    "embeddings": 3
  }
}

Deletion receipts provide cryptographic proof of data deletion for GDPR/CCPA compliance. Store these receipts for your audit trail.

Important Notes

Async Enrichment

After ingest, a background worker enriches events asynchronously (1–5 seconds). Recall may return empty results until enrichment completes. In production, this is typically not a problem since recall happens on the next user interaction.

Token Budget Limits

The token_budget in recall controls how many tokens worth of memories are returned. CLAIV ranks by relevance and packs greedily until the budget is exhausted.

Candidate Caps

CLAIV considers a limited number of candidate memories for efficiency. Thecandidates_considered field in recall responses shows how many were evaluated.

Next Steps

Understand memory types and token budgets→Explore the full API reference→Open the Console dashboard→