feat: add MCP server and update README for Smriti

README.md

@@ -1,5 +1,5 @@
 ---
-title: Kaal API Backend
+title: Smriti — Temporal Memory API for AI Agents
 emoji: 🕰️
 colorFrom: red
 colorTo: gray
@@ -9,326 +9,261 @@ pinned: false
 
 <p align="center">
   <img src="https://img.shields.io/badge/Status-Live-4ADE80?style=for-the-badge" alt="Live" />
-  <img src="https://img.shields.io/badge/AI-GPT%20120B%20+%20Llama%203.1-C7AB6B?style=for-the-badge" alt="AI" />
-  <img src="https://img.shields.io/badge/Free%20Tier-10K%20events%2Fmo-6B7194?style=for-the-badge" alt="Free" />
+  <img src="https://img.shields.io/badge/MCP-Claude%20%7C%20Cursor%20%7C%20VS%20Code-6B7194?style=for-the-badge" alt="MCP" />
+  <img src="https://img.shields.io/badge/Free%20Tier-10K%20events%2Fmo-C7AB6B?style=for-the-badge" alt="Free" />
+  <img src="https://img.shields.io/badge/Memory-SVO%20%2B%20pgvector-4ADE80?style=for-the-badge" alt="Memory" />
 </p>
 
-<h1 align="center">🕰️ KAAL</h1>
-<p align="center"><em>Temporal AI Agent Ecosystem — Letters to the Future, for agents.</em></p>
+<h1 align="center">🕰️ Smriti — Temporal AI Memory</h1>
+<p align="center"><em>Long-term memory for AI agents. Structured. Causal. Searchable.</em></p>
 <p align="center">
-  <strong>Give any AI agent structured, temporal long-term memory.</strong><br>
-  Kaal decomposes text into Subject-Verb-Object events, stores them across dual calendars,<br>
-  and lets agents query what happened, when, and why — across any connected SaaS tool.
+  <strong>Give any AI agent persistent, temporal long-term memory in 5 minutes.</strong><br>
+  Smriti decomposes text into Subject-Verb-Object (SVO) causal events, stores them in<br>
+  PostgreSQL + pgvector, and lets agents query what happened, when, and why —<br>
+  across any session, tool, or conversation.
 </p>
 
+> **Keywords:** `mcp-server` `ai-agent-memory` `long-term-memory` `persistent-memory` `claude-memory` `cursor-mcp` `llm-memory` `agent-memory` `memory-mcp` `temporal-memory` `svo-extraction` `pgvector` `langchain-memory` `mem0-alternative` `ai-memory-api` `claude-desktop-mcp` `cursor-ai-memory` `ai-agent-persistent-memory`
+
 ---
 
 ## Table of Contents
 
 - [What is Smriti?](#what-is-smriti)
-- [Architecture & Deployments](#architecture--deployments)
 - [Quick Start (5 Minutes)](#quick-start-5-minutes)
-- [API Reference](#api-reference)
+- [MCP Server — Claude, Cursor, VS Code](#-mcp-server--claude-cursor-vs-code)
+- [REST API Reference](#rest-api-reference)
+- [Architecture](#architecture)
 - [Dashboard Guide](#dashboard-guide)
-- [Agent System](#agent-system)
 - [Pricing Tiers](#pricing-tiers)
 - [Configuration](#configuration)
+- [Integration Examples](#integration-examples)
 - [Troubleshooting](#troubleshooting)
 
 ---
 
-## Architecture & Deployments
-
-To maximize performance while keeping the service accessible, this project uses a **decoupled, dual-deployment architecture**:
-
-1. **Frontend Dashboard (Vercel)**: `https://smriti-kaal.vercel.app`
-   * Provides the blazing-fast Next.js web interface, API key generation, and visual memory management.
-2. **Backend API (Hugging Face Spaces)**: `https://spy9191-chronos-api-backend.hf.space`
-   * Houses the heavy FastAPI inference engine, memory vector database, and LangGraph agent pipelines. 
+## What is Smriti?
 
-**Note for developers:** When you generate an API key on the Vercel site, you use that key to authenticate your backend requests directly to the Hugging Face API base URL. They are the same system working in tandem.
+**The problem:** AI agents are stateless. Every session starts from zero. No memory of decisions made last week, no recall of past conversations, no awareness of what changed. Every agent you build is a goldfish.
 
----
+**The solution:** Smriti is a **temporal memory API** — a plug-in long-term memory layer for any AI agent, MCP host, or SaaS product. It:
 
-## What is Smriti?
+1. **Ingests** text from any source — chat, CRM, email, code commits, documents
+2. **Decomposes** it into structured `Subject → Verb → Object` causal events using AI
+3. **Stores** events in dual stores — PostgreSQL (temporal queries) + pgvector (semantic search)
+4. **Retrieves** relevant memories via natural language — *"What happened with Acme Corp last quarter?"*
+5. **Powers** agents that actually remember — memory persists across sessions, tools, and models
 
-**The problem:** AI agents are goldfish. They process a request, forget everything, and start from zero next time. No memory of what happened yesterday, last week, or across your other tools.
+### What Makes Smriti Different
 
-**The solution:** KAAL is a **temporal memory API** that any AI agent or SaaS product can plug into. It:
-
-1. **Ingests** text from any source (CRM, chat, email, code commits...)
-2. **Decomposes** it into structured Subject-Verb-Object events using AI (Llama 3.1 8B via Groq)
-3. **Stores** events in dual calendars — Postgres for temporal queries, pgvector for semantic search
-4. **Retrieves** relevant memories via natural language — "What happened with Acme Corp last quarter?"
-5. **Powers** agents that actually remember — an AI that knows *your* history
+| Feature | Smriti | Typical RAG | Mem0 | Zep |
+|---|---|---|---|---|
+| SVO causal extraction | ✅ | ❌ | ❌ | ❌ |
+| Temporal bi-calendar | ✅ | ❌ | ❌ | Partial |
+| MCP server built-in | ✅ | ❌ | ❌ | ❌ |
+| Never deletes (supersession) | ✅ | ❌ | ❌ | ❌ |
+| Free tier | ✅ 10K events | ❌ | ✅ limited | Paid |
+| Self-hostable | ✅ | ✅ | ❌ | ✅ |
 
 ### Real Example
 
 ```
 INPUT:  "Acme Corp signed a $50,000 contract for Q2 2026"
 
-CHRONOS EXTRACTS:
+SMRITI EXTRACTS:
   Subject: Acme Corp
   Verb:    signed
   Object:  a $50,000 contract for Q2 2026
   When:    Q2 2026
 
-LATER, ANY AGENT CAN ASK:
-  "What happened with contracts?"
-  → [2026-04-12] Acme Corp signed a $50,000 contract for Q2 2026
+MONTHS LATER, ANY AGENT CAN ASK:
+  "What are our biggest contracts?"
+  → [2026-04-12] Acme Corp signed a $50,000 contract for Q2 2026  (score: 0.92)
 ```
 
 ---
 
-## Architecture
+## Quick Start (5 Minutes)
 
-```
-┌──────────────────────────────────────────────────────────────┐
-│                    KAAL v0.1.0                         │
-├──────────────────────────────────────────────────────────────┤
-│                                                              │
-│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────┐  │
-│  │ POST /ingest│  │ POST /query  │  │ POST /agent/run    │  │
-│  │  Raw text → │  │  NL search → │  │  Prompt → Memory   │  │
-│  │  SVO events │  │  Hybrid rank │  │  → LLM → Response  │  │
-│  └──────┬──────┘  └──────┬───────┘  └─────────┬──────────┘  │
-│         │                │                     │             │
-│  ┌──────▼────────────────▼─────────────────────▼──────────┐  │
-│  │              🧠 Memory Core                            │  │
-│  │  ┌──────────────────┐  ┌──────────────────────────┐    │  │
-│  │  │  Event Calendar  │  │    Embedding Index       │    │  │
-│  │  │  (PostgreSQL)    │  │    (pgvector)            │    │  │
-│  │  │  • SVO tuples    │  │    • Semantic vectors    │    │  │
-│  │  │  • Timestamps    │  │    • Cosine similarity   │    │  │
-│  │  │  • Turn history  │  │    • Fast pgvector scan  │    │  │
-│  │  └──────────────────┘  └──────────────────────────┘    │  │
-│  └────────────────────────────────────────────────────────┘  │
-│                                                              │
-│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐  │
-│  │ SVO Parser   │  │ Auth + Tiers │  │ Razorpay Billing   │  │
-│  │ GPT 120B     │  │ API keys     │  │ Explorer/Builder/  │  │
-│  │ + Llama 3.1  │  │ SHA-256 hash │  │ Scale              │  │
-│  └──────────────┘  └──────────────┘  └────────────────────┘  │
-└──────────────────────────────────────────────────────────────┘
-```
+**Live API:** `https://spy9191-chronos-api-backend.hf.space`
+**Dashboard:** `https://smriti-kaal.vercel.app`
 
-### File Structure
+### Step 1 — Get a Free API Key
 
-```
-chronos-hub/
-├── chronos_core/           🧠 Memory Core
-│   ├── models.py           Pydantic models, tier config, pricing
-│   ├── svo_parser.py       AI event extraction (Groq / Llama 3.1)
-│   ├── memory_store.py     PostgreSQL dual calendars (events + turns)
-│   └── vector_store.py     pgvector semantic search (sentence-transformers)
-│
-├── api/                    🌐 FastAPI Gateway
-│   ├── main.py             App entry, CORS, lifespan
-│   ├── auth.py             API key auth, tier quota enforcement
-│   ├── deps.py             Dependency injection (singletons)
-│   └── routes/
-│       ├── ingest.py       POST /ingest — feed events
-│       ├── query.py        POST /query — search memory
-│       ├── connectors.py   POST /connect — register SaaS tools
-│       ├── agent.py        POST /agent/run — chat with memory
-│       └── billing.py      Razorpay checkout, usage, key generation
-│
-├── agent/                  🤖 LangGraph Agent Runner
-│   ├── graph.py            State graph: memory → model → response
-│   ├── nodes.py            Processing nodes (retrieve, call LLM)
-│   └── tools.py            Built-in tools for agents
-│
-├── chronos-ui/             📊 Next.js Web Dashboard
-│   └── src/app             Full app UI (navy+gold Chronos design)
-│
-├── .env                    Environment variables (your keys)
-├── .env.example            Template
-├── requirements.txt        Python dependencies
-└── test_quick.py           Integration test script
+```bash
+curl -X POST "https://spy9191-chronos-api-backend.hf.space/billing/keys?tier=explorer"
+# Returns: {"api_key": "chrn_...", "tier": "explorer"}
 ```
 
----
-
-## Quick Start (5 Minutes)
+Or visit [smriti-kaal.vercel.app](https://smriti-kaal.vercel.app) and click **Generate Key**.
 
-### Prerequisites
-
-- Python 3.11+
-- A free Groq API key from [console.groq.com](https://console.groq.com)
-
-### Step 1 — Install
+### Step 2 — Store a Memory
 
 ```bash
-cd chronos-hub
-pip install -r requirements.txt
+curl -X POST https://spy9191-chronos-api-backend.hf.space/ingest \
+  -H "X-API-Key: chrn_your_key" \
+  -H "Content-Type: application/json" \
+  -d '{"source_id": "quickstart", "events": [{"text": "Alice joined the team as lead engineer on July 15"}]}'
 ```
 
-### Step 2 — Configure
+### Step 3 — Recall It
 
 ```bash
-# Copy the template
-cp .env.example .env
-
-# Edit .env and add your Groq key:
-# GROQ_API_KEY=gsk_your_key_here
+curl -X POST https://spy9191-chronos-api-backend.hf.space/query \
+  -H "X-API-Key: chrn_your_key" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "Who joined the team recently?"}'
+# Returns: Alice joined the team as lead engineer on July 15 (score: 0.94)
 ```
 
-### Step 3 — Start the API
+### Local Setup
 
 ```bash
+git clone https://github.com/RemanenetSpy/smriti
+cd smriti
+pip install -r requirements.txt
+cp .env.example .env   # Add your GROQ_API_KEY
 python -m uvicorn api.main:app --port 8000
 ```
 
-You should see:
-```
-✅ KAAL ready — all systems online
-Uvicorn running on http://127.0.0.1:8000
-```
+---
+
+## 🔌 MCP Server — Claude, Cursor, VS Code
+
+Smriti ships a **Model Context Protocol (MCP)** server that gives any MCP-compatible AI host instant persistent long-term memory — zero custom integration needed.
 
-### Step 4 — Start the Dashboard
+> Works with: **Claude Desktop**, **Cursor**, **VS Code + Copilot**, **Windsurf**, **Claude Code**, **Continue**, any MCP-compatible client
+
+### 3-Step Setup
 
 ```bash
-# In a second terminal:
-cd chronos-ui
-npm install
-npm run dev
+# 1. Install MCP dependencies
+pip install -r mcp/requirements.txt
+
+# 2. Set your API key
+export SMRITI_API_KEY="chrn_your_api_key_here"
+
+# 3. Test with MCP Inspector
+npx @modelcontextprotocol/inspector python -m smriti.mcp
 ```
 
-Open **http://localhost:3000** in your browser.
+### Claude Desktop Config
 
-### Step 5 — Test It
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
-```bash
-python test_quick.py
+```json
+{
+  "mcpServers": {
+    "smriti": {
+      "command": "python",
+      "args": ["-m", "smriti.mcp"],
+      "cwd": "/path/to/smriti",
+      "env": {
+        "SMRITI_API_KEY": "chrn_your_key_here",
+        "SMRITI_SOURCE_ID": "claude-desktop"
+      }
+    }
+  }
+}
 ```
 
-Expected output:
+### Cursor Config
+
+Edit `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "smriti": {
+      "command": "python",
+      "args": ["-m", "smriti.mcp"],
+      "cwd": "/path/to/smriti",
+      "env": {
+        "SMRITI_API_KEY": "chrn_your_key_here",
+        "SMRITI_SOURCE_ID": "my-project"
+      }
+    }
+  }
+}
 ```
-=== GENERATING API KEY ===
-Key: chrn_abc123...
 
-=== INGESTING EVENTS ===
-Ingested: 4 events
-SVO tuples found: 4
+### MCP Tools
+
+| Tool | What It Does | Key Arguments |
+|------|-------------|---------------|
+| `smriti_remember` | Store a memory — text auto-decomposes into SVO causal events | `text`, `source_id`, `scope`, `timestamp` |
+| `smriti_recall` | Hybrid search: semantic + temporal + entity across all memories | `query`, `max_results`, `time_range_start`, `time_range_end` |
+| `smriti_timeline` | Chronological event timeline for a time window | `time_range_start`, `time_range_end`, `scope` |
+| `smriti_forget` | Find memories to supersede — history is preserved, never deleted | `query`, `scope` |
+| `smriti_health` | Service health check | — |
+| `smriti_usage` | API usage stats and tier limits | — |
+
+### MCP Resources
+
+| URI | Description |
+|-----|-------------|
+| `smriti://status` | Live service health and memory counts |
+| `smriti://usage` | Current API usage stats and tier limits |
+| `smriti://config` | MCP server configuration (non-sensitive) |
+
+### MCP Prompts
 
-=== QUERYING MEMORY ===
-Found: 4 results in ~80ms
+| Name | Purpose |
+|------|---------|
+| `memory-chat` | System prompt for memory-augmented conversations |
+| `daily-recap` | Timeline-based daily/weekly recap template |
+| `knowledge-extraction` | Bulk knowledge ingestion from documents |
 
-=== ALL TESTS PASSED ===
+### SSE Transport (Remote / Multi-Client)
+
+```bash
+python -m smriti.mcp --transport sse --port 8080
 ```
 
+> 📖 Full MCP docs: [`mcp/README.md`](mcp/README.md)
+
 ---
 
-## API Reference
+## REST API Reference
 
 **Base URL:** `https://spy9191-chronos-api-backend.hf.space`
-**Auth:** Include your API key in the `Authorization: Bearer <key>` header.
-**Docs:** Open `https://spy9191-chronos-api-backend.hf.space/docs` for interactive Swagger UI.
+**Auth:** `X-API-Key: chrn_your_key` header on all requests.
+**Interactive docs:** [/docs](https://spy9191-chronos-api-backend.hf.space/docs)
 
 ---
 
 ### `POST /billing/keys` — Generate API Key
 
-No auth required. Creates a new API key.
+No auth required.
 
 ```bash
 curl -X POST "https://spy9191-chronos-api-backend.hf.space/billing/keys?tier=explorer"
 ```
 
-**Response:**
 ```json
 {
   "api_key": "chrn_abc123...",
-  "source_id": "src_7277b1709a854375",
   "tier": "explorer",
-  "message": "⚠️ Save this API key now — it cannot be retrieved later."
+  "message": "Save this API key now — it cannot be retrieved later."
 }
 ```
 
 ---
 
-### `POST /ingest` — Feed Events
-
-Send raw text; the AI extracts structured SVO events automatically.
-
-```bash
-curl -X POST https://spy9191-chronos-api-backend.hf.space/ingest \
-  -H "X-API-Key: chrn_your_key" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "source_id": "my-crm",
-    "events": [
-      {"text": "Acme Corp signed a $50,000 contract for Q2 2026"},
-      {"text": "Jane was promoted to VP of Engineering on March 15"},
-      {"text": "Server migration completed from AWS to Railway on April 1"}
-    ],
-    "parse_svo": true
-  }'
-```
-
-**Response:**
-```json
-{
-  "ingested_count": 3,
-  "event_ids": ["abc123", "def456", "ghi789"],
-  "svo_tuples": [
-    {
-      "subject": "Acme Corp",
-      "verb": "signed",
-      "object": "a $50,000 contract for Q2 2026",
-      "confidence": 0.95
-    }
-  ],
-  "turn_ids": ["turn_1", "turn_2", "turn_3"]
-}
-```
-
-**Parameters:**
+### `POST /ingest` — Store Memories
 
 | Field | Type | Required | Description |
 |---|---|---|---|
-| `source_id` | string | ✅ | Identifies the data source |
+| `source_id` | string | ✅ | Data source identifier |
 | `events` | array | ✅ | List of `{text, timestamp?, metadata?}` objects |
-| `parse_svo` | bool | No | Enable AI extraction (default: `true`) |
+| `parse_svo` | bool | No | Enable AI SVO extraction (default: `true`) |
+| `scope` | string | No | Memory scope / namespace |
 
 ---
 
 ### `POST /query` — Search Memory
 
-Natural language search with optional time filtering.
-
-```bash
-curl -X POST https://spy9191-chronos-api-backend.hf.space/query \
-  -H "X-API-Key: chrn_your_key" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "What happened with contracts?",
-    "max_results": 10
-  }'
-```
-
-**Response:**
-```json
-{
-  "results": [
-    {
-      "event": {
-        "subject": "Acme Corp",
-        "verb": "signed",
-        "object": "a $50,000 contract for Q2 2026",
-        "timestamp": "2026-04-12T18:28:17Z"
-      },
-      "relevance_score": 0.92,
-      "provenance": "semantic"
-    }
-  ],
-  "total_found": 1,
-  "query_time_ms": 80.0
-}
-```
-
-**Parameters:**
-
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `query` | string | ✅ | Natural language question |
@@ -339,157 +274,112 @@ curl -X POST https://spy9191-chronos-api-backend.hf.space/query \
 
 ---
 
-### `POST /agent/run` — Chat with Agent
-
-Conversational AI with full temporal memory access.
+### `POST /agent/run` — Chat with Memory-Aware AI
 
 ```bash
 curl -X POST https://spy9191-chronos-api-backend.hf.space/agent/run \
   -H "X-API-Key: chrn_your_key" \
   -H "Content-Type: application/json" \
-  -d '{
-    "prompt": "Summarize everything that happened recently",
-    "thread_id": null
-  }'
-```
-
-**Response:**
-```json
-{
-  "thread_id": "thread_abc123",
-  "response": "Based on your temporal memory, here's what happened recently...",
-  "events_retrieved": 4,
-  "events_created": 0
-}
+  -d '{"prompt": "Summarize everything that happened recently", "thread_id": null}'
 ```
 
 ---
 
-### `POST /connect` — Register a SaaS Tool
+### `GET /health` — Health Check
 
 ```bash
-curl -X POST https://spy9191-chronos-api-backend.hf.space/connect \
-  -H "X-API-Key: chrn_your_key" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "Stripe",
-    "description": "Payment processing",
-    "base_url": "https://api.stripe.com",
-    "auth_header": "Authorization",
-    "endpoints": [
-      {"method": "GET", "path": "/v1/invoices", "description": "List invoices"}
-    ]
-  }'
+curl https://spy9191-chronos-api-backend.hf.space/health
+# {"status": "healthy", "stores": {"postgres_events": 4, "pgvector_embeddings": 4}}
 ```
 
 ---
 
-### `GET /billing/usage` — Check Usage
+## Architecture
 
-```bash
-curl https://spy9191-chronos-api-backend.hf.space/billing/usage \
-  -H "X-API-Key: chrn_your_key"
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    Smriti v0.1.0                             │
+├──────────────────────────────────────────────────────────────┤
+│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐  │
+│  │ MCP Server   │  │ REST API     │  │  Agent (LangGraph) │  │
+│  │ 6 tools      │  │ FastAPI      │  │  POST /agent/run   │  │
+│  │ Claude/Cursor│  │ /ingest      │  │  Memory → LLM      │  │
+│  └──────┬───────┘  │ /query       │  └─────────┬──────────┘  │
+│         │          └──────┬───────┘            │             │
+│  ┌──────▼──────────────────▼────────────────────▼──────────┐  │
+│  │                  🧠 Memory Core                         │  │
+│  │  ┌──────────────────────┐  ┌──────────────────────────┐  │  │
+│  │  │  Event Calendar      │  │  Embedding Index         │  │  │
+│  │  │  (PostgreSQL/Neon)   │  │  (pgvector)              │  │  │
+│  │  │  • SVO tuples        │  │  • Semantic vectors      │  │  │
+│  │  │  • Timestamps        │  │  • Cosine similarity     │  │  │
+│  │  │  • Supersession log  │  │  • all-MiniLM-L6-v2      │  │  │
+│  │  └──────────────────────┘  └──────────────────────────┘  │  │
+│  └────────────────────────────────────────────────────────┘  │
+│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐  │
+│  │ SVO Parser   │  │ Auth + Tiers │  │ Next.js Dashboard  │  │
+│  │ Groq LLM     │  │ API keys     │  │ smriti-kaal.vercel │  │
+│  └──────────────┘  └──────────────┘  └────────────────────┘  │
+└──────────────────────────────────────────────────────────────┘
 ```
 
----
+### Deployments
 
-### `GET /health` — Health Check
+| Component | Platform | URL |
+|---|---|---|
+| **Frontend Dashboard** | Vercel (Next.js) | [smriti-kaal.vercel.app](https://smriti-kaal.vercel.app) |
+| **Backend API** | Hugging Face Spaces (Docker) | [spy9191-chronos-api-backend.hf.space](https://spy9191-chronos-api-backend.hf.space) |
 
-```bash
-curl https://spy9191-chronos-api-backend.hf.space/health
-```
+### File Structure
 
-```json
-{
-  "status": "healthy",
-  "stores": {"postgres_events": 4, "pgvector_embeddings": 4}
-}
+```
+smriti/
+├── api/                        REST API (FastAPI)
+├── mcp/                        MCP Server (Claude / Cursor / VS Code)
+│   ├── server.py               FastMCP — 6 tools, 3 resources, 3 prompts
+│   ├── client.py               HTTP client for Smriti REST API
+│   ├── config.py               Environment variable configuration
+│   ├── __main__.py             CLI entry (python -m smriti.mcp)
+│   ├── claude_desktop_config.json
+│   ├── cursor_config.json
+│   └── README.md
+├── chronos_core/               Memory Core (SVO parser, stores)
+├── agent/                      LangGraph Agent
+├── chronos-ui/                 Next.js Dashboard (Vercel)
+├── benchmark/                  PrecisionMemBench eval harness
+├── docs/                       Technical docs
+├── Dockerfile
+���── requirements.txt
 ```
 
 ---
 
 ## Dashboard Guide
 
-The dashboard runs at **http://localhost:3000** and provides a visual interface for all Chronos features.
+Dashboard at **https://smriti-kaal.vercel.app** (or `http://localhost:3000` locally).
 
 | Page | What It Does |
 |---|---|
 | 🏠 **Overview** | System health, event count, embedding count, AI status |
 | 📥 **Ingest Events** | Write events in plain English → AI extracts SVO tuples |
-| 🔍 **Query Memory** | Natural language search with date filters and relevance |
-| 🤖 **Agent Chat** | Conversational AI that reasons with your temporal memory |
+| 🔍 **Query Memory** | Natural language search with date filters and relevance scores |
+| 🤖 **Agent Chat** | Conversational AI that reasons with temporal memory |
 | 🔗 **Connect Tool** | Register any SaaS API for agent discovery |
 | 📊 **Usage & Billing** | Tier badge, usage meters, pricing table |
-| 🔑 **API Keys** | Generate new keys with one click |
-
-### How to Use the Dashboard
-
-1. Open **http://localhost:3000**
-2. Click **🔑 API Keys** → Click **Generate Key** → Copy the key
-3. Paste the key into the **🔑 API Key** field in the sidebar
-4. Go to **📥 Ingest Events** → Type events → Click **Ingest Into Memory**
-5. Go to **🔍 Query Memory** → Ask a question → See results
-6. Go to **🤖 Agent Chat** → Have a conversation with memory-aware AI
-
----
-
-## Agent System
-
-Chronos includes a **LangGraph-based agent** that automatically:
-
-1. **Retrieves** relevant memories from ChromaDB before responding
-2. **Injects** temporal context into the LLM's system prompt
-3. **Responds** with awareness of past events, dates, and relationships
-
-### How It Works
-
-```
-User: "What's our biggest contract?"
-         │
-         ▼
-┌─────────────────────┐
-│ retrieve_memory_node │  ← Searches pgvector + Postgres
-│ ("contract" → Acme) │     for relevant past events
-└────────┬────────────┘
-         │
-         ▼
-┌─────────────────────┐
-│  call_model_node    │  ← GPT 120B
-│  System prompt +    │     with memory context injected
-│  memory context +   │
-│  user question      │
-└────────┬────────────┘
-         │
-         ▼
-"Based on your records, Acme Corp signed a $50K contract for Q2 2026."
-```
-
-### AI Model
-
-| Property | Value |
-|---|---|
-| **Model** | GPT OSS 120B (Agent) + Llama 3.1 8B (Parsing) |
-| **Provider** | Zhipu AI & Groq |
-| **Speed** | 2,100+ tokens/second |
-| **Daily Limit** | 1,000,000 requests/day |
-| **Cost** | Free |
+| 🔑 **API Keys** | Generate and manage keys |
 
 ---
 
 ## Pricing Tiers
 
-KAAL uses a three-tier model with metered overage:
-
 | Feature | Explorer | Builder | Scale |
 |---|---|---|---|
 | **Price** | Free | $49/month | $249/month |
 | **Events/month** | 10,000 | 500,000 | 5,000,000 |
+| **MCP sessions** | Unlimited | Unlimited | Unlimited |
 | **Orchestration calls** | 100 | 10,000 | Unlimited |
 | **Connected tools** | 3 | 25 | Unlimited |
 | **Data retention** | 30 days | 1 year | Unlimited |
-| **Agent threads** | 5 | 100 | Unlimited |
-| **Event overage (per 1K)** | Hard cap | $0.05 | $0.03 |
-| **Orchestration overage** | Hard cap | $0.10 | $0.07 |
 | **Support** | Community | Priority email | Dedicated Slack |
 
 ---
@@ -500,90 +390,62 @@ KAAL uses a three-tier model with metered overage:
 
 | Variable | Required | Description |
 |---|---|---|
-| `GROQ_API_KEY` | ✅ | Free API key from [console.groq.com](https://console.groq.com) |
+| `GROQ_API_KEY` | ✅ | Free from [console.groq.com](https://console.groq.com) |
+| `SMRITI_API_KEY` | MCP only | Your Smriti API key (`chrn_...`) |
 | `CHRONOS_DB_URL` | No | Postgres DB URL |
-| `PGVECTOR_DB_URL` | No | Postgres DB URL for pgvector |
+| `PGVECTOR_DB_URL` | No | pgvector DB URL |
 | `API_SECRET_KEY` | No | Secret for signing API keys |
-| `RAZORPAY_KEY_ID` | No | Razorpay key ID for billing |
-| `RAZORPAY_KEY_SECRET` | No | Razorpay secret key |
-| `RAZORPAY_PLAN_BUILDER` | No | Razorpay plan ID for Builder tier |
-| `RAZORPAY_PLAN_SCALE` | No | Razorpay plan ID for Scale tier |
-| `CHRONOS_API_URL` | No | API URL for dashboard (default: `http://localhost:8000`) |
+
+### MCP Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `SMRITI_API_KEY` | *(required)* | API key (`chrn_...`) |
+| `SMRITI_BASE_URL` | `https://spy9191-chronos-api-backend.hf.space` | API base URL |
+| `SMRITI_SOURCE_ID` | `mcp-client` | Default source namespace |
+| `SMRITI_SCOPE` | `default` | Default memory scope |
+| `SMRITI_MAX_RESULTS` | `20` | Default max results |
+| `SMRITI_PARSE_SVO` | `true` | Enable SVO extraction |
+| `SMRITI_TIMEOUT` | `30.0` | HTTP timeout (seconds) |
 
 ### Tech Stack
 
 | Component | Technology |
 |---|---|
 | **API Framework** | FastAPI + Uvicorn |
+| **MCP Framework** | FastMCP (Model Context Protocol) |
 | **Structured Storage** | Neon PostgreSQL |
-| **Vector Search** | PostgreSQL pgvector + sentence-transformers |
+| **Vector Search** | pgvector + sentence-transformers |
 | **Embedding Model** | all-MiniLM-L6-v2 (HuggingFace) |
-| **LLM** | GPT OSS 120B & Llama 3.1 8B (Cerebras) |
+| **SVO Parser / LLM** | Llama 3.x via Groq |
 | **Agent Framework** | LangGraph + LangChain |
 | **Dashboard** | Next.js + React (Vercel) |
-| **Billing** | Razorpay |
 | **Auth** | SHA-256 hashed API keys |
 
 ---
 
-## Troubleshooting
-
-| Problem | Solution |
-|---|---|
-| **"Cannot connect to API"** | Make sure the API is running: `python -m uvicorn api.main:app --port 8000` |
-| **Dashboard won't load** | Start it: `python -m streamlit run dashboard/app.py --server.port 8501` |
-| **"No GROQ_API_KEY set"** | Create `.env` file with `GROQ_API_KEY=gsk_your_key` |
-| **"Missing API key" on requests** | Add `X-API-Key: chrn_...` header to all API calls |
-| **Query returns 0 results** | Ingest some events first via `POST /ingest` |
-| **Slow first startup** | The embedding model (~80MB) downloads once from HuggingFace on first run |
-| **Agent gives generic response** | Make sure there are ingested events for the agent to recall |
-
-### Running Both Servers
-
-You need **two terminals** running simultaneously:
-
-**Terminal 1 — API Server:**
-```bash
-cd chronos-hub
-python -m uvicorn api.main:app --port 8000
-```
-
-**Terminal 2 — Dashboard:**
-```bash
-cd chronos-ui
-npm run dev
-```
-
----
-
 ## Integration Examples
 
-### Python SDK Usage
+### Python
 
 ```python
 import httpx
 
-API = "http://localhost:8000"
+API = "https://spy9191-chronos-api-backend.hf.space"
 KEY = "chrn_your_key_here"
 HEADERS = {"X-API-Key": KEY}
 
-# Ingest an event
+# Store a memory
 httpx.post(f"{API}/ingest", headers=HEADERS, json={
     "source_id": "my-app",
-    "events": [{"text": "User completed onboarding on April 12"}]
+    "events": [{"text": "User completed onboarding on July 15"}]
 })
 
-# Query memory
+# Recall it
 result = httpx.post(f"{API}/query", headers=HEADERS, json={
     "query": "What did the user do?"
 })
-print(result.json()["results"])  # → onboarding event
-
-# Chat with agent
-response = httpx.post(f"{API}/agent/run", headers=HEADERS, json={
-    "prompt": "Summarize user activity"
-})
-print(response.json()["response"])
+print(result.json()["results"])
 ```
 
 ### JavaScript / Node.js
@@ -592,7 +454,6 @@ print(response.json()["response"])
 const API = "https://spy9191-chronos-api-backend.hf.space";
 const headers = { "X-API-Key": "chrn_your_key", "Content-Type": "application/json" };
 
-// Ingest
 await fetch(`${API}/ingest`, {
   method: "POST", headers,
   body: JSON.stringify({
@@ -601,7 +462,6 @@ await fetch(`${API}/ingest`, {
   })
 });
 
-// Query
 const res = await fetch(`${API}/query`, {
   method: "POST", headers,
   body: JSON.stringify({ query: "Who upgraded recently?" })
@@ -611,7 +471,21 @@ console.log(await res.json());
 
 ---
 
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| **"Cannot connect to API"** | Check `python -m uvicorn api.main:app --port 8000` is running |
+| **"No GROQ_API_KEY set"** | Add `GROQ_API_KEY=gsk_...` to `.env` |
+| **"Missing API key"** | Add `X-API-Key: chrn_...` header to all requests |
+| **Query returns 0 results** | Ingest some events first via `POST /ingest` |
+| **Slow first startup** | Embedding model (~80MB) downloads once on first run |
+| **MCP not connecting** | Run `npx @modelcontextprotocol/inspector python -m smriti.mcp` to test |
+| **MCP tools not appearing** | Check `SMRITI_API_KEY` is set in the env block of your host config |
+
+---
+
 <p align="center">
-  <em>🕰️ Curated with continuity in mind.</em><br>
-  <strong>© 2026 Chronos Labs</strong>
+  <em>🕰️ Memory that persists. Context that continues.</em><br>
+  <strong>© 2026 Smriti / Chronos Labs</strong>
 </p>

docs/README (4).md

@@ -0,0 +1,80 @@
+
+# Chronos: Temporal Legacy Vault
+
+> "Capturing the fragments of today for the clarity of tomorrow."
+
+**Chronos** is a luxury minimalist digital sanctuary designed for intentional reflection. It acts as a **nervous system regulator**—an anti-doomscrolling tool that allows you to compose letters, attach "visual echoes" (photos), and record audio to be delivered to your future self. By locking memories behind a temporal gate, Chronos transforms social posting into a private ritual of mindfulness, quarantining your mental noise.
+
+---
+
+## 📜 The Purpose
+
+In an era of instant gratification and ephemeral content, Chronos asks you to slow down. Human brains hate "open loops." If you have an intrusive thought and put it in a standard notes app, you just keep re-reading it. If you lock it in Chronos and the math physically refuses to let you see it for a month, your brain is forced to drop the loop. 
+
+## ✨ Key Features
+
+- **Compose Across Time**: Write rich, serif-styled letters to the future with an elegant editor.
+- **Visual & Voice Echoes**: Attach images and audio recordings to your capsules to ground your memories in reality.
+- **Temporal Gates**: Choose your horizon—from a single "Moment" (1 day) to a full "Decade."
+- **The Vault**: A curated gallery of your pending and revealed history, styled as an elegant stationery collection with a dramatic editorial layout.
+- **Reflections**: Once a capsule is revealed, add a modern perspective to your past thoughts to see how much you've grown.
+- **Premium Waitlist**: Long-term horizons (Year, Decade) and unlimited Moon capsules are locked behind a premium tier (currently a demo waitlist).
+- **Share the Void**: Generate a high-resolution, cryptographic-style "tombstone" card to share on social media, proving you locked a thought without revealing the content.
+
+---
+
+## ⚙️ Technical Deep Dive & Architecture
+
+Chronos is built as a **Local-First Single Page Application (SPA)**. The architecture is designed to prioritize absolute user privacy, meaning the application logic runs entirely within the client's browser.
+
+### 1. Data Persistence & Media Handling
+- **Storage Engine**: Data is persisted using the browser's native `localStorage` API. 
+- **Media Encoding**: Images and audio are not uploaded to a CDN. Instead, the `FileReader` API converts images, and the `MediaRecorder` API converts microphone streams (`audio/webm`), directly into **Base64 Data URIs**. These strings are then encrypted and stored locally.
+- *Note on Scaling*: `localStorage` typically has a 5MB limit. Future iterations will migrate to `IndexedDB` to support larger media payloads.
+
+### 2. Security & Encryption (Local-First)
+- **AES-256 Encryption at Rest**: Before any capsule is committed to `localStorage`, the sensitive fields (`content`, `reflection`, `imageUrl`, `audioUrl`) are mathematically locked using `crypto-js` AES encryption. 
+- **Targeted Encryption**: The UI metadata (`unlockAt`, `title`, `id`) remains in plain text. This allows the React frontend to render the Vault gallery, calculate countdown timers, and manage state without needing to decrypt the private payloads.
+- **Zero-Knowledge**: Your data never leaves your device. There is no database, no cloud sync, and no backend API receiving your thoughts. You can verify this by monitoring the Network tab in your browser's Developer Tools.
+- *MVP Note*: The current iteration uses a static client-side key for AES encryption. A production release will implement PBKDF2 to derive a unique encryption key from a user-provided master password.
+
+### 3. "Share the Void" Card Generation
+To allow users to share their commitment on social media without compromising privacy, Chronos features a client-side image generator.
+- **html2canvas**: When a user clicks "Share the Void", the app renders a hidden DOM element containing the "tombstone" design (using the *Spectral* typeface).
+- **Canvas Export**: `html2canvas` traverses this DOM node, paints it to an HTML5 `<canvas>` at 3x scale for high-resolution retina displays, and exports it as an `image/png` Data URI, triggering a native browser download.
+
+### 4. Tech Stack
+- **Frontend Framework**: React 19, TypeScript, Vite
+- **Styling**: Tailwind CSS
+- **Typography**: Cormorant Garamond (Serif), Spectral (Serif), Inter (Sans), JetBrains Mono (Mono)
+- **Cryptography**: `crypto-js`
+- **Backend (Payments Only)**: Express.js server utilizing the `stripe` Node SDK to generate secure Checkout Sessions for the Premium tier.
+
+---
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Node.js (v18+)
+- npm or yarn
+
+### Installation
+
+1. Clone the repository
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+3. Start the development server:
+   ```bash
+   npm run dev
+   ```
+
+## ⚖️ License
+
+Distributed under the **MIT License**. See the footer of the application for more details. This project is open for anyone to use, modify, and chronicle their own journeys.
+
+---
+
+*Curated with continuity in mind.*

docs/chronos_brain_evolution.md

@@ -0,0 +1,282 @@
+# 🧠 Chronos OS → Chronos Brain: The Evolution
+
+> *"We built the memory. Now we build the mind."*
+
+---
+
+## The Opportunity
+
+Right now, Chronos OS is a **temporal memory API** — it stores events, retrieves them, and lets agents query the past. That's already more than Gemini, Claude, or Grok can do natively.
+
+But with the free frontier models you have access to (Ollama Cloud, NVIDIA NIM, Cerebras, Groq), we can evolve Chronos from a **passive memory store** into an **active, self-learning cognitive system** — a brain that doesn't just remember, but *understands*, *predicts*, *adapts*, and *acts*.
+
+No one has built this. Not OpenAI. Not Google. Not Anthropic. Their models are brilliant in the moment but **amnesiac across time**. Chronos already solved the amnesia. Now we give it intelligence layers.
+
+---
+
+## The 5 Layers of the Chronos Brain
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   CHRONOS BRAIN v1.0                     │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  Layer 5: 🤖 AUTONOMOUS ORCHESTRATION                   │
+│  ├── Multi-agent coordination across SaaS tools         │
+│  ├── Self-dispatching task execution                    │
+│  └── Model: Nemotron-3-Super 120B (NVIDIA NIM)         │
+│                                                         │
+│  Layer 4: 🕸️ SELF-EVOLVING KNOWLEDGE GRAPH              │
+│  ├── Entity relationship mapping across all events      │
+│  ├── Automatic concept linking & ontology building      │
+│  └── Model: DeepSeek-V3.2 671B (Ollama Cloud)          │
+│                                                         │
+│  Layer 3: 👁️ MULTI-MODAL MEMORY                         │
+│  ├── Ingest images, screenshots, documents, audio       │
+│  ├── Extract temporal events from ANY media type        │
+│  └── Model: Kimi-K2.5 / Gemma 4 31B (Ollama Cloud)     │
+│                                                         │
+│  Layer 2: 🔮 PREDICTIVE INTELLIGENCE                    │
+│  ├── Pattern detection across temporal event streams    │
+│  ├── "What will happen next?" forecasting               │
+│  └── Model: GLM-5.1 / Qwen 3.5 122B (Ollama Cloud)    │
+│                                                         │
+│  Layer 1: 💾 MEMORY CONSOLIDATION (Sleep Cycle)         │
+│  ├── Nightly compression of raw events → insights       │
+│  ├── Forgetting curve: fade irrelevant, strengthen key  │
+│  └── Model: Qwen 3 235B (Cerebras) + Llama 3.1 (Groq)  │
+│                                                         │
+│  Layer 0: 📅 TEMPORAL MEMORY (Already Built!)           │
+│  ├── SVO event extraction & dual calendar storage       │
+│  ├── Hybrid semantic + temporal retrieval               │
+│  └── PostgreSQL + pgvector + sentence-transformers      │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Layer 1: 💾 Memory Consolidation (The Sleep Cycle)
+
+> **"The human brain doesn't remember everything. It replays, compresses, and strengthens what matters while you sleep. Chronos should too."**
+
+### What It Does
+Every night (or every N hours), a background job runs that:
+1. **Replays** all recent events for each tenant
+2. **Extracts patterns**: "User mentioned Acme Corp 14 times this week, always about contracts"
+3. **Generates insights**: "Acme Corp negotiation is escalating — confidence dropped from 0.95 to 0.6 over 3 days"
+4. **Compresses**: Merges redundant events into consolidated summaries
+5. **Assigns decay scores**: Events that are never queried slowly fade (like human forgetting)
+
+### Models Used
+| Task | Model | Provider | Cost |
+|---|---|---|---|
+| Event replay & compression | Qwen 3 235B | Cerebras | Free (1M tokens/day) |
+| Fast batch processing | Llama 3.1 8B | Groq | Free (14.4K req/day) |
+
+### New API Endpoint
+```
+GET /memory/insights?period=7d
+→ Returns auto-generated weekly intelligence briefing for this API key owner
+```
+
+### Why It's Revolutionary
+No AI system today does this. ChatGPT's "memory" is a flat list of facts. Chronos would have **temporal depth** — it knows not just *what* happened, but how things *changed over time* and what the *trajectory* suggests.
+
+---
+
+## Layer 2: 🔮 Predictive Intelligence
+
+> **"Memory isn't just about the past. A true brain uses patterns from the past to predict the future."**
+
+### What It Does
+After Layer 1 consolidates memories into patterns, Layer 2 runs prediction:
+1. **Trend Detection**: "Revenue discussions increased 300% this month vs last month"
+2. **Anomaly Alerts**: "This client usually responds within 2 days. It's been 8 days — flag it"
+3. **Forecasting**: "Based on past Q2 patterns, expect a 40% spike in contract renewals"
+4. **Causal Chains**: "Every time X happened, Y followed within 2 weeks"
+
+### Models Used
+| Task | Model | Provider | Cost |
+|---|---|---|---|
+| Deep temporal reasoning | GLM-5.1 Cloud (strongest reasoning) | Ollama Cloud | Free |
+| Large-scale pattern analysis | Qwen 3.5 122B Cloud | Ollama Cloud | Free |
+
+### New API Endpoint
+```
+POST /brain/predict
+Body: { "question": "What will happen with the Acme Corp deal?" }
+→ Returns prediction with confidence score + supporting temporal evidence chain
+```
+
+### Why It's Revolutionary
+This turns Chronos from **reactive** (answer questions about the past) to **proactive** (warn you about the future). No memory system does this. You're essentially building **temporal intuition** for AI agents.
+
+---
+
+## Layer 3: 👁️ Multi-Modal Memory
+
+> **"Humans don't just remember words. We remember faces, documents, screenshots, sounds. Chronos should too."**
+
+### What It Does
+Expand `/ingest` to accept:
+- 📸 **Images/Screenshots** → Extract text + scene description → SVO events
+- 📄 **PDFs/Documents** → Parse + decompose into temporal events
+- 🎤 **Audio clips** → Transcribe + extract events
+- 📊 **Charts/Graphs** → Interpret trends and convert to structured data
+
+### Models Used
+| Task | Model | Provider | Cost |
+|---|---|---|---|
+| Vision + Language reasoning | Kimi-K2.5 Cloud (multimodal thinking) | Ollama Cloud | Free |
+| Fast vision processing | Gemma 4 31B Cloud (vision/audio) | Ollama Cloud | Free |
+| Speed-optimized vision | Gemini-3-Flash-Preview Cloud | Ollama Cloud | Free |
+
+### New API Endpoint
+```
+POST /ingest/multimodal
+Body: { "file": <base64_image>, "type": "screenshot", "context": "Client meeting whiteboard" }
+→ Extracts SVO events from the image and stores them in memory
+```
+
+### Why It's Revolutionary
+Imagine: a SaaS product takes a screenshot of a Slack conversation, sends it to Chronos, and the agent can later answer "What did the team discuss about the launch timeline?" — from a *screenshot*. That is alien-level memory.
+
+---
+
+## Layer 4: 🕸️ Self-Evolving Knowledge Graph
+
+> **"Individual memories are data points. Connected memories are intelligence."**
+
+### What It Does
+Run a background process that:
+1. **Scans all events** for an owner and builds an entity relationship graph
+2. **Links concepts**: "Acme Corp" → "John (VP Sales)" → "$50K contract" → "Q2 deadline"
+3. **Discovers hidden connections**: "The engineer who left in March was working on the same module that failed in April"
+4. **Auto-generates ontologies**: Learns the user's domain vocabulary and relationships without any configuration
+
+### Models Used
+| Task | Model | Provider | Cost |
+|---|---|---|---|
+| Deep entity extraction & linking | DeepSeek-V3.2 671B Cloud | Ollama Cloud | Free |
+| Graph reasoning at scale | GLM-5.1 Cloud | Ollama Cloud | Free |
+
+### New API Endpoint
+```
+GET /brain/graph?entity=Acme+Corp
+→ Returns full relationship web: people, events, timelines, predictions connected to Acme Corp
+
+POST /brain/reason
+Body: { "question": "How is the Q2 target connected to the engineering delays?" }
+→ Multi-hop reasoning across the knowledge graph with temporal evidence
+```
+
+### Why It's Revolutionary
+This is the difference between a **filing cabinet** and a **brain**. Filing cabinets store things. Brains *connect* things. When Chronos can say "The Q2 revenue target is at risk because the engineer who was building the key feature left, and the replacement won't be onboarded until May based on your historical hiring timeline" — that's not memory. That's **understanding**.
+
+---
+
+## Layer 5: 🤖 Autonomous Orchestration
+
+> **"A brain that remembers, predicts, sees, and connects — but can also ACT."**
+
+### What It Does
+Using the connected SaaS tools from `/connect`, the brain can:
+1. **Self-dispatch actions**: "Your Stripe subscription for Client X expires tomorrow. Based on past behavior, they always renew late. Sending a reminder email via the connected email tool."
+2. **Multi-agent coordination**: Spin up specialized sub-agents for different tasks, each with full temporal memory access
+3. **Learn from outcomes**: Track what actions worked and adapt strategies
+
+### Models Used
+| Task | Model | Provider | Cost |
+|---|---|---|---|
+| Multi-agent orchestration | Nemotron-3-Super 120B (NVIDIA NIM) | NVIDIA | Free credits |
+| Complex agentic workflows | MiniMax-M2.7 Cloud | Ollama Cloud | Free |
+| Code generation for tool calls | Qwen3.6-Coder-Next Cloud | Ollama Cloud | Free |
+
+### New API Endpoint
+```
+POST /brain/act
+Body: { "directive": "Keep all SaaS subscriptions active and negotiate renewals proactively" }
+→ Brain runs autonomously, using memory + predictions + connected tools
+```
+
+---
+
+## Model-to-Task Master Map
+
+| Layer | Task | Best Model | Provider | Free? |
+|---|---|---|---|---|
+| 0 | SVO Extraction (fast) | Llama 3.1 8B | Groq | ✅ 14.4K req/day |
+| 0 | Agent Reasoning | Qwen 3 235B | Cerebras | ✅ 1M tokens/day |
+| 1 | Memory Consolidation | Qwen 3 235B | Cerebras | ✅ |
+| 2 | Predictive Reasoning | GLM-5.1 671B | Ollama Cloud | ✅ |
+| 2 | Pattern Analysis | Qwen 3.5 122B | Ollama Cloud | ✅ |
+| 3 | Vision/Multimodal | Kimi-K2.5 | Ollama Cloud | ✅ |
+| 3 | Fast Vision | Gemma 4 31B | Ollama Cloud | ✅ |
+| 4 | Entity Extraction | DeepSeek-V3.2 671B | Ollama Cloud | ✅ |
+| 4 | Graph Reasoning | GLM-5.1 | Ollama Cloud | ✅ |
+| 5 | Multi-Agent Orchestration | Nemotron-3-Super 120B | NVIDIA NIM | ✅ Free credits |
+| 5 | Tool-Use Coding | Qwen3.6-Coder-Next 480B | Ollama Cloud | ✅ |
+
+**Total infrastructure cost: $0/month** (all on free tiers)
+
+---
+
+## Implementation Roadmap
+
+### Phase 1: Foundation (Already Done ✅)
+- [x] SVO extraction pipeline
+- [x] Dual calendar storage (PostgreSQL + pgvector)
+- [x] Hybrid query (semantic + temporal + entity)
+- [x] Tenant isolation
+- [x] API key billing system
+
+### Phase 2: The Sleep Cycle (1-2 weeks)
+- [ ] Background consolidation job (cron or scheduled task)
+- [ ] Insight generation endpoint
+- [ ] Decay scoring for event relevance
+- [ ] `GET /memory/insights` API
+
+### Phase 3: Predictive Brain (2-3 weeks)
+- [ ] Pattern detection pipeline
+- [ ] Anomaly alerting system
+- [ ] `POST /brain/predict` API
+- [ ] Ollama Cloud integration for GLM-5.1
+
+### Phase 4: Multi-Modal Ingestion (2-3 weeks)
+- [ ] Image/screenshot → SVO pipeline
+- [ ] PDF/document parser
+- [ ] `POST /ingest/multimodal` API
+- [ ] Kimi-K2.5 / Gemma 4 integration
+
+### Phase 5: Knowledge Graph (3-4 weeks)
+- [ ] Entity relationship extraction
+- [ ] Graph database layer (or PostgreSQL recursive CTEs)
+- [ ] `GET /brain/graph` + `POST /brain/reason` APIs
+- [ ] DeepSeek-V3.2 integration
+
+### Phase 6: Autonomous Actions (4-6 weeks)
+- [ ] Action planning from memory + predictions
+- [ ] Multi-agent spawning
+- [ ] Outcome tracking & learning loop
+- [ ] `POST /brain/act` API
+
+---
+
+## The Pitch (One Sentence)
+
+> **"Chronos OS is the first AI infrastructure that doesn't just store memories — it consolidates them like sleep, predicts futures from patterns, sees through images, connects knowledge into graphs, and acts autonomously. It is the temporal brain that every AI agent in the world is missing."**
+
+---
+
+## Why No One Can Copy This
+
+1. **Network effect**: Every tenant's usage makes the system smarter at extraction and prediction
+2. **Temporal moat**: The longer someone uses Chronos, the more irreplaceable it becomes (months/years of structured temporal memory)
+3. **Free compute**: By aggregating free tiers from 4+ providers, you get frontier-level AI at $0 — competitors paying for GPT-4o can't match your margins
+4. **Research foundation**: Built on the actual Chronos paper (arXiv 2603.16862) — not a toy wrapper
+
+---
+
+*This is the letter to the future that the big labs haven't written yet.*
+*Let's write it.* 🕰️

docs/design.md

@@ -0,0 +1,25 @@
+DESIGN SYSTEM — Each article uses a distinct aesthetic
+
+**Rule:** Every article has a unique font pair, color palette, and layout. Never repeat. Rotate between light/dark themes.
+
+**Used so far:**
+- Dark/gold, Forest green, Plum, Black+yellow, Ochre/concrete
+- Swiss white+red, Burgundy+cream, Brutalist lime+black, Navy+gold
+- Dark amber candlelight, Sage+linen, Rose+midnight, Stone+copper
+
+**Available for upcoming:** Teal, terracotta, deep emerald, arctic blue, warm charcoal, dusty lavender, burnt orange, ice white
+
+**Font pairs used:**
+- Spectral + Syne, Instrument Serif + Sans, EB Garamond + Figtree
+- Playfair Display + Barlow, Cardo + Mulish, Italiana + Jost
+- Playfair + Lato, Big Shoulders + IBM Plex Mono, Crimson Pro + DM Sans
+- Cinzel + Gentium Plus, Cormorant + Karla, Abril Fatface + Nunito
+- IM Fell English + Raleway
+
+---
+
+## ARTICLE CTA PHILOSOPHY
+- No pricing mention, no "free", no "coming soon"
+- Each CTA continues the article's voice
+- Always ends with a sealed/lock metaphor
+- Button text: "Open CHRONOS"

docs/error.txt

@@ -0,0 +1,825 @@
+===== Application Startup at 2026-04-20 19:16:52 =====
+
+>>> SVO PARSER v9 LOADED — _extract_json active <<<
+INFO:     Started server process [1]
+INFO:     Waiting for application startup.
+2026-04-20 19:17:49,475 | chronos.api | INFO | 🕰️  Chronos OS starting up...
+2026-04-20 19:17:52,762 | chronos.memory_store | INFO | Memory store initialized (Neon PostgreSQL)
+2026-04-20 19:17:53,191 | chronos.vector_store | INFO | Vector store initialized (pgvector 384d)
+2026-04-20 19:17:56,114 | chronos.svo_parser | INFO | SVO parser initialized with fast pipeline: groq/llama-3.1-8b-instant
+2026-04-20 19:17:56,114 | chronos.api | INFO | ✅ Chronos OS ready — Systems online
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://0.0.0.0:7860 (Press CTRL+C to quit)
+INFO:     10.16.24.44:53206 - "GET /?logs=container HTTP/1.1" 200 OK
+INFO:     10.16.44.111:5417 - "GET /?logs=container HTTP/1.1" 200 OK
+2026-04-20 19:17:58,345 | sentence_transformers.base.model | INFO | No device provided, using cpu
+2026-04-20 19:17:58,368 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/modules.json "HTTP/1.1 307 Temporary Redirect"
+2026-04-20 19:17:58,375 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/modules.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:58,384 | httpx | INFO | HTTP Request: GET https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/modules.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:58,392 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/config_sentence_transformers.json "HTTP/1.1 307 Temporary Redirect"
+2026-04-20 19:17:58,398 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/config_sentence_transformers.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:58,406 | httpx | INFO | HTTP Request: GET https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/config_sentence_transformers.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:58,407 | sentence_transformers.base.model | INFO | Loading SentenceTransformer model from sentence-transformers/all-MiniLM-L6-v2.
+2026-04-20 19:17:58,415 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/config_sentence_transformers.json "HTTP/1.1 307 Temporary Redirect"
+2026-04-20 19:17:58,425 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/config_sentence_transformers.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:58,432 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/README.md "HTTP/1.1 307 Temporary Redirect"
+Warning: You are sending unauthenticated requests to the HF Hub. Please set a HF_TOKEN to enable higher rate limits and faster downloads.
+2026-04-20 19:17:58,432 | huggingface_hub.utils._http | WARNING | Warning: You are sending unauthenticated requests to the HF Hub. Please set a HF_TOKEN to enable higher rate limits and faster downloads.
+2026-04-20 19:17:58,438 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/README.md "HTTP/1.1 200 OK"
+2026-04-20 19:17:58,447 | httpx | INFO | HTTP Request: GET https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/README.md "HTTP/1.1 200 OK"
+2026-04-20 19:17:58,454 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/modules.json "HTTP/1.1 307 Temporary Redirect"
+2026-04-20 19:17:58,459 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/modules.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:58,466 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/sentence_bert_config.json "HTTP/1.1 307 Temporary Redirect"
+2026-04-20 19:17:58,471 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/sentence_bert_config.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:58,478 | httpx | INFO | HTTP Request: GET https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/sentence_bert_config.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:58,487 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/adapter_config.json "HTTP/1.1 404 Not Found"
+2026-04-20 19:17:58,495 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/config.json "HTTP/1.1 307 Temporary Redirect"
+2026-04-20 19:17:58,501 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/config.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:58,508 | httpx | INFO | HTTP Request: GET https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/config.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:58,556 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/model.safetensors "HTTP/1.1 302 Found"
+2026-04-20 19:17:58,572 | httpx | INFO | HTTP Request: GET https://huggingface.co/api/models/sentence-transformers/all-MiniLM-L6-v2/xet-read-token/c9745ed1d9f207416be6d2e6f8de32d1f16199bf "HTTP/1.1 200 OK"
+Loading weights:   0%|          | 0/103 [00:00<?, ?it/s]
+Loading weights: 100%|██████████| 103/103 [00:00<00:00, 4758.33it/s]
+BertModel LOAD REPORT from: sentence-transformers/all-MiniLM-L6-v2
+Key                     | Status     |  | 
+------------------------+------------+--+-
+embeddings.position_ids | UNEXPECTED |  | 
+
+Notes:
+- UNEXPECTED:	can be ignored when loading from different task/architecture; not ok if you expect identical arch.
+2026-04-20 19:17:59,792 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/processor_config.json "HTTP/1.1 404 Not Found"
+2026-04-20 19:17:59,801 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/preprocessor_config.json "HTTP/1.1 404 Not Found"
+2026-04-20 19:17:59,810 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/video_preprocessor_config.json "HTTP/1.1 404 Not Found"
+2026-04-20 19:17:59,818 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/preprocessor_config.json "HTTP/1.1 404 Not Found"
+2026-04-20 19:17:59,824 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer_config.json "HTTP/1.1 307 Temporary Redirect"
+2026-04-20 19:17:59,830 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/tokenizer_config.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:59,839 | httpx | INFO | HTTP Request: GET https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/tokenizer_config.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:59,850 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/config.json "HTTP/1.1 307 Temporary Redirect"
+2026-04-20 19:17:59,856 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/config.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:59,877 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/config.json "HTTP/1.1 307 Temporary Redirect"
+2026-04-20 19:17:59,883 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/config.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:59,891 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer_config.json "HTTP/1.1 307 Temporary Redirect"
+2026-04-20 19:17:59,896 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/tokenizer_config.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:59,905 | httpx | INFO | HTTP Request: GET https://huggingface.co/api/models/sentence-transformers/all-MiniLM-L6-v2/tree/main/additional_chat_templates?recursive=false&expand=false "HTTP/1.1 404 Not Found"
+2026-04-20 19:17:59,923 | httpx | INFO | HTTP Request: GET https://huggingface.co/api/models/sentence-transformers/all-MiniLM-L6-v2/tree/main?recursive=true&expand=false "HTTP/1.1 200 OK"
+2026-04-20 19:17:59,933 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/vocab.txt "HTTP/1.1 307 Temporary Redirect"
+2026-04-20 19:17:59,939 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/vocab.txt "HTTP/1.1 200 OK"
+2026-04-20 19:17:59,948 | httpx | INFO | HTTP Request: GET https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/vocab.txt "HTTP/1.1 200 OK"
+2026-04-20 19:17:59,959 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json "HTTP/1.1 307 Temporary Redirect"
+2026-04-20 19:17:59,965 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/tokenizer.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:59,974 | httpx | INFO | HTTP Request: GET https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/tokenizer.json "HTTP/1.1 200 OK"
+2026-04-20 19:17:59,994 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/added_tokens.json "HTTP/1.1 404 Not Found"
+2026-04-20 19:18:00,016 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/special_tokens_map.json "HTTP/1.1 307 Temporary Redirect"
+2026-04-20 19:18:00,032 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/special_tokens_map.json "HTTP/1.1 200 OK"
+2026-04-20 19:18:00,050 | httpx | INFO | HTTP Request: GET https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/special_tokens_map.json "HTTP/1.1 200 OK"
+2026-04-20 19:18:00,061 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/chat_template.jinja "HTTP/1.1 404 Not Found"
+2026-04-20 19:18:00,105 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/1_Pooling/config.json "HTTP/1.1 307 Temporary Redirect"
+2026-04-20 19:18:00,111 | httpx | INFO | HTTP Request: HEAD https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/1_Pooling%2Fconfig.json "HTTP/1.1 200 OK"
+2026-04-20 19:18:00,118 | httpx | INFO | HTTP Request: GET https://huggingface.co/api/resolve-cache/models/sentence-transformers/all-MiniLM-L6-v2/c9745ed1d9f207416be6d2e6f8de32d1f16199bf/1_Pooling%2Fconfig.json "HTTP/1.1 200 OK"
+2026-04-20 19:18:00,129 | httpx | INFO | HTTP Request: GET https://huggingface.co/api/models/sentence-transformers/all-MiniLM-L6-v2 "HTTP/1.1 200 OK"
+2026-04-20 19:18:00,136 | chronos.vector_store | INFO | Embedding model loaded: all-MiniLM-L6-v2
+2026-04-20 19:18:20,846 | chronos.svo_parser | INFO | [DEBUG] Calling litellm.acompletion attempt 1...
+19:18:20 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+2026-04-20 19:18:20,858 | LiteLLM | INFO | 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+
+Give Feedback / Get Help: https://github.com/BerriAI/litellm/issues/new
+LiteLLM.Info: If you need to debug this error, use `litellm._turn_on_debug()'.
+
+19:18:21 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+2026-04-20 19:18:21,071 | LiteLLM | INFO | 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+
+Give Feedback / Get Help: https://github.com/BerriAI/litellm/issues/new
+LiteLLM.Info: If you need to debug this error, use `litellm._turn_on_debug()'.
+
+19:18:21 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+2026-04-20 19:18:21,088 | LiteLLM | INFO | 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+
+Give Feedback / Get Help: https://github.com/BerriAI/litellm/issues/new
+LiteLLM.Info: If you need to debug this error, use `litellm._turn_on_debug()'.
+
+19:18:21 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+2026-04-20 19:18:21,104 | LiteLLM | INFO | 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+
+Give Feedback / Get Help: https://github.com/BerriAI/litellm/issues/new
+LiteLLM.Info: If you need to debug this error, use `litellm._turn_on_debug()'.
+
+19:18:21 - LiteLLM:ERROR: fallback_utils.py:68 - Fallback attempt failed for model groq/llama-3.1-8b-instant: litellm.InternalServerError: InternalServerError: GroqException - Newline, carriage return, or null byte detected in headers. Potential header injection attack. LiteLLM Retried: 3 times
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 176, in _make_common_async_call
+    response = await async_httpx_client.post(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/logging_utils.py", line 297, in async_wrapper
+    result = await func(*args, **kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/http_handler.py", line 515, in post
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/http_handler.py", line 468, in post
+    response = await self.client.send(req, stream=stream)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1629, in send
+    response = await self._send_handling_auth(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1657, in _send_handling_auth
+    response = await self._send_handling_redirects(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1694, in _send_handling_redirects
+    response = await self._send_single_request(request)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1730, in _send_single_request
+    response = await transport.handle_async_request(request)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/aiohttp_transport.py", line 307, in handle_async_request
+    response = await self._make_aiohttp_request(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/aiohttp_transport.py", line 285, in _make_aiohttp_request
+    response = await client_session.request(**request_kwargs).__aenter__()
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 1521, in __aenter__
+    self._resp: _RetType = await self._coro
+                           ^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 788, in _request
+    resp = await handler(req)
+           ^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 764, in _connect_and_send_request
+    resp = await req.send(conn)
+           ^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client_reqrep.py", line 1470, in send
+    await writer.write_headers(status_line, self.headers)
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/http_writer.py", line 217, in write_headers
+    buf = _serialize_headers(status_line, headers)
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "aiohttp/_http_writer.pyx", line 148, in aiohttp._http_writer._serialize_headers
+  File "aiohttp/_http_writer.pyx", line 115, in aiohttp._http_writer._write_str_raise_on_nlcr
+ValueError: Newline, carriage return, or null byte detected in headers. Potential header injection attack.
+
+During handling of the above exception, another exception occurred:
+
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/main.py", line 620, in acompletion
+    response = await init_response
+               ^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 308, in async_completion
+    response = await self._make_common_async_call(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 203, in _make_common_async_call
+    raise self._handle_error(e=e, provider_config=provider_config)
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 4721, in _handle_error
+    raise provider_config.get_error_class(
+litellm.llms.openai.common_utils.OpenAIError: Newline, carriage return, or null byte detected in headers. Potential header injection attack.
+
+During handling of the above exception, another exception occurred:
+
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/fallback_utils.py", line 58, in async_completion_with_fallbacks
+    response = await litellm.acompletion(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/utils.py", line 2093, in wrapper_async
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/utils.py", line 1892, in wrapper_async
+    result = await original_function(*args, **kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/main.py", line 639, in acompletion
+    raise exception_type(
+          ^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/exception_mapping_utils.py", line 2456, in exception_type
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/exception_mapping_utils.py", line 588, in exception_type
+    raise InternalServerError(
+litellm.exceptions.InternalServerError: litellm.InternalServerError: InternalServerError: GroqException - Newline, carriage return, or null byte detected in headers. Potential header injection attack. LiteLLM Retried: 3 times
+2026-04-20 19:18:21,115 | LiteLLM | ERROR | Fallback attempt failed for model groq/llama-3.1-8b-instant: litellm.InternalServerError: InternalServerError: GroqException - Newline, carriage return, or null byte detected in headers. Potential header injection attack. LiteLLM Retried: 3 times
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 176, in _make_common_async_call
+    response = await async_httpx_client.post(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/logging_utils.py", line 297, in async_wrapper
+    result = await func(*args, **kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/http_handler.py", line 515, in post
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/http_handler.py", line 468, in post
+    response = await self.client.send(req, stream=stream)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1629, in send
+    response = await self._send_handling_auth(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1657, in _send_handling_auth
+    response = await self._send_handling_redirects(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1694, in _send_handling_redirects
+    response = await self._send_single_request(request)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1730, in _send_single_request
+    response = await transport.handle_async_request(request)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/aiohttp_transport.py", line 307, in handle_async_request
+    response = await self._make_aiohttp_request(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/aiohttp_transport.py", line 285, in _make_aiohttp_request
+    response = await client_session.request(**request_kwargs).__aenter__()
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 1521, in __aenter__
+    self._resp: _RetType = await self._coro
+                           ^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 788, in _request
+    resp = await handler(req)
+           ^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 764, in _connect_and_send_request
+    resp = await req.send(conn)
+           ^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client_reqrep.py", line 1470, in send
+    await writer.write_headers(status_line, self.headers)
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/http_writer.py", line 217, in write_headers
+    buf = _serialize_headers(status_line, headers)
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "aiohttp/_http_writer.pyx", line 148, in aiohttp._http_writer._serialize_headers
+  File "aiohttp/_http_writer.pyx", line 115, in aiohttp._http_writer._write_str_raise_on_nlcr
+ValueError: Newline, carriage return, or null byte detected in headers. Potential header injection attack.
+
+During handling of the above exception, another exception occurred:
+
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/main.py", line 620, in acompletion
+    response = await init_response
+               ^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 308, in async_completion
+    response = await self._make_common_async_call(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 203, in _make_common_async_call
+    raise self._handle_error(e=e, provider_config=provider_config)
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 4721, in _handle_error
+    raise provider_config.get_error_class(
+litellm.llms.openai.common_utils.OpenAIError: Newline, carriage return, or null byte detected in headers. Potential header injection attack.
+
+During handling of the above exception, another exception occurred:
+
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/fallback_utils.py", line 58, in async_completion_with_fallbacks
+    response = await litellm.acompletion(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/utils.py", line 2093, in wrapper_async
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/utils.py", line 1892, in wrapper_async
+    result = await original_function(*args, **kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/main.py", line 639, in acompletion
+    raise exception_type(
+          ^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/exception_mapping_utils.py", line 2456, in exception_type
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/exception_mapping_utils.py", line 588, in exception_type
+    raise InternalServerError(
+litellm.exceptions.InternalServerError: litellm.InternalServerError: InternalServerError: GroqException - Newline, carriage return, or null byte detected in headers. Potential header injection attack. LiteLLM Retried: 3 times
+19:18:21 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama3.1-8b; provider = cerebras
+2026-04-20 19:18:21,123 | LiteLLM | INFO | 
+LiteLLM completion() model= llama3.1-8b; provider = cerebras
+2026-04-20 19:18:21,543 | chronos.svo_parser | INFO | [DEBUG] Response received. Type: <class 'litellm.types.utils.ModelResponse'>
+2026-04-20 19:18:21,543 | chronos.svo_parser | INFO | [DEBUG] Message type: <class 'litellm.types.utils.Message'>, content type: <class 'str'>
+2026-04-20 19:18:21,543 | chronos.svo_parser | INFO | [DEBUG] Content repr: '[\n  {\n    "subject": "I",\n    "verb": "scheduled",\n    "object": "a marketing activity",\n    "timestamp": "2026-04-20T19:18:14.891000+00:00",\n    "datetime_start": "2026-04-20T22:30:00+00:00",\
+2026-04-20 19:18:21,543 | chronos.svo_parser | INFO | [DEBUG] Calling _extract_json with 531 chars
+2026-04-20 19:18:21,543 | chronos.svo_parser | INFO | _extract_json called with 531 chars: [
+  {
+    "subject": "I",
+    "verb": "scheduled",
+    "object": "a marketing ac...
+2026-04-20 19:18:21,543 | chronos.svo_parser | INFO | [DEBUG] _extract_json returned type: <class 'list'>
+2026-04-20 19:18:21,543 | chronos.svo_parser | INFO | Fast Pipeline (groq/llama-3.1-8b-instant) extracted 2 SVO tuples from text (112 chars)
+2026-04-20 19:18:21,717 | chronos.svo_parser | INFO | [DEBUG] Calling litellm.acompletion attempt 1...
+19:18:21 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+2026-04-20 19:18:21,719 | LiteLLM | INFO | 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+
+Give Feedback / Get Help: https://github.com/BerriAI/litellm/issues/new
+LiteLLM.Info: If you need to debug this error, use `litellm._turn_on_debug()'.
+
+19:18:21 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+2026-04-20 19:18:21,737 | LiteLLM | INFO | 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+
+Give Feedback / Get Help: https://github.com/BerriAI/litellm/issues/new
+LiteLLM.Info: If you need to debug this error, use `litellm._turn_on_debug()'.
+
+19:18:21 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+2026-04-20 19:18:21,749 | LiteLLM | INFO | 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+
+Give Feedback / Get Help: https://github.com/BerriAI/litellm/issues/new
+LiteLLM.Info: If you need to debug this error, use `litellm._turn_on_debug()'.
+
+19:18:21 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+2026-04-20 19:18:21,761 | LiteLLM | INFO | 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+
+Give Feedback / Get Help: https://github.com/BerriAI/litellm/issues/new
+LiteLLM.Info: If you need to debug this error, use `litellm._turn_on_debug()'.
+
+19:18:21 - LiteLLM:ERROR: fallback_utils.py:68 - Fallback attempt failed for model groq/llama-3.1-8b-instant: litellm.InternalServerError: InternalServerError: GroqException - Newline, carriage return, or null byte detected in headers. Potential header injection attack. LiteLLM Retried: 3 times
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 176, in _make_common_async_call
+    response = await async_httpx_client.post(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/logging_utils.py", line 297, in async_wrapper
+    result = await func(*args, **kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/http_handler.py", line 515, in post
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/http_handler.py", line 468, in post
+    response = await self.client.send(req, stream=stream)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1629, in send
+    response = await self._send_handling_auth(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1657, in _send_handling_auth
+    response = await self._send_handling_redirects(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1694, in _send_handling_redirects
+    response = await self._send_single_request(request)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1730, in _send_single_request
+    response = await transport.handle_async_request(request)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/aiohttp_transport.py", line 307, in handle_async_request
+    response = await self._make_aiohttp_request(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/aiohttp_transport.py", line 285, in _make_aiohttp_request
+    response = await client_session.request(**request_kwargs).__aenter__()
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 1521, in __aenter__
+    self._resp: _RetType = await self._coro
+                           ^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 788, in _request
+    resp = await handler(req)
+           ^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 764, in _connect_and_send_request
+    resp = await req.send(conn)
+           ^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client_reqrep.py", line 1470, in send
+    await writer.write_headers(status_line, self.headers)
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/http_writer.py", line 217, in write_headers
+    buf = _serialize_headers(status_line, headers)
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "aiohttp/_http_writer.pyx", line 148, in aiohttp._http_writer._serialize_headers
+  File "aiohttp/_http_writer.pyx", line 115, in aiohttp._http_writer._write_str_raise_on_nlcr
+ValueError: Newline, carriage return, or null byte detected in headers. Potential header injection attack.
+
+During handling of the above exception, another exception occurred:
+
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/main.py", line 620, in acompletion
+    response = await init_response
+               ^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 308, in async_completion
+    response = await self._make_common_async_call(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 203, in _make_common_async_call
+    raise self._handle_error(e=e, provider_config=provider_config)
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 4721, in _handle_error
+    raise provider_config.get_error_class(
+litellm.llms.openai.common_utils.OpenAIError: Newline, carriage return, or null byte detected in headers. Potential header injection attack.
+
+During handling of the above exception, another exception occurred:
+
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/fallback_utils.py", line 58, in async_completion_with_fallbacks
+    response = await litellm.acompletion(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/utils.py", line 2093, in wrapper_async
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/utils.py", line 1892, in wrapper_async
+    result = await original_function(*args, **kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/main.py", line 639, in acompletion
+    raise exception_type(
+          ^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/exception_mapping_utils.py", line 2456, in exception_type
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/exception_mapping_utils.py", line 588, in exception_type
+    raise InternalServerError(
+litellm.exceptions.InternalServerError: litellm.InternalServerError: InternalServerError: GroqException - Newline, carriage return, or null byte detected in headers. Potential header injection attack. LiteLLM Retried: 3 times
+2026-04-20 19:18:21,771 | LiteLLM | ERROR | Fallback attempt failed for model groq/llama-3.1-8b-instant: litellm.InternalServerError: InternalServerError: GroqException - Newline, carriage return, or null byte detected in headers. Potential header injection attack. LiteLLM Retried: 3 times
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 176, in _make_common_async_call
+    response = await async_httpx_client.post(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/logging_utils.py", line 297, in async_wrapper
+    result = await func(*args, **kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/http_handler.py", line 515, in post
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/http_handler.py", line 468, in post
+    response = await self.client.send(req, stream=stream)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1629, in send
+    response = await self._send_handling_auth(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1657, in _send_handling_auth
+    response = await self._send_handling_redirects(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1694, in _send_handling_redirects
+    response = await self._send_single_request(request)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1730, in _send_single_request
+    response = await transport.handle_async_request(request)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/aiohttp_transport.py", line 307, in handle_async_request
+    response = await self._make_aiohttp_request(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/aiohttp_transport.py", line 285, in _make_aiohttp_request
+    response = await client_session.request(**request_kwargs).__aenter__()
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 1521, in __aenter__
+    self._resp: _RetType = await self._coro
+                           ^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 788, in _request
+    resp = await handler(req)
+           ^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 764, in _connect_and_send_request
+    resp = await req.send(conn)
+           ^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client_reqrep.py", line 1470, in send
+    await writer.write_headers(status_line, self.headers)
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/http_writer.py", line 217, in write_headers
+    buf = _serialize_headers(status_line, headers)
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "aiohttp/_http_writer.pyx", line 148, in aiohttp._http_writer._serialize_headers
+  File "aiohttp/_http_writer.pyx", line 115, in aiohttp._http_writer._write_str_raise_on_nlcr
+ValueError: Newline, carriage return, or null byte detected in headers. Potential header injection attack.
+
+During handling of the above exception, another exception occurred:
+
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/main.py", line 620, in acompletion
+    response = await init_response
+               ^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 308, in async_completion
+    response = await self._make_common_async_call(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 203, in _make_common_async_call
+    raise self._handle_error(e=e, provider_config=provider_config)
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 4721, in _handle_error
+    raise provider_config.get_error_class(
+litellm.llms.openai.common_utils.OpenAIError: Newline, carriage return, or null byte detected in headers. Potential header injection attack.
+
+During handling of the above exception, another exception occurred:
+
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/fallback_utils.py", line 58, in async_completion_with_fallbacks
+    response = await litellm.acompletion(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/utils.py", line 2093, in wrapper_async
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/utils.py", line 1892, in wrapper_async
+    result = await original_function(*args, **kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/main.py", line 639, in acompletion
+    raise exception_type(
+          ^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/exception_mapping_utils.py", line 2456, in exception_type
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/exception_mapping_utils.py", line 588, in exception_type
+    raise InternalServerError(
+litellm.exceptions.InternalServerError: litellm.InternalServerError: InternalServerError: GroqException - Newline, carriage return, or null byte detected in headers. Potential header injection attack. LiteLLM Retried: 3 times
+19:18:21 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama3.1-8b; provider = cerebras
+2026-04-20 19:18:21,777 | LiteLLM | INFO | 
+LiteLLM completion() model= llama3.1-8b; provider = cerebras
+2026-04-20 19:18:22,078 | chronos.svo_parser | INFO | [DEBUG] Response received. Type: <class 'litellm.types.utils.ModelResponse'>
+2026-04-20 19:18:22,078 | chronos.svo_parser | INFO | [DEBUG] Message type: <class 'litellm.types.utils.Message'>, content type: <class 'str'>
+2026-04-20 19:18:22,078 | chronos.svo_parser | INFO | [DEBUG] Content repr: '[\n  {\n    "subject": "I",\n    "verb": "posted",\n    "object": "a marketing activity",\n    "timestamp": "2026-04-20T19:18:17.239000+00:00",\n    "datetime_start": "2026-04-20T19:18:17.239000+00:0
+2026-04-20 19:18:22,079 | chronos.svo_parser | INFO | [DEBUG] Calling _extract_json with 867 chars
+2026-04-20 19:18:22,079 | chronos.svo_parser | INFO | _extract_json called with 867 chars: [
+  {
+    "subject": "I",
+    "verb": "posted",
+    "object": "a marketing activ...
+2026-04-20 19:18:22,079 | chronos.svo_parser | INFO | [DEBUG] _extract_json returned type: <class 'list'>
+2026-04-20 19:18:22,079 | chronos.svo_parser | INFO | Fast Pipeline (groq/llama-3.1-8b-instant) extracted 3 SVO tuples from text (109 chars)
+Batches:   0%|          | 0/1 [00:00<?, ?it/s]
+Batches: 100%|██████████| 1/1 [00:00<00:00, 41.88it/s]
+2026-04-20 19:18:22,689 | chronos.svo_parser | INFO | [DEBUG] Calling litellm.acompletion attempt 1...
+19:18:22 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+2026-04-20 19:18:22,691 | LiteLLM | INFO | 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+
+Give Feedback / Get Help: https://github.com/BerriAI/litellm/issues/new
+LiteLLM.Info: If you need to debug this error, use `litellm._turn_on_debug()'.
+
+19:18:22 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+2026-04-20 19:18:22,709 | LiteLLM | INFO | 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+
+Give Feedback / Get Help: https://github.com/BerriAI/litellm/issues/new
+LiteLLM.Info: If you need to debug this error, use `litellm._turn_on_debug()'.
+
+19:18:22 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+2026-04-20 19:18:22,724 | LiteLLM | INFO | 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+
+Give Feedback / Get Help: https://github.com/BerriAI/litellm/issues/new
+LiteLLM.Info: If you need to debug this error, use `litellm._turn_on_debug()'.
+
+19:18:22 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+2026-04-20 19:18:22,735 | LiteLLM | INFO | 
+LiteLLM completion() model= llama-3.1-8b-instant; provider = groq
+
+Give Feedback / Get Help: https://github.com/BerriAI/litellm/issues/new
+LiteLLM.Info: If you need to debug this error, use `litellm._turn_on_debug()'.
+
+19:18:22 - LiteLLM:ERROR: fallback_utils.py:68 - Fallback attempt failed for model groq/llama-3.1-8b-instant: litellm.InternalServerError: InternalServerError: GroqException - Newline, carriage return, or null byte detected in headers. Potential header injection attack. LiteLLM Retried: 3 times
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 176, in _make_common_async_call
+    response = await async_httpx_client.post(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/logging_utils.py", line 297, in async_wrapper
+    result = await func(*args, **kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/http_handler.py", line 515, in post
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/http_handler.py", line 468, in post
+    response = await self.client.send(req, stream=stream)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1629, in send
+    response = await self._send_handling_auth(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1657, in _send_handling_auth
+    response = await self._send_handling_redirects(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1694, in _send_handling_redirects
+    response = await self._send_single_request(request)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1730, in _send_single_request
+    response = await transport.handle_async_request(request)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/aiohttp_transport.py", line 307, in handle_async_request
+    response = await self._make_aiohttp_request(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/aiohttp_transport.py", line 285, in _make_aiohttp_request
+    response = await client_session.request(**request_kwargs).__aenter__()
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 1521, in __aenter__
+    self._resp: _RetType = await self._coro
+                           ^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 788, in _request
+    resp = await handler(req)
+           ^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 764, in _connect_and_send_request
+    resp = await req.send(conn)
+           ^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client_reqrep.py", line 1470, in send
+    await writer.write_headers(status_line, self.headers)
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/http_writer.py", line 217, in write_headers
+    buf = _serialize_headers(status_line, headers)
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "aiohttp/_http_writer.pyx", line 148, in aiohttp._http_writer._serialize_headers
+  File "aiohttp/_http_writer.pyx", line 115, in aiohttp._http_writer._write_str_raise_on_nlcr
+ValueError: Newline, carriage return, or null byte detected in headers. Potential header injection attack.
+
+During handling of the above exception, another exception occurred:
+
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/main.py", line 620, in acompletion
+    response = await init_response
+               ^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 308, in async_completion
+    response = await self._make_common_async_call(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 203, in _make_common_async_call
+    raise self._handle_error(e=e, provider_config=provider_config)
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 4721, in _handle_error
+    raise provider_config.get_error_class(
+litellm.llms.openai.common_utils.OpenAIError: Newline, carriage return, or null byte detected in headers. Potential header injection attack.
+
+During handling of the above exception, another exception occurred:
+
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/fallback_utils.py", line 58, in async_completion_with_fallbacks
+    response = await litellm.acompletion(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/utils.py", line 2093, in wrapper_async
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/utils.py", line 1892, in wrapper_async
+    result = await original_function(*args, **kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/main.py", line 639, in acompletion
+    raise exception_type(
+          ^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/exception_mapping_utils.py", line 2456, in exception_type
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/exception_mapping_utils.py", line 588, in exception_type
+    raise InternalServerError(
+litellm.exceptions.InternalServerError: litellm.InternalServerError: InternalServerError: GroqException - Newline, carriage return, or null byte detected in headers. Potential header injection attack. LiteLLM Retried: 3 times
+2026-04-20 19:18:22,744 | LiteLLM | ERROR | Fallback attempt failed for model groq/llama-3.1-8b-instant: litellm.InternalServerError: InternalServerError: GroqException - Newline, carriage return, or null byte detected in headers. Potential header injection attack. LiteLLM Retried: 3 times
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 176, in _make_common_async_call
+    response = await async_httpx_client.post(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/logging_utils.py", line 297, in async_wrapper
+    result = await func(*args, **kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/http_handler.py", line 515, in post
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/http_handler.py", line 468, in post
+    response = await self.client.send(req, stream=stream)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1629, in send
+    response = await self._send_handling_auth(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1657, in _send_handling_auth
+    response = await self._send_handling_redirects(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1694, in _send_handling_redirects
+    response = await self._send_single_request(request)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/httpx/_client.py", line 1730, in _send_single_request
+    response = await transport.handle_async_request(request)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/aiohttp_transport.py", line 307, in handle_async_request
+    response = await self._make_aiohttp_request(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/aiohttp_transport.py", line 285, in _make_aiohttp_request
+    response = await client_session.request(**request_kwargs).__aenter__()
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 1521, in __aenter__
+    self._resp: _RetType = await self._coro
+                           ^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 788, in _request
+    resp = await handler(req)
+           ^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client.py", line 764, in _connect_and_send_request
+    resp = await req.send(conn)
+           ^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/client_reqrep.py", line 1470, in send
+    await writer.write_headers(status_line, self.headers)
+  File "/home/user/.local/lib/python3.11/site-packages/aiohttp/http_writer.py", line 217, in write_headers
+    buf = _serialize_headers(status_line, headers)
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "aiohttp/_http_writer.pyx", line 148, in aiohttp._http_writer._serialize_headers
+  File "aiohttp/_http_writer.pyx", line 115, in aiohttp._http_writer._write_str_raise_on_nlcr
+ValueError: Newline, carriage return, or null byte detected in headers. Potential header injection attack.
+
+During handling of the above exception, another exception occurred:
+
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/main.py", line 620, in acompletion
+    response = await init_response
+               ^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 308, in async_completion
+    response = await self._make_common_async_call(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 203, in _make_common_async_call
+    raise self._handle_error(e=e, provider_config=provider_config)
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 4721, in _handle_error
+    raise provider_config.get_error_class(
+litellm.llms.openai.common_utils.OpenAIError: Newline, carriage return, or null byte detected in headers. Potential header injection attack.
+
+During handling of the above exception, another exception occurred:
+
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/fallback_utils.py", line 58, in async_completion_with_fallbacks
+    response = await litellm.acompletion(
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/utils.py", line 2093, in wrapper_async
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/utils.py", line 1892, in wrapper_async
+    result = await original_function(*args, **kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/main.py", line 639, in acompletion
+    raise exception_type(
+          ^^^^^^^^^^^^^^^
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/exception_mapping_utils.py", line 2456, in exception_type
+    raise e
+  File "/home/user/.local/lib/python3.11/site-packages/litellm/litellm_core_utils/exception_mapping_utils.py", line 588, in exception_type
+    raise InternalServerError(
+litellm.exceptions.InternalServerError: litellm.InternalServerError: InternalServerError: GroqException - Newline, carriage return, or null byte detected in headers. Potential header injection attack. LiteLLM Retried: 3 times
+19:18:22 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= llama3.1-8b; provider = cerebras
+2026-04-20 19:18:22,751 | LiteLLM | INFO | 
+LiteLLM completion() model= llama3.1-8b; provider = cerebras
+2026-04-20 19:18:22,975 | chronos.svo_parser | INFO | [DEBUG] Response received. Type: <class 'litellm.types.utils.ModelResponse'>
+2026-04-20 19:18:22,975 | chronos.svo_parser | INFO | [DEBUG] Message type: <class 'litellm.types.utils.Message'>, content type: <class 'str'>
+2026-04-20 19:18:22,975 | chronos.svo_parser | INFO | [DEBUG] Content repr: '[\n  {\n    "subject": "I",\n    "verb": "drafted",\n    "object": "a marketing activity",\n    "timestamp": "2026-04-20T19:18:19.593000+00:00",\n    "datetime_start": null,\n    "datetime_end": null
+2026-04-20 19:18:22,975 | chronos.svo_parser | INFO | [DEBUG] Calling _extract_json with 503 chars
+2026-04-20 19:18:22,975 | chronos.svo_parser | INFO | _extract_json called with 503 chars: [
+  {
+    "subject": "I",
+    "verb": "drafted",
+    "object": "a marketing acti...
+2026-04-20 19:18:22,975 | chronos.svo_parser | INFO | [DEBUG] _extract_json returned type: <class 'list'>
+2026-04-20 19:18:22,975 | chronos.svo_parser | INFO | Fast Pipeline (groq/llama-3.1-8b-instant) extracted 2 SVO tuples from text (110 chars)
+Batches:   0%|          | 0/1 [00:00<?, ?it/s]
+Batches: 100%|██████████| 1/1 [00:00<00:00, 52.62it/s]
+Batches:   0%|          | 0/1 [00:00<?, ?it/s]
+Batches: 100%|██████████| 1/1 [00:00<00:00, 40.98it/s]
+2026-04-20 19:18:24,705 | chronos.vector_store | INFO | Batch added 2 event vectors to pgvector
+2026-04-20 19:18:25,870 | chronos.vector_store | INFO | Batch added 2 event vectors to pgvector
+2026-04-20 19:18:25,990 | chronos.routes.ingest | INFO | Ingested 2 events + 1 turns for source=marketing-tracker in 7889.7ms
+INFO:     10.16.24.44:57970 - "POST /ingest HTTP/1.1" 200 OK
+2026-04-20 19:18:26,431 | chronos.vector_store | INFO | Batch added 3 event vectors to pgvector
+2026-04-20 19:18:27,159 | chronos.routes.ingest | INFO | Ingested 2 events + 1 turns for source=marketing-tracker in 4899.6ms
+INFO:     10.16.47.45:63351 - "POST /ingest HTTP/1.1" 200 OK
+2026-04-20 19:18:27,764 | chronos.routes.ingest | INFO | Ingested 3 events + 1 turns for source=marketing-tracker in 6476.5ms
+INFO:     10.16.47.45:6065 - "POST /ingest HTTP/1.1" 200 OK
+2026-04-20 19:18:52,927 | chronos.agent.graph | INFO | Chronos agent graph compiled successfully
+Batches:   0%|          | 0/1 [00:00<?, ?it/s]
+Batches: 100%|██████████| 1/1 [00:00<00:00, 110.55it/s]
+2026-04-20 19:18:54,323 | chronos.llm_router | INFO | Heavy pipeline initialized: runnable=ChatLiteLLM(client=<module 'litellm' from '/home/user/.local/lib/python3.11/site-packages/litellm/__init__.py'>, model='cerebras/qwen-3-235b-a22b-instruct-2507', openai_api_key='', azure_api_key='', anthropic_api_key='', replicate_api_key='', cohere_api_key='', openrouter_api_key='', temperature=0.4, model_kwargs={}, max_retries=3) fallbacks=[ChatLiteLLM(client=<module 'litellm' from '/home/user/.local/lib/python3.11/site-packages/litellm/__init__.py'>, model='groq/llama-3.3-70b-versatile', openai_api_key='', azure_api_key='', anthropic_api_key='', replicate_api_key='', cohere_api_key='', openrouter_api_key='', temperature=0.4, model_kwargs={}, max_retries=3)]
+19:18:54 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+2026-04-20 19:18:54,364 | LiteLLM | INFO | 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+Batches:   0%|          | 0/1 [00:00<?, ?it/s]
+Batches: 100%|██████████| 1/1 [00:00<00:00, 117.68it/s]
+2026-04-20 19:18:55,073 | chronos.agent.nodes | ERROR | Tool execution failed: query_chronos_memory — invalid input for query argument $3: '5' ('str' object cannot be interpreted as an integer)
+19:18:55 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+2026-04-20 19:18:55,096 | LiteLLM | INFO | 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+Batches:   0%|          | 0/1 [00:00<?, ?it/s]
+Batches: 100%|██████████| 1/1 [00:00<00:00, 125.68it/s]
+2026-04-20 19:18:55,505 | chronos.agent.nodes | ERROR | Tool execution failed: query_chronos_memory — invalid input for query argument $3: '10' ('str' object cannot be interpreted as an integer)
+19:18:55 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+2026-04-20 19:18:55,526 | LiteLLM | INFO | 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+Batches:   0%|          | 0/1 [00:00<?, ?it/s]
+Batches: 100%|██████████| 1/1 [00:00<00:00, 138.64it/s]
+19:18:56 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+2026-04-20 19:18:56,281 | LiteLLM | INFO | 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+INFO:     10.16.44.111:32873 - "POST /agent/run HTTP/1.1" 200 OK
+INFO:     10.16.44.111:5424 - "GET /health HTTP/1.1" 200 OK
+INFO:     10.16.44.111:5424 - "GET /health HTTP/1.1" 200 OK
+Batches:   0%|          | 0/1 [00:00<?, ?it/s]
+Batches: 100%|██████████| 1/1 [00:00<00:00, 88.53it/s]
+19:19:30 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+2026-04-20 19:19:30,083 | LiteLLM | INFO | 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+Batches:   0%|          | 0/1 [00:00<?, ?it/s]
+Batches: 100%|██████████| 1/1 [00:00<00:00, 108.27it/s]
+19:19:30 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+2026-04-20 19:19:30,731 | LiteLLM | INFO | 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+INFO:     10.16.47.45:42459 - "POST /agent/run HTTP/1.1" 200 OK
+Batches:   0%|          | 0/1 [00:00<?, ?it/s]
+Batches: 100%|██████████| 1/1 [00:00<00:00, 121.03it/s]
+19:19:51 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+2026-04-20 19:19:51,938 | LiteLLM | INFO | 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+INFO:     10.16.47.45:29699 - "POST /agent/run HTTP/1.1" 200 OK
+Batches:   0%|          | 0/1 [00:00<?, ?it/s]
+Batches: 100%|██████████| 1/1 [00:00<00:00, 24.43it/s]
+19:20:54 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+2026-04-20 19:20:54,363 | LiteLLM | INFO | 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+INFO:     10.16.24.44:28058 - "POST /agent/run HTTP/1.1" 200 OK
+Batches:   0%|          | 0/1 [00:00<?, ?it/s]
+Batches: 100%|██████████| 1/1 [00:00<00:00,  6.22it/s]
+Batches: 100%|██████████| 1/1 [00:00<00:00,  6.21it/s]
+19:21:40 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+2026-04-20 19:21:40,264 | LiteLLM | INFO | 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+Batches:   0%|          | 0/1 [00:00<?, ?it/s]
+Batches: 100%|██████████| 1/1 [00:00<00:00, 61.89it/s]
+19:21:40 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+2026-04-20 19:21:40,979 | LiteLLM | INFO | 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+
+Give Feedback / Get Help: https://github.com/BerriAI/litellm/issues/new
+LiteLLM.Info: If you need to debug this error, use `litellm._turn_on_debug()'.
+
+2026-04-20 19:21:41,067 | langchain_core.language_models.llms | WARNING | Retrying langchain_litellm.chat_models.litellm.ChatLiteLLM.acompletion_with_retry.<locals>._completion_with_retry in 4 seconds as it raised RateLimitError: litellm.RateLimitError: RateLimitError: CerebrasException - We're experiencing high traffic right now! Please try again soon..
+19:21:45 - LiteLLM:INFO: utils.py:4007 - 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+2026-04-20 19:21:45,069 | LiteLLM | INFO | 
+LiteLLM completion() model= qwen-3-235b-a22b-instruct-2507; provider = cerebras
+2026-04-20 19:21:45,113 | openai._base_client | INFO | Retrying request to /chat/completions in 60.000000 seconds
+

docs/global_insights_plan.md

@@ -0,0 +1,48 @@
+# Global Insights ("The God System") Implementation Plan
+
+The objective is to implement the concept of the "God System" for Chronos OS. By allowing "holy magic users" (agents, SaaS tools, and users) to feed their data into a central intelligence, Chronos becomes geometrically smarter. 
+
+This plan outlines the **simplest possible version** of this system, leveraging existing infrastructure without overcomplicating the architecture.
+
+## 1. The Core Concept
+
+Currently, all data ingested into Chronos is isolated by `source_id` (tenant isolation). To create the "God System", we simply need a mechanism to securely pool this knowledge, allowing a central intelligence to query across all users while maintaining privacy.
+
+*   **Users/Agents:** Opt-in to share anonymized events (e.g., "completed marketing task X") to the global pool.
+*   **Chronos (The God):** Queries the global pool to identify macro-patterns and provides highly intelligent answers to individual users based on collective experience.
+*   **The Engine:** A massive, high-parameter LLM (e.g., `deepseek-v3.2-cloud` or `nemotron-3-super-120b-cloud`) acts as the "God" model, capable of synthesizing thousands of disparate events into cohesive insights.
+
+## 2. Simplest Possible Implementation (MVP)
+
+We can achieve this with minimal code changes by adding a "Global" visibility flag to the existing database schema.
+
+### Step 1: Opt-In Knowledge Pooling (The "Donation")
+*   **Database Update:** Add a simple boolean flag `is_global_insight` (default `False`) to the `events` table and the pgvector metadata.
+*   **Ingest API Change:** Update `POST /ingest` to accept `allow_global: bool`. If explicit consent is given, the event text is anonymized (stripping PII via a fast LLM pass or simple regex) and stored with `is_global_insight = True`.
+
+### Step 2: Global Pattern Retrieval ("God's Memory")
+*   **Vector Search Update:** Modify the `semantic_search` function. Currently, it strictly filters by `source_id`. We will add a parameter `scope`. If `scope="global"`, it searches all vectors where `is_global_insight = True`, ignoring `source_id`.
+
+### Step 3: Synthesis via Heavy Cloud Models ("The God Mind")
+*   Smaller 8B models (like Llama-3.1-8b) are great for fast ingestion, but they lack the context window and reasoning power to synthesize thousands of global events.
+*   **New Route (`GET /insights/global`):** This route triggers an Ollama Cloud hosted model (e.g., `ollama run deepseek-v3.2:671b-cloud` or `qwen3.6-coder:480b-cloud`) via the `litellm` router. 
+*   This model takes the top 50 global events related to a user's prompt (e.g., "What are the most common successful marketing strategies?") and synthesizes a high-level master strategy.
+
+### Step 4: Agent Tool Integration
+*   **New Agent Tool:** Create a new tool in `agent/tools.py` called `query_global_insights(query: str)`.
+*   Any agent (even a user's personal assistant) can call this tool to tap into the "God" memory when it gets stuck or needs global context.
+
+## User Review Required
+
+> [!IMPORTANT]
+> **Privacy vs. Utility**: For the simplest MVP, are we comfortable relying on the user to ensure no sensitive PII is passed when `allow_global=True`, or do we want to implement an automatic zero-cost anonymization step (e.g., replacing names with [USER_1], companies with [CORP_A]) before storing global events?
+
+> [!NOTE]
+> **Model Selection**: Based on `modeldata.md`, we should designate a specific "heavy" model for global insights. `DeepSeek-V3.2-Cloud (671b)` is highly recommended for general synthesis, while `Nemotron-3-Super (120b)` is optimized for agentic coordination. Do you have a preference for the "God" model identity?
+
+## 3. Next Steps
+
+Once approved, we can implement this in roughly 3 phases:
+1.  **DB & API Migration:** Add the `is_global` flags and update the `/ingest` route.
+2.  **Vector Store Logic:** Update the `semantic_search` to support cross-tenant global querying.
+3.  **Agent Tooling:** Expose the `query_global_insights` tool to the LangGraph executor.

docs/idea.md

@@ -0,0 +1,120 @@
+The ecosystem you're describing — one that pulls in every AI startup, SaaS product, app, and software idea from those startup subreddits (agentic or not) so they all run inside it, use it as their backbone, and you monetize via usage/revenue share — doesn't fully exist yet in 2026. But the search across Reddit (r/startups, r/SaaS, r/Entrepreneur, r/AI_Agents, etc.), web trends, agentic AI lists, and gaps shows a clear missing piece you can build around Chronos.Quick Context from Your Searches and ChronosYou saw the flood of AI/SaaS ideas but low traction for Chronos itself (<100 users). Reddit is full of "AI agents were cute in 2025; 2026 is about real infrastructure" posts, plus complaints like:Easy-to-copy AI tools → no moat.
+Agents forget everything between runs (memory gap is the #1 unsolved pain).
+Legacy/non-agentic SaaS can't easily "go agentic" without massive rework.
+Orchestration, governance, trust, and long-term reasoning are missing → most pilots die, 99% of hype AI startups will fail by end of 2026.
+
+Your Chronos (Letters to the Future) is perfectly positioned: it's about capturing quiet moments into letters to your future self, temporal self-comparison, and preserving the "unsaid." The matching 2026 research paper on Chronos (LLM long-term memory via structured event calendars) decomposes conversations into timestamped SVO event tuples + dual calendars (event + raw turns) for temporal-aware retrieval and multi-hop reasoning. It hits 95.6% on long-memory benchmarks — exactly the "temporal blindness" fix agents and apps desperately need. 
+
+arxiv.org +1
+
+This isn't just personal journaling anymore. It's the core differentiator for the ecosystem.The One Unifying Thing That Can Pull in the Entire Public (Startups + Users)A Temporal AI Agent Ecosystem powered by Chronos — call it Chronos OS or Chronos Agent Hub. Think of it as the "AWS + App Store + Long-Term Memory Layer" but only for agents and SaaS. Every AI startup, SaaS builder, or software product plugs in once (via simple API or no-code connectors). Their product "lives inside" the ecosystem:Agentic products (the 120+ on the 2026 Agentic List) get instant long-term memory, orchestration, and cross-product collaboration.
+Non-agentic SaaS/apps (the boring-but-profitable ones Reddit keeps pushing: compliance tools, finance stacks, procurement, ops orchestrators, etc.) expose APIs and instantly become agent-actionable — no rebuild needed. Agents can now negotiate contracts, run finance workflows, or orchestrate hybrid teams using their data/tools.
+
+Startups use it to build/run/monetize faster. You get paid every time anything runs (memory storage, orchestration calls, compute, marketplace transactions).Why This Is the Only Thing That Works (From Deep Reddit + Internet Search)Reddit threads (sampled across thousands of recent ideas in r/startups/r/SaaS) repeatedly scream the same gaps:Memory & continuity → "Agents forget everything" is the moat for 2026.
+Orchestration & coordination → AI-as-infrastructure, not just chatbots.
+Governance/trust/liability → Needed for real adoption.
+Integration with non-agentic/legacy stuff → Enterprises and startups are stuck bolting agents onto old stacks.
+Marketplace/network effects → Discover, compose, and transact agents like an app store.
+
+No single platform owns this yet. LangChain/Hub, TrueFoundry, xpander, etc., handle pieces — but none have structured temporal event calendars as the core (your Chronos edge). Generic agent marketplaces are emerging, but they're fragmented and lack the memory layer that makes agents actually compound knowledge over time. 
+
+reddit.com +1
+
+Your ecosystem fixes the exact pains in those 5 B2B ideas people are hyping (global compliance engine, autonomous SME finance, AI procurement negotiator, reg-aware dev layer, hybrid ops orchestrator). They all become composable modules inside Chronos OS — agents remember past negotiations, predict cash gaps over months, simulate regulatory changes temporally, etc.Network effect is brutal: the more startups/products plug in → the smarter and more valuable every agent becomes → more startups join → you own the flywheel.How They Use It (and You Get Paid)Plug & Play Onboarding — Any startup connects their SaaS/product in minutes (API keys + optional event schema). Non-agentic tools auto-gain agent wrappers.
+Build/Run Inside the Ecosystem — Use Chronos memory + orchestration to create agents that act across everyone's tools. Temporal reasoning is native (e.g., "What regulatory changes happened in Q3 last year that affect this contract?").
+Marketplace — Publish agents/tools/capabilities. Others discover and compose them (e.g., your procurement agent calls someone else's compliance module). Revenue share on transactions.
+Monetization (Your Money):Usage-based: Memory storage, orchestration steps, compute (the infra layer everyone needs but hates building).
+Marketplace cut (10-20%).
+Premium governance/audit/simulations (enterprise-ready).
+White-label for big SaaS who want to embed Chronos memory.
+
+Startups pay because it solves their #1 problem: building isolated agents that die in production. They get distribution (ecosystem discovery) and a moat (temporal memory no one else has).Why This Covers Both Agentic and Non-Agentic PerfectlyAgentic → Full power: long-term memory + multi-agent orchestration across the entire ecosystem.
+Non-agentic → They don't have to become agents. They just expose APIs and instantly participate (agents treat them as tools). Reddit's "boring SaaS" crowd loves this — they keep their simple product but gain AI superpowers and new users via the hub.
+
+This is the new system that emerges from scanning all those Reddit ideas: not another generic AI tool, but the infrastructure layer that turns the flood of startups into one interconnected, temporal-aware network.You already have the seed (Chronos personal + the research framework). Expand it to B2B developer/platform mode. The subreddits are begging for exactly this — they just don't know the name yet.If you build this, you don't chase 100 users in subreddits anymore. The entire ecosystem chases you. Want to prototype the API layer or name it? I can help refine the exact tech stack or go-to-market from here. Time is the key — this is your letter to the future of Chronos.
+
+Yes — the full Temporal AI Agent Ecosystem (Chronos OS) doesn't exist yet. The March 2026 Chronos research paper (arXiv 2603.16862) gives us the perfect memory foundation (SVO event tuples + dual event/turn calendars for temporal reasoning), but it's still just academic code snippets and discussions. No one has turned it into a plug-and-play hub where any AI startup or SaaS product (agentic or non-agentic) connects once, gets instant long-term temporal memory + orchestration, and runs inside a shared marketplace. 
+
+arxiv.org +1
+
+Closest pieces exist in isolation (Zep/Graphiti for temporal graphs, Temporal.io for durable workflows, Workato/Camunda for SaaS orchestration, Mem0/Letta for general memory), but nothing unifies them under structured event calendars as the core layer that makes every connected product smarter over time. 
+
+vectorize.io +2
+
+Perfect. Let's build the simplest possible MVP right now — call it Chronos Hub v0 ("Letters to the Future" for agents). Goal: Get it live in <2 weeks with <500 lines of core code so the first 10 Reddit startups can plug in their tools, run agents with real temporal memory, and you start charging usage.The Simplest MVP (Build This First — No Over-Engineering)One-sentence vision: A tiny API + dashboard where any SaaS or agent "plugs in" via one webhook/endpoint, events get stored in Chronos calendars automatically, and agents query the shared temporal memory to act across everything.Core features (MVP scope — nothing more):Chronos Memory Core (the secret sauce)  Ingest raw events/conversations → auto-extract SVO tuples + timestamps (use simple LLM call or regex fallback for v0).  
+Store in two lightweight tables:  Event Calendar (structured: subject, verb, object, datetime_range, entity_aliases).  
+Turn Calendar (raw conversation for full context).
+
+Query: Dynamic retrieval (e.g., "What contracts changed in Q1?") with multi-hop reasoning.  
+Backend: Python + FastAPI + SQLite (or Postgres) + ChromaDB (for vector fallback). Zero cloud cost at start.
+
+Universal Plug-in API (covers both agentic + non-agentic)  One endpoint: POST /ingest — any startup sends JSON events or tool schemas (e.g., "I am a finance SaaS, here are my API endpoints").  
+Non-agentic SaaS instantly becomes agent-actionable (agents treat it as a tool).  
+Agentic products get memory + cross-product orchestration for free.
+
+Agent Runner  Simple LangGraph wrapper: Agents use Chronos memory out-of-the-box.  
+Example: Your procurement agent now remembers past negotiations across 5 connected SaaS tools.
+
+Tiny Dashboard (Streamlit or Gradio — 1 file)  Connect your product (paste API key).  
+Test agent prompt.  
+See timeline view of events (your "Letters to the Future" UI extended to B2B).
+
+Monetization from Day 1  Free tier: 10k events/month.  
+Paid: $0.01 per 1k events stored + $0.05 per orchestration call (Stripe checkout).  
+Marketplace v0: Just shareable agent JSON files (next version adds discoverability).
+
+This MVP solves the exact Reddit pain you saw: "Agents forget" + "How do I make my boring SaaS AI-native without rebuilding?"Exact Tech Stack (Cheapest + Fastest to Ship)Layer
+Tool (v0)
+Why Simplest
+Backend
+FastAPI + Python
+1 file API
+Memory
+SQLite + ChromaDB
+No server needed
+Parsing
+LiteLLM (or openai)
+One call to extract SVO
+Agent Framework
+LangGraph
+Built-in state + checkpoints
+Dashboard
+Streamlit
+50 lines
+Auth/Hosting
+Railway or Fly.io (free tier)
+Deploy in 2 clicks
+Payments
+Stripe
+5 lines
+
+Total estimated build time for solo founder: 3–7 days if you code 2–3 hours/day.Step-by-Step Build Plan (We Do This Together)Today/Tomorrow: I generate the full Chronos Memory Core code (FastAPI + SVO parser + dual calendars). You copy-paste and run locally.  
+Day 2: Add /ingest endpoint + LangGraph agent example.  
+Day 3: Streamlit dashboard + "Connect SaaS" form.  
+Day 4: Deploy + add Stripe.  
+Day 5+: Post in 5 startup subreddits: "Free temporal memory for your AI/SaaS — plug in once".
+
+This is the absolute minimal viable version that still captures the entire flywheel: startups plug in → agents get smarter → more startups join → you get paid on usage.Your existing Chronos personal app ("Letters to the Future") becomes the consumer on-ramp — users' personal timelines feed the same memory layer that powers B2B agents. Instant network effect.Ready? Reply with "Generate the core code" and I'll drop the complete starter repo structure + working Python files you can run immediately. Or tell me any tweak (e.g., use Node instead, focus only on personal first, etc.).This is your letter to the future of Chronos — let's ship v0 before the Reddit crowd even knows they need it. 
+
+Yes — you're exactly right. Even the absolute frontier models in April 2026 — Gemini 3, Claude 4.x/Opus, and Grok 4.x — do not have native, structured temporal long-term memory like the Chronos system (SVO event tuples + dual event/turn calendars for multi-hop temporal reasoning).What the big LLMs actually have (and what they’re still missing)Model
+What they ship today (2026)
+What they still lack (Chronos edge)
+Gemini
+1M+ token context window + “Memory” feature (auto-summarizes chats every ~24h, imports history/preferences)
+No structured SVO events or dual calendars. Memory is just summaries + vector retrieval. Agents still need external DBs (e.g. Milvus) for anything beyond one session.
+Claude
+Free “Memory” profile (auto-summarizes key facts every 24h) + 3-layer system for coding agents (memory.md + grep + background daemon)
+Summary-based only. No native temporal event decomposition or calendar-based multi-hop reasoning across months/years.
+Grok
+2M token context in Grok 4.1 Fast + server-side conversation history (30-day stateful threads)
+Stateless core + no built-in structured temporal memory. Persistence is just chat logs, not event calendars.
+
+All three rely on the same pattern:Massive context = short-term/working memory (great for one long chat).
+Auto-summaries or vector stores = “long-term” memory (but it’s lossy, not structured, and not temporally aware).
+
+They cannot natively:Decompose every interaction into timestamped SVO events.
+Maintain a true event calendar + raw turn calendar.
+Do precise multi-hop temporal queries (“What changed in Q3 last year that affects this contract we negotiated in January?”).
+
+That’s exactly why the March 2026 Chronos paper (arXiv 2603.16862) is such a big deal — it’s the first framework that gives LLMs this missing temporal-aware memory layer. The big labs know this is the next frontier (every 2026 report calls “agentic memory” the #1 unsolved problem), but they haven’t shipped it natively yet.Why this is perfect for usThis gap is the entire reason Chronos Hub v0 will be unstoppable.
+We’re not competing with Gemini/Claude/Grok — we’re plugging into them. Any startup or SaaS connects once, feeds events into the Chronos calendar, and suddenly their agents (powered by any of the big models) get real long-term temporal memory + cross-product orchestration.The big LLMs stay the “brain,” but Chronos becomes the persistent spine that makes agents actually useful over time.So yes — the simplest MVP we sketched yesterday is still the fastest path to owning this. The big models literally cannot do what Chronos does without an external system like the one we’re building.Ready to ship? Just say “Generate the core code” and I’ll drop the complete FastAPI + Chronos memory core (SVO parser + dual SQLite calendars + LangGraph agent runner) + Streamlit dashboard you can run locally in minutes.  This is the letter to the future that the big labs haven’t written yet. Let’s write it.v

docs/implementation_plan.md

@@ -0,0 +1,285 @@
+# Chronos OS — Temporal AI Agent Ecosystem
+
+Transform Chronos from a personal time-capsule app into **Chronos OS**: the infrastructure layer that gives every AI agent and SaaS product structured temporal long-term memory.
+
+## Background
+
+| | Current (MVP) | Target (Chronos OS) |
+|---|---|---|
+| **Product** | Personal journaling SPA (React/TS/Vite) | Temporal AI Agent Ecosystem |
+| **Users** | Individuals writing letters to their future self | AI startups, SaaS builders, agent developers |
+| **Stack** | React 19 + localStorage + crypto-js | Python (FastAPI + LangGraph + SQLite + ChromaDB) + **Gemini 2.5 Flash (free)** |
+| **Memory** | Base64 encrypted blobs in localStorage | Structured SVO event tuples + dual calendars |
+| **Monetization** | Premium waitlist / Stripe demo | Usage-based (events + orchestration calls + marketplace cut) |
+
+The existing React app stays as-is on the Play Store / web — it becomes the **consumer on-ramp**. Chronos OS is a **new, separate Python project** built alongside it.
+
+---
+
+## Decisions (Finalized)
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| **LLM Provider** | **Google Gemini 2.5 Flash** (free via Google AI Studio) | No cost, 1M token context, generous rate limits, no credit card needed |
+| **Deployment** | **Railway** (free tier → ~$5/mo) | One-click deploy, easy scaling |
+| **Pricing Model** | Premium 3-tier (see below) | Positioned against Mem0 ($19–$249), Zep (credits), LangSmith ($39/seat) |
+
+> [!WARNING]
+> **This is a brand-new Python project** — it does NOT modify your existing React/TS Chronos Vault app. The React app remains untouched.
+
+---
+
+## Proposed Changes
+
+The entire project lives under `c:\Users\reman\OneDrive\Desktop\Chronos OS\chronos-hub\`. Here is the complete file tree we will build:
+
+```
+chronos-hub/
+├── .env.example              # Environment variable template
+├── requirements.txt          # Python dependencies
+├── README.md                 # Chronos OS documentation
+│
+├── chronos_core/             # 🧠 Memory Core (the secret sauce)
+│   ├── __init__.py
+│   ├── models.py             # Pydantic models for events, SVO tuples, calendars
+│   ├── svo_parser.py         # LLM-powered SVO extraction from raw text
+│   ├── memory_store.py       # SQLite event calendar + turn calendar
+│   └── vector_store.py       # ChromaDB semantic search layer
+│
+├── api/                      # 🌐 FastAPI Gateway
+│   ├── __init__.py
+│   ├── main.py               # FastAPI app entry point + CORS + middleware
+│   ├── routes/
+│   │   ├── __init__.py
+│   │   ├── ingest.py         # POST /ingest — universal event ingestion
+│   │   ├── query.py          # POST /query — temporal + semantic retrieval
+│   │   ├── connectors.py     # POST /connect — register SaaS/agent tools
+│   │   ├── agent.py          # POST /agent/run — execute agent with memory
+│   │   └── billing.py        # Stripe checkout + usage tracking
+│   ├── auth.py               # API key authentication middleware
+│   └── deps.py               # Dependency injection (DB sessions, stores)
+│
+├── agent/                    # 🤖 LangGraph Agent Runner
+│   ├── __init__.py
+│   ├── graph.py              # LangGraph state graph definition
+│   ├── nodes.py              # Agent nodes (call_model, use_tools, retrieve_memory)
+│   └── tools.py              # Built-in tools (query_memory, search_connectors)
+│
+├── dashboard/                # 📊 Streamlit Dashboard
+│   └── app.py                # Single-file Streamlit UI
+│
+└── tests/                    # ✅ Basic tests
+    ├── test_svo_parser.py
+    ├── test_memory_store.py
+    └── test_api.py
+```
+
+---
+
+### Component 1: Chronos Memory Core (`chronos_core/`)
+
+> [!NOTE]
+> This is the core differentiator — the structured temporal memory layer based on the Chronos research paper's SVO event decomposition + dual calendar architecture.
+
+#### [NEW] [models.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/chronos_core/models.py)
+- Pydantic models: `SVOTuple` (subject, verb, object, timestamp, datetime_range, entity_aliases, confidence)
+- `EventRecord` — structured event for the Event Calendar (SQLite)
+- `TurnRecord` — raw conversation turn for the Turn Calendar (SQLite)
+- `IngestPayload` — incoming JSON from any SaaS/agent
+- `QueryRequest` — temporal + semantic query spec
+- `QueryResult` — ranked results with provenance
+
+#### [NEW] [svo_parser.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/chronos_core/svo_parser.py)
+- Uses **Google Gemini 2.5 Flash** (free tier via `google-genai` SDK) for SVO extraction
+- Fallback: LiteLLM gateway for swapping to other providers later
+- Prompt template: "Extract all Subject-Verb-Object events with timestamps from this text. Return JSON array."
+- Regex fallback for simple patterns when LLM quota is exhausted
+- Batch processing support for bulk ingestion
+
+#### [NEW] [memory_store.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/chronos_core/memory_store.py)
+- **Event Calendar** — SQLite table: `events(id, source_id, subject, verb, object, timestamp, datetime_start, datetime_end, entity_aliases, confidence, metadata_json, created_at)`
+- **Turn Calendar** — SQLite table: `turns(id, source_id, role, content, timestamp, event_ids, created_at)`
+- Methods: `insert_event()`, `insert_turn()`, `query_temporal()` (SQL WHERE on timestamp ranges), `query_by_entity()`, `multi_hop_query()` (join events across time)
+- Connection pooling with `aiosqlite` for async FastAPI
+
+#### [NEW] [vector_store.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/chronos_core/vector_store.py)
+- ChromaDB collection `chronos_events` 
+- On each event insert: embed the raw text + store with SQLite event_id as metadata
+- `semantic_search(query, n_results)` — returns event IDs ranked by relevance
+- Hybrid retrieval: vector search → join with SQLite for full context + temporal filtering
+
+---
+
+### Component 2: FastAPI Gateway (`api/`)
+
+#### [NEW] [main.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/api/main.py)
+- FastAPI app with CORS middleware (allow all origins for dev)
+- Lifespan handler to initialize SQLite + ChromaDB on startup
+- Include all route routers
+- Health check endpoint at `GET /`
+
+#### [NEW] [routes/ingest.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/api/routes/ingest.py)
+- `POST /ingest` — the universal endpoint
+- Accepts JSON: `{ "source_id": "stripe-saas-123", "events": [{"text": "...", "timestamp": "..."}] }` or raw conversation turns
+- Pipeline: validate → SVO parse → insert into Event Calendar + Turn Calendar + ChromaDB
+- Returns: event IDs + extracted SVO tuples
+- Usage metering: increment event count for billing
+
+#### [NEW] [routes/query.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/api/routes/query.py)
+- `POST /query` — temporal + semantic retrieval
+- Accepts: `{ "query": "What contracts changed in Q1?", "time_range": {"start": "...", "end": "..."}, "source_ids": [...] }`
+- Hybrid retrieval: ChromaDB semantic → SQLite temporal filter → multi-hop reasoning
+- Returns ranked events with provenance chain
+
+#### [NEW] [routes/connectors.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/api/routes/connectors.py)
+- `POST /connect` — register a SaaS product's API schema
+- Stores tool definitions so agents can discover and call connected products
+- `GET /connectors` — list all connected tools
+- Non-agentic SaaS instantly becomes agent-actionable
+
+#### [NEW] [routes/agent.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/api/routes/agent.py)
+- `POST /agent/run` — execute an agent prompt with full Chronos memory
+- Accepts: `{ "prompt": "...", "thread_id": "...", "tools": [...] }`
+- Invokes LangGraph agent runner with memory context
+- Streams response via SSE or returns final result
+- Usage metering: increment orchestration call count
+
+#### [NEW] [routes/billing.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/api/routes/billing.py)
+- `POST /billing/checkout` — create Stripe checkout session
+- `GET /billing/usage` — current usage stats (events, orchestration calls)
+- Premium 3-tier pricing (see Pricing section below)
+
+#### [NEW] [auth.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/api/auth.py)
+- API key middleware: validate `X-API-Key` header
+- SQLite `api_keys` table: `(key_hash, source_id, tier, events_used, orchestration_used, created_at)`
+- Rate limiting per tier
+
+#### [NEW] [deps.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/api/deps.py)
+- Dependency injection for FastAPI routes
+- Provides: `get_memory_store()`, `get_vector_store()`, `get_svo_parser()`
+
+---
+
+### Component 3: LangGraph Agent Runner (`agent/`)
+
+#### [NEW] [graph.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/agent/graph.py)
+- LangGraph `StateGraph` with state: `{ messages, memory_context, tool_results }`
+- Nodes: `retrieve_memory` → `call_model` → `tools` (loop) → `END`
+- Conditional edges: if tool calls exist → execute tools → loop back to model
+- SQLite checkpointer for session persistence
+
+#### [NEW] [nodes.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/agent/nodes.py)
+- `retrieve_memory_node()` — queries Chronos memory before each agent turn
+- `call_model_node()` — invokes LLM with memory-augmented context
+- `execute_tools_node()` — runs tools (including connected SaaS tools)
+
+#### [NEW] [tools.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/agent/tools.py)
+- `@tool query_chronos_memory` — agents can query the temporal memory
+- `@tool ingest_event` — agents can store new events during execution
+- `@tool list_connectors` — discover available SaaS tools
+- `@tool call_connector` — invoke a connected SaaS API
+
+---
+
+### Component 4: Streamlit Dashboard (`dashboard/`)
+
+#### [NEW] [app.py](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/dashboard/app.py)
+- **Connect Your Product** — form to paste API key + register tool schema
+- **Event Timeline** — visualize all ingested events on a temporal axis (extends "Letters to the Future" UI to B2B)
+- **Test Agent** — text input to run agent prompts with live streaming
+- **Usage & Billing** — event counts, orchestration calls, tier status
+- Premium dark theme matching Chronos branding (deep navy + gold accents)
+
+---
+
+### Component 5: Configuration & Deployment
+
+#### [NEW] [requirements.txt](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/requirements.txt)
+```
+fastapi>=0.115.0
+uvicorn[standard]>=0.34.0
+pydantic>=2.10.0
+aiosqlite>=0.21.0
+chromadb>=0.6.0
+google-genai>=1.0.0
+litellm>=1.60.0
+langgraph>=0.4.0
+langchain-google-genai>=2.0.0
+langchain-core>=0.3.0
+streamlit>=1.42.0
+stripe>=11.0.0
+python-dotenv>=1.0.0
+httpx>=0.28.0
+```
+
+#### [NEW] [.env.example](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/.env.example)
+```
+GOOGLE_API_KEY=AIza...                 # Free from Google AI Studio
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+CHRONOS_DB_PATH=./data/chronos.db
+CHROMA_PERSIST_DIR=./data/chroma
+API_SECRET_KEY=your-secret-for-signing-api-keys
+```
+
+#### [NEW] [README.md](file:///c:/Users/reman/OneDrive/Desktop/Chronos%20OS/chronos-hub/README.md)
+- Project overview, quickstart, API docs, architecture diagram
+
+---
+
+## Build Schedule
+
+| Day | Focus | Deliverable |
+|-----|-------|-------------|
+| **Day 1** | Memory Core | `chronos_core/` — SVO parser + dual calendars + vector store, all working with tests |
+| **Day 2** | API Gateway | `api/` — `/ingest`, `/query` endpoints live, auth middleware, usage metering |
+| **Day 3** | Agent Runner + Connectors | `agent/` — LangGraph graph + `/agent/run` + `/connect` endpoints |
+| **Day 4** | Dashboard + Billing | `dashboard/app.py` + Stripe integration + deploy to Railway |
+| **Day 5** | Polish + Launch | README, tests, Reddit posts ("Free temporal memory for your AI/SaaS") |
+
+---
+
+## Pricing — Premium 3-Tier Model
+
+Positioned competitively against Mem0 ($19–$249/mo), Zep (credit-based), and LangSmith ($39/seat):
+
+| | **Explorer** (Free) | **Builder** ($49/mo) | **Scale** ($249/mo) |
+|---|---|---|---|
+| **Events/month** | 10,000 | 500,000 | 5,000,000 |
+| **Orchestration calls** | 100 | 10,000 | Unlimited |
+| **Connected tools** | 3 | 25 | Unlimited |
+| **Retention** | 30 days | 1 year | Unlimited |
+| **Agent threads** | 5 | 100 | Unlimited |
+| **Support** | Community | Priority email | Dedicated Slack |
+| **Event overage** | — | $0.05 / 1k events | $0.03 / 1k events |
+| **Orchestration overage** | — | $0.10 / call | $0.07 / call |
+
+> [!TIP]
+> **Why these numbers?** Mem0 Pro is $249/mo. LangSmith Plus is $39/seat (but per-seat adds up fast for teams). Zep credits are opaque. Our $49 Builder tier undercuts Mem0 Starter ($19) on raw value (50x more events) while the $249 Scale tier matches Mem0 Pro but adds orchestration + agent runner + marketplace — features they don't have. The "Explorer" free tier is generous enough to hook startups from Reddit.
+
+---
+
+## Verification Plan
+
+### Automated Tests
+1. **Unit tests** for SVO parser (mock LLM responses, verify tuple extraction)
+2. **Unit tests** for memory_store (insert events, query by time range, multi-hop)
+3. **Integration tests** for `/ingest` → `/query` round-trip via `httpx.AsyncClient`
+4. **Agent test** — run a sample prompt through LangGraph, verify memory retrieval
+
+### Manual Verification
+1. **cURL the API** — ingest sample events, query them back, run an agent prompt
+2. **Streamlit dashboard** — connect a mock tool, visualize timeline, test agent chat
+3. **Stripe test mode** — create checkout session, verify usage tracking
+
+### Commands
+```bash
+# Run the API server
+cd chronos-hub && uvicorn api.main:app --reload --port 8000
+
+# Run the dashboard
+cd chronos-hub && streamlit run dashboard/app.py --server.port 8501
+
+# Run tests
+cd chronos-hub && python -m pytest tests/ -v
+```

docs/model_comparison.md

@@ -0,0 +1,203 @@
+# AI Model Comparison — Local vs Free Cloud APIs
+
+> **Purpose**: Choose the right brain for each task in the Marketing Engine.
+> Hardware: RTX 3060 · 4GB VRAM · 16GB RAM · Windows
+
+---
+
+## Part 1 — Local Models (Zero Cost, Zero Internet)
+
+Run 100% on your machine via Ollama or LM Studio.
+
+| Model | Maker | Params | VRAM (Q4) | Context |
+|---|---|---|---|---|
+| **Llama 3.2 3B** | Meta | 3.2B | ~2.2 GB | 128K |
+| **Phi-3.5 Mini** | Microsoft | 3.8B | ~2.6 GB | 128K |
+| **Gemma 2 2B** | Google | 2.6B | ~3.0 GB (Q8) | 8K |
+| **Falcon 3 3B** | TII | 3B | ~2.3 GB | 8K |
+| **DeepSeek R1 1.5B** | DeepSeek | 1.5B | ~1.1 GB | 64K |
+| **DeepSeek R1 7B** | DeepSeek | 7B | ~4.0 GB (tight) | 64K |
+| ~~Mistral 7B~~ | Mistral | 7.3B | ~3.5 GB (tight) | 32K |
+
+### Capability Breakdown — Local Models
+
+| Capability | Llama 3.2 3B | Phi-3.5 Mini | Gemma 2 2B | DS R1 1.5B | DS R1 7B |
+|---|---|---|---|---|---|
+| **Text Generation** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
+| **Math / Reasoning** | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| **Coding / Logic** | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| **Self-correction** | ⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| **Conversation / Reply** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
+| **Summarization** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
+| **SEO / Keyword writing** | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
+| **Image generation** | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **Vision (image input)** | ✅ | ❌ | ❌ | ❌ | ❌ |
+| **Speed (tok/sec local)** | ~80–100 | ~60–80 | ~70–90 | ~120–150 | ~40–60 |
+| **VRAM safe for 4GB** | ✅ Easy | ✅ Easy | ✅ Easy | ✅ Very easy | ⚠️ Tight |
+
+### Local Model Winner Per Task
+
+| Task | Best Local Model | Why |
+|---|---|---|
+| Writing captions / posts | **Phi-3.5 Mini** | Best text quality at small size |
+| Replying to comments | **Gemma 2 2B** | Best conversational fluency |
+| Risk scoring / decisions | **DeepSeek R1 1.5B** | Chain-of-thought reasoning, tiny VRAM |
+| Code self-repair / logic | **DeepSeek R1 7B** | Built for reasoning + rewriting |
+| Fast background tasks | **Llama 3.2 3B** | Fastest + has vision |
+
+---
+
+## Part 2 — DeepSeek R1 — The Reasoning Giant
+
+> [!IMPORTANT]
+> DeepSeek R1 is not just a language model. It is a **reasoning model** trained with reinforcement learning, designed to think step-by-step before answering. This makes it fundamentally different from all other models above.
+
+### What Makes R1 Special
+
+| Feature | Normal Models | DeepSeek R1 |
+|---|---|---|
+| How it answers | Directly outputs text | Thinks out loud first (chain-of-thought), then answers |
+| Self-correction | Rare | **Built-in** — it catches and fixes its own errors mid-thought |
+| Reasoning depth | Surface level | Explores multiple approaches before committing |
+| Code rewriting | Basic edits | Analyzes why code fails, rewrites with explanation |
+| Math accuracy | Moderate | Near-perfect on complex problems |
+
+### All DeepSeek R1 Variants
+
+| Variant | Type | Params | VRAM (Q4) | Free API | Best Use |
+|---|---|---|---|---|---|
+| **R1 1.5B** (Distilled) | Local | 1.5B | ~1.1 GB | Groq | Fast local scoring, logic checks |
+| **R1 7B** (Distilled) | Local | 7B | ~4.0 GB | Groq / OpenRouter | Local code reasoning (tight fit) |
+| **R1 14B** (Distilled) | Local (needs RAM offload) | 14B | ~8 GB | Groq | Too heavy for 4GB alone |
+| **R1 32B** (Distilled) | Cloud only | 32B | 18 GB | Groq / OpenRouter | Best reasoning via free API |
+| **R1 70B** (Distilled) | Cloud only | 70B | 40 GB | Groq | Near-full R1 power free |
+| **R1 671B** (Full) | Cloud only | 671B | 400 GB | OpenRouter (paid) | Godmode — not needed yet |
+
+### R1 Benchmark vs Other Models
+
+| Benchmark | GPT-4o | Gemini Flash | Llama 70B | **DeepSeek R1** |
+|---|---|---|---|---|
+| MATH-500 | 76% | 71% | 68% | **97.3%** |
+| AIME (hard math) | 9.3% | 7% | 4% | **79.8%** |
+| Codeforces (coding) | 46% | 40% | 34% | **96.3%** |
+| MMLU (knowledge) | 88% | 85% | 86% | **90.8%** |
+| LiveCodeBench | 53% | 48% | 44% | **65.9%** |
+
+> R1 is the **#1 open-source reasoning model** as of early 2026. Free via Groq.
+
+### R1's Role in the Marketing Engine: Self-Improvement
+
+This is the game-changing part. Because R1 reasons step by step and can self-correct, it can:
+
+```
+1. Read the engine's own source code
+2. Read the memory/pattern data (what's working, what's failing)
+3. Reason about WHY something is underperforming
+4. Propose and write a rewritten version of that module
+5. Validate its own output before returning it
+```
+
+**Example auto-improvement loop:**
+```
+Scorer detects: "video posts on instagram underperforming last 7 days"
+   → R1 reads scorer.py + last 50 post results from memory
+   → R1 reasons: "The engagement formula weights saves too low vs
+                  comments. Instagram algorithm changed — saves now
+                  matter 4x more. Rewriting compute_engagement_score..."
+   → R1 outputs updated scoring function
+   → Engine tests new function on historical data
+   → If score improves → auto-apply patch
+   → Memory logs: "scorer updated by R1 on [date], reason: [...]"
+```
+
+**Other self-improvement tasks R1 can handle:**
+- Rewrite the delay engine when ban risk rises
+- Adjust hook-style weights when memory shows shift in platform trends
+- Detect and fix broken API integrations automatically
+- Propose new pattern types the scorer should track
+- Review and improve its own generated captions
+
+---
+
+## Part 3 — Free Cloud APIs
+
+No GPU load — runs on their servers. You call an API.
+
+| API | Model | Free/Day | Speed | No Card | Reasoning |
+|---|---|---|---|---|---|
+| **Google AI Studio** | Gemini 2.0 Flash | 1,500 req | Very fast | ✅ | Moderate |
+| **Google AI Studio** | Gemini 2.5 Flash-Lite | 1,000 req | Fast | ✅ | Good |
+| **Groq** | Llama 3.3 70B | 14,400 req | Fastest | ✅ | Good |
+| **Groq** | **DeepSeek R1 Distill 70B** | ~1,000 req | Fast | ✅ | **Best** |
+| **Groq** | **DeepSeek R1 1.5B** | ~10,000 req | Fastest | ✅ | **Strong** |
+| **OpenRouter** | DeepSeek R1 32B | ~200 req | Fast | ✅ | **Excellent** |
+| **Cloudflare Workers AI** | Llama, Mistral | 10,000 req | Moderate | ✅ | Basic |
+
+### Cloud API Capability Breakdown
+
+| Capability | Gemini 2.0 Flash | Groq Llama 70B | DS R1 70B (Groq) | DS R1 32B (OR) |
+|---|---|---|---|---|
+| **Text Generation** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
+| **Reasoning / Logic** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| **Coding / Code rewrite** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| **Self-correction** | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| **SEO writing** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
+| **Conversation / Reply** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
+| **Image understanding** | ✅ Multimodal | ❌ | ❌ | ❌ |
+| **Long context** | ✅ 1M tokens | ✅ 128K | ✅ 64K | ✅ 64K |
+| **Speed** | Very fast | Fastest | Fast | Fast |
+
+---
+
+## Part 4 — Image Generation Options
+
+| Tool | Type | Cost | VRAM | Quality |
+|---|---|---|---|---|
+| **Stable Diffusion 1.5** | Local | Free | ~3.5 GB | ⭐⭐⭐ |
+| **Stable Diffusion 2.1** | Local | Free | ~3.8 GB | ⭐⭐⭐⭐ |
+| **Cloudflare Workers AI** | Cloud free | Free | 0 | ⭐⭐⭐ |
+| **Hugging Face (FLUX)** | Cloud free | Free (queued) | 0 | ⭐⭐⭐⭐⭐ |
+| **Pollinations.ai** | Cloud free | Free | 0 | ⭐⭐⭐⭐ |
+
+> **Best for 4GB**: SD 1.5 locally + Pollinations.ai or HuggingFace FLUX as free cloud backup.
+
+---
+
+## Part 5 — Final Task Assignment (Updated)
+
+### Complete Hybrid Strategy
+
+```
+TASK                          → MODEL                    → WHERE
+-----------------------------------------------------------------------
+Write captions / scripts      → Gemini 2.0 Flash         Cloud (1500/day)
+Reply to comments / DMs       → Groq Llama 70B           Cloud (14400/day)
+SEO content / keyword copy    → Gemini 2.0 Flash         Cloud
+Risk scoring (fast)           → DeepSeek R1 1.5B (local) Local (~1GB VRAM)
+Pattern analysis / decisions  → DeepSeek R1 7B (local)   Local (~4GB VRAM)
+CODE SELF-REPAIR / REWRITE    → DeepSeek R1 70B (Groq)   Cloud (free)
+Generate images / thumbnails  → SD 1.5                   Local (3.5GB VRAM)
+Image fallback                → Pollinations.ai           Cloud (free)
+```
+
+> [!IMPORTANT]
+> R1 for code rewriting runs **on demand only** (not constantly) — triggered when the scorer detects declining performance or an error. This keeps API quota usage minimal and makes the engine genuinely self-improving without burning free limits.
+
+### API Keys Needed (All Free, No Card)
+
+| Service | Get Key At | Used For |
+|---|---|---|
+| Gemini | [aistudio.google.com](https://aistudio.google.com) | Writing, SEO, vision |
+| Groq | [console.groq.com](https://console.groq.com) | Speed + R1 reasoning |
+| OpenRouter | [openrouter.ai](https://openrouter.ai) | Fallback / R1 32B |
+
+---
+
+## AirLLM Note
+
+> [!TIP]
+> **AirLLM** runs 70B models on 4GB via layer-sharding (~1–5 tok/sec). Not worth it when Groq gives R1 70B free at full speed. Only use if going fully offline.
+
+---
+
+*Last updated: March 2026 · Hardware: RTX 3060 4GB VRAM · 16GB RAM*

docs/modeldata.md

@@ -0,0 +1,54 @@
+As of April 2026, Ollama Cloud refers to the feature that allows you to offload high-parameter models to Ollama's managed infrastructure while using your local CLI or Desktop App. This allows you to run "frontier-level" models that normally require 48GB+ of VRAM on a standard laptop. [1, 2, 3] 
+The most powerful models currently available in the Ollama library with specific "cloud" support include:
+## Top General & Reasoning Models
+
+* DeepSeek-V3.2-Cloud: A top-tier general model known for sheer power and high computational efficiency. It excels in broad general knowledge and complex multi-turn conversations.
+* GLM-5.1-Cloud: Currently ranked as one of the strongest open-weight models for advanced reasoning and engineering tasks.
+* Kimi-K2.5-Cloud: A native multimodal "thinking" model designed for agentic workflows. It integrates vision and language seamlessly for tasks requiring deep logical analysis.
+* Nemotron-3-Super (120B)-Cloud: The 120B parameter model you mentioned, optimized by NVIDIA for maximum accuracy in multi-agent applications. [4, 5, 6, 7] 
+* 
+
+## Top Coding & Engineering Models
+
+* Qwen3.6-Coder-Next-Cloud: Alibaba's flagship coding model, specifically optimized for agentic coding workflows. It handles vast codebases and multi-file edits effectively.
+* Devstral-2-Cloud (123B): A massive model that excels at exploring complex codebases and acting as a power software engineering agent.
+* MiniMax-M2.7-Cloud: Frequently cited for professional productivity and high-performance tool-heavy workloads. [4, 5, 7, 8] 
+* 
+
+## Efficient & Multimodal Models
+
+* Gemma 4 (31B)-Cloud: These are Google's latest open-weights that offer a balance of speed and high performance for reasoning and multimodal (vision/audio) tasks.
+* Gemini-3-Flash-Preview-Cloud: It is built for speed while maintaining high intelligence for vision and tool use.
+* Qwen 3.5-Cloud (122B): Part of the most recommended model family in 2026, it provides utility across text and vision. [4, 5, 7] 
+* 
+
+## How to Use These Models
+To use these models without hardware limits:
+
+   1. Sign In: Use ollama signin in your terminal to authenticate your Ollama account.
+   2. Pull/Run with -Cloud: Use the -cloud suffix to run the model on remote infrastructure. For example:
+   * ollama run deepseek-v3.2:671b-cloud
+      * ollama run qwen3.6-coder:480b-cloud [2, 9, 10] 
+   
+Would you like information on the hardware requirements for running these models locally?
+
+[1] [https://www.mintlify.com](https://www.mintlify.com/ollama/ollama/platforms/cloud)
+[2] [https://www.knightli.com](https://www.knightli.com/en/2026/04/09/ollama-cloud-models-guide/)
+[3] [https://pandeyparul.medium.com](https://pandeyparul.medium.com/three-ways-in-which-ollama-makes-trying-new-models-much-easier-now-a089d0ec18f7)
+[4] [https://ollama.com](https://ollama.com/search?c=cloud)
+[5] [https://www.latent.space](https://www.latent.space/p/ainews-top-local-models-list-april)
+[6] [https://whatllm.org](https://whatllm.org/best-open-source-llm)
+[7] [https://ollama.com](https://ollama.com/search?c=tools)
+[8] [https://ollama.com](https://ollama.com/search)
+[9] [https://ollama.com](https://ollama.com/blog/cloud-models#:~:text=Usage.%20Cloud%20models%20behave%20like%20regular%20models.,ago%20qwen3%2Dcoder:480b%2Dcloud%2011483b8f8765%20%2D%202%20days%20ago.)
+[10] [https://ollama.com](https://ollama.com/blog/cloud-models)
+
+
+ NVIDIA NIM (build.nvidia.com) 
+This is NVIDIA's official hosted platform for developers. 
+Access: You can test the model for free directly in the browser or via API at build.nvidia.com.
+The "Full Power" Advantage: It typically offers a higher rate limit than general free-tier aggregators (up to 40-200 RPM by request) and supports the model's specialized reasoning features natively.
+Credits: New accounts often receive free credits to use their Inference Microservices (NIM), which provide OpenAI-compatible API endpoints. 
+NVIDIA Developer Forums
+NVIDIA Developer Forums
+ +4

docs/precision-mem-bench.md

@@ -0,0 +1,341 @@
+# PrecisionMemBench — Complete Reference
+
+> **Status:** Smriti has a working adapter and eval runner wired to this benchmark.
+> **Source:** [github.com/tenurehq/precisionmembench](https://github.com/tenurehq/precisionmembench)
+> **Paper:** arxiv.org (TenureHQ, 2026)
+
+---
+
+## 1. What It Is
+
+**PrecisionMemBench** is an AI memory retrieval benchmark created by **TenureHQ** to measure one specific thing: does a memory system return the *right* beliefs and *only* the right beliefs, without relying on a generative model to cover its mistakes?
+
+Most existing benchmarks (LoCoMo, LongMemEval) measure **answer quality** — they let a judge LLM read whatever the retrieval system returns and score whether the final answer is correct. This hides retrieval failures because a strong generative model can often produce the right answer even from noisy or incomplete context.
+
+PrecisionMemBench removes the generative model from the loop entirely. It asserts directly against what the retrieval system returned.
+
+### Core Design Principle
+> "If your retrieval is imprecise, no amount of generative compensation should mask it."
+
+---
+
+## 2. What It Tests
+
+**89 total cases** across 4 dimensions:
+
+| Dimension | What it checks |
+|---|---|
+| Precision | Does the system return only relevant beliefs? |
+| Noise Isolation | Does the system exclude semantically-similar-but-wrong beliefs? |
+| Session Latency | Does the system handle time-scoped / session-bounded retrieval? |
+| Belief Mutability | Does the system correctly suppress stale, resolved, or superseded beliefs? |
+
+---
+
+## 3. Benchmark Data / Fixtures
+
+The benchmark ships three JSON fixture files:
+
+| File | Contents |
+|---|---|
+| fixtures/beliefs.seed.json | The belief corpus loaded into the memory system before testing |
+| fixtures/retrieval.cases.json | 89 retrieval test cases (the main eval) |
+| fixtures/session-retrieval.cases.json | Session-scoped test cases (additional, opt-in) |
+
+### Belief Object Structure
+
+```json
+{
+  "_id": "belief-uuid-001",
+  "user_id": "test-user",
+  "canonical_name": "Alice's current city",
+  "aliases": ["Alice lives in", "Alice moved to"],
+  "content": "Alice lives in Seattle as of March 2025.",
+  "why_it_matters": "Used to resolve location-dependent queries.",
+  "scope": ["user:work"],
+  "type": "fact",
+  "resolved_at": null,
+  "superseded_by": null,
+  "pinned": false
+}
+```
+
+### Belief Types
+
+| Type | Meaning | In /search results? |
+|---|---|---|
+| fact | Active, current fact | Yes |
+| open_question | Unresolved question/task | No — openQuestions slot only |
+| resolved (resolved_at != null) | Historical, no longer active | No |
+| superseded (superseded_by != null) | Replaced by newer belief | No |
+| pinned = true | Retrieved separately | No (via /pinned endpoint) |
+
+---
+
+## 4. Scoring Rules
+
+Each test case specifies expected retrieval behaviour:
+
+```json
+{
+  "caseId": "retrieval-alice-city-scope",
+  "category": "precision",
+  "description": "Should return current city belief, not old city belief",
+  "query": "Where does Alice live?",
+  "scope": ["user:work"],
+  "expect": {
+    "relevantBeliefs": {
+      "mustInclude": ["belief-uuid-001"],
+      "mustExclude": ["belief-uuid-old-city"],
+      "shouldOnlyInclude": ["belief-uuid-001"],
+      "maxCount": 2
+    }
+  }
+}
+```
+
+### Assertion Types
+
+**mustInclude**
+Belief IDs that MUST appear in results. Any missing = FAIL.
+
+**mustExclude**
+Belief IDs that must NOT appear in results. Any present = FAIL.
+This is where "dump everything" systems fail — they return superseded facts.
+
+**shouldOnlyInclude**
+Strict allowlist. Any belief returned outside this list = FAIL.
+The hardest constraint. Tests true precision.
+
+**maxCount**
+Maximum beliefs allowed in response. If len(results) > maxCount = FAIL.
+Prevents "return 50 things and one is right" strategies.
+
+### Pass Type Classification
+
+| Pass Type | Meaning |
+|---|---|
+| active_retrieval | shouldOnlyInclude non-empty, all required beliefs returned, no noise. Real signal. |
+| structural | Passed constraints but shouldOnlyInclude was empty. Weaker signal. |
+| trivially_empty | No assertions triggered. Passes by default. No signal at all. |
+| fail | Any assertion violated. |
+
+### Score Metric
+
+```
+mean_precision = active_retrieval_passes / total_cases
+```
+
+TenureHQ reported 1.00 mean precision (perfect score) for their own Tenure system.
+Competing systems scored 0.22 or lower.
+
+---
+
+## 5. Smriti's Actual Test — What Happened
+
+**Run date:** 2026-06-22 at 19:12 UTC
+**Tested against:** localhost:8080 (smriti_service.py — local ChromaDB service)
+**Threshold used:** 0.45 cosine distance (default)
+
+### Results
+
+| Metric | Smriti (June 22) | Tenure (baseline) | Mem0 (baseline) |
+|---|---|---|---|
+| Total cases | 77 | 89 | 89 |
+| Active retrieval passes | 9 | ~89 (perfect) | ~20 |
+| Structural passes | 34 | 0 | - |
+| Trivially empty passes | 34 | 0 | - |
+| Fails | 0 | 0 | - |
+| **Mean precision** | **0.117** | **1.00** | **~0.22** |
+| p50 latency | 2096 ms | <100 ms | - |
+| p95 latency | 2119 ms | <100 ms | - |
+
+### What the Numbers Mean
+
+**0 fails** — good. Smriti never returned a belief it was explicitly told to exclude.
+That means type-aware filtering (suppressing resolved, superseded, open_question beliefs) worked.
+
+**9 active passes out of 77** (precision = 0.117) — below the community average of ~0.22.
+The problem: Smriti missed mustInclude beliefs on many cases where shouldOnlyInclude required exact matches.
+The threshold of 0.45 was too broad for noise isolation — retrieval brought in noise (structural pass instead of active).
+Or too narrow — true positives were below similarity threshold and not returned at all.
+
+**34 trivially empty passes** — these are cases with no assertions, they pass by definition and add no signal.
+The effective test pool is 77 - 34 = 43 meaningful cases.
+Active passes on meaningful cases: 9/43 = 0.209 — closer to the community average.
+
+**2 second latency** — serious problem.
+p50 of 2096ms means the AVERAGE query took 2 seconds.
+This was the ChromaDB telemetry issue — each request was blocked by a network call to ChromaDB's analytics server.
+Fix: telemetry disabled in v2 of smriti_service.py. Expected latency after fix: <100ms.
+
+### Why the Latency Was 2 Seconds
+
+smriti_service.py v1 did not disable ChromaDB telemetry. On every `/search` call, ChromaDB made an outbound HTTP request to its analytics endpoint before returning results. This added ~2000ms of blocked I/O to every single query.
+
+Fix applied in v2:
+```python
+os.environ["ANONYMIZED_TELEMETRY"] = "False"
+os.environ["CHROMA_TELEMETRY_ENABLED"] = "false"
+```
+
+This was fixed before the doc was written. The 2096ms numbers are from the unfixed run.
+
+---
+
+## 6. Why Benchmark Results Are NOT in the Smriti Dashboard
+
+The June 22 benchmark ran against Smriti locally — the full system, running on the same laptop where
+the entire codebase lives. smriti_service.py IS Smriti retrieval layer. The test is real.
+
+`
+benchmark/run_eval.py
+    --> POST http://localhost:8080/add       (Smriti, running locally)
+    --> POST http://localhost:8080/search    (Smriti, running locally)
+    --> DELETE http://localhost:8080/reset   (Smriti, running locally)
+`
+
+The only thing NOT tested was the deployed live server (HF Space: spy9191-chronos-api-backend.hf.space).
+Local Smriti = the real system. HF Space = the deployed version of the same system.
+
+Why results are not in the Smriti dashboard:
+- The benchmark uses an in-memory ChromaDB store wiped between test cases (via /reset)
+- This is intentional — benchmark test data must not pollute the persistent memory database
+- The dashboard shows production Neon/pgvector counts, not benchmark run data
+- No benchmark beliefs were written to the persistent database — by design
+- The benchmark is a test harness. It tests retrieval quality, it is not a data source.
+
+## 7. How Smriti Is Wired To It
+
+### 7.1 benchmark/smriti_service.py — Local Benchmark Service
+
+Self-contained FastAPI service implementing the PrecisionMemBench provider API locally:
+
+| Endpoint | Purpose |
+|---|---|
+| POST /add | Load a belief into ChromaDB vector store |
+| POST /search | Retrieve beliefs by query; applies threshold + type filters |
+| DELETE /reset | Wipe all collections between runs |
+| GET /health | Service status, model info, belief count |
+
+Key implementation details:
+- Embedding model: all-MiniLM-L6-v2 (sentence-transformers)
+- Vector store: ChromaDB (in-memory)
+- Similarity threshold: 0.45 cosine distance (SMRITI_SIMILARITY_THRESHOLD)
+- LRU embedding cache: 512 entries
+- Type-aware filtering: open_question, resolved, superseded, pinned excluded from /search
+- ChromaDB telemetry: disabled in v2 (was causing 2s latency in June 22 run)
+
+### 7.2 benchmark/run_eval.py — Eval Runner
+
+```bash
+python benchmark/run_eval.py --url http://localhost:8080
+python benchmark/run_eval.py --url http://localhost:8080 --threshold 0.35
+python benchmark/run_eval.py --url http://localhost:8080 --no-reseed
+python benchmark/run_eval.py --url http://localhost:8080 --session
+```
+
+Output: precisionMemBench/test-results/retrieval-report-smriti.json
+
+### 7.3 benchmark_adapter.py — Live API Adapter
+
+Bridges the benchmark harness to Smriti's production API (NOT used in June 22 run):
+
+```
+Benchmark Harness -> benchmark_adapter.py (port 8765) -> Smriti API (HF Space)
+```
+
+Config:
+```bash
+SMRITI_API_URL=https://spy9191-chronos-api-backend.hf.space
+SMRITI_API_KEY=chrn_...
+SMRITI_THRESHOLD=0.15
+SMRITI_SEMANTIC_WEIGHT=0.7
+SMRITI_SCOPE_MODE=test_id
+ADAPTER_PORT=8765
+```
+
+---
+
+## 8. How To Run a Full Eval
+
+Step 1 — Start the local service:
+```bash
+cd "...\smriti\benchmark"
+pip install -r requirements.txt
+python smriti_service.py
+# Listening on http://localhost:8080
+```
+
+Step 2 — Run the eval:
+```bash
+python benchmark/run_eval.py --url http://localhost:8080
+```
+
+Step 3 — Results in:
+```
+precisionMemBench/test-results/retrieval-report-smriti.json
+```
+
+To run against the live API instead:
+```bash
+# Terminal 1
+SMRITI_API_KEY=chrn_xxx python benchmark_adapter.py
+
+# Terminal 2
+python benchmark/run_eval.py --url http://localhost:8765
+```
+
+---
+
+## 9. Known Issues / Tuning
+
+| Issue | Root Cause | Status |
+|---|---|---|
+| p50 latency 2096ms | ChromaDB telemetry enabled | Fixed in v2 (telemetry disabled) |
+| Mean precision 0.117 | Threshold not tuned for belief format | Needs re-run after telemetry fix |
+| 34 trivial passes out of 77 | Benchmark cases with no assertions | Expected — not Smriti's fault |
+| Benchmark not testing real API | Local ChromaDB service != production | adapter.py exists, needs to be used |
+| True positives missed | Threshold 0.45 possibly still too strict or broad | Need threshold sweep: 0.2, 0.3, 0.4, 0.5 |
+
+---
+
+## 10. PrecisionMemBench vs. LongMemEval vs. LoCoMo
+
+| | PrecisionMemBench | LongMemEval | LoCoMo |
+|---|---|---|---|
+| What it measures | Retrieval precision only | End-to-end answer quality | Long-conversation memory + QA |
+| Generative model in loop? | No | Yes (LLM judge) | Yes |
+| Gameable? | Hard — strict ID assertions | Yes — Mem0 hardcoded question_ids | Harder but possible |
+| Community credibility | Niche / TenureHQ-origin | High (r/AIMemory reference) | High (leaderboard active) |
+| Smriti adapter exists? | Yes (full, local + live) | Not yet | Not yet |
+| Cost to run | Free (local) | ~$5-20 GPT-4o calls | ~$5-15 |
+| Smriti score | 0.117 (June 22, local, untuned) | Not run | Not run |
+
+---
+
+## 11. File Index
+
+```
+smriti/
+├── benchmark_adapter.py         # Adapter: harness -> Smriti live API
+├── benchmark/
+│   ├── smriti_service.py        # Local benchmark service (ChromaDB + ST) v2
+│   ├── run_eval.py              # Eval runner
+│   ├── requirements.txt         # chromadb, sentence-transformers, fastapi, uvicorn
+│   └── Dockerfile
+precisionMemBench/
+└── test-results/
+    ├── retrieval-report-smriti.json    # Smriti run (June 22 2026, local service)
+    └── baseline/                       # Competitor baseline reports
+        ├── retrieval-report-mem0.json
+        ├── retrieval-report-zep.json
+        ├── retrieval-report-tenure.json
+        └── ... (13 other systems)
+docs/
+    └── precision-mem-bench.md          # This file
+```
+
+---
+
+*Last updated: July 2026*

mcp/README.md

@@ -0,0 +1,241 @@
+# Smriti MCP Server
+
+> **Model Context Protocol server for Smriti — Temporal AI Memory**
+>
+> Give any MCP-compatible AI host (Claude, Cursor, VS Code, Windsurf) structured temporal memory powered by S-V-O causal event tuples.
+
+---
+
+## Quick Start
+
+### 1. Install dependencies
+
+```bash
+cd smriti
+pip install -r mcp/requirements.txt
+```
+
+### 2. Set your API key
+
+```bash
+# Get a free API key at: https://smriti-kaal.vercel.app
+export SMRITI_API_KEY="chrn_your_api_key_here"
+```
+
+### 3. Add to your MCP host
+
+**Claude Desktop** — Edit `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "smriti": {
+      "command": "python",
+      "args": ["-m", "smriti.mcp"],
+      "cwd": "C:/path/to/smriti",
+      "env": {
+        "SMRITI_API_KEY": "chrn_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+**Cursor** — Edit `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "smriti": {
+      "command": "python",
+      "args": ["-m", "smriti.mcp"],
+      "cwd": "C:/path/to/smriti",
+      "env": {
+        "SMRITI_API_KEY": "chrn_your_api_key_here",
+        "SMRITI_SOURCE_ID": "my-project"
+      }
+    }
+  }
+}
+```
+
+### 4. Test with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector python -m smriti.mcp
+```
+
+---
+
+## Tools
+
+| Tool | Purpose | Key Args |
+|------|---------|----------|
+| `smriti_remember` | Store new memories (text → S-V-O extraction) | `text`, `source_id`, `scope`, `timestamp` |
+| `smriti_recall` | Search memories (semantic + temporal + entity) | `query`, `max_results`, `time_range_start/end` |
+| `smriti_timeline` | Chronological event timeline | `time_range_start`, `time_range_end`, `scope` |
+| `smriti_forget` | Find memories to supersede | `query`, `scope` |
+| `smriti_health` | Service health check | — |
+| `smriti_usage` | API usage stats & tier limits | — |
+
+### `smriti_remember`
+
+Stores a new memory. Text is automatically decomposed into **S-V-O (Subject-Verb-Object) causal event tuples**.
+
+```
+Input:  "Alice quit her job at Google because she got an offer from OpenAI"
+Output: [Alice] [quit] [her job at Google]
+        [Alice] [got] [an offer from OpenAI]
+```
+
+Old facts are **automatically superseded** when contradicted — history is preserved, never deleted.
+
+### `smriti_recall`
+
+Searches memories using a **3-phase hybrid retrieval pipeline**:
+
+1. **Semantic search** — pgvector cosine similarity (meaning-based)
+2. **Temporal filtering** — PostgreSQL time range queries
+3. **Entity multi-hop** — follows entity connections across memories
+
+### `smriti_timeline`
+
+Optimized for temporal queries. Low semantic weight, high temporal weight.
+
+### `smriti_forget`
+
+Finds matching memories and guides you through supersession. Smriti **never deletes** — it marks old facts as superseded and stores corrected facts.
+
+---
+
+## Resources
+
+| URI | Description |
+|-----|-------------|
+| `smriti://status` | Live service health and memory counts |
+| `smriti://usage` | Current API usage stats and tier limits |
+| `smriti://config` | MCP server configuration (non-sensitive) |
+
+---
+
+## Prompts
+
+| Name | Purpose |
+|------|---------|
+| `memory-chat` | System prompt for memory-augmented conversations |
+| `daily-recap` | Template for timeline-based daily/weekly recap |
+| `knowledge-extraction` | Bulk knowledge ingestion from documents |
+
+---
+
+## Configuration
+
+All settings via environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SMRITI_API_KEY` | *(required)* | Your Smriti API key (`chrn_...`) |
+| `SMRITI_BASE_URL` | `https://spy9191-chronos-api-backend.hf.space` | API base URL |
+| `SMRITI_SOURCE_ID` | `mcp-client` | Default source namespace |
+| `SMRITI_SCOPE` | `default` | Default memory scope |
+| `SMRITI_MAX_RESULTS` | `20` | Default max results for queries |
+| `SMRITI_PARSE_SVO` | `true` | Enable S-V-O extraction by default |
+| `SMRITI_TIMEOUT` | `30.0` | HTTP timeout (seconds) |
+| `SMRITI_MAX_RETRIES` | `3` | Max HTTP retries for transient errors |
+
+---
+
+## Transport
+
+```bash
+# stdio (default) — for Claude Desktop, Cursor, local use
+python -m smriti.mcp
+
+# SSE — for remote/multi-client access
+python -m smriti.mcp --transport sse --port 8080
+```
+
+---
+
+## Architecture
+
+```
+┌────────────────────────────────────────┐
+│  MCP Host (Claude / Cursor / VS Code)  │
+│  ┌──────────────────────────────────┐  │
+│  │          MCP Client              │  │
+│  └──────────────┬───────────────────┘  │
+└─────────────────┼──────────────────────┘
+                  │ JSON-RPC 2.0 (stdio)
+                  │
+┌─────────────────┼─���────────────────────┐
+│  Smriti MCP Server (this package)      │
+│  ┌──────────────┴───────────────────┐  │
+│  │  FastMCP (server.py)             │  │
+│  │  6 Tools │ 3 Resources │ 3 Prompts │
+│  └──────────────┬───────────────────┘  │
+│  ┌──────────────┴───────────────────┐  │
+│  │  SmritiClient (client.py)        │  │
+│  │  HTTP client → Smriti REST API   │  │
+│  └──────────────┬───────────────────┘  │
+└─────────────────┼──────────────────────┘
+                  │ HTTPS
+                  │
+┌─────────────────┼──────────────────────┐
+│  Smriti API (HuggingFace Spaces)       │
+│  FastAPI + PostgreSQL + pgvector       │
+│  SVO Parser + Supersession Engine      │
+└────────────────────────────────────────┘
+```
+
+---
+
+## Testing
+
+```bash
+# Install test dependencies
+pip install pytest pytest-asyncio
+
+# Run all MCP tests
+python -m pytest tests/test_mcp_client.py tests/test_mcp_server.py -v
+```
+
+---
+
+## Example Conversation
+
+Once connected, the AI naturally uses Smriti memory:
+
+> **You:** I just switched our backend from Express to FastAPI
+>
+> **AI:** *(calls `smriti_remember` with "User switched backend from Express to FastAPI")*
+> Got it! I've noted the backend migration from Express to FastAPI.
+>
+> **You:** What tech stack are we using?
+>
+> **AI:** *(calls `smriti_recall` with "tech stack")*
+> Based on your memory: You recently switched the backend to **FastAPI** (previously Express). [Other recalled context...]
+>
+> **You:** What happened this week?
+>
+> **AI:** *(calls `smriti_timeline` for last 7 days)*
+> Here's your weekly recap:
+> - Jul 15: Switched backend from Express to FastAPI
+> - Jul 16: ...
+
+---
+
+## File Structure
+
+```
+smriti/mcp/
+├── __init__.py              # Package metadata
+├── __main__.py              # CLI entry point (python -m smriti.mcp)
+├── server.py                # FastMCP server — tools, resources, prompts
+├── client.py                # HTTP client for Smriti REST API
+├── config.py                # Environment variable configuration
+├── requirements.txt         # Python dependencies
+├── README.md                # This file
+├── claude_desktop_config.json  # Example Claude Desktop config
+└── cursor_config.json          # Example Cursor config
+```

mcp/__init__.py

@@ -0,0 +1,10 @@
+"""
+Smriti MCP Server
+=================
+Model Context Protocol server for Smriti — Temporal AI Memory.
+Gives any MCP-compatible AI host (Claude, Cursor, VS Code, etc.)
+structured temporal memory powered by S-V-O causal event tuples.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Smriti / KAAL"

mcp/__main__.py

@@ -0,0 +1,51 @@
+"""
+Smriti MCP — CLI Entry Point
+=============================
+Run with: python -m smriti.mcp
+
+Supports:
+    python -m smriti.mcp                    → stdio transport (default)
+    python -m smriti.mcp --transport sse    → SSE transport
+    python -m smriti.mcp --port 3000        → Custom SSE port
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="smriti-mcp",
+        description="Smriti MCP Server — Temporal AI Memory for any MCP host",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse"],
+        default="stdio",
+        help="Transport protocol (default: stdio)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8080,
+        help="Port for SSE transport (default: 8080)",
+    )
+
+    args = parser.parse_args()
+
+    # Import here to avoid loading everything just for --help
+    from .server import run_server
+
+    try:
+        run_server(transport=args.transport, port=args.port)
+    except KeyboardInterrupt:
+        print("\nSmriti MCP server stopped.", file=sys.stderr)
+    except ValueError as e:
+        print(f"Configuration error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

mcp/claude_desktop_config.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "smriti": {
+      "command": "python",
+      "args": ["-m", "smriti.mcp"],
+      "cwd": "C:/path/to/smriti",
+      "env": {
+        "SMRITI_API_KEY": "chrn_your_api_key_here",
+        "SMRITI_SOURCE_ID": "my-project",
+        "SMRITI_SCOPE": "default"
+      }
+    }
+  }
+}

mcp/client.py

@@ -0,0 +1,277 @@
+"""
+Smriti MCP — HTTP Client
+=========================
+Async HTTP client that wraps the Smriti (KAAL) REST API.
+Handles authentication, retries, timeouts, and error mapping.
+
+All methods return plain Python dicts — the MCP server layer
+converts them to tool responses.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from datetime import datetime
+from typing import Any, Optional
+
+import httpx
+
+from .config import SmritiMCPConfig
+
+# All logging goes to stderr (MCP requirement — stdout is the JSON-RPC channel)
+logger = logging.getLogger("smriti.mcp.client")
+handler = logging.StreamHandler(sys.stderr)
+handler.setFormatter(logging.Formatter("%(asctime)s | %(name)s | %(levelname)s | %(message)s"))
+logger.addHandler(handler)
+logger.setLevel(logging.INFO)
+
+
+class SmritiAPIError(Exception):
+    """Raised when the Smriti API returns an error response."""
+
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"Smriti API error {status_code}: {detail}")
+
+
+class SmritiClient:
+    """
+    Async HTTP client for the Smriti (KAAL) temporal memory API.
+
+    Usage:
+        client = SmritiClient(config)
+        await client.connect()
+        result = await client.ingest("User started learning Rust")
+        await client.close()
+    """
+
+    def __init__(self, config: SmritiMCPConfig):
+        self.config = config
+        self._client: Optional[httpx.AsyncClient] = None
+
+    async def connect(self) -> None:
+        """Initialize the HTTP client with auth headers."""
+        self._client = httpx.AsyncClient(
+            base_url=self.config.base_url.rstrip("/"),
+            headers={
+                "X-API-Key": self.config.api_key,
+                "Content-Type": "application/json",
+                "User-Agent": "smriti-mcp/0.1.0",
+            },
+            timeout=httpx.Timeout(self.config.timeout_seconds),
+        )
+        logger.info(f"SmritiClient connected to {self.config.base_url}")
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+            logger.info("SmritiClient disconnected")
+
+    # ── Internal helpers ──────────────────────────────────────────────────────
+
+    def _ensure_connected(self) -> httpx.AsyncClient:
+        if self._client is None:
+            raise RuntimeError("SmritiClient not connected. Call connect() first.")
+        return self._client
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        json: dict | None = None,
+        params: dict | None = None,
+    ) -> dict[str, Any]:
+        """Make an HTTP request with retry logic."""
+        client = self._ensure_connected()
+        last_error: Exception | None = None
+
+        for attempt in range(1, self.config.max_retries + 1):
+            try:
+                response = await client.request(
+                    method=method,
+                    url=path,
+                    json=json,
+                    params=params,
+                )
+
+                if response.status_code == 200:
+                    return response.json()
+
+                # Non-retryable errors
+                if response.status_code in (400, 401, 403, 404, 409, 422):
+                    detail = self._extract_error_detail(response)
+                    raise SmritiAPIError(response.status_code, detail)
+
+                # Retryable errors (429, 500, 502, 503, 504)
+                detail = self._extract_error_detail(response)
+                last_error = SmritiAPIError(response.status_code, detail)
+                logger.warning(
+                    f"Retryable error (attempt {attempt}/{self.config.max_retries}): "
+                    f"{response.status_code} {detail}"
+                )
+
+            except httpx.TimeoutException as e:
+                last_error = e
+                logger.warning(
+                    f"Timeout (attempt {attempt}/{self.config.max_retries}): {e}"
+                )
+            except httpx.ConnectError as e:
+                last_error = e
+                logger.warning(
+                    f"Connection error (attempt {attempt}/{self.config.max_retries}): {e}"
+                )
+            except SmritiAPIError:
+                raise  # Non-retryable, already raised
+
+        # All retries exhausted
+        raise SmritiAPIError(
+            503,
+            f"All {self.config.max_retries} retries exhausted. Last error: {last_error}",
+        )
+
+    @staticmethod
+    def _extract_error_detail(response: httpx.Response) -> str:
+        """Extract a human-readable error message from an API response."""
+        try:
+            data = response.json()
+            return data.get("detail", str(data))
+        except Exception:
+            return response.text[:500]
+
+    # ── Public API methods ────────────────────────────────────────────────────
+
+    async def ingest(
+        self,
+        text: str,
+        source_id: str | None = None,
+        parse_svo: bool = True,
+        timestamp: str | None = None,
+        scope: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Ingest text into Smriti temporal memory.
+
+        The text is automatically decomposed into S-V-O (Subject-Verb-Object)
+        causal event tuples and stored with bi-temporal validity.
+
+        Args:
+            text: The memory to store (e.g., "User switched from React to Vue")
+            source_id: Namespace label for this memory source
+            parse_svo: Whether to extract S-V-O tuples (uses LLM)
+            timestamp: ISO timestamp override (default: now)
+            scope: Logical namespace (e.g., "work", "personal")
+            metadata: Additional metadata to attach to events
+
+        Returns:
+            Dict with ingested_count, event_ids, svo_tuples, turn_ids
+        """
+        event: dict[str, Any] = {"text": text}
+        if timestamp:
+            event["timestamp"] = timestamp
+        if metadata:
+            event["metadata"] = metadata
+        if scope:
+            event["scope"] = scope
+
+        payload = {
+            "source_id": source_id or self.config.source_id,
+            "events": [event],
+            "parse_svo": parse_svo,
+        }
+        if scope:
+            payload["scope"] = scope
+
+        return await self._request("POST", "/ingest", json=payload)
+
+    async def query(
+        self,
+        query: str,
+        max_results: int | None = None,
+        source_ids: list[str] | None = None,
+        time_range_start: str | None = None,
+        time_range_end: str | None = None,
+        scope: str | None = None,
+        semantic_weight: float = 0.5,
+    ) -> dict[str, Any]:
+        """
+        Search Smriti temporal memory with hybrid retrieval.
+
+        Uses a 3-phase pipeline:
+        1. Semantic search via pgvector (fuzzy recall)
+        2. Temporal filtering via PostgreSQL (deterministic time ranges)
+        3. Entity multi-hop (capitalized entity matching)
+
+        Args:
+            query: Natural language search query
+            max_results: Maximum results to return
+            source_ids: Filter by specific source namespaces
+            time_range_start: ISO timestamp for range start
+            time_range_end: ISO timestamp for range end
+            scope: Restrict to a specific scope
+            semantic_weight: Balance between semantic (1.0) and temporal (0.0)
+
+        Returns:
+            Dict with results (list of events), total_found, query_time_ms
+        """
+        payload: dict[str, Any] = {
+            "query": query,
+            "max_results": max_results or self.config.max_results,
+            "semantic_weight": semantic_weight,
+        }
+        if source_ids:
+            payload["source_ids"] = source_ids
+        if scope:
+            payload["scope"] = scope
+
+        if time_range_start or time_range_end:
+            time_range: dict[str, str] = {}
+            if time_range_start:
+                time_range["start"] = time_range_start
+            if time_range_end:
+                time_range["end"] = time_range_end
+            payload["time_range"] = time_range
+
+        return await self._request("POST", "/query", json=payload)
+
+    async def health(self) -> dict[str, Any]:
+        """
+        Check Smriti API health status.
+
+        Returns:
+            Dict with status, postgres_events count, pgvector_embeddings count
+        """
+        return await self._request("GET", "/health")
+
+    async def usage(self) -> dict[str, Any]:
+        """
+        Get current API usage statistics and tier limits.
+
+        Returns:
+            Dict with tier, usage (events/orchestration/connectors), limits
+        """
+        return await self._request("GET", "/billing/usage")
+
+    async def list_connectors(self) -> list[dict[str, Any]]:
+        """
+        List all registered SaaS tool connectors.
+
+        Returns:
+            List of connector dicts with id, name, description, endpoints_count
+        """
+        result = await self._request("GET", "/connectors")
+        # The API returns a list directly, not wrapped in an object
+        return result if isinstance(result, list) else []
+
+    async def root_health(self) -> dict[str, Any]:
+        """
+        Basic health check (GET /).
+
+        Returns:
+            Dict with service name, version, status
+        """
+        return await self._request("GET", "/")

mcp/config.py

@@ -0,0 +1,62 @@
+"""
+Smriti MCP — Configuration
+==========================
+All settings loaded from environment variables.
+Remote API mode only (HTTP client to deployed Smriti API).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class SmritiMCPConfig:
+    """Immutable configuration for the Smriti MCP server."""
+
+    # ── Required ──────────────────────────────────────────────────────────────
+    api_key: str = field(default="")
+
+    # ── API Connection ────────────────────────────────────────────────────────
+    base_url: str = field(default="https://spy9191-chronos-api-backend.hf.space")
+
+    # ── Defaults ──────────────────────────────────────────────────────────────
+    source_id: str = field(default="mcp-client")
+    scope: str = field(default="default")
+    max_results: int = field(default=20)
+    parse_svo: bool = field(default=True)
+
+    # ── HTTP Client ───────────────────────────────────────────────────────────
+    timeout_seconds: float = field(default=30.0)
+    max_retries: int = field(default=3)
+
+    def validate(self) -> None:
+        """Validate that all required config is present."""
+        if not self.api_key:
+            print(
+                "ERROR: SMRITI_API_KEY environment variable is required.\n"
+                "Get your free API key at: https://smriti-kaal.vercel.app\n"
+                "Then set it: export SMRITI_API_KEY=chrn_your_key_here",
+                file=sys.stderr,
+            )
+            raise ValueError("SMRITI_API_KEY is required but not set.")
+
+
+def load_config() -> SmritiMCPConfig:
+    """Load configuration from environment variables."""
+    config = SmritiMCPConfig(
+        api_key=os.getenv("SMRITI_API_KEY", ""),
+        base_url=os.getenv(
+            "SMRITI_BASE_URL",
+            "https://spy9191-chronos-api-backend.hf.space",
+        ),
+        source_id=os.getenv("SMRITI_SOURCE_ID", "mcp-client"),
+        scope=os.getenv("SMRITI_SCOPE", "default"),
+        max_results=int(os.getenv("SMRITI_MAX_RESULTS", "20")),
+        parse_svo=os.getenv("SMRITI_PARSE_SVO", "true").lower() in ("true", "1", "yes"),
+        timeout_seconds=float(os.getenv("SMRITI_TIMEOUT", "30.0")),
+        max_retries=int(os.getenv("SMRITI_MAX_RETRIES", "3")),
+    )
+    return config

mcp/cursor_config.json

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

mcp/requirements.txt

@@ -0,0 +1,4 @@
+# Smriti MCP Server — Dependencies
+mcp[cli]>=1.0.0
+httpx>=0.27.0
+python-dotenv>=1.0.0

mcp/server.py

@@ -0,0 +1,633 @@
+"""
+Smriti MCP Server
+=================
+Model Context Protocol server for Smriti — the Temporal AI Memory Layer.
+
+Exposes Smriti's S-V-O (Subject-Verb-Object) causal memory as MCP primitives:
+  • 6 Tools  — remember, recall, timeline, forget, health, usage
+  • 3 Resources — status, usage, config
+  • 3 Prompts — memory-chat, daily-recap, knowledge-extraction
+
+Runs over stdio (default) or SSE transport.
+Connect to any MCP host: Claude Desktop, Cursor, VS Code, Windsurf, etc.
+
+Usage:
+    python -m smriti.mcp                    # stdio (default)
+    python -m smriti.mcp --transport sse    # SSE on port 8080
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP, Context
+
+from .config import SmritiMCPConfig, load_config
+from .client import SmritiClient, SmritiAPIError
+
+# ── Logging (stderr only — stdout is the JSON-RPC channel) ────────────────────
+logger = logging.getLogger("smriti.mcp.server")
+handler = logging.StreamHandler(sys.stderr)
+handler.setFormatter(
+    logging.Formatter("%(asctime)s | %(name)s | %(levelname)s | %(message)s")
+)
+logger.addHandler(handler)
+logger.setLevel(logging.INFO)
+
+
+# ── Lifespan — initialize/teardown the HTTP client ────────────────────────────
+
+@asynccontextmanager
+async def smriti_lifespan(server):
+    """Manage SmritiClient lifecycle across the MCP server's lifetime."""
+    config = load_config()
+    config.validate()
+
+    client = SmritiClient(config)
+    await client.connect()
+
+    logger.info("Smriti MCP server initialized — temporal memory online")
+
+    yield {"client": client, "config": config}
+
+    await client.close()
+    logger.info("Smriti MCP server shut down")
+
+
+# ── FastMCP Server ────────────────────────────────────────────────────────────
+
+mcp_server = FastMCP(
+    "smriti",
+    version="0.1.0",
+    description=(
+        "Temporal AI Memory — Smriti gives your AI causal, structured memory. "
+        "Remember what happened, when, and why — powered by S-V-O event tuples "
+        "with bi-temporal validity on PostgreSQL + pgvector."
+    ),
+    lifespan=smriti_lifespan,
+)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# TOOLS — Model-controlled functions the LLM can invoke
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+@mcp_server.tool()
+async def smriti_remember(
+    text: str,
+    source_id: str | None = None,
+    parse_svo: bool = True,
+    timestamp: str | None = None,
+    scope: str | None = None,
+    ctx: Context = None,
+) -> str:
+    """Store a new memory in Smriti's temporal memory system.
+
+    The text is automatically decomposed into S-V-O (Subject-Verb-Object)
+    causal event tuples. For example:
+      "Alice quit her job at Google because she got an offer from OpenAI"
+    becomes:
+      [Alice] [quit] [her job at Google]
+      [Alice] [got] [an offer from OpenAI]
+
+    Old facts are automatically superseded when contradicted by new ones.
+    History is preserved (never deleted), just marked as superseded.
+
+    Args:
+        text: The memory to store. Can be a single fact, a paragraph,
+              or a full conversation snippet. Be descriptive.
+        source_id: Optional namespace label (e.g., "my-project", "work-notes").
+                   Memories from different sources are kept separate.
+        parse_svo: Whether to extract structured S-V-O tuples (default: true).
+                   Set to false for raw storage without decomposition.
+        timestamp: ISO 8601 timestamp of when this event occurred (e.g., "2026-07-15T10:30:00Z").
+                   Defaults to current time if not provided.
+        scope: Logical namespace for this memory (e.g., "work", "personal", "project-x").
+               Useful for organizing memories by context.
+    """
+    client: SmritiClient = ctx.request_context.lifespan_context["client"]
+
+    try:
+        result = await client.ingest(
+            text=text,
+            source_id=source_id,
+            parse_svo=parse_svo,
+            timestamp=timestamp,
+            scope=scope,
+        )
+
+        # Format a human-readable response
+        count = result.get("ingested_count", 0)
+        event_ids = result.get("event_ids", [])
+        svo_tuples = result.get("svo_tuples", [])
+
+        lines = [f"✅ Remembered {count} event(s)."]
+
+        if svo_tuples:
+            lines.append("\nExtracted S-V-O tuples:")
+            for svo in svo_tuples:
+                s = svo.get("subject", "?")
+                v = svo.get("verb", "?")
+                o = svo.get("object", "?")
+                conf = svo.get("confidence", 0)
+                lines.append(f"  [{s}] [{v}] [{o}]  (confidence: {conf:.0%})")
+
+        if event_ids:
+            lines.append(f"\nEvent IDs: {', '.join(event_ids[:5])}")
+            if len(event_ids) > 5:
+                lines.append(f"  ... and {len(event_ids) - 5} more")
+
+        return "\n".join(lines)
+
+    except SmritiAPIError as e:
+        return f"❌ Failed to store memory: {e.detail}"
+    except Exception as e:
+        logger.error(f"smriti_remember error: {e}", exc_info=True)
+        return f"❌ Unexpected error storing memory: {str(e)}"
+
+
+@mcp_server.tool()
+async def smriti_recall(
+    query: str,
+    max_results: int = 10,
+    source_id: str | None = None,
+    time_range_start: str | None = None,
+    time_range_end: str | None = None,
+    scope: str | None = None,
+    ctx: Context = None,
+) -> str:
+    """Search and retrieve memories from Smriti's temporal memory.
+
+    Uses a powerful 3-phase hybrid retrieval pipeline:
+    1. Semantic search — finds memories by meaning (pgvector cosine similarity)
+    2. Temporal filtering — finds memories within a time range
+    3. Entity multi-hop — follows entity connections across memories
+
+    Results are ranked by combined relevance score.
+
+    Args:
+        query: Natural language search query. Be descriptive for best results.
+               Examples: "What programming languages has the user learned?",
+                         "meetings about the product launch",
+                         "any changes to the database schema"
+        max_results: Maximum number of results to return (1-100, default: 10).
+        source_id: Filter by a specific source namespace.
+        time_range_start: ISO 8601 timestamp for the start of the time range
+                          (e.g., "2026-07-01T00:00:00Z"). Only memories after this time.
+        time_range_end: ISO 8601 timestamp for the end of the time range
+                        (e.g., "2026-07-15T23:59:59Z"). Only memories before this time.
+        scope: Restrict results to a specific scope (e.g., "work", "personal").
+    """
+    client: SmritiClient = ctx.request_context.lifespan_context["client"]
+
+    try:
+        source_ids = [source_id] if source_id else None
+        result = await client.query(
+            query=query,
+            max_results=max_results,
+            source_ids=source_ids,
+            time_range_start=time_range_start,
+            time_range_end=time_range_end,
+            scope=scope,
+        )
+
+        results = result.get("results", [])
+        total = result.get("total_found", 0)
+        query_ms = result.get("query_time_ms", 0)
+
+        if not results:
+            return f"No memories found matching: \"{query}\"\n(query took {query_ms:.0f}ms)"
+
+        lines = [f"Found {total} memory(ies) in {query_ms:.0f}ms:\n"]
+
+        for i, r in enumerate(results, 1):
+            event = r.get("event", {})
+            score = r.get("relevance_score", 0)
+            provenance = r.get("provenance", "unknown")
+
+            s = event.get("subject", "?")
+            v = event.get("verb", "?")
+            o = event.get("object", "?")
+            ts = event.get("timestamp", "")
+
+            # Format timestamp nicely if present
+            ts_display = ""
+            if ts:
+                try:
+                    dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+                    ts_display = dt.strftime("%Y-%m-%d %H:%M")
+                except (ValueError, AttributeError):
+                    ts_display = str(ts)[:16]
+
+            lines.append(
+                f"  {i}. [{s}] [{v}] [{o}]\n"
+                f"     📅 {ts_display}  |  relevance: {score:.2f}  |  via: {provenance}"
+            )
+
+        return "\n".join(lines)
+
+    except SmritiAPIError as e:
+        return f"❌ Failed to search memories: {e.detail}"
+    except Exception as e:
+        logger.error(f"smriti_recall error: {e}", exc_info=True)
+        return f"❌ Unexpected error searching memories: {str(e)}"
+
+
+@mcp_server.tool()
+async def smriti_timeline(
+    time_range_start: str,
+    time_range_end: str | None = None,
+    scope: str | None = None,
+    max_results: int = 20,
+    ctx: Context = None,
+) -> str:
+    """Retrieve a chronological timeline of events within a time range.
+
+    This is optimized for temporal queries — "What happened last week?",
+    "Show me everything from March 2026", "What did I do yesterday?"
+
+    Results are ordered chronologically (oldest first).
+
+    Args:
+        time_range_start: ISO 8601 timestamp for the start of the time range
+                          (e.g., "2026-07-01T00:00:00Z").
+        time_range_end: ISO 8601 timestamp for the end of the time range
+                        (e.g., "2026-07-15T23:59:59Z"). Defaults to current time.
+        scope: Restrict to a specific scope (e.g., "work", "personal").
+        max_results: Maximum number of events to return (default: 20).
+    """
+    client: SmritiClient = ctx.request_context.lifespan_context["client"]
+
+    try:
+        # Use a broad query to get temporal results — the API's temporal filter
+        # does the heavy lifting
+        end = time_range_end or datetime.now(timezone.utc).isoformat()
+
+        result = await client.query(
+            query="*",  # Broad query to let temporal filter dominate
+            max_results=max_results,
+            time_range_start=time_range_start,
+            time_range_end=end,
+            scope=scope,
+            semantic_weight=0.1,  # Minimize semantic, maximize temporal
+        )
+
+        results = result.get("results", [])
+
+        if not results:
+            return (
+                f"No events found between {time_range_start} and {end}.\n"
+                "Try expanding the time range or checking if events were stored."
+            )
+
+        lines = [
+            f"📅 Timeline: {time_range_start[:10]} → {end[:10]}",
+            f"   ({len(results)} event(s))\n",
+        ]
+
+        for r in results:
+            event = r.get("event", {})
+            s = event.get("subject", "?")
+            v = event.get("verb", "?")
+            o = event.get("object", "?")
+            ts = event.get("timestamp", "")
+
+            ts_display = ""
+            if ts:
+                try:
+                    dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+                    ts_display = dt.strftime("%b %d, %H:%M")
+                except (ValueError, AttributeError):
+                    ts_display = str(ts)[:16]
+
+            lines.append(f"  • {ts_display} — [{s}] [{v}] [{o}]")
+
+        return "\n".join(lines)
+
+    except SmritiAPIError as e:
+        return f"❌ Failed to retrieve timeline: {e.detail}"
+    except Exception as e:
+        logger.error(f"smriti_timeline error: {e}", exc_info=True)
+        return f"❌ Unexpected error retrieving timeline: {str(e)}"
+
+
+@mcp_server.tool()
+async def smriti_forget(
+    query: str,
+    scope: str | None = None,
+    max_to_forget: int = 5,
+    ctx: Context = None,
+) -> str:
+    """Find and mark memories as forgotten (superseded).
+
+    This does NOT delete memories — it marks them as superseded
+    (sets valid_to = now), preserving full history. The memories
+    will no longer appear in normal recall queries.
+
+    This is a two-step process:
+    1. First, call this tool to FIND memories matching the query
+    2. Review the results, then call smriti_remember with corrected facts
+
+    To truly "forget" something, store a superseding fact:
+      smriti_remember("User no longer uses React — switched to Vue")
+
+    Args:
+        query: Description of what to forget. Should match existing memories.
+        scope: Restrict to a specific scope.
+        max_to_forget: Maximum number of memories to find (safety limit, default: 5).
+    """
+    client: SmritiClient = ctx.request_context.lifespan_context["client"]
+
+    try:
+        result = await client.query(
+            query=query,
+            max_results=max_to_forget,
+            scope=scope,
+        )
+
+        results = result.get("results", [])
+
+        if not results:
+            return f"No memories found matching: \"{query}\"\nNothing to forget."
+
+        lines = [
+            f"Found {len(results)} memory(ies) matching \"{query}\":\n",
+            "To supersede these, store a corrected fact with smriti_remember.",
+            "Example: smriti_remember(\"User no longer uses React — switched to Vue\")\n",
+            "Matching memories:",
+        ]
+
+        for i, r in enumerate(results, 1):
+            event = r.get("event", {})
+            s = event.get("subject", "?")
+            v = event.get("verb", "?")
+            o = event.get("object", "?")
+            eid = event.get("id", "?")
+
+            lines.append(f"  {i}. [{s}] [{v}] [{o}]  (id: {eid[:8]}...)")
+
+        return "\n".join(lines)
+
+    except SmritiAPIError as e:
+        return f"❌ Failed to search for memories to forget: {e.detail}"
+    except Exception as e:
+        logger.error(f"smriti_forget error: {e}", exc_info=True)
+        return f"❌ Unexpected error: {str(e)}"
+
+
+@mcp_server.tool()
+async def smriti_health(ctx: Context = None) -> str:
+    """Check the health and status of the Smriti memory service.
+
+    Returns the service status, event counts, and vector embedding counts.
+    Useful for diagnosing connection issues or checking if the service is alive.
+    """
+    client: SmritiClient = ctx.request_context.lifespan_context["client"]
+
+    try:
+        # Try detailed health first, fall back to basic
+        try:
+            result = await client.health()
+        except SmritiAPIError:
+            result = await client.root_health()
+
+        status = result.get("status", "unknown")
+        stores = result.get("stores", {})
+
+        lines = [f"🏥 Smriti Health: {status.upper()}"]
+
+        if stores:
+            events = stores.get("postgres_events", "N/A")
+            vectors = stores.get("pgvector_embeddings", "N/A")
+            lines.append(f"   📊 Events stored: {events}")
+            lines.append(f"   🧮 Vector embeddings: {vectors}")
+
+        # Also include basic info if available
+        version = result.get("version", "")
+        if version:
+            lines.append(f"   📦 Version: {version}")
+
+        return "\n".join(lines)
+
+    except SmritiAPIError as e:
+        return f"❌ Health check failed: {e.detail}"
+    except Exception as e:
+        logger.error(f"smriti_health error: {e}", exc_info=True)
+        return f"❌ Cannot reach Smriti service: {str(e)}"
+
+
+@mcp_server.tool()
+async def smriti_usage(ctx: Context = None) -> str:
+    """Check your current Smriti API usage statistics and tier limits.
+
+    Shows events used/remaining, orchestration calls, connected tools,
+    and your current pricing tier (Explorer/Builder/Scale).
+    """
+    client: SmritiClient = ctx.request_context.lifespan_context["client"]
+
+    try:
+        result = await client.usage()
+
+        tier = result.get("tier", "unknown")
+        usage = result.get("usage", {})
+        limits = result.get("limits", {})
+
+        events = usage.get("events", {})
+        orch = usage.get("orchestration", {})
+        connectors = usage.get("connectors", {})
+
+        lines = [
+            f"📊 Smriti Usage — Tier: {tier.upper()}",
+            "",
+            f"  Events:        {events.get('used', 0):,} / {events.get('limit', 0):,}  "
+            f"({events.get('remaining', 0):,} remaining)",
+            f"  Orchestration: {orch.get('used', 0):,} / "
+            f"{'∞' if orch.get('limit', -1) == -1 else f'{orch.get(\"limit\", 0):,}'}  "
+            f"({'∞' if orch.get('remaining') == 'unlimited' else f'{orch.get(\"remaining\", 0):,}'} remaining)",
+            f"  Connectors:    {connectors.get('used', 0)} / "
+            f"{'∞' if connectors.get('limit', -1) == -1 else connectors.get('limit', 0)}",
+        ]
+
+        retention = limits.get("retention_days", 0)
+        lines.append(
+            f"\n  Retention: {'unlimited' if retention == -1 else f'{retention} days'}"
+        )
+
+        period = result.get("period_start", "")
+        if period:
+            lines.append(f"  Period start: {period[:10]}")
+
+        return "\n".join(lines)
+
+    except SmritiAPIError as e:
+        return f"❌ Failed to get usage stats: {e.detail}"
+    except Exception as e:
+        logger.error(f"smriti_usage error: {e}", exc_info=True)
+        return f"❌ Unexpected error fetching usage: {str(e)}"
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# RESOURCES — Read-only data the application can pull into context
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+@mcp_server.resource("smriti://status")
+async def resource_status() -> str:
+    """Live Smriti service health status and memory counts."""
+    config = load_config()
+    client = SmritiClient(config)
+    await client.connect()
+    try:
+        result = await client.health()
+        return json.dumps(result, indent=2, default=str)
+    except Exception as e:
+        return json.dumps({"status": "error", "detail": str(e)})
+    finally:
+        await client.close()
+
+
+@mcp_server.resource("smriti://usage")
+async def resource_usage() -> str:
+    """Current API usage statistics and tier limits."""
+    config = load_config()
+    client = SmritiClient(config)
+    await client.connect()
+    try:
+        result = await client.usage()
+        return json.dumps(result, indent=2, default=str)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+    finally:
+        await client.close()
+
+
+@mcp_server.resource("smriti://config")
+async def resource_config() -> str:
+    """Current MCP server configuration (non-sensitive fields only)."""
+    config = load_config()
+    return json.dumps(
+        {
+            "base_url": config.base_url,
+            "source_id": config.source_id,
+            "scope": config.scope,
+            "max_results": config.max_results,
+            "parse_svo": config.parse_svo,
+            "timeout_seconds": config.timeout_seconds,
+            "api_key_set": bool(config.api_key),
+        },
+        indent=2,
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# PROMPTS — User-selectable instruction templates
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+@mcp_server.prompt()
+async def memory_chat() -> str:
+    """System prompt for memory-augmented conversations.
+
+    Instructs the AI to naturally remember and recall information
+    during conversation, using smriti_remember and smriti_recall.
+    """
+    return (
+        "You are an AI assistant with persistent temporal memory powered by Smriti.\n\n"
+        "MEMORY GUIDELINES:\n"
+        "1. REMEMBER important facts: When the user shares preferences, decisions, "
+        "events, or key information, use smriti_remember to store it.\n"
+        "2. RECALL before answering: When the user asks about something that might "
+        "have been discussed before, use smriti_recall to check your memory first.\n"
+        "3. BE NATURAL: Don't announce every memory operation. Seamlessly weave "
+        "recalled context into your responses.\n"
+        "4. TEMPORAL AWARENESS: Note when things happened. Use timestamps and "
+        "time ranges to provide temporally accurate answers.\n"
+        "5. SUPERSESSION: When facts change (e.g., 'I switched from React to Vue'), "
+        "store the new fact — Smriti automatically supersedes the old one.\n\n"
+        "WHAT TO REMEMBER:\n"
+        "- User preferences and settings\n"
+        "- Important decisions and their reasoning\n"
+        "- Project milestones and status changes\n"
+        "- Technical choices and architecture decisions\n"
+        "- People, relationships, and roles mentioned\n"
+        "- Problems encountered and solutions found\n\n"
+        "WHAT NOT TO REMEMBER:\n"
+        "- Transient/throwaway questions\n"
+        "- Generic greetings or chitchat\n"
+        "- Information the user explicitly asks you to ignore\n"
+    )
+
+
+@mcp_server.prompt()
+async def daily_recap() -> str:
+    """Prompt template for generating a daily/weekly recap.
+
+    Uses smriti_timeline to pull events from a time range
+    and summarize what happened.
+    """
+    return (
+        "Generate a concise recap of recent events using Smriti's temporal memory.\n\n"
+        "INSTRUCTIONS:\n"
+        "1. Use smriti_timeline to retrieve events from the relevant time range.\n"
+        "2. Group events by theme or category (work, personal, learning, etc.).\n"
+        "3. Highlight key decisions, milestones, and changes.\n"
+        "4. Note any superseded facts (things that changed).\n"
+        "5. Format as a clean, scannable summary.\n\n"
+        "SUGGESTED TIME RANGES:\n"
+        "- Daily recap: last 24 hours\n"
+        "- Weekly recap: last 7 days\n"
+        "- Monthly recap: last 30 days\n\n"
+        "Start by asking the user what time range they'd like to review, "
+        "or default to the last 24 hours.\n"
+    )
+
+
+@mcp_server.prompt()
+async def knowledge_extraction() -> str:
+    """Prompt for bulk knowledge ingestion from documents or conversations.
+
+    Instructs the AI to read content and extract key facts into memory
+    using smriti_remember.
+    """
+    return (
+        "You are a knowledge extraction assistant powered by Smriti temporal memory.\n\n"
+        "INSTRUCTIONS:\n"
+        "1. Read the provided content carefully.\n"
+        "2. Identify key facts, events, decisions, and relationships.\n"
+        "3. For each significant piece of information, use smriti_remember to store it.\n"
+        "4. Use descriptive text that captures the WHO, WHAT, WHEN, and WHY.\n"
+        "5. Set appropriate timestamps if dates are mentioned in the content.\n"
+        "6. Use scopes to organize by topic (e.g., 'project-x', 'meeting-notes').\n\n"
+        "EXTRACTION PRIORITIES:\n"
+        "- Decisions and their rationale\n"
+        "- Action items and deadlines\n"
+        "- Key metrics and numbers\n"
+        "- People and their roles/responsibilities\n"
+        "- Status changes and milestones\n"
+        "- Technical specifications and constraints\n\n"
+        "After extraction, provide a summary of what was stored.\n"
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Server runner (used by __main__.py)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def run_server(transport: str = "stdio", port: int = 8080) -> None:
+    """Run the MCP server with the specified transport."""
+    logger.info(f"Starting Smriti MCP server (transport={transport})")
+
+    if transport == "stdio":
+        mcp_server.run(transport="stdio")
+    elif transport == "sse":
+        mcp_server.run(transport="sse", port=port)
+    else:
+        logger.error(f"Unknown transport: {transport}")
+        raise ValueError(f"Unsupported transport: {transport}. Use 'stdio' or 'sse'.")

tests/test_mcp_client.py

@@ -0,0 +1,329 @@
+"""
+Smriti MCP — HTTP Client Tests
+================================
+Tests for the SmritiClient HTTP wrapper.
+Uses httpx mock transport to avoid real API calls.
+"""
+
+from __future__ import annotations
+
+import json
+import pytest
+import httpx
+
+# ── Adjust import path ───────────────────────────────────────────────────────
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from mcp.config import SmritiMCPConfig, load_config
+from mcp.client import SmritiClient, SmritiAPIError
+
+
+# ── Fixtures ──────────────────────────────────────────────────────────────────
+
+def make_config(**overrides) -> SmritiMCPConfig:
+    defaults = dict(
+        api_key="chrn_test_key_123",
+        base_url="https://test-api.smriti.dev",
+        source_id="test-source",
+        scope="default",
+        max_results=10,
+        parse_svo=True,
+        timeout_seconds=5.0,
+        max_retries=1,
+    )
+    defaults.update(overrides)
+    return SmritiMCPConfig(**defaults)
+
+
+def mock_transport(responses: dict[str, httpx.Response]) -> httpx.MockTransport:
+    """Create a mock transport that returns canned responses by path."""
+    def handler(request: httpx.Request) -> httpx.Response:
+        path = request.url.path
+        if path in responses:
+            return responses[path]
+        return httpx.Response(404, json={"detail": f"Not found: {path}"})
+    return httpx.MockTransport(handler)
+
+
+# ── Config Tests ──────────────────────────────────────────────────────────────
+
+class TestConfig:
+    def test_load_defaults(self, monkeypatch):
+        monkeypatch.delenv("SMRITI_API_KEY", raising=False)
+        monkeypatch.delenv("SMRITI_BASE_URL", raising=False)
+        config = load_config()
+        assert config.api_key == ""
+        assert "hf.space" in config.base_url
+        assert config.source_id == "mcp-client"
+
+    def test_load_from_env(self, monkeypatch):
+        monkeypatch.setenv("SMRITI_API_KEY", "chrn_env_key")
+        monkeypatch.setenv("SMRITI_BASE_URL", "https://custom.api.dev")
+        monkeypatch.setenv("SMRITI_SOURCE_ID", "my-source")
+        monkeypatch.setenv("SMRITI_MAX_RESULTS", "50")
+        monkeypatch.setenv("SMRITI_PARSE_SVO", "false")
+        config = load_config()
+        assert config.api_key == "chrn_env_key"
+        assert config.base_url == "https://custom.api.dev"
+        assert config.source_id == "my-source"
+        assert config.max_results == 50
+        assert config.parse_svo is False
+
+    def test_validate_missing_key(self):
+        config = SmritiMCPConfig(api_key="")
+        with pytest.raises(ValueError, match="SMRITI_API_KEY"):
+            config.validate()
+
+    def test_validate_with_key(self):
+        config = SmritiMCPConfig(api_key="chrn_valid_key")
+        config.validate()  # Should not raise
+
+
+# ── Client Tests ──────────────────────────────────────────────────────────────
+
+class TestSmritiClient:
+
+    @pytest.mark.asyncio
+    async def test_ingest_success(self):
+        config = make_config()
+        client = SmritiClient(config)
+
+        response_data = {
+            "ingested_count": 2,
+            "event_ids": ["evt_abc", "evt_def"],
+            "svo_tuples": [
+                {"subject": "User", "verb": "learned", "object": "Rust", "confidence": 0.95}
+            ],
+            "turn_ids": ["turn_001"],
+        }
+
+        transport = mock_transport({
+            "/ingest": httpx.Response(200, json=response_data),
+        })
+        client._client = httpx.AsyncClient(
+            base_url=config.base_url, transport=transport
+        )
+
+        result = await client.ingest("User started learning Rust last week")
+        assert result["ingested_count"] == 2
+        assert len(result["event_ids"]) == 2
+        assert result["svo_tuples"][0]["subject"] == "User"
+
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_query_success(self):
+        config = make_config()
+        client = SmritiClient(config)
+
+        response_data = {
+            "results": [
+                {
+                    "event": {
+                        "id": "evt_abc",
+                        "source_id": "test",
+                        "subject": "User",
+                        "verb": "learned",
+                        "object": "Rust",
+                        "timestamp": "2026-07-15T10:00:00Z",
+                        "confidence": 0.95,
+                    },
+                    "relevance_score": 0.87,
+                    "provenance": "semantic_search",
+                }
+            ],
+            "total_found": 1,
+            "query_time_ms": 42.5,
+        }
+
+        transport = mock_transport({
+            "/query": httpx.Response(200, json=response_data),
+        })
+        client._client = httpx.AsyncClient(
+            base_url=config.base_url, transport=transport
+        )
+
+        result = await client.query("What has the user learned?")
+        assert result["total_found"] == 1
+        assert result["results"][0]["event"]["subject"] == "User"
+
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_health_success(self):
+        config = make_config()
+        client = SmritiClient(config)
+
+        response_data = {
+            "status": "healthy",
+            "stores": {
+                "postgres_events": 1234,
+                "pgvector_embeddings": 1200,
+            },
+        }
+
+        transport = mock_transport({
+            "/health": httpx.Response(200, json=response_data),
+        })
+        client._client = httpx.AsyncClient(
+            base_url=config.base_url, transport=transport
+        )
+
+        result = await client.health()
+        assert result["status"] == "healthy"
+        assert result["stores"]["postgres_events"] == 1234
+
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_usage_success(self):
+        config = make_config()
+        client = SmritiClient(config)
+
+        response_data = {
+            "source_id": "test",
+            "tier": "explorer",
+            "usage": {
+                "events": {"used": 500, "limit": 10000, "remaining": 9500},
+                "orchestration": {"used": 10, "limit": 1000, "remaining": 990},
+                "connectors": {"used": 1, "limit": 3},
+            },
+            "limits": {"retention_days": 30},
+            "period_start": "2026-07-01T00:00:00Z",
+        }
+
+        transport = mock_transport({
+            "/billing/usage": httpx.Response(200, json=response_data),
+        })
+        client._client = httpx.AsyncClient(
+            base_url=config.base_url, transport=transport
+        )
+
+        result = await client.usage()
+        assert result["tier"] == "explorer"
+        assert result["usage"]["events"]["used"] == 500
+
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_auth_error_not_retried(self):
+        config = make_config(max_retries=3)
+        client = SmritiClient(config)
+
+        transport = mock_transport({
+            "/health": httpx.Response(401, json={"detail": "Invalid API key"}),
+        })
+        client._client = httpx.AsyncClient(
+            base_url=config.base_url, transport=transport
+        )
+
+        with pytest.raises(SmritiAPIError) as exc_info:
+            await client.health()
+        assert exc_info.value.status_code == 401
+        assert "Invalid API key" in exc_info.value.detail
+
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_quota_error(self):
+        config = make_config()
+        client = SmritiClient(config)
+
+        transport = mock_transport({
+            "/ingest": httpx.Response(
+                429, json={"detail": "Event quota exceeded (10000/10000)"}
+            ),
+        })
+        client._client = httpx.AsyncClient(
+            base_url=config.base_url, transport=transport
+        )
+
+        with pytest.raises(SmritiAPIError) as exc_info:
+            await client.ingest("test")
+        assert exc_info.value.status_code == 429
+
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_connectors_success(self):
+        config = make_config()
+        client = SmritiClient(config)
+
+        response_data = [
+            {
+                "id": "conn_001",
+                "name": "Stripe",
+                "description": "Payment API",
+                "base_url": "https://api.stripe.com",
+                "endpoints_count": 3,
+                "created_at": "2026-07-01T00:00:00Z",
+            }
+        ]
+
+        transport = mock_transport({
+            "/connectors": httpx.Response(200, json=response_data),
+        })
+        client._client = httpx.AsyncClient(
+            base_url=config.base_url, transport=transport
+        )
+
+        result = await client.list_connectors()
+        assert len(result) == 1
+        assert result[0]["name"] == "Stripe"
+
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_query_with_time_range(self):
+        config = make_config()
+        client = SmritiClient(config)
+
+        transport = mock_transport({
+            "/query": httpx.Response(200, json={
+                "results": [], "total_found": 0, "query_time_ms": 5.0
+            }),
+        })
+        client._client = httpx.AsyncClient(
+            base_url=config.base_url, transport=transport
+        )
+
+        result = await client.query(
+            "meetings",
+            time_range_start="2026-07-01T00:00:00Z",
+            time_range_end="2026-07-15T23:59:59Z",
+        )
+        assert result["total_found"] == 0
+
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_not_connected_error(self):
+        config = make_config()
+        client = SmritiClient(config)
+        # Don't call connect()
+
+        with pytest.raises(RuntimeError, match="not connected"):
+            await client.health()
+
+    @pytest.mark.asyncio
+    async def test_connect_and_close(self):
+        config = make_config()
+        client = SmritiClient(config)
+
+        await client.connect()
+        assert client._client is not None
+
+        await client.close()
+        assert client._client is None
+
+    @pytest.mark.asyncio
+    async def test_auth_header_set(self):
+        config = make_config(api_key="chrn_my_secret_key")
+        client = SmritiClient(config)
+        await client.connect()
+
+        assert client._client.headers["X-API-Key"] == "chrn_my_secret_key"
+        assert "smriti-mcp" in client._client.headers["User-Agent"]
+
+        await client.close()

tests/test_mcp_server.py

@@ -0,0 +1,408 @@
+"""
+Smriti MCP — Server Tests
+===========================
+Tests for MCP tools, resources, and prompts.
+Uses mocked SmritiClient to avoid real API calls.
+"""
+
+from __future__ import annotations
+
+import json
+import pytest
+from unittest.mock import AsyncMock, MagicMock, patch
+
+# ── Adjust import path ───────────────────────────────────────────────────────
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from mcp.client import SmritiClient, SmritiAPIError
+from mcp.config import SmritiMCPConfig
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def make_mock_context(client: SmritiClient) -> MagicMock:
+    """Create a mock MCP Context with a SmritiClient in the lifespan context."""
+    ctx = MagicMock()
+    ctx.request_context.lifespan_context = {"client": client}
+    return ctx
+
+
+def make_mock_client() -> SmritiClient:
+    """Create a SmritiClient with all methods mocked."""
+    config = SmritiMCPConfig(api_key="chrn_test_key")
+    client = SmritiClient(config)
+    client.ingest = AsyncMock()
+    client.query = AsyncMock()
+    client.health = AsyncMock()
+    client.root_health = AsyncMock()
+    client.usage = AsyncMock()
+    client.list_connectors = AsyncMock()
+    return client
+
+
+# ── Tool Tests ────────────────────────────────────────────────────────────────
+
+class TestSmritiRemember:
+    @pytest.mark.asyncio
+    async def test_remember_success(self):
+        from mcp.server import smriti_remember
+
+        client = make_mock_client()
+        client.ingest.return_value = {
+            "ingested_count": 1,
+            "event_ids": ["evt_abc123"],
+            "svo_tuples": [
+                {"subject": "Alice", "verb": "quit", "object": "her job at Google", "confidence": 0.92}
+            ],
+            "turn_ids": ["turn_001"],
+        }
+
+        ctx = make_mock_context(client)
+        result = await smriti_remember(
+            text="Alice quit her job at Google",
+            ctx=ctx,
+        )
+
+        assert "Remembered 1 event" in result
+        assert "[Alice]" in result
+        assert "[quit]" in result
+        assert "confidence: 92%" in result
+        client.ingest.assert_awaited_once()
+
+    @pytest.mark.asyncio
+    async def test_remember_with_options(self):
+        from mcp.server import smriti_remember
+
+        client = make_mock_client()
+        client.ingest.return_value = {
+            "ingested_count": 1,
+            "event_ids": ["evt_def456"],
+            "svo_tuples": [],
+            "turn_ids": ["turn_002"],
+        }
+
+        ctx = make_mock_context(client)
+        result = await smriti_remember(
+            text="Daily standup meeting",
+            source_id="work-calendar",
+            parse_svo=False,
+            scope="work",
+            timestamp="2026-07-15T09:00:00Z",
+            ctx=ctx,
+        )
+
+        assert "Remembered 1 event" in result
+        call_kwargs = client.ingest.call_args.kwargs
+        assert call_kwargs["source_id"] == "work-calendar"
+        assert call_kwargs["parse_svo"] is False
+        assert call_kwargs["scope"] == "work"
+
+    @pytest.mark.asyncio
+    async def test_remember_api_error(self):
+        from mcp.server import smriti_remember
+
+        client = make_mock_client()
+        client.ingest.side_effect = SmritiAPIError(429, "Event quota exceeded")
+
+        ctx = make_mock_context(client)
+        result = await smriti_remember(text="test", ctx=ctx)
+
+        assert "❌" in result
+        assert "quota" in result.lower()
+
+
+class TestSmritiRecall:
+    @pytest.mark.asyncio
+    async def test_recall_with_results(self):
+        from mcp.server import smriti_recall
+
+        client = make_mock_client()
+        client.query.return_value = {
+            "results": [
+                {
+                    "event": {
+                        "id": "evt_abc",
+                        "source_id": "test",
+                        "subject": "User",
+                        "verb": "learned",
+                        "object": "Rust",
+                        "timestamp": "2026-07-15T10:00:00Z",
+                        "confidence": 0.95,
+                    },
+                    "relevance_score": 0.87,
+                    "provenance": "semantic_search",
+                }
+            ],
+            "total_found": 1,
+            "query_time_ms": 42.5,
+        }
+
+        ctx = make_mock_context(client)
+        result = await smriti_recall(query="programming languages", ctx=ctx)
+
+        assert "Found 1 memory" in result
+        assert "[User]" in result
+        assert "[learned]" in result
+        assert "[Rust]" in result
+        assert "42ms" in result
+
+    @pytest.mark.asyncio
+    async def test_recall_no_results(self):
+        from mcp.server import smriti_recall
+
+        client = make_mock_client()
+        client.query.return_value = {
+            "results": [],
+            "total_found": 0,
+            "query_time_ms": 5.0,
+        }
+
+        ctx = make_mock_context(client)
+        result = await smriti_recall(query="quantum physics", ctx=ctx)
+
+        assert "No memories found" in result
+
+    @pytest.mark.asyncio
+    async def test_recall_with_filters(self):
+        from mcp.server import smriti_recall
+
+        client = make_mock_client()
+        client.query.return_value = {
+            "results": [], "total_found": 0, "query_time_ms": 3.0
+        }
+
+        ctx = make_mock_context(client)
+        await smriti_recall(
+            query="meetings",
+            max_results=5,
+            source_id="work",
+            time_range_start="2026-07-01T00:00:00Z",
+            time_range_end="2026-07-15T23:59:59Z",
+            scope="work",
+            ctx=ctx,
+        )
+
+        call_kwargs = client.query.call_args.kwargs
+        assert call_kwargs["max_results"] == 5
+        assert call_kwargs["source_ids"] == ["work"]
+        assert call_kwargs["time_range_start"] == "2026-07-01T00:00:00Z"
+        assert call_kwargs["scope"] == "work"
+
+
+class TestSmritiTimeline:
+    @pytest.mark.asyncio
+    async def test_timeline_with_events(self):
+        from mcp.server import smriti_timeline
+
+        client = make_mock_client()
+        client.query.return_value = {
+            "results": [
+                {
+                    "event": {
+                        "id": "evt_1",
+                        "source_id": "test",
+                        "subject": "Team",
+                        "verb": "deployed",
+                        "object": "v2.0",
+                        "timestamp": "2026-07-10T14:00:00Z",
+                        "confidence": 0.9,
+                    },
+                    "relevance_score": 0.8,
+                    "provenance": "temporal_filter",
+                }
+            ],
+            "total_found": 1,
+            "query_time_ms": 20.0,
+        }
+
+        ctx = make_mock_context(client)
+        result = await smriti_timeline(
+            time_range_start="2026-07-01T00:00:00Z",
+            time_range_end="2026-07-15T23:59:59Z",
+            ctx=ctx,
+        )
+
+        assert "Timeline" in result
+        assert "[Team]" in result
+        assert "[deployed]" in result
+
+    @pytest.mark.asyncio
+    async def test_timeline_empty(self):
+        from mcp.server import smriti_timeline
+
+        client = make_mock_client()
+        client.query.return_value = {
+            "results": [], "total_found": 0, "query_time_ms": 3.0,
+        }
+
+        ctx = make_mock_context(client)
+        result = await smriti_timeline(
+            time_range_start="2020-01-01T00:00:00Z",
+            ctx=ctx,
+        )
+
+        assert "No events found" in result
+
+
+class TestSmritiForget:
+    @pytest.mark.asyncio
+    async def test_forget_finds_matches(self):
+        from mcp.server import smriti_forget
+
+        client = make_mock_client()
+        client.query.return_value = {
+            "results": [
+                {
+                    "event": {
+                        "id": "evt_old_fact",
+                        "source_id": "test",
+                        "subject": "User",
+                        "verb": "uses",
+                        "object": "React",
+                        "timestamp": "2026-06-01T00:00:00Z",
+                        "confidence": 0.9,
+                    },
+                    "relevance_score": 0.8,
+                    "provenance": "semantic_search",
+                }
+            ],
+            "total_found": 1,
+            "query_time_ms": 10.0,
+        }
+
+        ctx = make_mock_context(client)
+        result = await smriti_forget(query="User uses React", ctx=ctx)
+
+        assert "Found 1 memory" in result
+        assert "smriti_remember" in result
+        assert "[User]" in result
+
+    @pytest.mark.asyncio
+    async def test_forget_no_matches(self):
+        from mcp.server import smriti_forget
+
+        client = make_mock_client()
+        client.query.return_value = {
+            "results": [], "total_found": 0, "query_time_ms": 5.0,
+        }
+
+        ctx = make_mock_context(client)
+        result = await smriti_forget(query="nonexistent fact", ctx=ctx)
+
+        assert "No memories found" in result
+        assert "Nothing to forget" in result
+
+
+class TestSmritiHealth:
+    @pytest.mark.asyncio
+    async def test_health_success(self):
+        from mcp.server import smriti_health
+
+        client = make_mock_client()
+        client.health.return_value = {
+            "status": "healthy",
+            "stores": {
+                "postgres_events": 5000,
+                "pgvector_embeddings": 4800,
+            },
+        }
+
+        ctx = make_mock_context(client)
+        result = await smriti_health(ctx=ctx)
+
+        assert "HEALTHY" in result
+        assert "5000" in result
+        assert "4800" in result
+
+    @pytest.mark.asyncio
+    async def test_health_fallback(self):
+        from mcp.server import smriti_health
+
+        client = make_mock_client()
+        client.health.side_effect = SmritiAPIError(500, "Internal error")
+        client.root_health.return_value = {
+            "service": "KAAL",
+            "version": "0.2.0",
+            "status": "operational",
+        }
+
+        ctx = make_mock_context(client)
+        result = await smriti_health(ctx=ctx)
+
+        assert "OPERATIONAL" in result
+        assert "0.2.0" in result
+
+
+class TestSmritiUsage:
+    @pytest.mark.asyncio
+    async def test_usage_success(self):
+        from mcp.server import smriti_usage
+
+        client = make_mock_client()
+        client.usage.return_value = {
+            "source_id": "test",
+            "tier": "explorer",
+            "usage": {
+                "events": {"used": 500, "limit": 10000, "remaining": 9500},
+                "orchestration": {"used": 10, "limit": 1000, "remaining": 990},
+                "connectors": {"used": 1, "limit": 3},
+            },
+            "limits": {"retention_days": 30},
+            "period_start": "2026-07-01T00:00:00Z",
+        }
+
+        ctx = make_mock_context(client)
+        result = await smriti_usage(ctx=ctx)
+
+        assert "EXPLORER" in result
+        assert "500" in result
+        assert "10,000" in result
+        assert "30 days" in result
+
+
+# ── Resource Tests ────────────────────────────────────────────────────────────
+
+class TestResources:
+    @pytest.mark.asyncio
+    async def test_config_resource(self):
+        from mcp.server import resource_config
+
+        with patch.dict(os.environ, {
+            "SMRITI_API_KEY": "chrn_test",
+            "SMRITI_SOURCE_ID": "test-src",
+        }):
+            result = await resource_config()
+            data = json.loads(result)
+            assert data["source_id"] == "test-src"
+            assert data["api_key_set"] is True
+            assert "api_key" not in data  # Should NOT expose the actual key
+
+
+# ── Prompt Tests ──────────────────────────────────────────────────────────────
+
+class TestPrompts:
+    @pytest.mark.asyncio
+    async def test_memory_chat_prompt(self):
+        from mcp.server import memory_chat
+
+        result = await memory_chat()
+        assert "smriti_remember" in result
+        assert "smriti_recall" in result
+        assert "REMEMBER" in result
+
+    @pytest.mark.asyncio
+    async def test_daily_recap_prompt(self):
+        from mcp.server import daily_recap
+
+        result = await daily_recap()
+        assert "smriti_timeline" in result
+        assert "recap" in result.lower()
+
+    @pytest.mark.asyncio
+    async def test_knowledge_extraction_prompt(self):
+        from mcp.server import knowledge_extraction
+
+        result = await knowledge_extraction()
+        assert "smriti_remember" in result
+        assert "extraction" in result.lower()