Torqon Documentation

Introduction

Every message you send passes through a 6-stage pipeline: intent classification, context optimization, vector retrieval, context assembly, LLM generation, and async memory extraction. The retrieval and assembly stages add less than 10ms to your p95. Memory extraction runs fully async — it never blocks a response.

Quickstart

Get persistent memory in your Claude Desktop setup in under 2 minutes. You need an API key from the dashboard — free tier requires no credit card.

// Add this to your existing mcpServers block
{
  "mcpServers": {
    "torqon": {
      "command": "npx",
      "args": ["-y", "@torqon/mcp@latest"],
      "env": {
        "TORQON_API_KEY": "tq_live_your_key_here"
      }
    }
  }
}

You:   I’m building a Next.js 14 app called Torqon with pgvector on Railway.
        We never use mocks in tests. Always a real database.

Claude: Got it. I’ve noted your stack and testing preference.

---  3 days later, new conversation ---

You:   How should I write the migration script?

Claude: For your Railway + pgvector setup, you’ll want to...
        ? Claude remembered your stack from 3 days ago

Integration Paths

MCP Server

The easiest path. The MCP server exposes store_memory, retrieve_context, and auto_process tools that Claude calls automatically based on conversation content.

REST API

Call Torqon directly from any HTTP client. All endpoints live at https://api.torqon.dev. Authenticate with an API key header on every request.

# Store a fact
curl -X POST https://api.torqon.dev/chat \
  -H "X-Api-Key: tq_live_••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "My project is called Helios. We use Rust for the backend.",
    "conversationId": "user-session-001",
    "storeOnly": true
  }'

# Ask a question — memory auto-retrieved
curl -X POST https://api.torqon.dev/chat \
  -H "X-Api-Key: tq_live_••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What language are we using for the backend?",
    "conversationId": "user-session-001"
  }'

Authentication

All endpoints except GET /, GET /health, and POST /auth/register require an API key. Pass it in the X-Api-Key header.

POST /chat
X-Api-Key: tq_live_abc123
Content-Type: application/json

{"message": "..."}

POST /chat
Content-Type: application/json

{"message": "..."}

→ {"error":"Missing X-Api-Key header.
    Register at /auth/register"}

POST /chat

The core endpoint. Runs the full pipeline: intent classification → context optimization → memory retrieval → context assembly → LLM generation → async memory extraction. Returns the LLM response with a trace ID for debugging.

Request Body

Response

{
  "response": {
    "content": "You're using Rust for the Helios backend.",
    "usage": {
      "promptTokens": 312,
      "completionTokens": 47,
      "totalTokens": 359
    }
  },
  "traceId": "trace_a1b2c3d4",
  "evaluation": {
    "baselineTokens": 1840,
    "optimizedTokens": 312,
    "tokenSavings": 83.0,
    "memoryUsed": 3,
    "avgSimilarity": 0.87,
    "latencyMs": 641
  }
}

Error codes

POST /auth/register

Creates a new user account and returns an API key. No authentication required. This is the only unauthenticated write endpoint.

{
  "email": "you@example.com",
  "name": "Your Name"
}

{
  "apiKey": "tq_live_abc123...",
  "userId": "usr_xyz",
  "plan": "free"
}

GET /health

Health check endpoint. No authentication required. Use this to verify the API is reachable before sending requests.

{
  "status": "ok",
  "uptime": 48293
}

Request Pipeline

Every call to POST /chat runs through six stages. Stages 1–5 are synchronous and complete before the response is returned. Stage 6 (memory extraction) is fully asynchronous and never blocks.

Memory Model

Torqon does not store conversation history. It extracts the smallest independently reusable unit of knowledge — an atomic fact — and stores each one as a separate embedding. This means retrieval precision holds even as your fact store grows to thousands of entries.

Storage schema

CREATE TABLE facts (
  id              UUID       PRIMARY KEY,
  user_id         TEXT       NOT NULL,
  conversation_id TEXT       NOT NULL,
  content         TEXT       NOT NULL,
  fact_type       TEXT       NOT NULL,
  embedding       VECTOR(1536),
  is_current_fact BOOLEAN    DEFAULT true,
  confidence      FLOAT,
  created_at      TIMESTAMPTZ DEFAULT now()
);

-- pgvector cosine distance index
CREATE INDEX facts_embedding_idx
  ON facts USING ivfflat (embedding vector_cosine_ops)
  WITH (lists = 100);

Fact Types

Every stored fact is tagged with a type. Types inform retrieval priority and how the fact is presented in the assembled context. Torqon auto-classifies fact type during extraction.

Content Optimizer

Messages longer than 30 tokens are compressed before being passed to retrieval and the LLM. The optimizer detects content type and routes to the appropriate compressor — only prose reaches the LLM compressor, so JSON and code compression adds under 5ms.

Real example — prose compression

Retrieval System

Retrieval is a single pgvector cosine similarity query. There is no re-ranking model, no BM25 hybrid, no post-processing — just one fast query filtered and sorted by similarity score. This keeps p95 latency under 8ms.

SELECT
  id,
  content,
  fact_type,
  1 - (embedding <=> $1) AS similarity
FROM  facts
WHERE user_id = $2
  AND  is_current_fact = true
  AND  1 - (embedding <=> $1) > 0.72   -- similarity floor
ORDER BY similarity DESC
LIMIT 12;                               -- top-K cap

What the similarity threshold means in practice

CacheAligner

LLM providers like Anthropic and OpenAI cache prompt prefixes — if the start of your prompt is identical across requests, they skip re-processing it and charge you less. CacheAligner keeps the system prompt stable across every request so the prefix cache always hits.

System: "You are a helpful assistant.
The user's name is Alice. They are
building Helios on Next.js..."

↑ System prompt changes every request.
  Provider re-processes from scratch.
  You pay full input tokens every time.

System: "You are a precise, concise
assistant. When verified facts are
provided, answer from them directly."

User: "[VERIFIED FACTS]
name: Alice
tech_stack: Next.js 14, pgvector

[QUESTION]
How should I write the migration?"

↑ System prompt never changes.
  Facts move into the user message.
  Provider caches the prefix. Cheaper.

The assembled user message format is always: [VERIFIED FACTS]\n{facts}\n\n[QUESTION]\n{message} when facts were retrieved, or just {message} when no facts matched. The system prompt is the same single string on every call, regardless of facts retrieved.

Observability

Every request returns an evaluation block with token accounting and retrieval quality metrics. Detailed traces are available from the dashboard.

Plans & Limits

Quotas reset on the first of each calendar month. Exceeding a quota returns a 429 with the quota type specified in the error body.

Roadmap