Novyx SDK

Governed actions, memory, audit, and rollback for AI agents. Let agents touch real systems through policy gates, human approval, tamper-evident evidence, and rollback. Persistent memory, semantic recall, draft review, context spaces, and replay are built in. (Cortex and Eval are experimental — see below.)

Installation

pip install novyx

Async Support (Optional)

pip install novyx[async]

CLI Installation (Optional)

pip install novyx[cli]

Quick Start (Sync)

from novyx import Novyx

nx = Novyx(api_key="nram_your_key_here")

# Submit a risky production action for policy evaluation
result = nx.submit_action(
    "github.issue.create",
    {
        "connector": "github",
        "operation": "issues/create",
        "environment": "production",
        "repo": "acme/api",
        "title": "Investigate failed rollback",
    },
    agent_id="github-production-agent",
)

if result["status"] == "pending_review":
    action_id = result["policy_result"]["action_id"]
    pending = nx.list_approvals(status_filter="pending_review")
    approval = next(item for item in pending["approvals"] if item["action_id"] == action_id)
    nx.approve_action(approval["approval_id"], reason="Scoped production investigation")
    print(nx.explain_action(action_id)["summary"])

Quick Start (Async)

from novyx import AsyncNovyx

async with AsyncNovyx(api_key="nram_your_key_here") as nx:
    result = await nx.submit_action(
        "github.issue.create",
        {"environment": "production", "repo": "acme/api"},
        agent_id="github-production-agent",
    )
    print(result["status"])

Novyx Control — Governance

Novyx Control is the policy-as-code governance layer. Define rules, evaluate actions, route high-severity violations through human approval, and aggregate everything into a dashboard. Five surfaces:

1. Custom Policies (Starter+)

Define policies as YAML/JSON. Each rule has a regex pattern, severity, and on_violation outcome.

nx.create_policy(
    name="pii_protection",
    description="Block actions exposing PII to external systems",
    rules=[
        {
            "match": "(ssn|social.security|passport)",
            "severity": "critical",
            "on_violation": "block",        # block | require_approval | warn
            "reason": "PII detected: {match}",
        },
        {
            "match": "(email|phone)",
            "context_requires": "(external|public)",
            "severity": "high",
            # on_violation defaults from severity:
            # critical → block, high → require_approval, medium/low → warn
        },
    ],
    whitelisted_domains=["internal.company.com"],
)

nx.list_policies()                    # built-in + custom
nx.get_policy("pii_protection")       # tenant-wide
nx.delete_policy("pii_protection")    # soft delete

2. Submit Governed Actions

result = nx.submit_action(
    "github.issue.create",
    {
        "connector": "github",
        "operation": "issues/create",
        "environment": "production",
        "owner": "acme",
        "repo": "api",
        "title": "Investigate failed deploy",
    },
    agent_id="github-production-agent",
)

# result["status"] is one of:
#   "allowed"        → action passed all policies
#   "blocked"        → critical violation, action stopped at the boundary
#   "pending_review" → high-severity violation, awaiting human approval

submit_action() is the main Novyx Cloud governance path. The older action_submit() helper targets a separate legacy Control instance and should only be used by deployments that still rely on the strata action envelope.

Supported connector metadata: github, slack, linear, pagerduty, http.

3. Approval Workflows

When an action is pending_review, it lands in the approvals queue.

pending = nx.list_approvals(status_filter="pending_review")
for action in pending["approvals"]:
    print(action["approval_id"], action["action"], action["risk_score"])

# Approve by approval id
nx.approve_action("apr-...", decision="approve", reason="Verified by oncall")

Approval modes (Solo / Team / Enterprise) are configured per tenant. Decisions log to the cryptographic audit chain.

4. Agent-Scoped Policies (Pro+)

The same policy name can have a tenant-wide version AND per-agent overrides. Per-agent rules override tenant-wide by name for that agent only.

# Tenant-wide policy applies to all agents
nx.create_policy(name="financial_check", rules=[...])

# Agent-scoped override — billing-bot has stricter rules
nx.create_policy(
    name="financial_check",
    agent_id="billing-bot",
    rules=[{"match": "wire_transfer", "severity": "critical"}],
)

# When billing-bot submits an action, the agent-scoped version wins
nx.submit_action("http.post", {...}, agent_id="billing-bot")

5. Governance Dashboard (Starter+)

Aggregated stats from the audit chain — totals, violations by policy, violations by agent, time-series.

dashboard = nx.governance_dashboard(window="7d")  # 24h | 7d | 30d
print(dashboard["totals"])              # evaluations, executed, pending_review, approved, denied
print(dashboard["violations_by_policy"]) # which policies fire most
print(dashboard["violations_by_agent"])  # which agents trip the most violations
print(dashboard["time_series"])          # bucketed by hour or day

# Per-agent drill-down
violations = nx.agent_violations("billing-bot", limit=20)

REST endpoints

Complete Lifecycle Example

from novyx import Novyx

nx = Novyx(api_key="nram_your_key_here")

# 1. Store memories
nx.remember("User mentioned budget is $50K for Q1", tags=["sales", "budget"], importance=8)
nx.remember("User prefers email over phone calls", tags=["preferences"], importance=7)
nx.remember("User is building a real estate AI assistant", tags=["project"])

# 2. Search with semantic recall
memories = nx.recall("what is the user's budget?", limit=3)
print(f"Found: {memories[0]['observation']}")

# 3. Check audit trail
audit = nx.audit(limit=5, operation="CREATE")
print(f"Created {len(audit)} memories")

# 4. Rollback if needed (Pro+ only)
# Preview what will change
preview = nx.rollback_preview("1 hour ago")
if preview["safe_rollback"]:
    result = nx.rollback("1 hour ago")
    print(f"Rolled back {result['operations_undone']} operations")

# 5. Trace agent actions (Pro+ only)
trace = nx.trace_create("sales-agent", session_id="session-123")
nx.trace_step(trace["trace_id"], "thought", "Analyzing budget — user has $50K")
nx.trace_step(trace["trace_id"], "action", "draft_proposal", metadata={"budget": 50000})
result = nx.trace_complete(trace["trace_id"])
print(f"Trace completed with signature: {result['signature'][:16]}...")

Canonical Workflow: Draft, Review, Merge

If an agent learns something high-impact, don't write it straight into canonical memory.

from novyx import Novyx

nx = Novyx(api_key="nram_your_key_here")

draft = nx.draft_memory(
    "Deploys fail if REDIS_URL is missing in staging",
    tags=["ops", "staging"],
    importance=8,
    branch_id="staging-fixes",
)

branch = nx.memory_branch("staging-fixes")
print(branch["recommendations"])

# Compare one draft against the closest existing memory
diff = nx.draft_diff(draft["draft_id"])
print(diff["recommendation"])

# Merge the whole reviewed branch
merged = nx.merge_branch("staging-fixes")
print(merged["merged_memory_ids"])

# Or reject the whole branch instead
# nx.reject_branch("staging-fixes", reason="not verified yet")

This is the safest default when an agent is learning operational facts, preferences, or anything that could drive future actions across a coding session.

Features

🧠 Persistent Memory

Store observations about users, contexts, and decisions. Your AI remembers everything across sessions.

# Store with metadata
nx.remember(
    "Customer mentioned budget is $50K for Q1",
    tags=["sales", "budget"],
    importance=8,
    metadata={"customer_id": "12345", "quarter": "Q1"}
)

# List all memories
all_memories = nx.memories(limit=100, min_importance=7)
print(f"Found {len(all_memories)} high-importance memories")

# Get specific memory
memory = nx.memory("urn:uuid:abc123...")

# Delete memory
nx.forget("urn:uuid:abc123...")

🔍 Semantic Search

Find relevant memories using natural language queries. No exact keyword matching required. Send plain text — Novyx handles embedding generation server-side.

memories = nx.recall("what is the user working on?", limit=3)
# Returns: "User is building a real estate AI assistant"

# Filter by tags
memories = nx.recall("budget constraints", tags=["sales"], limit=5)

⏮️ Magic Rollback (Pro+)

Made a mistake? Roll back your AI's memory to any point in time.

# Preview rollback first
preview = nx.rollback_preview("2 hours ago")
print(f"Will restore {preview['artifacts_restored']} artifacts")
print(f"Warnings: {preview['warnings']}")

# Execute rollback
result = nx.rollback("2 hours ago")
print(f"Rolled back to {result['rolled_back_to']}")

# View rollback history
history = nx.rollback_history(limit=10)
for rb in history:
    print(f"Rollback to {rb['target_timestamp']}")

📜 Cryptographic Audit Trail

Every operation is logged with SHA-256 hashing for tamper-evident history.

# Get recent audit entries
audit = nx.audit(limit=50, operation="CREATE")

# Filter by time range
from datetime import datetime, timedelta
since = (datetime.now() - timedelta(days=7)).isoformat()
audit = nx.audit(since=since, operation="ROLLBACK")

# Export audit log (Pro+)
csv_data = nx.audit_export(format="csv")
with open("audit.csv", "wb") as f:
    f.write(csv_data)

# Verify integrity
verification = nx.audit_verify()
if verification["valid"]:
    print("✅ Audit trail integrity verified!")

🔐 Trace Audit (Pro+)

Track agent actions with RSA signatures and real-time policy enforcement.

# Create trace session
trace = nx.trace_create("my-agent", session_id="session-123")

# Add steps
nx.trace_step(trace["trace_id"], "thought", "Planning email")
nx.trace_step(trace["trace_id"], "action", "send_email", metadata={"to": "user@example.com"})
nx.trace_step(trace["trace_id"], "observation", "Email sent successfully")

# Finalize with RSA signature
result = nx.trace_complete(trace["trace_id"])

# Verify integrity later
verification = nx.trace_verify(trace["trace_id"])
print(f"Verified {verification['steps_verified']} steps")

🌐 Context Spaces (Multi-Agent)

Create shared memory spaces for multi-agent collaboration with fine-grained permissions.

# Share a tag with another user
result = nx.share_context("project-notes", "colleague@example.com", permission="write")

# List shared spaces
ctx = nx.shared_contexts()
for s in ctx["shared_by_me"]:
    print(f"Shared '{s['tag']}' with {s.get('shared_with_email')}")

# Store memory in a space
nx.remember("Shared insight", space_id="cs_abc123", tags=["shared"])

# Recall from a space
memories = nx.recall("insights", space_id="cs_abc123")

🔄 Replay — Time-Travel Debugging (Pro+)

Inspect how your agent's memory changed over time.

# Timeline of operations
timeline = nx.replay_timeline(since="2026-01-01T00:00:00Z", limit=50)
for event in timeline["entries"]:
    print(f"{event['timestamp']} - {event['operation']}")

# Point-in-time snapshot
snapshot = nx.replay_snapshot("2026-01-15T10:00:00Z")
print(f"{snapshot['total']} memories at that point")

# Full lifecycle of a memory
lifecycle = nx.replay_memory("urn:uuid:abc123...")

# Diff between two timestamps
diff = nx.replay_diff("2026-01-01T00:00:00Z", "2026-01-15T00:00:00Z")
print(f"Added: {diff['added']}, Removed: {diff['removed']}")

# Counterfactual recall (Enterprise)
result = nx.replay_recall("user preferences", at="2026-01-10T00:00:00Z")

🧬 Cortex — Autonomous Memory Intelligence (Experimental)

Experimental — 403 unless NOVYX_ENABLE_EXPERIMENTAL=1 is set on the server. The consolidation/decay logic has no end-to-end test coverage and the "insights" are template-generated summaries, not analysis. Not recommended for production.

Cortex consolidates near-duplicates, boosts frequently-recalled memories, decays forgotten ones, and generates insights.

# Check cortex status
status = nx.cortex_status()
print(f"Enabled: {status['enabled']}, Last run: {status['last_run_at']}")

# Configure cortex
nx.cortex_update_config(
    consolidation_enabled=True,
    consolidation_threshold=0.90,
    decay_age_days=30,
)

# Trigger a manual cycle
result = nx.cortex_run()
print(f"Consolidated: {result['consolidated']}, Boosted: {result['boosted']}, Decayed: {result['decayed']}")

# Get insights (Enterprise)
insights = nx.cortex_insights(limit=10)
for insight in insights["insights"]:
    print(f"Insight: {insight['observation']}")

📊 Eval — Memory Health Scoring (Experimental)

Experimental — 403 unless NOVYX_ENABLE_EXPERIMENTAL=1 is set on the server. The composite score is unproven and not recommended for production gating yet.

Score your agent's memory health, detect regressions, and gate CI/CD deployments.

# Run a health evaluation
result = nx.eval_run()
print(f"Health: {result['health_score']}/100")
print(f"Recall: {result['breakdown']['recall_consistency']}")
print(f"Drift: {result['breakdown']['drift_score']}")

# CI/CD gate — block deploys below threshold
gate = nx.eval_gate(min_score=80.0)
if not gate["passed"]:
    raise Exception(f"Memory health too low: {gate['health_score']}")

# Save baselines for regression testing
nx.eval_baseline_create("capital of France", "The capital of France is Paris")

# Check drift over time
drift = nx.eval_drift()
print(f"Memory count delta: {drift['memory_count_delta']}")

# View eval history
history = nx.eval_history(limit=10)
for entry in history["entries"]:
    print(f"{entry['created_at']}: {entry['health_score']}")

🤖 Runtime v2 — Agents, Missions & Orchestration

First-class agent entities, goal-driven missions, capability packs (tool bundles), checkpoints, and supervisor interventions.

Agents (All tiers)

# Create an agent
agent = nx.create_agent(
    "research-bot",
    model="gpt-4o",
    provider="openai",
    instructions="You research competitor pricing.",
    capabilities=["web-search", "file-read"],
)

# List and manage agents
agents = nx.list_agents(status="active")
agent = nx.get_agent(agent["agent_id"])
nx.update_agent(agent["agent_id"], name="updated-name")
nx.delete_agent(agent["agent_id"])

Missions (All tiers)

# Create a mission for an agent
mission = nx.create_mission(
    agent["agent_id"],
    "Research competitor pricing for Q2",
    constraints=["Do not contact competitors directly"],
    success_criteria=["Report with at least 5 competitors"],
)

# Manage mission lifecycle
mission = nx.get_mission(mission["mission_id"])
missions = nx.list_missions(agent_id=agent["agent_id"], status="active")
nx.pause_mission(mission["mission_id"])
nx.resume_mission(mission["mission_id"])
nx.cancel_mission(mission["mission_id"])

Capability Packs (Starter+)

# Define what tools an agent can use and under what rules
cap = nx.create_capability(
    "web-search",
    description="Web search with rate limiting",
    tools=[{"name": "search", "provider": "google"}],
    risk_levels={"default": "low"},
    approval_requirements={"high_risk": True},
)

caps = nx.list_capabilities(status="active")

Checkpoints (Pro+)

# Save mission state before risky operations
ckpt = nx.create_checkpoint(mission["mission_id"], label="before-deploy")

# List checkpoints for a mission
checkpoints = nx.list_checkpoints(mission["mission_id"])

# Rollback to a checkpoint if things go wrong
nx.rollback_to_checkpoint(
    mission["mission_id"],
    ckpt["checkpoint_id"],
    reason="deploy failed",
)

Interventions (Enterprise)

# Record a supervisor intervention
intv = nx.create_intervention(
    "pause",
    mission_id=mission["mission_id"],
    rationale="Agent spending too much on API calls",
)

# List interventions
interventions = nx.list_interventions(mission_id=mission["mission_id"])

📊 Usage & Plans

Monitor your usage and explore pricing options.

# Check current usage
usage = nx.usage()
print(f"Tier: {usage['tier']}")
print(f"API calls: {usage['api_calls']['current']}/{usage['api_calls']['limit']}")
print(f"Memories: {usage['memories']['current']}")

# View available plans
plans = nx.plans()
for plan in plans:
    print(f"{plan['name']}: {plan['price_display']}")
    print(f"  Memories: {plan['memory_limit'] or 'Unlimited'}")
    print(f"  Features: {', '.join([k for k, v in plan['features'].items() if v])}")

API Reference

Memory Methods

Rollback Methods (Pro+)

Audit Methods

Trace Methods (Pro+)

Context Space Methods

Replay Methods (Pro+)

Cortex Methods (Experimental)

403 unless NOVYX_ENABLE_EXPERIMENTAL=1 is set on the server. Unproven; see the Cortex section above.

Knowledge Graph Methods (Pro+)

Link / Edge Methods

Eval Methods (Experimental)

403 unless NOVYX_ENABLE_EXPERIMENTAL=1 is set on the server. Unproven; see the Eval section above.

Runtime v2 — Agent Methods

Runtime v2 — Mission Methods

Runtime v2 — Capability Methods (Starter+)

Runtime v2 — Checkpoint Methods (Pro+)

Runtime v2 — Intervention Methods (Enterprise)

Usage & Plans

Error Handling

from novyx import (
    Novyx,
    NovyxRateLimitError,
    NovyxForbiddenError,
    NovyxAuthError,
    NovyxNotFoundError
)

nx = Novyx(api_key="nram_...")

try:
    nx.remember("Test memory")
except NovyxRateLimitError as e:
    # Memory limit exceeded
    print(f"Limit exceeded: {e.current}/{e.limit}")
    print(f"Upgrade at: {e.upgrade_url}")
except NovyxForbiddenError as e:
    # Feature not available on current plan
    print(f"Requires {e.tier_required} tier")
    print(f"Upgrade at: {e.upgrade_url}")
except NovyxAuthError as e:
    # Invalid API key
    print(f"Auth error: {e}")
except NovyxNotFoundError as e:
    # Resource not found
    print(f"Not found: {e}")

Pricing

Command-Line Interface (CLI)

Novyx includes a powerful CLI for managing memory, rollback, audit, and traces from the terminal.

Setup

# Install with CLI support
pip install novyx[cli]

# Configure API key
novyx config set api_key nram_your_key_here

# Or use environment variable
export NOVYX_API_KEY=nram_your_key_here

Quick Start

# Check API health and usage
novyx status

# List memories
novyx memories list --limit 20

# Semantic search
novyx memories search "user preferences"

# Get memory count
novyx memories count

# Delete memory
novyx memories delete <uuid>

Memory Management

# List all memories
novyx memories list --limit 100 --format table

# Export as JSON
novyx memories list --format json > memories.json

# Filter by tags
novyx memories list --tags "important,user-data"

# Semantic search with relevance scores
novyx memories search "what are the user's communication preferences?" --limit 5

# Delete with confirmation
novyx memories delete urn:uuid:abc123...

Rollback (Pro+)

# Preview rollback (ALWAYS do this first)
novyx rollback preview "2 hours ago"

# Execute rollback (shows preview + confirmation)
novyx rollback "2 hours ago"

# Skip confirmation (use with caution!)
novyx rollback "1 hour ago" --yes

# View rollback history
novyx rollback history --limit 10

Audit Trail

# List recent audit entries
novyx audit list --limit 50

# Filter by operation
novyx audit list --operation CREATE --limit 20
novyx audit list --operation ROLLBACK

# Export audit log (Pro+)
novyx audit export --format csv > audit.csv
novyx audit export --format json > audit.json

# Verify audit integrity
novyx audit verify

Trace Audit (Pro+)

# Verify trace integrity
novyx traces verify trace-abc123

# List and show coming in v2.1
novyx traces list
novyx traces show trace-abc123

Account & Status

# Show API health, plan, and usage
novyx status

# Configure API key
novyx config set api_key nram_your_key_here

# Show configuration (API key masked)
novyx config show

# Reset configuration
novyx config reset

CLI Features

• Rich Output: Beautiful tables and colored output with Rich
• Progress Indicators: Spinners for long-running operations
• Safety First: Rollback always shows preview + requires confirmation
• Multiple Formats: JSON or table output for easy parsing
• API Key Resolution: Flag > Environment > Config file (priority order)
• Error Handling: Clear, human-readable error messages

API Key Priority

The CLI resolves API keys in this order:

1. --api-key flag (highest priority)
2. NOVYX_API_KEY environment variable
3. ~/.novyx/config.json (lowest priority)

# Using flag
novyx --api-key nram_xxx status

# Using environment variable
export NOVYX_API_KEY=nram_xxx
novyx status

# Using config file
novyx config set api_key nram_xxx
novyx status

Example Workflow

# 1. Check system status
novyx status

# 2. List recent memories
novyx memories list --limit 20

# 3. Search for specific context
novyx memories search "budget constraints" --min-score 0.7

# 4. Made a mistake? Preview rollback
novyx rollback preview "1 hour ago"

# 5. Execute rollback if safe
novyx rollback "1 hour ago"

# 6. Verify audit integrity
novyx audit verify

# 7. Export audit for compliance
novyx audit export --format csv > audit-2026-02.csv

Links

• Documentation
• Pricing
• Get API Key

License

MIT