Documentation

Everything you need to integrate, connect MCP, and build with KAAL & Smriti.

🔑 Authentication 🔌 MCP Server (Claude/Cursor)🗄️ Supabase (BYODB)⚡ Ingest API 🔍 Query API

Authentication

All API requests must be authenticated using a Bearer token or X-API-Key header.

Authorization: Bearer chrn_...
# OR
X-API-Key: chrn_...

Model Context Protocol (MCP) Server

New

Connect Smriti directly to Claude Desktop, Cursor IDE, VS Code, or Windsurf using the official Model Context Protocol (MCP) server. Give your AI persistent temporal memory with zero glue code.

1. Quick 3-Step Setup

# 1. Install dependencies
pip install -r mcp/requirements.txt

# 2. Set your API Key
export SMRITI_API_KEY="chrn_your_api_key_here"

# 3. Run stdio server (or test with MCP Inspector)
python -m smriti.mcp
# npx @modelcontextprotocol/inspector python -m smriti.mcp

2. Claude Desktop Integration

Add this snippet to your claude_desktop_config.json file:

{
  "mcpServers": {
    "smriti": {
      "command": "python",
      "args": ["-m", "smriti.mcp"],
      "cwd": "/path/to/smriti",
      "env": {
        "SMRITI_API_KEY": "chrn_your_api_key_here",
        "SMRITI_SOURCE_ID": "claude-desktop"
      }
    }
  }
}

3. Cursor IDE Integration

Add to your project's .cursor/mcp.json or global Cursor settings:

{
  "mcpServers": {
    "smriti": {
      "command": "python",
      "args": ["-m", "smriti.mcp"],
      "cwd": "/path/to/smriti",
      "env": {
        "SMRITI_API_KEY": "chrn_your_api_key_here",
        "SMRITI_SOURCE_ID": "cursor-workspace",
        "SMRITI_SCOPE": "code"
      }
    }
  }
}

Exposed MCP Tools

Tool Name	Description	Parameters
smriti_remember	Stores text memory; auto-extracts Subject-Verb-Object causal tuples	text, source_id, scope, timestamp
smriti_recall	Hybrid search across semantic, temporal, and entity indexes	query, max_results, source_id, scope
smriti_timeline	Retrieves chronological event timeline for a specified time range	time_range_start, time_range_end, scope
smriti_forget	Finds memories to mark as superseded (preserving bi-temporal history)	query, scope, max_to_forget
smriti_health	Checks memory engine status, event count & embedding statistics	none
smriti_usage	Fetches current monthly usage statistics and plan tier limits	none

MCP Environment Variables

Variable	Default	Description
SMRITI_API_KEY	(required)	Your Smriti API key (`chrn_...`)
SMRITI_BASE_URL	https://spy9191-chronos-api-backend.hf.space	Base URL of your deployed Smriti API backend
SMRITI_SOURCE_ID	mcp-client	Default source identifier for memory operations
SMRITI_SCOPE	default	Logical namespace scope for memory partitioning
SMRITI_MAX_RESULTS	20	Default max search results for recall & timeline
SMRITI_SUPABASE_URL	(optional)	Your Supabase direct connection string (port 5432). Routes all memory to your own DB.

Supabase Integration (Bring Your Own DB)

New

Store your AI memory in your own Supabase database instead of the Smriti cloud. The full SVO extraction, supersession, and semantic search pipeline runs identically — your data never leaves your infrastructure.

How it works

🧠 Smriti CloudRuns the AI — SVO parsing, embedding, semantic search

🗄️ Your SupabaseStores the results — events, turns, vectors. Fully yours.

🔑 Smriti API KeyStill validates your quota. Auth always stays with us.

Create a free Supabase project

Go to supabase.com → New Project. The free tier is sufficient. Wait ~1 minute for it to provision.

Run the Smriti migration SQL

In your Supabase dashboard: SQL Editor → New Query. Paste and run this (takes ~2 seconds):

-- Enable pgvector (built into Supabase)
CREATE EXTENSION IF NOT EXISTS vector;

-- Event Calendar
CREATE TABLE IF NOT EXISTS events (
    id TEXT PRIMARY KEY, source_id TEXT NOT NULL,
    subject TEXT NOT NULL, verb TEXT NOT NULL, object TEXT NOT NULL,
    timestamp TIMESTAMPTZ NOT NULL, confidence REAL DEFAULT 1.0,
    metadata_json JSONB DEFAULT '{}', raw_text TEXT DEFAULT '',
    created_at TIMESTAMPTZ NOT NULL, scope TEXT NOT NULL DEFAULT 'default',
    valid_from TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    valid_to TIMESTAMPTZ, superseded_by TEXT,
    datetime_start TIMESTAMPTZ, datetime_end TIMESTAMPTZ,
    entity_aliases JSONB DEFAULT '[]'
);
CREATE INDEX IF NOT EXISTS idx_events_active ON events(valid_to) WHERE valid_to IS NULL;

-- Turn Calendar
CREATE TABLE IF NOT EXISTS turns (
    id TEXT PRIMARY KEY, source_id TEXT NOT NULL,
    role TEXT NOT NULL DEFAULT 'user', content TEXT NOT NULL,
    timestamp TIMESTAMPTZ NOT NULL, event_ids JSONB DEFAULT '[]',
    created_at TIMESTAMPTZ NOT NULL
);

-- Vector Embeddings (384-dim)
CREATE TABLE IF NOT EXISTS event_vectors (
    event_id TEXT PRIMARY KEY REFERENCES events(id) ON DELETE CASCADE,
    source_id TEXT NOT NULL, owner_id TEXT NOT NULL,
    scope TEXT NOT NULL DEFAULT 'default',
    embedding vector(384) NOT NULL,
    embed_text TEXT NOT NULL, timestamp TIMESTAMPTZ NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_vectors_hnsw
    ON event_vectors USING hnsw (embedding vector_cosine_ops);

Copy your direct connection string

In Supabase: Project Settings → Database → Connection string → URI tab. Copy the string.

postgresql://postgres.YOURREF:YOURPASSWORD@db.YOURREF.supabase.co:5432/postgres
#                                                                        ^^^^
#                                              Must be port 5432 (direct), NOT 6543

Test — Ingest a memory to your Supabase

Add the X-Supabase-Url header to your ingest call:

curl -X POST https://spy9191-chronos-api-backend.hf.space/ingest \
  -H "X-API-Key: chrn_your_key" \
  -H "X-Supabase-Url: postgresql://postgres.YOURREF:PW@db.YOURREF.supabase.co:5432/postgres" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "my-test",
    "events": [{"text": "Alice joined the engineering team today"}]
  }'

Test — Query memory from your Supabase

curl -X POST https://spy9191-chronos-api-backend.hf.space/query \
  -H "X-API-Key: chrn_your_key" \
  -H "X-Supabase-Url: postgresql://postgres.YOURREF:PW@db.YOURREF.supabase.co:5432/postgres" \
  -H "Content-Type: application/json" \
  -d '{"query": "Who joined the team?"}'

# Expected response:
# { "results": [{ "subject": "Alice", "verb": "joined", "object": "engineering team" }] }

Verify — Check your Supabase tables

In Supabase dashboard: Table Editor → events. You should see rows with the extracted S-V-O memory. Or run SQL directly:

-- Run in Supabase SQL Editor to verify
SELECT subject, verb, object, timestamp
FROM events
ORDER BY timestamp DESC
LIMIT 10;

-- Also check vector embeddings were stored
SELECT event_id, embed_text FROM event_vectors LIMIT 5;

🔌 To disconnect (eject)

Remove the X-Supabase-Url header from your requests. Smriti immediately reverts to the default cloud storage. No config to undo. Your Supabase data remains untouched.

Ingest Event

Feed unstructured text to your agent's memory. KAAL automatically extracts S-V-O relationships, entities, and temporal data.

POST/ingest

curl -X POST https://spy9191-chronos-api-backend.hf.space/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "my-app",
    "events": [{"text": "Acme Corp signed a new $50k contract today"}]
  }'

Query Memory

Search your agent's memory using natural language. Performs hybrid semantic + temporal + entity retrieval.

POST/query

curl -X POST https://spy9191-chronos-api-backend.hf.space/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What did Acme Corp do?"}'