cortyxia 0.1.13a1

The Memory Layer for Enterprise AI — persistent memory and 40% token cost reduction for any LLM stack

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 3-tier memory graph (raw → indexed → entity-linked) with ONNX extractors, cross-encoder reranking, and semantic relevance scoring. Sits as a transparent proxy — sub-50ms routing overhead, zero prompt changes, and 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=[e-mail]
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

Parameter	Type	Required	Description
messages	List[dict]	Yes	OpenAI-format messages
model	str	No	Model ID (auto-resolved from key if omitted)
iso_token	str	No	Specific key to use
temperature	float	No	Sampling temperature
max_tokens	int	No	Max output tokens

---

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:

Location	Path	Priority
Project-local	./.cortyxia/credentials.json	1st
Machine-global	~/.cortyxia/credentials.json	2nd

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"] = "[e-mail]"
client = Cortyxia()

---

Environment Variables

Variable	Required	Description
CORTYXIA_EMAIL	Yes (first run)	Email for provisioning
API_KEY	No	LLM provider API key (for initialize())
API_PROVIDER	No	Provider name: groq, openai, anthropic, gemini, deepseek, xai
API_MODEL	No	Model ID (for initialize())
DEV_MODE	No	true or false (default: false)

---

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?"

Cortyxia itself is free (MIT license). 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
• Open source — you can audit every line

"Can I use this in production?"

Yes. The alpha tag means the API surface may evolve, but the core routing and memory layers are battle-tested. Pin your version: pip install cortyxia==0.1.12a1.

---

Push to PyPI (Pre-release)

Bump the version in pyproject.toml (e.g., 0.1.12a1):

[project]
name = "cortyxia"
version = "0.1.12a1"

Build and upload:

cd sdks/python
python -m build
python -m twine upload --repository pypi dist/*

Or use TestPyPI first:

python -m twine upload --repository testpypi dist/*

Install the pre-release:

pip install --pre cortyxia

---

License

MIT