Cortyxia Python SDK

Your LLM app with a memory upgrade. Drop-in persistent memory. 40% fewer tokens. One line to get started.

Why Cortyxia?

Building LLM apps that "remember" across sessions shouldn't require a PhD in vector databases, embedding pipelines, or context-window math.

Cortyxia is a drop-in memory layer — you swap your openai.chat.completions.create() for client.chat.completions.create(), and suddenly your app remembers everything. No schema design. No Pinecone setup. No chunking strategies. It just works.

Under the hood: a memory node infrastructure with multi-tier graph mechanisms (raw → indexed → entity-linked) and separate node architecture per tier. ONNX extractors, cross-encoder reranking, and semantic relevance scoring run at the proxy layer — sub-50ms routing overhead, zero prompt changes, fully compatible with whatever RAG or vector DB you're already running.

What you get

• Persistent memory — conversations, facts, and context survive restarts
• 40% token cost reduction — intelligent context assembly sends only what matters
• Multi-provider routing — Groq, OpenAI, Anthropic, Gemini, DeepSeek, xAI via one ISO token
• Project isolation — separate memory namespaces per team/project
• Dev mode keys — isolated context windows for agentic coding workflows

What you DON'T need

• No vector DB setup (Pinecone, Weaviate, Chroma, etc.)
• No embedding pipeline
• No chunking / token-counting logic
• No config files to manage
• No signup forms — just an email

The 30-Second Test

pip install cortyxia

Set your provider key, provider, and model in a .env file, then:

from cortyxia import Cortyxia

client = Cortyxia()
key = client.initialize()   # Creates project + key from your .env

# Chat with memory
resp = client.chat.completions.create(
    messages=[{"role": "user", "content": "My name is Alice"}]
)

# Later, in a new session:
resp2 = client.chat.completions.create(
    messages=[{"role": "user", "content": "What's my name?"}]
)
# It remembers. It answers "Alice".

No database connection strings. No index creation. One package. One line. Done.

Installation

pip install cortyxia

• Python >= 3.9
• One dependency: requests
• Zero system packages (no ONNX, no CUDA drivers, no Rust toolchain)

That's it. If requests works, Cortyxia works.

One-Shot Setup (Recommended)

Create a .env file in your project root:

# .env
CORTYXIA_EMAIL=you@example.com
API_KEY=gsk_your_groq_key_here
API_PROVIDER=groq
API_MODEL=llama-3.1-8b-instant
# Optional: DEV_MODE=true

Then one line:

from cortyxia import Cortyxia

client = Cortyxia()
key = client.initialize()        # Creates "Default Project" + "Default Key"
print(key["iso_token"])          # Grab your ISO token

.env is parsed automatically — no python-dotenv dependency, no manual load_dotenv() call. We read it with pathlib (stdlib only).

Migrating from OpenAI / LangChain / Raw HTTP

Already using openai? Swap is two lines:

# Before
import openai
client = openai.OpenAI(api_key="sk-...")
resp = client.chat.completions.create(model="gpt-4o", messages=[...])

# After
from cortyxia import Cortyxia
client = Cortyxia()
resp = client.chat.completions.create(messages=[...])  # model auto-resolved

Your prompts don't change. Your message format doesn't change. The response shape is identical. If you don't like it, remove the import and go back. No lock-in.

Chat

Non-streaming

from cortyxia import Cortyxia, answer

client = Cortyxia()

resp = client.chat.completions.create(
    messages=[{"role": "user", "content": "What was I working on yesterday?"}]
)
print(answer(resp))   # Just the assistant text

Streaming

for line in client.chat.completions.stream(
    messages=[{"role": "user", "content": "Explain quantum computing"}]
):
    print(line, end="")

Use a specific key (iso_token)

resp = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello"}],
    iso_token="iso-your-token-here"   # Overrides default key
)

Parameters

Memory

Add a memory node

node = client.memory.add(
    content="User prefers Rust over Go for systems programming",
    tags=["preference", "language"]
)

Query memory

results = client.memory.query("What language does the user prefer?", limit=5)
for hit in results["hits"]:
    print(hit["content"])

Query scoped to a specific key

results = client.memory.query("deployment issues", iso_token="iso-your-token")

Projects

# List all projects
projects = client.projects.list()

# Create
project = client.projects.create("Agentic Coding", shared_memory_enabled=True)

# Get / Delete
project = client.projects.get(project["id"])
client.projects.delete(project["id"])

Keys

Create a key

key = client.keys.create(
    project_id=client.project_id,
    label="Production Key",
    provider="groq",
    model="llama-3.1-8b-instant",
    provider_key="gsk_your_key_here",   # Auto-maps to correct provider field
)

Create with explicit provider fields

key = client.keys.create(
    project_id=client.project_id,
    label="OpenAI Key",
    provider="openai",
    model="gpt-4o",
    openai_key="sk-...",
)

Dev mode key (isolated context)

key = client.keys.create(
    project_id=client.project_id,
    label="Claude Agent",
    provider="anthropic",
    model="claude-sonnet-4-20250514",
    dev_mode=True,
    dev_namespace="agent_1",
    recent_window_min=2,
    recent_window_max=8,
)

Update

# By key ID
client.keys.update(
    project_id=client.project_id,
    key_id=key["id"],
    model="llama-3.3-70b-versatile",
)

# By ISO token (no project_id needed)
client.keys.update_by_token(
    iso_token="iso-your-token",
    model="llama-3.3-70b-versatile",
)

Delete

# By key ID
client.keys.delete(client.project_id, key["id"])

# By ISO token
client.keys.delete_by_token("iso-your-token")

List all keys

for project in client.projects.list():
    for key in client.keys.list(project["id"]):
        print(key["iso_token"])

Helper Functions

answer(response) — Extract assistant text

from cortyxia import answer

resp = client.chat.completions.create(messages=[...])
print(answer(resp))   # Clean string, no JSON digging

Credential Storage

Cortyxia stores credentials in two locations for resilience:

Both files are created with 0600 permissions. A ./.cortyxia/.gitignore with * is auto-generated.

Resolution Order

1. CORTYXIA_EMAIL env var triggers provisioning / override
2. ./.cortyxia/credentials.json (per-project)
3. ~/.cortyxia/credentials.json (machine-wide)
4. Auto-provision if credentials don't exist

Email switching: Change CORTYXIA_EMAIL to switch accounts. Each email has its own isolated project world.

import os
os.environ["CORTYXIA_EMAIL"] = "work@company.com"
client = Cortyxia()

Environment Variables

Error Handling

from cortyxia import Cortyxia, CortyxiaError

try:
    client = Cortyxia()
    key = client.initialize()
except CortyxiaError as e:
    print(f"Setup failed: {e}")

FAQ

"What if Cortyxia goes down? Do my prompts break?"

Your prompts don't change. The response shape is identical to OpenAI's. If Cortyxia is unavailable, swap back to your original provider in one line. Your code stays the same.

"Do I need to redesign my app architecture?"

No. If you're already calling chat.completions.create(), you change the import. That's it. Memory happens automatically in the background.

"What about my existing vector DB / RAG pipeline?"

You can keep it. Cortyxia handles the "I talked to this user 3 days ago" memory layer. Your RAG pipeline handles the "here are the docs" layer. They complement each other.

"How much does this cost?"

Generous free tier — try it out or run small projects at no cost. You only pay for your LLM provider usage (Groq, OpenAI, etc.). And because Cortyxia assembles smarter context, you typically use fewer tokens — so your bill goes down, not up.

"Is my data safe?"

• Credentials stored locally with 0600 permissions
• Each email has fully isolated project data
• No third-party analytics or telemetry

"Can I use this in production?"

Yes. The core routing and memory layers are battle-tested. Pin your version: pip install cortyxia==0.1.14.

License

MIT