Skip to content
contexta
Official Developer Documentation

Documentation.

Complete guides, SDK quickstarts, REST API specifications, and architectural rules for deploying Contexta as your agent's sovereign memory plane.

GitHub RepositoryInteractive Memory Lab→
Section // getting-started

Getting Started

Local-First Quickstart

Boot the complete offline memory plane (Go gateway on :8080, FastAPI cortex, Qwen3 model server on :8001, and PostgreSQL pgvector) with standard Docker Compose or native scripts.

bash
# Clone and start the sovereign offline-first stack:
git clone https://github.com/Aethlon/Contexta.git
cd Contexta

# macOS & Linux:
./entrypoint.sh

# Windows (PowerShell):
.\start.ps1

# Stack boots:
# - Go High-Throughput Gateway: http://localhost:8080
# - Qwen3 Micro-Batched Server: http://localhost:8001
# - Operator Inspector Console: http://localhost:3000

Core Architectural Invariants

Contexta adheres to strict sovereign design rules: zero cloud API key requirements, hard tenant isolation at the PostgreSQL kernel, automatic secret redaction, and no billing/metering code.

Section // sdks

Client SDKs

Python SDK (contexta-ai)

Lightweight client library centered on two ergonomic calls: observe() to record turns with automatic credential redaction, and context() to fetch compressed memory in sub-50ms.

python
pip install contexta-ai

from contexta import Contexta

# Connect to sovereign local gateway or remote data-plane
memory = Contexta(url="http://localhost:8080", org_id="org_default")

# 1. Observe interaction (synchronously sanitized before persistence)
memory.observe(
    user_id="usr_42",
    messages=[
        {"role": "user", "content": "I prefer PostgreSQL 16 on port 5432."},
        {"role": "assistant", "content": "Understood. Configured PostgreSQL 16."}
    ]
)

# 2. Retrieve fused context within tight prompt token budget
prompt_context = memory.context(
    user_id="usr_42",
    query="What database engine and port should I connect to?",
    token_budget=300
)

print(prompt_context.to_system_prompt())
# Output: "User prefers PostgreSQL 16 on port 5432."

TypeScript / Node.js SDK (@contexta/sdk)

Native async client optimized for Next.js, Vercel AI SDK, Bun, and LangChain/LlamaIndex pipelines.

typescript
npm install @contexta/sdk

import { Contexta } from "@contexta/sdk";

const memory = new Contexta({
  baseUrl: "http://localhost:8080",
  organizationId: "org_default",
});

// 1. Ingest agent conversation turn
await memory.observe({
  userId: "usr_42",
  messages: [
    { role: "user", content: "Switch DB preference to Cloudflare D1." }
  ],
});

// 2. Query active truth with zero contradictory facts
const facts = await memory.context({
  userId: "usr_42",
  query: "What database does user prefer?",
  tokenBudget: 350,
});

console.log(facts.formatted);
Section // api-reference

REST API Reference

POST /v1/observe

Ingests raw conversation turns or events. Automatically strips passwords and API keys via deterministic regex scanning, performs bi-temporal supersession, and updates entity graphs.

bash
curl -X POST http://localhost:8080/v1/observe \
  -H "Content-Type: application/json" \
  -H "x-organization-id: org_default" \
  -d '{
    "user_id": "usr_42",
    "messages": [
      {
        "role": "user",
        "content": "Database secret is DB_URL=postgres://root:p@ssw0rd_99@db:5432"
      }
    ]
  }'

# Response:
# {
#   "status": "ingested",
#   "redacted_tokens": 1,
#   "entities_resolved": ["Database"],
#   "active_memories_created": 1
# }

POST /v1/context

Tri-modal recall combining dense pgvector HNSW search, lexical TSVECTOR GIN matching, and entity graph traversal, fused with Reciprocal Rank Fusion (RRF) and scored by the local neural reranker in < 42ms.

bash
curl -X POST http://localhost:8080/v1/context \
  -H "Content-Type: application/json" \
  -H "x-organization-id: org_default" \
  -d '{
    "user_id": "usr_42",
    "query": "What database configuration is active?",
    "token_budget": 300
  }'

# Response:
# {
#   "latency_ms": 38.2,
#   "token_count": 48,
#   "memories": [
#     {
#       "id": "mem_88b",
#       "content": "User prefers Cloudflare D1 with edge replication",
#       "confidence": 0.98,
#       "valid_from": "2026-09-22T14:02:19Z"
#     }
#   ]
# }
Section // mcp-protocol

Model Context Protocol (MCP)

Universal MCP Configuration

Connect Contexta long-term memory to Claude Desktop, Cursor, or Antigravity IDE over standard Stdio or SSE transport with a single configuration block.

json
// Claude Desktop configuration (claude_desktop_config.json):
{
  "mcpServers": {
    "contexta": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "contexta_cortex",
        "python",
        "-m",
        "contexta.mcp.server"
      ]
    }
  }
}